nugrant 2.0.0.pre1 → 2.0.0.pre2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 9f14bf2a70810293d967c9e9d24b60408880e5b0
-  data.tar.gz: 1d24d5cfa15fde530b4daab7743adb9b29bf74a4
+  metadata.gz: 969a898ed0ac4d45b6adc22f43304d80a61d3eda
+  data.tar.gz: a2f9140bab38bd74f9297cda110572d49c0f8425
 SHA512:
-  metadata.gz: 4ade947b4d55e761d3ec22065b34b680cac998f9544fa98e30a309ce9c65d4f2a76bde76233633e9eb630725c0fc622ea6c8b163332af8401347af8d0dd409d9
-  data.tar.gz: 20d4f38d519f1e15f487d0bdecd6d74246a8b748d4933f98285504587360c24cd5936c111fb85dfb578079abb9a28a47e7f8dccf7b22655510aa77a87a91725b
+  metadata.gz: ba35c594059cb9c04fef4495e55ca55fddbdafe95041335cd6ddec5e4234d6c65150f6418d407fc3d9dad28cff383a7402c369d0c429f3541eed7c00c7ed7dfe
+  data.tar.gz: b5684cd172236eb57add8c9492fc8818b23707f813adbc2c9dc21ce951f5b8c4f949646e208a2acdb510f1ef53ea68ddb4491872f4af96fd530cacf2c38b03e1

data/CHANGELOG.md

@@ -1,5 +1,23 @@
 # 2.0.0 (In progress)
 
+* Added possibility to change array merge strategy. This can
+  be used in Vagrant by doing `config.user.array_merge_strategy = <strategy>`
+  where valid strategies are:
+
+   * :replace => Replace current values by new ones
+   * :extend => Merge current values with new ones
+   * :concat => Append new values to current ones
+
+* Better handling in Vagrant of cases where the vagrant user
+  file cannot be parsed correctly. This is now reported
+  as an error in Vagrant an nicely displayed with the path
+  of the offending file and the parser error message.
+
+* Better handling of how global Nugrant options are passed and
+  handled. Everything is now located in the `Nugrant::Config`
+  object and used by everything that need some configuration
+  parameters.
+
 * It is now possible to customize key error handling by passing
   an options hash with key `:key_error` and a `Proc` value.
 

data/README.md

@@ -126,6 +126,10 @@ In text, this means that current parameters overrides user
 parameters, user parameters overrides system parameters and
 finally system parameters overrides defaults parameters.
 
+When two keys that are merged together points to Array values,
+the default operation is to replace current Array by
+overriding one. The default merge strategy can be customized.
+
 ### Vagrant
 
 All examples shown here are for Vagrant 1.1+. They have
@@ -323,6 +327,36 @@ If the user decides to change it, he just has to set it in his
 own `.vagrantuser` and it will override the default value defined
 in the Vagrantfile.
 
+#### Array merge strategies
+
+As stated previously, when two arrays are merged together,
+the default strategy is to replace current array with new one.
+
+However, in some certain circumstances, you may need another
+behavior. That is why we also provide two other strategies
+that can be used.
+
+ * `:concat`
+   With this strategy, new array is appended to the end
+   of current array when merged. The `Array` `+` operator
+   is used to concatenante the two arrays.
+
+ * `:extend`
+   With this strategy, current array is extended with values
+   from new one. The `Array` `|` (union) operator
+   is used to extend the array.
+
+You can use the following snippet directly within your Vagrantfile
+to change the array merge strategy:
+
+    Vagrant.configure("2") do |config|
+      config.user.array_merge_strategy = :extend
+
+      config.ssh.port config.user.vm.ssh_port
+    end
+
+If you specify an unsupported strategy, nothing will happen.
+
 #### Commands
 
 In this section, we describe the various vagrant commands defined

data/lib/nugrant/bag.rb

@@ -7,49 +7,41 @@ module Nugrant
     # differences with a normal Hash are indifferent access
     # (symbol or string) and method access (via method call).
     #
+    # Hash objects in the map are converted to Bag. This ensure
+    # proper nesting of functionality.
+    #
     # =| Arguments
     #  * `elements`
     #    The initial elements the bag should be built with it.'
     #    Must be an object responding to `each` and accepting
-    #    a block with two arguments: `key, value`.]. Defaults to
+    #    a block with two arguments: `key, value`. Defaults to
     #    the empty hash.
     #
-    #  * `options`
-    #    An options hash where some customization option can be passed.
-    #    Defaults to an empty hash, see options for specific option default
-    #    values.
-    #
-    # =| Options
-    #  * `:key_error`
-    #    A callable object receiving a single parameter `key` that is
-    #    called when a key cannot be found in the Bag. The received key
-    #    is already converted to a symbol. If the callable does not
-    #    raise an exception, the result of it's execution is returned.
-    #    The default value is a callable that throws a KeyError exception.
+    #  * `config`
+    #    A Nugrant::Config object or hash passed to Nugrant::Config
+    #    constructor. Used for `key_error` handler.
     #
-    def initialize(elements = {}, options = {})
+    def initialize(elements = {}, config = {})
       super()
 
-      @__key_error = options[:key_error] || Proc.new do |key|
-        raise KeyError, "Undefined parameter '#{key}'" if not key?(key)
-      end
+      @__config = Config::convert(config)
 
       (elements || {}).each do |key, value|
-        self[key] = value.kind_of?(Hash) ? Bag.new(value, options) : value
+        self[key] = value.kind_of?(Hash) ? Bag.new(value, config) : value
       end
     end
 
     def method_missing(method, *args, &block)
-      return self[method]
+      self[method]
     end
 
     ##
-    ### Hash Overriden Methods (for string & symbol indifferent access)
+    ### Hash Overridden Methods (for string & symbol indifferent access)
     ##
 
     def [](input)
       key = __convert_key(input)
-      return @__key_error.call(key) if not key?(key)
+      return @__config.key_error.call(key) if not key?(key)
 
       super(key)
     end
@@ -63,24 +55,10 @@ module Nugrant
     end
 
     ##
-    # This method first start by converting the `input` parameter
-    # into a bag. It will then *deep* merge current values with
-    # the new ones coming from the `input`.
+    # This method deeply merge two instance together
     #
-    # The array merge strategy is by default to replace current
-    # values with new ones. You can use option `:array_strategy`
-    # to change this default behavior.
     #
-    # +Options+
-    #  * :array_strategy
-    #     * :replace (Default) => Replace current values by new ones
-    #     * :extend => Merge current values with new ones
-    #     * :concat => Append new values to current ones
-    #
-    def merge!(input, options = {})
-      options = {:array_strategy => :replace}.merge(options)
-
-      array_strategy = options[:array_strategy]
+    def merge!(input)
       input.each do |key, value|
         current = __get(key)
         case
@@ -88,10 +66,10 @@ module Nugrant
             self[key] = value
 
           when current.kind_of?(Hash) && value.kind_of?(Hash)
-            current.merge!(value, options)
+            current.merge!(value)
 
           when current.kind_of?(Array) && value.kind_of?(Array)
-            self[key] = send("__#{array_strategy}_array_merge", current, value)
+            self[key] = send("__#{@__config.array_merge_strategy}_array_merge", current, value)
 
           when value != nil
             self[key] = value

data/lib/nugrant/config.rb

@@ -2,10 +2,27 @@ require 'rbconfig'
 
 module Nugrant
   class Config
+    DEFAULT_ARRAY_MERGE_STRATEGY = :replace
     DEFAULT_PARAMS_FILENAME = ".nuparams"
     DEFAULT_PARAMS_FORMAT = :yaml
 
-    attr_reader :params_filename, :params_format, :current_path, :user_path, :system_path
+    SUPPORTED_ARRAY_MERGE_STRATEGIES = [:concat, :extend, :replace]
+    SUPPORTED_PARAMS_FORMATS = [:json, :yaml]
+
+    attr_reader :params_filename, :params_format,
+                :current_path, :user_path, :system_path,
+                :array_merge_strategy,
+                :key_error, :parse_error
+
+    attr_writer :array_merge_strategy
+
+    ##
+    # Convenience method to easily accept either a hash that will
+    # be converted to a Nugrant::Config object or directly a config
+    # object.
+    def self.convert(config = {})
+      return config.kind_of?(Nugrant::Config) ? config : Nugrant::Config.new(config)
+    end
 
     ##
     # Return the fully expanded path of the user parameters
@@ -27,6 +44,14 @@ module Nugrant
       "/etc"
     end
 
+    def self.supported_array_merge_strategy(strategy)
+      SUPPORTED_ARRAY_MERGE_STRATEGIES.include?(strategy)
+    end
+
+    def self.supported_params_format(format)
+      SUPPORTED_PARAMS_FORMATS.include?(format)
+    end
+
     ##
     # Return true if we are currently on a Windows platform.
     #
@@ -64,18 +89,50 @@ module Nugrant
     #                         parameters should resides. The parameters loaded from this
     #                         location have the third highest precedence.
     #                           Defaults => Default system path depending on OS + @params_filename
+    #  * +:array_merge_strategy+  - This option controls how array values are merged together when merging
+    #                               two Bag instances. Possible values are:
+    #                                 * :replace => Replace current values by new ones
+    #                                 * :extend => Merge current values with new ones
+    #                                 * :concat => Append new values to current ones
+    #                                Defaults => The strategy :replace.
+    #  * +:key_error+     - A callback method receiving one argument, the key as a symbol, and that
+    #                       deal with the error. If the callable does not
+    #                       raise an exception, the result of it's execution is returned.
+    #                         Defaults => A callable that throws a KeyError exception.
+    #  * +:parse_error+   - A callback method receiving two arguments, the offending filename and
+    #                       the error object, that deal with the error. If the callable does not
+    #                       raise an exception, the result of it's execution is returned.
+    #                         Defaults => A callable that returns the empty hash.
     #
     def initialize(options = {})
       @params_filename = options[:params_filename] || DEFAULT_PARAMS_FILENAME
       @params_format = options[:params_format] || DEFAULT_PARAMS_FORMAT
 
-      raise ArgumentError,
-        "Invalid value for :params_format. \
-        The format [#{@params_format}] is currently not supported." if not [:json, :yaml].include?(@params_format)
-
       @current_path = File.expand_path(options[:current_path] || "./#{@params_filename}")
       @user_path = File.expand_path(options[:user_path] || "#{Config.default_user_path()}/#{@params_filename}")
       @system_path = File.expand_path(options[:system_path] || "#{Config.default_system_path()}/#{@params_filename}")
+
+      @array_merge_strategy = options[:array_merge_strategy] || :replace
+
+      @key_error = options[:key_error] || Proc.new do |key|
+        raise KeyError, "Undefined parameter '#{key}'"
+      end
+
+      @parse_error = options[:parse_error] || Proc.new do |filename, error|
+        {}
+      end
+
+      validate()
+    end
+
+    def validate()
+      raise ArgumentError,
+        "Invalid value for :params_format. \
+         The format [#{@params_format}] is currently not supported." if not Config.supported_params_format(@params_format)
+
+      raise ArgumentError,
+          "Invalid value for :array_merge_strategy. \
+           The array merge strategy [#{@array_merge_strategy}] is currently not supported." if not Config.supported_array_merge_strategy(@array_merge_strategy)
     end
   end
 end

data/lib/nugrant/helper/bag.rb

@@ -6,26 +6,24 @@ require 'nugrant/bag'
 module Nugrant
   module Helper
     module Bag
-      def self.read(filepath, filetype, options = {})
-        data = parse_data(filepath, filetype, options)
-
-        return Nugrant::Bag.new(data, options)
+      def self.read(filepath, filetype, config)
+        Nugrant::Bag.new(parse_data(filepath, filetype, config), config)
       end
 
       def self.restricted_keys()
         Nugrant::Bag.instance_methods()
       end
 
-      def self.parse_data(filepath, filetype, options = {})
+      private
+
+      def self.parse_data(filepath, filetype, config)
         return if not File.exists?(filepath)
 
         File.open(filepath, "rb") do |file|
           return send("parse_#{filetype}", file)
         end
       rescue => error
-        if options[:error_handler]
-          options[:error_handler].handle("Could not parse the user #{filetype} parameters file '#{filepath}': #{error}")
-        end
+        config.parse_error.call(filepath, error)
       end
 
       def self.parse_json(io)

data/lib/nugrant/mixin/parameters.rb

@@ -29,6 +29,19 @@ module Nugrant
         @__defaults
       end
 
+      def array_merge_strategy
+        @__config.array_merge_strategy
+      end
+
+      def array_merge_strategy=(strategy)
+        return if not Nugrant::Config.supported_array_merge_strategy(strategy)
+
+        @__config.array_merge_strategy = strategy
+
+        # When array_merge_strategy change, we need to recompute parameters hierarchy
+        compute_all!()
+      end
+
       ##
       # Set the new default values for the
       # various parameters contain by this instance.
@@ -39,46 +52,44 @@ module Nugrant
       #  * +elements+ - The new default elements
       #
       def defaults=(elements)
-        @__defaults = Bag.new(elements, @__options)
+        @__defaults = Bag.new(elements, @__config)
 
         # When defaults change, we need to recompute parameters hierarchy
-        compute_all!(@__options)
+        compute_all!()
       end
 
       ##
-      # Compute all parameters bags (current, user, system, default and all).
+      # Setup instance variables of the mixin. It will compute all parameters bags
+      # (current, user, system, default and all) and stored them to these respective
+      # instance variables:
       #
-      # =| Arguments
-      #  * `config`
-      #    The configuration object used to determine where to find the various
-      #    bag source data. This can be either directly a `Nugrant::Config`
-      #    object or a hash that will be pass to `Nugrant::Config` constructor.
-      #
-      #  * `options`
-      #    An options hash where some customization option can be passed.
-      #    Defaults to an empty hash, see options for specific option default
-      #    values.
+      #  * @__current
+      #  * @__user
+      #  * @__system
+      #  * @__defaults
       #
-      # =| Options
-      #  * `:defaults`
+      # =| Arguments
+      #  * `defaults`
       #    A hash that is used as the initial data for the defaults bag. Defaults
       #    to an empty hash.
       #
-      #  * `:key_error`
-      #    This option is passed to Bag.new constructor in it's options hash. See
-      #    Bag.new for details on this options.
+      #  * `config`
+      #    A Nugrant::Config object or hash passed to Nugrant::Config
+      #    constructor. Used to determine where to find the various
+      #    bag data sources.
       #
-      def compute_bags!(config, options = {})
-        config = config.kind_of?(Nugrant::Config) ? config : Nugrant::Config.new(config)
-
-        @__options = options
+      #    Passed to nested structures that require nugrant configuration
+      #    parameters like the Bag object and Helper::Bag module.
+      #
+      def setup!(defaults = {}, config = {})
+        @__config = Nugrant::Config::convert(config);
 
-        @__current = Helper::Bag.read(config.current_path, config.params_format, options)
-        @__user = Helper::Bag.read(config.user_path, config.params_format, options)
-        @__system = Helper::Bag.read(config.system_path, config.params_format, options)
-        @__defaults = Bag.new(options[:defaults] || {}, options)
+        @__current = Helper::Bag.read(@__config.current_path, @__config.params_format, @__config)
+        @__user = Helper::Bag.read(@__config.user_path, @__config.params_format, @__config)
+        @__system = Helper::Bag.read(@__config.system_path, @__config.params_format, @__config)
+        @__defaults = Bag.new(defaults, @__config)
 
-        compute_all!(options)
+        compute_all!()
       end
 
       ##
@@ -86,8 +97,8 @@ module Nugrant
       # bag in the right order and return the result as a Nugrant::Bag
       # object.
       #
-      def compute_all!(options = {})
-        @__all = Bag.new({}, options)
+      def compute_all!()
+        @__all = Bag.new({}, @__config)
         @__all.merge!(@__defaults)
         @__all.merge!(@__system)
         @__all.merge!(@__user)

data/lib/nugrant/parameters.rb

@@ -15,17 +15,11 @@ module Nugrant
     #
     # =| Arguments
     #  * `config`
-    #    A hash that will be passed to Nugrant::Config.new() or
-    #    a Nugrant::Config instance directly.
-    #    See Nugrant::Config constructor for options that you can use.
+    #    Passed to Mixin::Parameters setup! method. See method
+    #    for further information.
     #
-    #  * `options`
-    #    An options hash that is passed to Mixin::Parameters.compute_bags! method.
-    #    See Mixin::Parameters.compute_bags! for details on the various options
-    #    available.
-    #
-    def initialize(config, options = {})
-      compute_bags!(config, options)
+    def initialize(config)
+      setup!({}, config)
     end
 
     include Mixin::Parameters

data/lib/nugrant/vagrant/errors.rb

@@ -7,6 +7,12 @@ module Nugrant
     module Errors
       class NugrantVagrantError < ::Vagrant::Errors::VagrantError
         error_namespace("nugrant.vagrant.errors")
+
+        def compute_context()
+          Helper::Stack.fetch_error_region(caller(), {
+            :matcher => /(.+Vagrantfile):([0-9]+)/
+          })
+        end
       end
 
       class ParameterNotFoundError < NugrantVagrantError
@@ -15,11 +21,13 @@ module Nugrant
         def initialize(options = nil, *args)
           super({:context => compute_context()}.merge(options || {}), *args)
         end
+      end
 
-        def compute_context()
-          Helper::Stack.fetch_error_region(caller(), {
-            :matcher => /(.+Vagrantfile):([0-9]+)/
-          })
+      class VagrantUserParseError < NugrantVagrantError
+        error_key(:parse_error)
+
+        def initialize(options = nil, *args)
+          super(options, *args)
         end
       end
     end

data/lib/nugrant/vagrant/v2/config/user.rb

@@ -10,11 +10,15 @@ module Nugrant
           attr_reader :__current, :__user, :__system, :__defaults, :__all
 
           def initialize()
-            compute_bags!({:params_filename => ".vagrantuser"}, options = {
+            setup!({},
+              :params_filename => ".vagrantuser",
               :key_error => Proc.new do |key|
                 raise Errors::ParameterNotFoundError, :key => key.to_s
+              end,
+              :parse_error => Proc.new do |filename, error|
+                raise Errors::VagrantUserParseError, :filename => filename.to_s, :error => error
               end
-            })
+            )
           end
 
           include Mixin::Parameters

data/lib/nugrant/version.rb

@@ -1,3 +1,3 @@
 module Nugrant
-  VERSION = "2.0.0.pre1"
+  VERSION = "2.0.0.pre2"
 end

data/locales/en.yml

@@ -11,3 +11,14 @@ en:
 
           If you think it should be found, don't hesitate to fill an
           issue @ https://github.com/maoueh/nugrant/issues.
+
+        parse_error: |-
+          Nugrant: Vagrant user file could not be parsed correctly,
+          the file is probably in an invalid state.
+
+           File: %{filename}
+           Error: %{error}
+
+          If you think this is an error, don't hesitate to fill an
+          issue @ https://github.com/maoueh/nugrant/issues.
+

data/test/lib/nugrant/test_bag.rb

@@ -131,33 +131,33 @@ module Nugrant
     end
 
     def test_merge_array_extend()
-      bag1 = create_bag({"first" => [1, 2]})
+      bag1 = create_bag({"first" => [1, 2]}, :array_merge_strategy => :extend)
       bag2 = create_bag({:first => [2, 3]})
 
-      bag1.merge!(bag2, :array_strategy => :extend);
+      bag1.merge!(bag2);
 
       assert_equal({:first => [1, 2, 3]}, bag1.to_hash())
 
-      bag1 = create_bag({"first" => [1, 2]})
+      bag1 = create_bag({"first" => [1, 2]}, :array_merge_strategy => :extend)
       bag2 = create_bag({:first => "string"})
 
-      bag1.merge!(bag2, :array_strategy => :extend);
+      bag1.merge!(bag2);
 
       assert_equal({:first => "string"}, bag1.to_hash())
     end
 
     def test_merge_array_concat()
-      bag1 = create_bag({"first" => [1, 2]})
+      bag1 = create_bag({"first" => [1, 2]}, :array_merge_strategy => :concat)
       bag2 = create_bag({:first => [2, 3]})
 
-      bag1.merge!(bag2, :array_strategy => :concat);
+      bag1.merge!(bag2);
 
       assert_equal({:first => [1, 2, 2, 3]}, bag1.to_hash())
 
-      bag1 = create_bag({"first" => [1, 2]})
+      bag1 = create_bag({"first" => [1, 2]}, :array_merge_strategy => :concat)
       bag2 = create_bag({:first => "string"})
 
-      bag1.merge!(bag2, :array_strategy => :concat);
+      bag1.merge!(bag2);
 
       assert_equal({:first => "string"}, bag1.to_hash())
     end

data/test/resources/README.md

@@ -1,7 +1,7 @@
 This readme give information on how to read resources file
 that test merge possibilities.
 
-Naming convetions
+Naming conventions
 -----------------
 
 The filename uses a specific convention:
@@ -9,7 +9,7 @@ The filename uses a specific convention:
     params_*kind*_*level*.[yml|json]
 
 The kind is one of: [`current`|`user`|`system`] and defines which
-responsability they will hold. The order is `current` overrides
+responsibility they will hold. The order is `current` overrides
 `user` overrides `system`.
 
 Inside file, keys have special meaning. They define how

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: nugrant
 version: !ruby/object:Gem::Version
-  version: 2.0.0.pre1
+  version: 2.0.0.pre2
 platform: ruby
 authors:
 - Matthieu Vachon
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-04-18 00:00:00.000000000 Z
+date: 2014-04-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: insensitive_hash