Module: Hocon::ConfigObject

Includes:
ConfigValue
Included in:
Impl::AbstractConfigObject
Defined in:
lib/hocon/config_object.rb

Overview

Subtype of 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 Config by calling ConfigObject#toConfig().

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

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

<p> The ConfigValue#valueType method on an object returns ConfigValueType#OBJECT.

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

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

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

<p> A ConfigObject may contain null values, which will have ConfigValue#valueType() equal to ConfigValueType#NULL. If 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 get(“key”) returns a ConfigValue with type ConfigValueType#NULL then the key was set to null explicitly in the config file.

<p> Do not implement interface 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.

Instance Method Summary collapse

Methods included from ConfigValue

#at_key, #at_path, #origin, #render, #value_type

Instance Method Details

#get(key) ⇒ Object

Gets a ConfigValue at the given key, or returns null if there is no value. The returned ConfigValue may have ConfigValueType#NULL or any other type, and the passed-in key must be a key in this object (rather than a path expression).

Parameters:

  • key —

    key to look up

Returns:

  • the value at the key or null if none

Raises:



100
101
102
 
# File 'lib/hocon/config_object.rb', line 100

def get(key)
  raise Hocon::ConfigError::ConfigBugOrBrokenError, "subclasses of ConfigObject should provide their own implementation of `get` (#{self.class})"
end

#to_config ⇒ Object

Converts this object to a Config instance, enabling you to use path expressions to find values in the object. This is a constant-time operation (it is not proportional to the size of the object).

Raises:



71
72
73
 
# File 'lib/hocon/config_object.rb', line 71

def to_config
  raise Hocon::ConfigError::ConfigBugOrBrokenError, "subclasses of ConfigObject should provide their own implementation of `to_config` (#{self.class})"
end

#unwrapped ⇒ Object

Recursively unwraps the object, returning a map from String to whatever plain Java values are unwrapped from the object’s values.

Raises:



81
82
83
 
# File 'lib/hocon/config_object.rb', line 81

def unwrapped
  raise Hocon::ConfigError::ConfigBugOrBrokenError, "subclasses of ConfigObject should provide their own implementation of `unwrapped` (#{self.class})"
end

#with_fallback(other) ⇒ Object

Raises:



85
86
87
 
# File 'lib/hocon/config_object.rb', line 85

def with_fallback(other)
  raise Hocon::ConfigError::ConfigBugOrBrokenError, "subclasses of ConfigObject should provide their own implementation of `with_fallback` (#{self.class})"
end

#with_only_key(key) ⇒ Object

Clone the object with only the given key (and its children) retained; all sibling keys are removed.

Parameters:

  • key —

    key to keep

Returns:

  • a copy of the object minus all keys except the one specified

Raises:



112
113
114
 
# File 'lib/hocon/config_object.rb', line 112

def with_only_key(key)
  raise Hocon::ConfigError::ConfigBugOrBrokenError, "subclasses of ConfigObject should provide their own implementation of `with_only_key` (#{self.class})"
end

#with_origin(origin) ⇒ Object

Raises:



143
144
145
 
# File 'lib/hocon/config_object.rb', line 143

def with_origin(origin)
  raise Hocon::ConfigError::ConfigBugOrBrokenError, "subclasses of ConfigObject should provide their own implementation of `with_origin` (#{self.class})"
end

#with_value(key, value) ⇒ Object

Returns a ConfigObject based on this one, but with the given key set to the given value. Does not modify this instance (since it’s immutable). If the key already has a value, that value is replaced. To remove a value, use ConfigObject#withoutKey(String).

Parameters:

  • key —

    key to add

  • value —

    value at the new key

Returns:

  • the new instance with the new map entry

Raises:



139
140
141
 
# File 'lib/hocon/config_object.rb', line 139

def with_value(key, value)
  raise Hocon::ConfigError::ConfigBugOrBrokenError, "subclasses of ConfigObject should provide their own implementation of `with_value` (#{self.class})"
end

#without_key(key) ⇒ Object

Clone the object with the given key removed.

Parameters:

  • key —

    key to remove

Returns:

  • a copy of the object minus the specified key

Raises:



123
124
125
 
# File 'lib/hocon/config_object.rb', line 123

def without_key(key)
  raise Hocon::ConfigError::ConfigBugOrBrokenError, "subclasses of ConfigObject should provide their own implementation of `without_key` (#{self.class})"
end