hocon 0.0.7 → 0.1.0

data/lib/hocon/config_error.rb

@@ -1,8 +1,16 @@
+# encoding: utf-8
+
 require 'hocon'
 
 class Hocon::ConfigError < StandardError
   def initialize(origin, message, cause)
-    super(message)
+    msg =
+      if origin.nil?
+        message
+      else
+        "#{origin.description}: #{message}"
+      end
+    super(msg)
     @origin = origin
     @cause = cause
   end
@@ -20,18 +28,40 @@ class Hocon::ConfigError < StandardError
     end
   end
 
+  class ConfigIOError < Hocon::ConfigError
+    def initialize(origin, message, cause = nil)
+      super(origin, message, cause)
+    end
+  end
+
   class ConfigParseError < Hocon::ConfigError
   end
 
   class ConfigWrongTypeError < Hocon::ConfigError
+    def self.with_expected_actual(origin, path, expected, actual, cause = nil)
+      ConfigWrongTypeError.new(origin, "#{path} has type #{actual} rather than #{expected}", cause)
+    end
   end
 
   class ConfigBugOrBrokenError < Hocon::ConfigError
-    def initialize(message, cause)
+    def initialize(message, cause = nil)
       super(nil, message, cause)
     end
   end
 
   class ConfigNotResolvedError < Hocon::ConfigError::ConfigBugOrBrokenError
   end
+
+  class ConfigBadPathError < Hocon::ConfigError
+    def initialize(origin, path, message, cause = nil)
+      error_message = !path.nil? ? "Invalid path '#{path}': #{message}" : message
+      super(origin, error_message, cause)
+    end
+  end
+
+  class UnresolvedSubstitutionError < ConfigParseError
+    def initialize(origin, detail, cause = nil)
+      super(origin, "Could not resolve substitution to a value: " + detail, cause)
+    end
+  end
 end

data/lib/hocon/config_factory.rb

@@ -1,6 +1,10 @@
+# encoding: utf-8
+
 require 'hocon'
 require 'hocon/impl/parseable'
 require 'hocon/config_parse_options'
+require 'hocon/impl/config_impl'
+require 'hocon/config_factory'
 
 class Hocon::ConfigFactory
   def self.parse_file(file_path, options = Hocon::ConfigParseOptions.defaults)
@@ -10,4 +14,46 @@ class Hocon::ConfigFactory
   def self.parse_string(string, options = Hocon::ConfigParseOptions.defaults)
     Hocon::Impl::Parseable.new_string(string, options).parse.to_config
   end
+
+  def self.parse_file_any_syntax(file_base_name, options)
+    Hocon::Impl::ConfigImpl.parse_file_any_syntax(file_base_name, options).to_config
+  end
+
+  def self.empty(origin_description = nil)
+    Hocon::Impl::ConfigImpl.empty_config(origin_description)
+  end
+
+  # Because of how optional arguments work, if either parse or resolve options is supplied
+  # both must be supplied. load_file_with_parse_options or load_file_with_resolve_options
+  # can be used instead, or the argument you don't care about in load_file can be nil
+  #
+  # e.g.:
+  # load_file("settings", my_parse_options, nil)
+  # is equivalent to:
+  # load_file_with_parse_options("settings", my_parse_options)
+  def self.load_file(file_base_name, parse_options = nil, resolve_options = nil)
+    parse_options ||= Hocon::ConfigParseOptions.defaults
+    resolve_options ||= Hocon::ConfigResolveOptions.defaults
+
+    config = Hocon::ConfigFactory.parse_file_any_syntax(file_base_name, parse_options)
+
+    self.load_from_config(config, resolve_options)
+  end
+
+  def self.load_file_with_parse_options(file_base_name, parse_options)
+    self.load_file(file_base_name, parse_options, nil)
+  end
+
+  def self.load_file_with_resolve_options(file_base_name, resolve_options)
+    self.load_file(file_base_name, nil, resolve_options)
+  end
+
+  def self.load_from_config(config, resolve_options)
+
+    config.with_fallback(self.default_reference).resolve(resolve_options)
+  end
+
+  def self.default_reference
+    Hocon::Impl::ConfigImpl.default_reference
+  end
 end

data/lib/hocon/config_include_context.rb

@@ -0,0 +1,49 @@
+# encoding: utf-8
+
+require 'hocon'
+require 'hocon/config_error'
+
+#
+# Context provided to a {@link ConfigIncluder}; this interface is only useful
+# inside a {@code ConfigIncluder} implementation, and is not intended for apps
+# to implement.
+#
+# <p>
+# <em>Do not implement this interface</em>; 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.
+#
+module Hocon::ConfigIncludeContext
+  #
+  # Tries to find a name relative to whatever is doing the including, for
+  # example in the same directory as the file doing the including. Returns
+  # null if it can't meaningfully create a relative name. The returned
+  # parseable may not exist; this function is not required to do any IO, just
+  # compute what the name would be.
+  #
+  # The passed-in filename has to be a complete name (with extension), not
+  # just a basename. (Include statements in config files are allowed to give
+  # just a basename.)
+  #
+  # @param filename
+  #            the name to make relative to the resource doing the including
+  # @return parseable item relative to the resource doing the including, or
+  #         null
+  #
+  def relative_to(filename)
+    raise Hocon::ConfigError::ConfigBugOrBrokenError, "subclasses of `ConfigIncludeContext` must implement `relative_to` (#{self.class})"
+  end
+
+  #
+  # Parse options to use (if you use another method to get a
+  # {@link ConfigParseable} then use {@link ConfigParseable#options()}
+  # instead though).
+  #
+  # @return the parse options
+  #
+  def parse_options
+    raise Hocon::ConfigError::ConfigBugOrBrokenError, "subclasses of `ConfigIncludeContext` must implement `parse_options` (#{self.class})"
+  end
+end

data/lib/hocon/config_includer_file.rb

@@ -0,0 +1,27 @@
+# encoding: utf-8
+
+require 'hocon'
+require 'hocon/config_error'
+
+#
+# Implement this <em>in addition to</em> {@link ConfigIncluder} if you want to
+# support inclusion of files with the {@code include file("filename")} syntax.
+# If you do not implement this but do implement {@link ConfigIncluder},
+# attempts to load files will use the default includer.
+#
+module Hocon::ConfigIncluderFile
+  #
+  # Parses another item to be included. The returned object typically would
+  # not have substitutions resolved. You can throw a ConfigException here to
+  # abort parsing, or return an empty object, but may not return null.
+  #
+  # @param context
+  #            some info about the include context
+  # @param what
+  #            the include statement's argument
+  # @return a non-null ConfigObject
+  #
+  def include_file(context, what)
+    raise Hocon::ConfigError::ConfigBugOrBrokenError, "subclasses of `ConfigIncluderFile` must implement `include_file` (#{self.class})"
+  end
+end

data/lib/hocon/config_list.rb

@@ -0,0 +1,49 @@
+# encoding: utf-8
+
+require 'hocon'
+require 'hocon/config_value'
+require 'hocon/config_error'
+
+#
+# Subtype of {@link ConfigValue} representing a list value, as in JSON's
+# {@code [1,2,3]} syntax.
+#
+# <p>
+# {@code ConfigList} implements {@code java.util.List<ConfigValue>} so you can
+# use it like a regular Java list. Or call {@link #unwrapped()} to unwrap the
+# list elements into plain Java values.
+#
+# <p>
+# Like all {@link ConfigValue} subtypes, {@code ConfigList} is immutable. This
+# makes it threadsafe and you never have to create "defensive copies." The
+# mutator methods from {@link java.util.List} all throw
+# {@link java.lang.UnsupportedOperationException}.
+#
+# <p>
+# The {@link ConfigValue#valueType} method on a list returns
+# {@link ConfigValueType#LIST}.
+#
+# <p>
+# <em>Do not implement {@code ConfigList}</em>; 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.
+#
+#
+module Hocon::ConfigList
+  include Hocon::ConfigValue
+
+  #
+  # Recursively unwraps the list, returning a list of plain Java values such
+  # as Integer or String or whatever is in the list.
+  #
+  def unwrapped
+    raise Hocon::ConfigError::ConfigBugOrBrokenError, "subclasses of ConfigValue should provide their own implementation of `unwrapped` (#{self.class})"
+  end
+
+  def with_origin(origin)
+    raise Hocon::ConfigError::ConfigBugOrBrokenError, "subclasses of ConfigValue should provide their own implementation of `with_origin` (#{self.class})"
+  end
+
+end

data/lib/hocon/config_mergeable.rb

@@ -0,0 +1,74 @@
+# encoding: utf-8
+
+require 'hocon'
+require 'hocon/config_error'
+
+#
+# Marker for types whose instances can be merged, that is {@link Config} and
+# {@link ConfigValue}. Instances of {@code Config} and {@code ConfigValue} can
+# be combined into a single new instance using the
+# {@link ConfigMergeable#withFallback withFallback()} method.
+#
+# <p>
+# <em>Do not implement this interface</em>; 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.
+#
+module Hocon::ConfigMergeable
+#
+# Returns a new value computed by merging this value with another, with
+# keys in this value "winning" over the other one.
+#
+# <p>
+# This associative operation may be used to combine configurations from
+# multiple sources (such as multiple configuration files).
+#
+# <p>
+# The semantics of merging are described in the <a
+# href="https://github.com/typesafehub/config/blob/master/HOCON.md">spec
+# for HOCON</a>. Merging typically occurs when either the same object is
+# created twice in the same file, or two config files are both loaded. For
+# example:
+#
+# <pre>
+#  foo = { a: 42 }
+#  foo = { b: 43 }
+# </pre>
+#
+# Here, the two objects are merged as if you had written:
+#
+# <pre>
+#  foo = { a: 42, b: 43 }
+# </pre>
+#
+# <p>
+# Only {@link ConfigObject} and {@link Config} instances do anything in
+# this method (they need to merge the fallback keys into themselves). All
+# other values just return the original value, since they automatically
+# override any fallback. This means that objects do not merge "across"
+# non-objects; if you write
+# <code>object.withFallback(nonObject).withFallback(otherObject)</code>,
+# then <code>otherObject</code> will simply be ignored. This is an
+# intentional part of how merging works, because non-objects such as
+# strings and integers replace (rather than merging with) any prior value:
+#
+# <pre>
+# foo = { a: 42 }
+# foo = 10
+# </pre>
+#
+# Here, the number 10 "wins" and the value of <code>foo</code> would be
+# simply 10. Again, for details see the spec.
+#
+# @param other
+#            an object whose keys should be used as fallbacks, if the keys
+#            are not present in this one
+# @return a new object (or the original one, if the fallback doesn't get
+#         used)
+#
+  def with_fallback(other)
+    raise Hocon::ConfigError::ConfigBugOrBrokenError, "subclasses of `ConfigMergeable` must implement `with_fallback` (#{self.class})"
+  end
+end

data/lib/hocon/config_object.rb

@@ -1,4 +1,147 @@
+# encoding: utf-8
+
 require 'hocon'
+require 'hocon/config_value'
 
+#
+# Subtype of {@link ConfigValue} representing an object (AKA dictionary or map)
+# value, as in JSON's curly brace <code>{ "a" : 42 }</code> 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>
+# <em>Do not implement interface {@code ConfigObject}</em>; 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.
+#
 module Hocon::ConfigObject
-end
+  include Hocon::ConfigValue
+
+    #
+    # Converts this object to a {@link 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).
+    #
+    # @return a {@link Config} with this object as its root
+    #
+    def to_config
+      raise Hocon::ConfigError::ConfigBugOrBrokenError, "subclasses of ConfigObject should provide their own implementation of `to_config` (#{self.class})"
+    end
+
+    #
+    # Recursively unwraps the object, returning a map from String to whatever
+    # plain Java values are unwrapped from the object's values.
+    #
+    # @return a {@link java.util.Map} containing plain Java objects
+    #
+    def unwrapped
+      raise Hocon::ConfigError::ConfigBugOrBrokenError, "subclasses of ConfigObject should provide their own implementation of `unwrapped` (#{self.class})"
+    end
+
+    def with_fallback(other)
+      raise Hocon::ConfigError::ConfigBugOrBrokenError, "subclasses of ConfigObject should provide their own implementation of `with_fallback` (#{self.class})"
+    end
+
+    #
+    # Gets a {@link ConfigValue} at the given key, or returns null if there is
+    # no value. The returned {@link ConfigValue} may have
+    # {@link ConfigValueType#NULL} or any other type, and the passed-in key
+    # must be a key in this object (rather than a path expression).
+    #
+    # @param key
+    #            key to look up
+    #
+    # @return the value at the key or null if none
+    #
+    def get(key)
+      raise Hocon::ConfigError::ConfigBugOrBrokenError, "subclasses of ConfigObject should provide their own implementation of `get` (#{self.class})"
+    end
+
+    #
+    # Clone the object with only the given key (and its children) retained; all
+    # sibling keys are removed.
+    #
+    # @param key
+    #            key to keep
+    # @return a copy of the object minus all keys except the one specified
+    #
+    def with_only_key(key)
+      raise Hocon::ConfigError::ConfigBugOrBrokenError, "subclasses of ConfigObject should provide their own implementation of `with_only_key` (#{self.class})"
+    end
+
+    #
+    # Clone the object with the given key removed.
+    #
+    # @param key
+    #            key to remove
+    # @return a copy of the object minus the specified key
+    #
+    def without_key(key)
+      raise Hocon::ConfigError::ConfigBugOrBrokenError, "subclasses of ConfigObject should provide their own implementation of `without_key` (#{self.class})"
+    end
+
+    #
+    # Returns a {@code 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 {@link ConfigObject#withoutKey(String)}.
+    #
+    # @param key
+    #            key to add
+    # @param value
+    #            value at the new key
+    # @return the new instance with the new map entry
+    #
+    def with_value(key, value)
+      raise Hocon::ConfigError::ConfigBugOrBrokenError, "subclasses of ConfigObject should provide their own implementation of `with_value` (#{self.class})"
+    end
+
+    def with_origin(origin)
+      raise Hocon::ConfigError::ConfigBugOrBrokenError, "subclasses of ConfigObject should provide their own implementation of `with_origin` (#{self.class})"
+    end
+
+end