module Hocon::ConfigObject

Subtype of {@link ConfigValue} representing an object (AKA dictionary or map) value, as in JSON’s curly brace { "a" : 42 } syntax.

<p> An object may also be viewed as a {@link Config} by calling {@link ConfigObject#toConfig()}.

<p> {@code ConfigObject} implements {@code java.util.Map<String, ConfigValue>} so you can use it like a regular Java map. Or call {@link unwrapped()} to unwrap the map to a map with plain Java values rather than {@code ConfigValue}.

<p> Like all {@link ConfigValue} subtypes, {@code ConfigObject} is immutable. This makes it threadsafe and you never have to create “defensive copies.” The mutator methods from {@link java.util.Map} all throw {@link java.lang.UnsupportedOperationException}.

<p> The {@link ConfigValue#valueType} method on an object returns {@link ConfigValueType#OBJECT}.

<p> In most cases you want to use the {@link Config} interface rather than this one. Call {@link toConfig()} to convert a {@code ConfigObject} to a {@code Config}.

<p> The API for a {@code ConfigObject} is in terms of keys, while the API for a {@link Config} is in terms of path expressions. Conceptually, {@code ConfigObject} is a tree of maps from keys to values, while a {@code Config} is a one-level map from paths to values.

<p> Use {@link ConfigUtil#joinPath} and {@link ConfigUtil#splitPath} to convert between path expressions and individual path elements (keys).

<p> A {@code ConfigObject} may contain null values, which will have {@link ConfigValue#valueType()} equal to {@link ConfigValueType#NULL}. If {@link ConfigObject#get(Object)} returns Java’s null then the key was not present in the parsed file (or wherever this value tree came from). If {@code get(“key”)} returns a {@link ConfigValue} with type {@code ConfigValueType#NULL} then the key was set to null explicitly in the config file.

<p> Do not implement interface {@code ConfigObject}; it should only be implemented by the config library. Arbitrary implementations will not work because the library internals assume a specific concrete implementation. Also, this interface is likely to grow new methods over time, so third-party implementations will break.