Class: Config
- Inherits:
-
Hocon::ConfigMergeable
- Object
- Hocon::ConfigMergeable
- Config
- Defined in:
- lib/hocon/config.rb
Overview
An immutable map from config paths to config values. Paths are dot-separated expressions such as foo.bar.baz
. Values are as in JSON (booleans, strings, numbers, lists, or objects), represented by ConfigValue instances. Values accessed through the Config
interface are never null.
<p> Config is an immutable object and thus safe to use from multiple threads. There’s never a need for “defensive copies.”
<p> Fundamental operations on a Config include getting configuration values, resolving substitutions with Config#resolve(), and merging configs using Config#withFallback(ConfigMergeable).
<p> All operations return a new immutable Config rather than modifying the original instance.
<p> <strong>Examples</strong>
<p> You can find an example app and library <a href=“github.com/typesafehub/config/tree/master/examples”>on GitHub</a>. Also be sure to read the <a href=“package-summary.html#package_description”>package overview</a> which describes the big picture as shown in those examples.
<p> <strong>Paths, keys, and Config vs. ConfigObject</strong>
<p> Config
is a view onto a tree of ConfigObject; the corresponding object tree can be found through Config#root(). ConfigObject
is a map from config keys, rather than paths, to config values. Think of ConfigObject
as a JSON object and Config
as a configuration API.
<p> The API tries to consistently use the terms “key” and “path.” A key is a key in a JSON object; it’s just a string that’s the key in a map. A “path” is a parseable expression with a syntax and it refers to a series of keys. Path expressions are described in the <a href=“github.com/typesafehub/config/blob/master/HOCON.md”>spec for Human-Optimized Config Object Notation</a>. In brief, a path is period-separated so “a.b.c” looks for key c in object b in object a in the root object. Sometimes double quotes are needed around special characters in path expressions.
<p> The API for a Config is in terms of path expressions, while the API for a ConfigObject is in terms of keys. Conceptually, Config is a one-level map from paths to values, while a ConfigObject is a tree of nested maps from keys to values.
<p> Use ConfigUtil#joinPath and ConfigUtil#splitPath to convert between path expressions and individual path elements (keys).
<p> Another difference between Config and ConfigObject is that conceptually, ConfigValues with a ConfigValue#valueType() valueType() of ConfigValueType#NULL NULL exist in a ConfigObject, while a Config treats null values as if they were missing.
<p> <strong>Getting configuration values</strong>
<p> The “getters” on a Config all work in the same way. They never return null, nor do they return a ConfigValue with ConfigValue#valueType() valueType() of ConfigValueType#NULL NULL. Instead, they throw ConfigException.Missing if the value is completely absent or set to null. If the value is set to null, a subtype of ConfigException.Missing called ConfigException.Null will be thrown. ConfigException.WrongType will be thrown anytime you ask for a type and the value has an incompatible type. Reasonable type conversions are performed for you though.
<p> <strong>Iteration</strong>
<p> If you want to iterate over the contents of a Config, you can get its ConfigObject with #root(), and then iterate over the ConfigObject (which implements java.util.Map
). Or, you can use #entrySet() which recurses the object tree for you and builds up a Set
of all path-value pairs where the value is not null.
<p> <strong>Resolving substitutions</strong>
<p> Substitutions are the ${foo.bar}
syntax in config files, described in the <a href= “github.com/typesafehub/config/blob/master/HOCON.md#substitutions” >specification</a>. Resolving substitutions replaces these references with real values.
<p> Before using a Config it’s necessary to call Config#resolve() to handle substitutions (though ConfigFactory#load() and similar methods will do the resolve for you already).
<p> <strong>Merging</strong>
<p> The full Config
for your application can be constructed using the associative operation Config#withFallback(ConfigMergeable). If you use ConfigFactory#load() (recommended), it merges system properties over the top of application.conf
over the top of reference.conf
, using withFallback
. You can add in additional sources of configuration in the same way (usually, custom layers should go either just above or just below application.conf
, keeping reference.conf
at the bottom and system properties at the top).
<p> <strong>Serialization</strong>
<p> Convert a Config
to a JSON or HOCON string by calling ConfigObject#render() on the root object, myConfig.root().render()
. There’s also a variant ConfigObject#render(ConfigRenderOptions) which allows you to control the format of the rendered string. (See ConfigRenderOptions.) Note that Config
does not remember the formatting of the original file, so if you load, modify, and re-save a config file, it will be substantially reformatted.
<p> As an alternative to ConfigObject#render(), the toString()
method produces a debug-output-oriented representation (which is not valid JSON).
<p> Java serialization is supported as well for Config
and all subtypes of ConfigValue
.
<p> <strong>This is an interface but don’t implement it yourself</strong>
<p> Do not implement Config; 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
-
#at_key(key) ⇒ Object
Places the config inside a Config at the given key.
-
#at_path(path) ⇒ Object
Places the config inside another Config at the given path.
-
#check_valid(reference, restrict_to_paths) ⇒ Object
Validates this config against a reference config, throwing an exception if it is invalid.
-
#empty? ⇒ Boolean
Returns true if the Config‘s root object contains no key-value pairs.
-
#entry_set ⇒ Object
Returns the set of path-value pairs, excluding any null values, found by recursing #root() the root object.
-
#get_any_ref(path) ⇒ Object
Gets the value at the path as an unwrapped Java boxed value ( java.lang.Boolean Boolean, java.lang.Integer Integer, and so on - see ConfigValue#unwrapped()).
-
#get_any_ref_list(path) ⇒ Object
Gets a list value with any kind of elements.
-
#get_boolean(path) ⇒ Object
The boolean value at the requested path.
-
#get_boolean_list(path) ⇒ Object
Gets a list value with boolean elements.
-
#get_bytes(path) ⇒ Object
Gets a value as a size in bytes (parses special strings like “128M”).
-
#get_bytes_list(path) ⇒ Object
Gets a list value with elements representing a size in bytes.
-
#get_config(path) ⇒ Object
The nested Config value at the requested path.
-
#get_config_list(path) ⇒ Object
Gets a list value with
Config
elements. -
#get_double(path) ⇒ Object
The floating-point value at the requested path.
-
#get_double_list(path) ⇒ Object
Gets a list value with double elements.
-
#get_duration(path, unit) ⇒ Object
Gets a value as a duration in a specified java.util.concurrent.TimeUnit TimeUnit.
-
#get_duration_list(path, unit) ⇒ Object
Gets a list, converting each value in the list to a duration, using the same rules as #getDuration(String, TimeUnit).
-
#get_int(path) ⇒ Object
Gets the integer at the given path.
-
#get_int_list(path) ⇒ Object
Gets a list value with int elements.
-
#get_list(path) ⇒ Object
Gets a list value (with any element type) as a ConfigList, which implements java.util.List<ConfigValue>.
-
#get_long(path) ⇒ Object
Gets the long integer at the given path.
-
#get_long_list(path) ⇒ Object
Gets a list value with long elements.
-
#get_memory_size(path) ⇒ Object
Gets a value as an amount of memory (parses special strings like “128M”).
-
#get_memory_size_list(path) ⇒ Object
Gets a list, converting each value in the list to a memory size, using the same rules as #getMemorySize(String).
-
#get_milliseconds(path) ⇒ Object
deprecated
Deprecated.
As of release 1.1, replaced by #getDuration(String, TimeUnit)
-
#get_milliseconds_list(path) ⇒ Object
deprecated
Deprecated.
As of release 1.1, replaced by #getDurationList(String, TimeUnit)
-
#get_nanoseconds(path) ⇒ Object
deprecated
Deprecated.
As of release 1.1, replaced by #getDuration(String, TimeUnit)
-
#get_nanoseconds_list(path) ⇒ Object
deprecated
Deprecated.
As of release 1.1, replaced by #getDurationList(String, TimeUnit)
-
#get_number(path) ⇒ Object
The numeric value at the requested path.
-
#get_number_list(path) ⇒ Object
Gets a list value with number elements.
- #get_object(path) ⇒ Object
-
#get_object_list(path) ⇒ Object
Gets a list value with object elements.
-
#get_string(path) ⇒ Object
The string value at the requested path.
-
#get_string_list(path) ⇒ Object
Gets a list value with string elements.
-
#get_value(path) ⇒ Object
Gets the value at the given path, unless the value is a null value or missing, in which case it throws just like the other getters.
-
#has_path(path) ⇒ Object
Checks whether a value is present and non-null at the given path.
-
#origin ⇒ Object
Gets the origin of the Config, which may be a file, or a file with a line number, or just a descriptive phrase.
-
#resolve(options) ⇒ Object
Returns a replacement config with all substitutions (the
${foo.bar}
syntax, see <a href=“github.com/typesafehub/config/blob/master/HOCON.md”>the spec</a>) resolved. -
#resolve_with(source, options) ⇒ Object
Like Config#resolveWith(Config) but allows you to specify non-default options.
-
#resolved? ⇒ Boolean
Checks whether the config is completely resolved.
-
#root ⇒ Object
Gets the Config as a tree of ConfigObject.
- #with_fallback(other) ⇒ Object
-
#with_only_path(path) ⇒ Object
Clone the config with only the given path (and its children) retained; all sibling paths are removed.
-
#with_value(path, value) ⇒ Object
Returns a Config based on this one, but with the given path set to the given value.
-
#without_path(path) ⇒ Object
Clone the config with the given path removed.
Instance Method Details
#at_key(key) ⇒ Object
Places the config inside a Config at the given key. See also atPath(). Note that a key is NOT a path expression (see ConfigUtil#joinPath and ConfigUtil#splitPath).
987 988 989 |
# File 'lib/hocon/config.rb', line 987 def at_key(key) raise Hocon::ConfigError::ConfigBugOrBrokenError, "subclasses of `Config` must implement `at_key` (#{self.class})" end |
#at_path(path) ⇒ Object
Places the config inside another Config at the given path. <p> Note that path expressions have a syntax and sometimes require quoting (see ConfigUtil#joinPath and ConfigUtil#splitPath).
973 974 975 |
# File 'lib/hocon/config.rb', line 973 def at_path(path) raise Hocon::ConfigError::ConfigBugOrBrokenError, "subclasses of `Config` must implement `at_path` (#{self.class})" end |
#check_valid(reference, restrict_to_paths) ⇒ Object
Validates this config against a reference config, throwing an exception if it is invalid. The purpose of this method is to “fail early” with a comprehensive list of problems; in general, anything this method can find would be detected later when trying to use the config, but it’s often more user-friendly to fail right away when loading the config.
<p> Using this method is always optional, since you can “fail late” instead.
<p> You must restrict validation to paths you “own” (those whose meaning are defined by your code module). If you validate globally, you may trigger errors about paths that happen to be in the config but have nothing to do with your module. It’s best to allow the modules owning those paths to validate them. Also, if every module validates only its own stuff, there isn’t as much redundant work being done.
<p> If no paths are specified in checkValid()
‘s parameter list, validation is for the entire config.
<p> If you specify paths that are not in the reference config, those paths are ignored. (There’s nothing to validate.)
<p> Here’s what validation involves:
<ul> <li>All paths found in the reference config must be present in this config or an exception will be thrown. <li> Some changes in type from the reference config to this config will cause an exception to be thrown. Not all potential type problems are detected, in particular it’s assumed that strings are compatible with everything except objects and lists. This is because string types are often “really” some other type (system properties always start out as strings, or a string like “5ms” could be used with #getMilliseconds). Also, it’s allowed to set any type to null or override null with any type. <li> Any unresolved substitutions in this config will cause a validation failure; both the reference config and this config should be resolved before validation. If the reference config is unresolved, it’s a bug in the caller of this method. </ul>
<p> If you want to allow a certain setting to have a flexible type (or otherwise want validation to be looser for some settings), you could either remove the problematic setting from the reference config provided to this method, or you could intercept the validation exception and screen out certain problems. Of course, this will only work if all other callers of this method are careful to restrict validation to their own paths, as they should be.
<p> If validation fails, the thrown exception contains a list of all problems found. See ConfigException.ValidationFailed#problems. The exception’s getMessage()
will have all the problems concatenated into one huge string, as well.
<p> Again, checkValid()
can’t guess every domain-specific way a setting can be invalid, so some problems may arise later when attempting to use the config. checkValid()
is limited to reporting generic, but common, problems such as missing settings and blatant type incompatibilities.
360 361 362 |
# File 'lib/hocon/config.rb', line 360 def check_valid(reference, restrict_to_paths) raise Hocon::ConfigError::ConfigBugOrBrokenError, "subclasses of `Config` must implement `check_valid` (#{self.class})" end |
#empty? ⇒ Boolean
Returns true if the Config‘s root object contains no key-value pairs.
397 398 399 |
# File 'lib/hocon/config.rb', line 397 def empty? raise Hocon::ConfigError::ConfigBugOrBrokenError, "subclasses of `Config` must implement `empty` (#{self.class})" end |
#entry_set ⇒ Object
Returns the set of path-value pairs, excluding any null values, found by recursing #root() the root object. Note that this is very different from root().entrySet()
which returns the set of immediate-child keys in the root object and includes null values. <p> Entries contain path expressions meaning there may be quoting and escaping involved. Parse path expressions with ConfigUtil#splitPath. <p> Because a Config
is conceptually a single-level map from paths to values, there will not be any ConfigObject values in the entries (that is, all entries represent leaf nodes). Use ConfigObject rather than Config
if you want a tree. (OK, this is a slight lie: Config
entries may contain ConfigList and the lists may contain objects. But no objects are directly included as entry values.)
423 424 425 |
# File 'lib/hocon/config.rb', line 423 def entry_set raise Hocon::ConfigError::ConfigBugOrBrokenError, "subclasses of `Config` must implement `entry_set` (#{self.class})" end |
#get_any_ref(path) ⇒ Object
Gets the value at the path as an unwrapped Java boxed value ( java.lang.Boolean Boolean, java.lang.Integer Integer, and so on - see ConfigValue#unwrapped()).
557 558 559 |
# File 'lib/hocon/config.rb', line 557 def get_any_ref(path) raise Hocon::ConfigError::ConfigBugOrBrokenError, "subclasses of `Config` must implement `get_any_ref` (#{self.class})" end |
#get_any_ref_list(path) ⇒ Object
Gets a list value with any kind of elements. Throws if the path is unset or null or not a list. Each element is “unwrapped” (see ConfigValue#unwrapped()).
862 863 864 |
# File 'lib/hocon/config.rb', line 862 def get_any_ref_list(path) raise Hocon::ConfigError::ConfigBugOrBrokenError, "subclasses of `Config` must implement `get_any_ref_list`path(#{self.class})" end |
#get_boolean(path) ⇒ Object
Returns the boolean value at the requested path.
437 438 439 |
# File 'lib/hocon/config.rb', line 437 def get_boolean(path) raise Hocon::ConfigError::ConfigBugOrBrokenError, "subclasses of `Config` must implement `get_boolean` (#{self.class})" end |
#get_boolean_list(path) ⇒ Object
Gets a list value with boolean elements. Throws if the path is unset or null or not a list or contains values not convertible to boolean.
726 727 728 |
# File 'lib/hocon/config.rb', line 726 def get_boolean_list(path) raise Hocon::ConfigError::ConfigBugOrBrokenError, "subclasses of `Config` must implement `get_boolean_list` (#{self.class})" end |
#get_bytes(path) ⇒ Object
Gets a value as a size in bytes (parses special strings like “128M”). If the value is already a number, then it’s left alone; if it’s a string, it’s parsed understanding unit suffixes such as “128K”, as documented in the <a href=“github.com/typesafehub/config/blob/master/HOCON.md”>the spec</a>.
596 597 598 |
# File 'lib/hocon/config.rb', line 596 def get_bytes(path) raise Hocon::ConfigError::ConfigBugOrBrokenError, "subclasses of `Config` must implement `get_bytes` (#{self.class})" end |
#get_bytes_list(path) ⇒ Object
Gets a list value with elements representing a size in bytes. Throws if the path is unset or null or not a list or contains values not convertible to memory sizes.
879 880 881 |
# File 'lib/hocon/config.rb', line 879 def get_bytes_list(path) raise Hocon::ConfigError::ConfigBugOrBrokenError, "subclasses of `Config` must implement `get_bytes_list` (#{self.class})" end |
#get_config(path) ⇒ Object
Returns the nested Config value at the requested path.
542 543 544 |
# File 'lib/hocon/config.rb', line 542 def get_config(path) raise Hocon::ConfigError::ConfigBugOrBrokenError, "subclasses of `Config` must implement `get_config` (#{self.class})" end |
#get_config_list(path) ⇒ Object
Gets a list value with Config
elements. Throws if the path is unset or null or not a list or contains values not convertible to Config
.
845 846 847 |
# File 'lib/hocon/config.rb', line 845 def get_config_list(path) raise Hocon::ConfigError::ConfigBugOrBrokenError, "subclasses of `Config` must implement `get_config_list` (#{self.class})" end |
#get_double(path) ⇒ Object
Returns the floating-point value at the requested path.
503 504 505 |
# File 'lib/hocon/config.rb', line 503 def get_double(path) raise Hocon::ConfigError::ConfigBugOrBrokenError, "subclasses of `Config` must implement `get_double` (#{self.class})" end |
#get_double_list(path) ⇒ Object
Gets a list value with double elements. Throws if the path is unset or null or not a list or contains values not convertible to double.
794 795 796 |
# File 'lib/hocon/config.rb', line 794 def get_double_list(path) raise Hocon::ConfigError::ConfigBugOrBrokenError, "subclasses of `Config` must implement `get_double_list` (#{self.class})" end |
#get_duration(path, unit) ⇒ Object
Gets a value as a duration in a specified java.util.concurrent.TimeUnit TimeUnit. If the value is already a number, then it’s taken as milliseconds and then converted to the requested TimeUnit; if it’s a string, it’s parsed understanding units suffixes like “10m” or “5ns” as documented in the <a href=“github.com/typesafehub/config/blob/master/HOCON.md”>the spec</a>.
692 693 694 |
# File 'lib/hocon/config.rb', line 692 def get_duration(path, unit) raise Hocon::ConfigError::ConfigBugOrBrokenError, "subclasses of `Config` must implement `get_duration` (#{self.class})" end |
#get_duration_list(path, unit) ⇒ Object
Gets a list, converting each value in the list to a duration, using the same rules as #getDuration(String, TimeUnit).
929 930 931 |
# File 'lib/hocon/config.rb', line 929 def get_duration_list(path, unit) raise Hocon::ConfigError::ConfigBugOrBrokenError, "subclasses of `Config` must implement `get_duration_list` (#{self.class})" end |
#get_int(path) ⇒ Object
Gets the integer at the given path. If the value at the path has a fractional (floating point) component, it will be discarded and only the integer part will be returned (it works like a “narrowing primitive conversion” in the Java language specification).
470 471 472 |
# File 'lib/hocon/config.rb', line 470 def get_int(path) raise Hocon::ConfigError::ConfigBugOrBrokenError, "subclasses of `Config` must implement `get_int` (#{self.class})" end |
#get_int_list(path) ⇒ Object
Gets a list value with int elements. Throws if the path is unset or null or not a list or contains values not convertible to int.
760 761 762 |
# File 'lib/hocon/config.rb', line 760 def get_int_list(path) raise Hocon::ConfigError::ConfigBugOrBrokenError, "subclasses of `Config` must implement `get_int_list` (#{self.class})" end |
#get_list(path) ⇒ Object
Gets a list value (with any element type) as a ConfigList, which implements java.util.List<ConfigValue>. Throws if the path is unset or null.
709 710 711 |
# File 'lib/hocon/config.rb', line 709 def get_list(path) raise Hocon::ConfigError::ConfigBugOrBrokenError, "subclasses of `Config` must implement `get_list` (#{self.class})" end |
#get_long(path) ⇒ Object
Gets the long integer at the given path. If the value at the path has a fractional (floating point) component, it will be discarded and only the integer part will be returned (it works like a “narrowing primitive conversion” in the Java language specification).
490 491 492 |
# File 'lib/hocon/config.rb', line 490 def get_long(path) raise Hocon::ConfigError::ConfigBugOrBrokenError, "subclasses of `Config` must implement `get_long` (#{self.class})" end |
#get_long_list(path) ⇒ Object
Gets a list value with long elements. Throws if the path is unset or null or not a list or contains values not convertible to long.
777 778 779 |
# File 'lib/hocon/config.rb', line 777 def get_long_list(path) raise Hocon::ConfigError::ConfigBugOrBrokenError, "subclasses of `Config` must implement `get_long_list` (#{self.class})" end |
#get_memory_size(path) ⇒ Object
Gets a value as an amount of memory (parses special strings like “128M”). If the value is already a number, then it’s left alone; if it’s a string, it’s parsed understanding unit suffixes such as “128K”, as documented in the <a href=“github.com/typesafehub/config/blob/master/HOCON.md”>the spec</a>.
620 621 622 |
# File 'lib/hocon/config.rb', line 620 def get_memory_size(path) raise Hocon::ConfigError::ConfigBugOrBrokenError, "subclasses of `Config` must implement `get_memory_size`path(#{self.class})" end |
#get_memory_size_list(path) ⇒ Object
Gets a list, converting each value in the list to a memory size, using the same rules as #getMemorySize(String).
896 897 898 |
# File 'lib/hocon/config.rb', line 896 def get_memory_size_list(path) raise Hocon::ConfigError::ConfigBugOrBrokenError, "subclasses of `Config` must implement `get_memory_size_list` (#{self.class})" end |
#get_milliseconds(path) ⇒ Object
As of release 1.1, replaced by #getDuration(String, TimeUnit)
Get value as a duration in milliseconds. If the value is already a number, then it’s left alone; if it’s a string, it’s parsed understanding units suffixes like “10m” or “5ns” as documented in the <a href=“github.com/typesafehub/config/blob/master/HOCON.md”>the spec</a>.
643 644 645 |
# File 'lib/hocon/config.rb', line 643 def get_milliseconds(path) raise Hocon::ConfigError::ConfigBugOrBrokenError, "subclasses of `Config` must implement `get_milliseconds` (#{self.class})" end |
#get_milliseconds_list(path) ⇒ Object
As of release 1.1, replaced by #getDurationList(String, TimeUnit)
Returns list of millisecond values.
905 906 907 |
# File 'lib/hocon/config.rb', line 905 def get_milliseconds_list(path) raise Hocon::ConfigError::ConfigBugOrBrokenError, "subclasses of `Config` must implement `get_milliseconds_list` (#{self.class})" end |
#get_nanoseconds(path) ⇒ Object
As of release 1.1, replaced by #getDuration(String, TimeUnit)
Get value as a duration in nanoseconds. If the value is already a number it’s taken as milliseconds and converted to nanoseconds. If it’s a string, it’s parsed understanding unit suffixes, as for #getDuration(String, TimeUnit).
665 666 667 |
# File 'lib/hocon/config.rb', line 665 def get_nanoseconds(path) raise Hocon::ConfigError::ConfigBugOrBrokenError, "subclasses of `Config` must implement `get_nanoseconds` (#{self.class})" end |
#get_nanoseconds_list(path) ⇒ Object
As of release 1.1, replaced by #getDurationList(String, TimeUnit)
Returns list of nanosecond values.
914 915 916 |
# File 'lib/hocon/config.rb', line 914 def get_nanoseconds_list(path) raise Hocon::ConfigError::ConfigBugOrBrokenError, "subclasses of `Config` must implement `get_nanoseconds_list` (#{self.class})" end |
#get_number(path) ⇒ Object
Returns the numeric value at the requested path.
450 451 452 |
# File 'lib/hocon/config.rb', line 450 def get_number(path) raise Hocon::ConfigError::ConfigBugOrBrokenError, "subclasses of `Config` must implement `get_number` (#{self.class})" end |
#get_number_list(path) ⇒ Object
Gets a list value with number elements. Throws if the path is unset or null or not a list or contains values not convertible to number.
743 744 745 |
# File 'lib/hocon/config.rb', line 743 def get_number_list(path) raise Hocon::ConfigError::ConfigBugOrBrokenError, "subclasses of `Config` must implement `get_number_list` (#{self.class})" end |
#get_object(path) ⇒ Object
529 530 531 |
# File 'lib/hocon/config.rb', line 529 def get_object(path) raise Hocon::ConfigError::ConfigBugOrBrokenError, "subclasses of `Config` must implement `get_object` (#{self.class})" end |
#get_object_list(path) ⇒ Object
Gets a list value with object elements. Throws if the path is unset or null or not a list or contains values not convertible to ConfigObject
.
828 829 830 |
# File 'lib/hocon/config.rb', line 828 def get_object_list(path) raise Hocon::ConfigError::ConfigBugOrBrokenError, "subclasses of `Config` must implement `get_object_list` (#{self.class})" end |
#get_string(path) ⇒ Object
Returns the string value at the requested path.
516 517 518 |
# File 'lib/hocon/config.rb', line 516 def get_string(path) raise Hocon::ConfigError::ConfigBugOrBrokenError, "subclasses of `Config` must implement `get_string` (#{self.class})" end |
#get_string_list(path) ⇒ Object
Gets a list value with string elements. Throws if the path is unset or null or not a list or contains values not convertible to string.
811 812 813 |
# File 'lib/hocon/config.rb', line 811 def get_string_list(path) raise Hocon::ConfigError::ConfigBugOrBrokenError, "subclasses of `Config` must implement `get_string_list` (#{self.class})" end |
#get_value(path) ⇒ Object
Gets the value at the given path, unless the value is a null value or missing, in which case it throws just like the other getters. Use get() on the Config#root() object (or other object in the tree) if you want an unprocessed value.
574 575 576 |
# File 'lib/hocon/config.rb', line 574 def get_value(path) raise Hocon::ConfigError::ConfigBugOrBrokenError, "subclasses of `Config` must implement `get_value`path(#{self.class})" end |
#has_path(path) ⇒ Object
Checks whether a value is present and non-null at the given path. This differs in two ways from Map.containsKey() as implemented by ConfigObject: it looks for a path expression, not a key; and it returns false for null values, while containsKey() returns true indicating that the object contains a null value for the key.
<p> If a path exists according to #hasPath(String), then #getValue(String) will never throw an exception. However, the typed getters, such as #getInt(String), will still throw if the value is not convertible to the requested type.
<p> Note that path expressions have a syntax and sometimes require quoting (see ConfigUtil#joinPath and ConfigUtil#splitPath).
387 388 389 |
# File 'lib/hocon/config.rb', line 387 def has_path(path) raise Hocon::ConfigError::ConfigBugOrBrokenError, "subclasses of `Config` must implement `has_path` (#{self.class})" end |
#origin ⇒ Object
Gets the origin of the Config, which may be a file, or a file with a line number, or just a descriptive phrase.
178 179 180 |
# File 'lib/hocon/config.rb', line 178 def origin raise Hocon::ConfigError::ConfigBugOrBrokenError, "subclasses of `Config` must implement `origin` (#{self.class})" end |
#resolve(options) ⇒ Object
Returns a replacement config with all substitutions (the ${foo.bar}
syntax, see <a href=“github.com/typesafehub/config/blob/master/HOCON.md”>the spec</a>) resolved. Substitutions are looked up using this Config
as the root object, that is, a substitution ${foo.bar}
will be replaced with the result of getValue("foo.bar")
.
<p> This method uses ConfigResolveOptions#defaults(), there is another variant Config#resolve(ConfigResolveOptions) which lets you specify non-default options.
<p> A given Config must be resolved before using it to retrieve config values, but ideally should be resolved one time for your entire stack of fallbacks (see Config#withFallback). Otherwise, some substitutions that could have resolved with all fallbacks available may not resolve, which will be potentially confusing for your application’s users.
<p> resolve()
should be invoked on root config objects, rather than on a subtree (a subtree is the result of something like config.getConfig("foo")
). The problem with resolve()
on a subtree is that substitutions are relative to the root of the config and the subtree will have no way to get values from the root. For example, if you did config.getConfig("foo").resolve()
on the below config file, it would not work:
<pre>
common-value = 10
foo {
whatever = ${common-value}
}
</pre>
<p> Many methods on ConfigFactory such as ConfigFactory#load() automatically resolve the loaded Config
on the loaded stack of config files.
<p> Resolving an already-resolved config is a harmless no-op, but again, it is best to resolve an entire stack of fallbacks (such as all your config files combined) rather than resolving each one individually.
241 242 243 |
# File 'lib/hocon/config.rb', line 241 def resolve() raise Hocon::ConfigError::ConfigBugOrBrokenError, "subclasses of `Config` must implement `resolve` (#{self.class})" end |
#resolve_with(source, options) ⇒ Object
Like Config#resolveWith(Config) but allows you to specify non-default options.
274 275 276 |
# File 'lib/hocon/config.rb', line 274 def resolve_with(source, ) raise Hocon::ConfigError::ConfigBugOrBrokenError, "subclasses of `Config` must implement `resolve_with` (#{self.class})" end |
#resolved? ⇒ Boolean
Checks whether the config is completely resolved. After a successful call to Config#resolve() it will be completely resolved, but after calling Config#resolve(ConfigResolveOptions) with allowUnresolved
set in the options, it may or may not be completely resolved. A newly-loaded config may or may not be completely resolved depending on whether there were substitutions present in the file.
258 259 260 |
# File 'lib/hocon/config.rb', line 258 def resolved? raise Hocon::ConfigError::ConfigBugOrBrokenError, "subclasses of `Config` must implement `resolved?` (#{self.class})" end |
#root ⇒ Object
Gets the Config as a tree of ConfigObject. This is a constant-time operation (it is not proportional to the number of values in the Config).
168 169 170 |
# File 'lib/hocon/config.rb', line 168 def root raise Hocon::ConfigError::ConfigBugOrBrokenError, "subclasses of `Config` must implement `root` (#{self.class})" end |
#with_fallback(other) ⇒ Object
182 183 184 |
# File 'lib/hocon/config.rb', line 182 def with_fallback(other) raise Hocon::ConfigError::ConfigBugOrBrokenError, "subclasses of `Config` must implement `with_fallback` (#{self.class})" end |
#with_only_path(path) ⇒ Object
Clone the config with only the given path (and its children) retained; all sibling paths are removed. <p> Note that path expressions have a syntax and sometimes require quoting (see ConfigUtil#joinPath and ConfigUtil#splitPath).
944 945 946 |
# File 'lib/hocon/config.rb', line 944 def with_only_path(path) raise Hocon::ConfigError::ConfigBugOrBrokenError, "subclasses of `Config` must implement `with_only_path` (#{self.class})" end |
#with_value(path, value) ⇒ Object
Returns a Config based on this one, but with the given path set to the given value. Does not modify this instance (since it’s immutable). If the path already has a value, that value is replaced. To remove a value, use withoutPath(). <p> Note that path expressions have a syntax and sometimes require quoting (see ConfigUtil#joinPath and ConfigUtil#splitPath).
1006 1007 1008 |
# File 'lib/hocon/config.rb', line 1006 def with_value(path, value) raise Hocon::ConfigError::ConfigBugOrBrokenError, "subclasses of `Config` must implement `with_value` (#{self.class})" end |
#without_path(path) ⇒ Object
Clone the config with the given path removed. <p> Note that path expressions have a syntax and sometimes require quoting (see ConfigUtil#joinPath and ConfigUtil#splitPath).
958 959 960 |
# File 'lib/hocon/config.rb', line 958 def without_path(path) raise Hocon::ConfigError::ConfigBugOrBrokenError, "subclasses of `Config` must implement `without_path` (#{self.class})" end |