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.

An object may also be viewed as a Config by calling ConfigObject#toConfig().

ConfigObject implements java.util.Map 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.

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.

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

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

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.

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

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.

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