hocon 0.0.7 → 0.1.0

data/lib/hocon/config_parse_options.rb

@@ -1,3 +1,5 @@
+# encoding: utf-8
+
 require 'hocon'
 
 class Hocon::ConfigParseOptions
@@ -14,11 +16,7 @@ class Hocon::ConfigParseOptions
     @includer = includer
   end
 
-  def allow_missing?
-    @allow_missing
-  end
-
-  def with_syntax(syntax)
+  def set_syntax(syntax)
     if @syntax == syntax
       self
     else
@@ -29,7 +27,33 @@ class Hocon::ConfigParseOptions
     end
   end
 
-  def with_includer(includer)
+  def set_origin_description(origin_description)
+    if @origin_description == origin_description
+      self
+    else
+      Hocon::ConfigParseOptions.new(@syntax,
+                                    origin_description,
+                                    @allow_missing,
+                                    @includer)
+    end
+  end
+
+  def set_allow_missing(allow_missing)
+    if allow_missing? == allow_missing
+      self
+    else
+      Hocon::ConfigParseOptions.new(@syntax,
+                                    @origin_description,
+                                    allow_missing,
+                                    @includer)
+    end
+  end
+
+  def allow_missing?
+    @allow_missing
+  end
+
+  def set_includer(includer)
     if @includer == includer
       self
     else
@@ -44,10 +68,10 @@ class Hocon::ConfigParseOptions
     if @includer == includer
       self
     elsif @includer
-      with_includer(@includer.with_fallback(includer))
+      set_includer(@includer.with_fallback(includer))
     else
-      with_includer(includer)
+      set_includer(includer)
     end
   end
 
-end
+end

data/lib/hocon/config_parseable.rb

@@ -0,0 +1,51 @@
+# encoding: utf-8
+
+require 'hocon'
+require 'hocon/config_error'
+
+#
+# An opaque handle to something that can be parsed, obtained from
+# {@link ConfigIncludeContext}.
+#
+# <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::ConfigParseable
+  #
+  # Parse whatever it is. The options should come from
+  # {@link ConfigParseable#options options()} but you could tweak them if you
+  # like.
+  #
+  # @param options
+  #            parse options, should be based on the ones from
+  #            {@link ConfigParseable#options options()}
+  # @return the parsed object
+  #
+  def parse(options)
+    raise Hocon::ConfigError::ConfigBugOrBrokenError, "subclasses of `ConfigParseable` must implement `parse` (#{self.class})"
+  end
+
+  #
+  # Returns a {@link ConfigOrigin} describing the origin of the parseable
+  # item.
+  # @return the origin of the parseable item
+  #
+  def origin
+    raise Hocon::ConfigError::ConfigBugOrBrokenError, "subclasses of `ConfigParseable` must implement `origin` (#{self.class})"
+  end
+
+  #
+  # Get the initial options, which can be modified then passed to parse().
+  # These options will have the right description, includer, and other
+  # parameters already set up.
+  # @return the initial options
+  #
+  def options
+    raise Hocon::ConfigError::ConfigBugOrBrokenError, "subclasses of `ConfigParseable` must implement `options` (#{self.class})"
+  end
+
+end

data/lib/hocon/config_render_options.rb

@@ -1,3 +1,5 @@
+# encoding: utf-8
+
 require 'hocon'
 
 class Hocon::ConfigRenderOptions
@@ -8,7 +10,7 @@ class Hocon::ConfigRenderOptions
     @json = json
   end
 
-  attr_writer :origin_comments, :comments, :formatted, :json
+  attr_accessor :origin_comments, :comments, :formatted, :json
 
   def origin_comments?
     @origin_comments
@@ -43,4 +45,4 @@ class Hocon::ConfigRenderOptions
   def self.concise
     Hocon::ConfigRenderOptions.new(false, false, false, true)
   end
-end
+end

data/lib/hocon/config_resolve_options.rb

@@ -0,0 +1,31 @@
+# encoding: utf-8
+
+require 'hocon'
+
+class Hocon::ConfigResolveOptions
+  attr_reader :use_system_environment, :allow_unresolved
+
+  def initialize(use_system_environment, allow_unresolved)
+    @use_system_environment = use_system_environment
+    @allow_unresolved = allow_unresolved
+  end
+
+  def set_use_system_environment(value)
+    self.class.new(value, @allow_unresolved)
+  end
+
+  def set_allow_unresolved(value)
+    self.class.new(@use_system_environment, value)
+  end
+
+  class << self
+
+    def defaults
+      self.new(true, false)
+    end
+
+    def no_system
+      defaults.set_use_system_environment(false)
+    end
+  end
+end

data/lib/hocon/config_syntax.rb

@@ -1,7 +1,10 @@
+# encoding: utf-8
+
 require 'hocon'
 
 module Hocon::ConfigSyntax
   JSON = 0
   CONF = 1
-  PROPERTIES = 2
-end
+  # we're not going to try to support .properties files any time soon :)
+  #PROPERTIES = 2
+end

data/lib/hocon/config_util.rb

@@ -0,0 +1,73 @@
+require 'hocon/impl/config_impl_util'
+
+
+# Contains static utility methods
+class Hocon::ConfigUtil
+  #
+  # Quotes and escapes a string, as in the JSON specification.
+  #
+  # @param string
+  #            a string
+  # @return the string quoted and escaped
+  #
+  def self.quote_string(string)
+    Hocon::Impl::ConfigImplUtil.render_json_string(string)
+  end
+
+  #
+  # Converts a list of keys to a path expression, by quoting the path
+  # elements as needed and then joining them separated by a period. A path
+  # expression is usable with a {@link Config}, while individual path
+  # elements are usable with a {@link ConfigObject}.
+  # <p>
+  # See the overview documentation for {@link Config} for more detail on path
+  # expressions vs. keys.
+  #
+  # @param elements
+  #            the keys in the path
+  # @return a path expression
+  # @throws ConfigException
+  #             if there are no elements
+  #
+  def self.join_path(*elements)
+    Hocon::Impl::ConfigImplUtil.join_path(*elements)
+  end
+
+  #
+  # Converts a list of strings to a path expression, by quoting the path
+  # elements as needed and then joining them separated by a period. A path
+  # expression is usable with a {@link Config}, while individual path
+  # elements are usable with a {@link ConfigObject}.
+  # <p>
+  # See the overview documentation for {@link Config} for more detail on path
+  # expressions vs. keys.
+  #
+  # @param elements
+  #            the keys in the path
+  # @return a path expression
+  # @throws ConfigException
+  #             if the list is empty
+  #
+  def self.join_path_from_list(elements)
+    self.join_path(*elements)
+  end
+
+  #
+  # Converts a path expression into a list of keys, by splitting on period
+  # and unquoting the individual path elements. A path expression is usable
+  # with a {@link Config}, while individual path elements are usable with a
+  # {@link ConfigObject}.
+  # <p>
+  # See the overview documentation for {@link Config} for more detail on path
+  # expressions vs. keys.
+  #
+  # @param path
+  #            a path expression
+  # @return the individual keys in the path
+  # @throws ConfigException
+  #             if the path expression is invalid
+  #
+  def self.split_path(path)
+    Hocon::Impl::ConfigImplUtil.split_path(path)
+  end
+end

data/lib/hocon/config_value.rb

@@ -0,0 +1,122 @@
+# encoding: utf-8
+
+require 'hocon'
+require 'hocon/config_mergeable'
+
+#
+# An immutable value, following the <a href="http://json.org">JSON</a> type
+# schema.
+#
+# <p>
+# Because this object is immutable, it is safe to use from multiple threads and
+# there's no need for "defensive copies."
+#
+# <p>
+# <em>Do not implement interface {@code ConfigValue}</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::ConfigValue
+  include Hocon::ConfigMergeable
+
+  #
+  # The origin of the value (file, line number, etc.), for debugging and
+  # error messages.
+  #
+  # @return where the value came from
+  #
+  def origin
+    raise Hocon::ConfigError::ConfigBugOrBrokenError, "subclasses of `ConfigValue` must implement `origin` (#{self.class})"
+  end
+
+
+  #
+  # The {@link ConfigValueType} of the value; matches the JSON type schema.
+  #
+  # @return value's type
+  #
+  def value_type
+    raise Hocon::ConfigError::ConfigBugOrBrokenError, "subclasses of `ConfigValue` must implement `value_type` (#{self.class})"
+  end
+
+  #
+  # Returns the value as a plain Java boxed value, that is, a {@code String},
+  # {@code Number}, {@code Boolean}, {@code Map<String,Object>},
+  # {@code List<Object>}, or {@code null}, matching the {@link #valueType()}
+  # of this {@code ConfigValue}. If the value is a {@link ConfigObject} or
+  # {@link ConfigList}, it is recursively unwrapped.
+  # @return a plain Java value corresponding to this ConfigValue
+  #
+  def unwrapped
+    raise Hocon::ConfigError::ConfigBugOrBrokenError, "subclasses of `ConfigValue` must implement `unwrapped` (#{self.class})"
+  end
+
+  #
+  # Renders the config value to a string, using the provided options.
+  #
+  # <p>
+  # If the config value has not been resolved (see {@link Config#resolve}),
+  # it's possible that it can't be rendered as valid HOCON. In that case the
+  # rendering should still be useful for debugging but you might not be able
+  # to parse it. If the value has been resolved, it will always be parseable.
+  #
+  # <p>
+  # If the config value has been resolved and the options disable all
+  # HOCON-specific features (such as comments), the rendering will be valid
+  # JSON. If you enable HOCON-only features such as comments, the rendering
+  # will not be valid JSON.
+  #
+  # @param options
+  #            the rendering options
+  # @return the rendered value
+  #
+  def render(options)
+    raise Hocon::ConfigError::ConfigBugOrBrokenError, "subclasses of `ConfigValue` must implement `render` (#{self.class})"
+  end
+
+  def with_fallback(other)
+    raise Hocon::ConfigError::ConfigBugOrBrokenError, "subclasses of `ConfigValue` must implement `with_fallback` (#{self.class})"
+  end
+
+  #
+  # Places the value inside a {@link Config} at the given path. See also
+  # {@link ConfigValue#atKey(String)}.
+  #
+  # @param path
+  #            path to store this value at.
+  # @return a {@code Config} instance containing this value at the given
+  #         path.
+  #
+  def at_path(path)
+    raise Hocon::ConfigError::ConfigBugOrBrokenError, "subclasses of `ConfigValue` must implement `at_path` (#{self.class})"
+  end
+
+  #
+  # Places the value inside a {@link Config} at the given key. See also
+  # {@link ConfigValue#atPath(String)}.
+  #
+  # @param key
+  #            key to store this value at.
+  # @return a {@code Config} instance containing this value at the given key.
+  #
+  def at_key(key)
+    raise Hocon::ConfigError::ConfigBugOrBrokenError, "subclasses of `ConfigValue` must implement `at_key` (#{self.class})"
+  end
+
+  #
+  # Returns a {@code ConfigValue} based on this one, but with the given
+  # origin. This is useful when you are parsing a new format of file or setting
+  # comments for a single ConfigValue.
+  #
+  # @since 1.3.0
+  #
+  # @param origin the origin set on the returned value
+  # @return the new ConfigValue with the given origin
+  #
+  def with_origin(origin)
+    raise Hocon::ConfigError::ConfigBugOrBrokenError, "subclasses of `ConfigValue` must implement `with_origin` (#{self.class})"
+  end
+
+end

data/lib/hocon/config_value_factory.rb

@@ -1,10 +1,74 @@
+# encoding: utf-8
+
 require 'hocon'
 require 'hocon/impl/config_impl'
 
 class Hocon::ConfigValueFactory
   ConfigImpl = Hocon::Impl::ConfigImpl
 
-  def self.from_any_ref(object, origin_description)
+  #
+  # Creates a {@link ConfigValue} from a plain value, which may be
+  # a <code>Boolean</code>, <code>Number</code>, <code>String</code>,
+  # <code>Hash</code>, or <code>nil</code>. A
+  # <code>Hash</code> must be a <code>Hash</code> from String to more values
+  # that can be supplied to <code>from_any_ref()</code>. A <code>Hash</code>
+  # will become a {@link ConfigObject} and an <code>Array</code> will become a
+  # {@link ConfigList}.
+  #
+  # <p>
+  # In a <code>Hash</code> passed to <code>from_any_ref()</code>, the map's keys
+  # are plain keys, not path expressions. So if your <code>Hash</code> has a
+  # key "foo.bar" then you will get one object with a key called "foo.bar",
+  # rather than an object with a key "foo" containing another object with a
+  # key "bar".
+  #
+  # <p>
+  # The origin_description will be used to set the origin() field on the
+  # ConfigValue. It should normally be the name of the file the values came
+  # from, or something short describing the value such as "default settings".
+  # The origin_description is prefixed to error messages so users can tell
+  # where problematic values are coming from.
+  #
+  # <p>
+  # Supplying the result of ConfigValue.unwrapped() to this function is
+  # guaranteed to work and should give you back a ConfigValue that matches
+  # the one you unwrapped. The re-wrapped ConfigValue will lose some
+  # information that was present in the original such as its origin, but it
+  # will have matching values.
+  #
+  # <p>
+  # If you pass in a <code>ConfigValue</code> to this
+  # function, it will be returned unmodified. (The
+  # <code>origin_description</code> will be ignored in this
+  # case.)
+  #
+  # <p>
+  # This function throws if you supply a value that cannot be converted to a
+  # ConfigValue, but supplying such a value is a bug in your program, so you
+  # should never handle the exception. Just fix your program (or report a bug
+  # against this library).
+  #
+  # @param object
+  #            object to convert to ConfigValue
+  # @param origin_description
+  #            name of origin file or brief description of what the value is
+  # @return a new value
+  #
+  def self.from_any_ref(object, origin_description = nil)
     ConfigImpl.from_any_ref(object, origin_description)
   end
-end
+
+  #
+  # See the {@link #from_any_ref(Object,String)} documentation for details
+  #
+  # <p>
+  # See also {@link ConfigFactory#parse_map(Map)} which interprets the keys in
+  # the map as path expressions.
+  #
+  # @param values map from keys to plain ruby values
+  # @return a new {@link ConfigObject}
+  #
+  def self.from_map(values, origin_description = nil)
+    ConfigImpl.from_any_ref(values, origin_description)
+  end
+end