ns-options 0.4.1 → 1.0.0.rc1

data/Rakefile

@@ -2,4 +2,4 @@
 require "bundler/gem_tasks"
 
 require 'assert/rake_tasks'
-Assert::RakeTasks.for :test
+Assert::RakeTasks.install

data/lib/ns-options/assert_macros.rb

@@ -1,13 +1,12 @@
-module NsOptions; end
+require 'ns-options'
+
 module NsOptions::AssertMacros
 
   # a set of Assert macros to help write namespace definition and
   # regression tests in Assert (https://github.com/teaminsight/assert)
 
   def self.included(receiver)
-    receiver.class_eval do
-      extend MacroMethods
-    end
+    receiver.class_eval { extend MacroMethods }
   end
 
   module MacroMethods
@@ -19,8 +18,7 @@ module NsOptions::AssertMacros
       Assert::Macro.new(macro_name) do
         namespaces.each do |ns|
           should "have a namespace named '#{ns}'", called_from do
-            assert_respond_to ns, subject
-            assert_kind_of NsOptions::Namespace, subject.send(ns)
+            assert subject.has_namespace?(ns)
           end
         end
       end
@@ -34,8 +32,7 @@ module NsOptions::AssertMacros
       Assert::Macro.new(macro_name) do
         options.each do |opt|
           should "have an option named '#{opt}'", called_from do
-            assert_respond_to opt, subject
-            assert_kind_of NsOptions::Option, subject.options[opt]
+            assert subject.has_option?(opt)
           end
         end
       end
@@ -43,7 +40,7 @@ module NsOptions::AssertMacros
 
     def have_option(*args)
       called_from = caller.first
-      rules, type_class, opt_name = NsOptions::Option.args(*args)
+      opt_name, type_class, rules = NsOptions::Option.args(args)
       test_name = [
         "have an option: '#{opt_name}'",
         "of type '#{type_class}'",
@@ -53,10 +50,10 @@ module NsOptions::AssertMacros
       Assert::Macro.new(test_name) do
 
         should test_name do
-          # name assertions
-          assert_respond_to opt_name, subject
 
-          opt = subject.options[opt_name]
+          # have assertions
+          assert subject.has_option?(opt_name)
+          opt = subject.__data__.child_options[opt_name]
           assert_kind_of NsOptions::Option, opt
 
           # type_class assertions

data/lib/ns-options/boolean.rb

@@ -1,3 +1,5 @@
+require 'ns-options'
+
 module NsOptions
   class Boolean
 

data/lib/ns-options/namespace.rb

@@ -1,119 +1,54 @@
+require 'ns-options/namespace_data'
+require 'ns-options/namespace_advisor'
+
 module NsOptions
 
   class Namespace
-    attr_accessor :options, :metaclass
 
-    # Every namespace tracks a metaclass to allow for individual reader/writers for their options,
-    # without any collisions. Since every namespace is of the same class, defining option reader and
-    # writer methods directly on the class would make multiple namespaces with different options
-    # impossible.
-    def initialize(key, parent = nil, &block)
-      self.metaclass = (class << self; self; end)
-      self.options = NsOptions::Options.new(key, parent)
-      self.define(&block)
-    end
+    attr_reader :__name__, :__data__
 
-    # This is a helper to check if options that were defined as :required have been set.
-    def required_set?
-      self.options.required_set?
+    def initialize(name, option_type_class=nil, &block)
+      @__name__ = name
+      @__data__ = NamespaceData.new(self, option_type_class || Object)
+      @__data__.define(&block)
     end
-    alias :valid? :required_set?
 
-    # Define an option for this namespace. Add the option to the namespace's options collection
-    # and then define accessors for the option. With the following:
-    #
-    # namespace.option(:root, String, { :some_option => true })
-    #
-    # you will get accessors for root:
-    #
-    # namespace.root = "something"      # set's the root option to 'something'
-    # namespace.root                    # => "something"
-    # namespace.root("something else")  # set's the root option to `something-else`
-    #
-    # The defined option is returned as well.
-    def option(*args)
-      NsOptions::Helper.advisor(self).is_this_option_ok?(args[0], caller)
-      option = self.options.add(*args)
-      NsOptions::Helper.define_option_methods(self, option)
-      option
+    def option(name, *args)
+      NamespaceAdvisor.new(@__data__, name, 'an option').run($stdout, caller)
+      @__data__.add_option(name, *args)
     end
     alias_method :opt, :option
 
-    # Define a namespace under this namespace. Firstly, a new key is constructured from this current
-    # namespace's key and the name for the new namespace. The namespace is then added to the
-    # options collection. Finally a reader method is defined for accessing the namespace. With the
-    # following:
-    #
-    # parent_namespace.namespace(:specific) do
-    #   option :root
-    # end
-    #
-    # you will get a reader for the namespace:
-    #
-    # parent_namespace.specific                     # => returns the namespace
-    # parent_namespace.specific.root = "something"  # => options are accessed in the same way
-    #
-    # The defined namespaces is returned as well.
-    def namespace(name, key = nil, &block)
-      key = "#{self.options.key}:#{(key || name)}"
-      NsOptions::Helper.advisor(self).is_this_sub_namespace_ok?(name, caller)
-      namespace = self.options.add_namespace(name, key, self, &block)
-      NsOptions::Helper.define_namespace_methods(self, name)
-      namespace
+    def namespace(name, *args, &block)
+      NamespaceAdvisor.new(@__data__, name, 'a namespace').run($stdout, caller)
+      @__data__.add_namespace(name, *args, &block)
     end
     alias_method :ns, :namespace
 
-    # The opposite of #to_hash. Takes a hash representation of options and namespaces and mass
-    # assigns option values.
-    def apply(option_values = {})
-      option_values.each do |name, value|
-        namespace = self.options.namespaces[name]
-        if self.options[name] || !namespace
-          self.send("#{name}=", value)
-        elsif namespace && value.kind_of?(Hash)
-          namespace.apply(value)
-        end
-      end
+    def option_type_class(*args)
+      return @__data__.option_type_class if args.empty?
+      @__data__.set_option_type_class(*args)
     end
+    alias_method :opt_type_class, :option_type_class
 
-    # return a hash representation of the namespace
-    # use symbols for the hash
-    def to_hash
-      Hash.new.tap do |out|
-        self.options.each do |name, opt|
-          out[name.to_sym] = opt.value
-        end
-        self.options.namespaces.each do |name, value|
-          out[name.to_sym] = value.to_hash
-        end
-      end
-    end
+    def has_option?(name);    @__data__.has_option?(name);    end
+    def has_namespace?(name); @__data__.has_namespace?(name); end
+    def required_set?;        @__data__.required_set?;        end
+    alias_method :valid?, :required_set?
+
+    def define(*args, &block);  @__data__.define(*args, &block);         end
+    def build_from(other_ns);   @__data__.build_from(other_ns.__data__); end
+    def reset(*args, &block);   @__data__.reset(*args, &block);          end
+    def apply(*args, &block);   @__data__.apply(*args, &block);          end
+    def to_hash(*args, &block); @__data__.to_hash(*args, &block);        end
+    def each(*args, &block);    @__data__.each(*args, &block);           end
 
-    # allow for iterating over the key/values of a namespace
-    # this uses #to_hash so you won't get option/namespace objs for the values
-    def each
-      self.to_hash.each { |k,v| yield k,v if block_given? }
+    def respond_to?(meth)
+      @__data__.ns_respond_to?(meth) || super
     end
 
-    # The define method is provided for convenience and commonization. The internal system
-    # uses it to commonly use a block with a namespace. The method can be used externally when
-    # a namespace is created separately from where options are added/set on it. For example:
-    #
-    # parent_namespace.namespace(:specific)
-    #
-    # parent_namespace.specific.define do
-    #   option :root
-    # end
-    #
-    # Will define a new namespace under the parent namespace and then will later on add options to
-    # it.
-    def define(&block)
-      if block && block.arity > 0
-        yield self
-      elsif block
-        self.instance_eval(&block)
-      end
-      self
+    def method_missing(meth, *args, &block)
+      @__data__.ns_method_missing(caller, meth, *args, &block)
     end
 
     def ==(other_ns)
@@ -124,43 +59,8 @@ module NsOptions
       end
     end
 
-    # There are a number of cases we want to watch for:
-    # 1. A reader of a 'known' option. This case is for an option that's been defined for an
-    #    ancestor of this namespace but not directly for this namespace. In this case we fetch
-    #    the options definition and use it to define the option directly for this namespace.
-    # 2. TODO
-    # 3. A writer of a 'known' option. This case is similar to the above, but instead we are
-    #    wanting to write a value. We need to fetch the option definition, define it and then
-    #    we write the option as we normally would.
-    # 4. A dynamic writer. The option is not 'known' to the namespace, so we use the value and it's
-    #    class to define the option for this namespace. Then we just use the writer as we normally
-    #    would.
-    def method_missing(method, *args, &block)
-      option_name = method.to_s.gsub("=", "")
-      value = args.size == 1 ? args[0] : args
-      if args.empty? && self.respond_to?(option_name)
-        option = NsOptions::Helper.find_and_define_option(self, option_name)
-        self.send(option.name)
-      elsif args.empty? && (namespace = self.options.get_namespace(option_name))
-        NsOptions::Helper.find_and_define_namespace(self, option_name)
-        self.send(option_name)
-      elsif !args.empty? && self.respond_to?(option_name)
-        option = NsOptions::Helper.find_and_define_option(self, option_name)
-        self.send("#{option.name}=", value)
-      elsif !args.empty?
-        option = self.option(option_name)
-        self.send("#{option.name}=", value)
-      else
-        super
-      end
-    end
-
-    def respond_to?(method)
-      super || self.options.is_defined?(method.to_s.gsub("=", ""))
-    end
-
     def inspect(*args)
-      "#<#{self.class}:#{'0x%x' % (self.object_id << 1)}:#{self.options.key} #{self.to_hash.inspect}>"
+      "#<#{self.class}:#{'0x%x' % (self.object_id << 1)}:#{@__name__} #{to_hash.inspect}>"
     end
 
   end

data/lib/ns-options/namespace_advisor.rb

@@ -0,0 +1,35 @@
+module NsOptions
+
+  class NamespaceAdvisor
+
+    def initialize(ns_data, name, kind)
+      @ns_data = ns_data
+      @name = name
+
+      @msg = if not_recommended?
+        "WARNING: Defining #{kind} with the name `#{@name}' overwrites a method"\
+        " NsOptions depends on.  It may cause NsOptions to behave oddly and"\
+        " is not recommended."
+      elsif duplicate?
+        "WARNING: `#{@name}' has already been defined and is being overwritten."
+      end
+    end
+
+    def run(io, from_caller)
+      return true if @msg.nil?
+
+      io.puts @msg
+      io.puts from_caller.first
+      false
+    end
+
+    def not_recommended?; not_recommended_names.include?(@name.to_sym); end
+    def duplicate?; @ns_data.has_option?(@name) || @ns_data.has_namespace?(@name); end
+
+    def not_recommended_names
+      NsOptions::Namespace.instance_methods(false).map(&:to_sym)
+    end
+
+  end
+
+end

data/lib/ns-options/namespace_data.rb

@@ -0,0 +1,166 @@
+require 'ns-options/options'
+require 'ns-options/namespaces'
+
+module NsOptions
+
+  class NamespaceData
+
+    attr_reader :ns, :option_type_class, :child_options, :child_namespaces
+
+    def initialize(ns, option_type_class)
+      @ns, @option_type_class = ns, option_type_class
+      @child_namespaces       = NsOptions::Namespaces.new
+      @child_options          = NsOptions::Options.new
+    end
+
+    # Recursively check if options that were defined as :required have been set.
+    def required_set?
+      @child_options.required_set? && @child_namespaces.required_set?
+    end
+
+    def set_option_type_class(value)
+      @option_type_class = value
+    end
+
+    def has_option?(name);     !!@child_options[name];         end
+    def get_option(name);      @child_options.get(name);       end
+    def set_option(name, val); @child_options.set(name, val);  end
+    def add_option(*args)
+      name = args.first
+      opt  = NsOptions::Option.new(*NsOptions::Option.args(args, @option_type_class))
+
+      @child_namespaces.rm(name)
+      @child_options.add(name, opt)
+    end
+
+    def has_namespace?(name);  !!@child_namespaces[name];      end
+    def get_namespace(name);   @child_namespaces.get(name);    end
+    def add_namespace(name, option_type_class=nil, &block)
+      opt_type_class = option_type_class || @option_type_class
+      ns = NsOptions::Namespace.new(name, opt_type_class, &block)
+
+      @child_options.rm(name)
+      @child_namespaces.add(name, ns)
+    end
+
+    # recursively build a hash representation of the namespace, using symbols
+    # for the option/namespace name-keys
+    def to_hash
+      Hash.new.tap do |hash|
+        @child_options.each{|name, opt| hash[name.to_sym] = opt.value}
+        @child_namespaces.each{|name, value| hash[name.to_sym] = value.to_hash}
+      end
+    end
+
+    # The opposite of #to_hash. Takes a hash representation of options and
+    # namespaces and mass assigns option values.
+    def apply(values=nil)
+      (values || {}).each do |name, value|
+        if has_namespace?(name)
+          # recursively apply namespace values if hash given; ignore otherwise.
+          get_namespace(name).apply(value) if value.kind_of?(Hash)
+        else
+          # be sure to use the namespace's writer to write the option value
+          @ns.send("#{name}=", value)
+        end
+      end
+    end
+
+    # allow for iterating over the key/values of a namespace
+    # this uses #to_hash so you won't get option/namespace objs for the values
+    def each
+      to_hash.each{|k,v| yield k,v if block_given? }
+    end
+
+    # define the parent ns using the given block
+    def define(&block)
+      if block && block.arity > 0
+        block.call @ns
+      elsif block
+        @ns.instance_eval(&block)
+      end
+      @ns
+    end
+
+    def build_from(other_ns_data)
+      set_option_type_class(other_ns_data.option_type_class)
+
+      other_ns_data.child_options.each do |name, opt|
+        add_option(name, opt.type_class, opt.rules)
+      end
+
+      other_ns_data.child_namespaces.each do |name, ns|
+        new_ns = add_namespace(name)
+        new_ns.build_from(ns)
+      end
+    end
+
+    def reset
+      child_options.each {|name, opt| opt.reset}
+      child_namespaces.each {|name, ns| ns.reset}
+    end
+
+    class DslMethod
+      attr_reader :name, :data
+
+      def initialize(meth, *args, &block)
+        @method_string, @args, @block = meth.to_s, args, block
+        @name = @method_string.gsub("=", "")
+        @data = args.size == 1 ? args[0] : args
+      end
+
+      def writer?;   !!(@method_string =~ /=\Z/); end
+      def reader?;   !self.writer?;               end
+      def has_args?; !@args.empty?;               end
+    end
+
+    def ns_respond_to?(meth)
+      dslm = DslMethod.new(meth)
+
+      has_namespace?(dslm.name) || # namespace reader
+      has_option?(dslm.name)    || # option reader
+      dslm.writer?              || # dynamic option writer
+      false
+    end
+
+    def ns_method_missing(bt, meth, *args, &block)
+      dslm = DslMethod.new(meth, *args, &block)
+
+      if is_namespace_reader?(dslm)
+        get_namespace(dslm.name).define(&block)
+      elsif is_option_reader?(dslm)
+        get_option(dslm.name)
+      elsif is_option_writer?(dslm)
+        # TODO: remove same-named opt/ns when adding the other with same name
+        add_option(dslm.name) unless has_option?(dslm.name)
+        begin
+          set_option(dslm.name, dslm.data)
+        rescue NsOptions::Option::CoerceError
+          error! bt, err # reraise this exception with a sane backtrace
+        end
+      else # namespace writer or unknown
+        # raise a no meth err with a sane backtrace
+        error! bt, NoMethodError.new("undefined method `#{meth}' for #{@ns.inspect}")
+      end
+    end
+
+    private
+
+    def is_namespace_reader?(dsl_method)
+      has_namespace?(dsl_method.name)  && !dsl_method.has_args?
+    end
+
+    def is_option_reader?(dsl_method)
+      has_option?(dsl_method.name)     && !dsl_method.has_args?
+    end
+
+    def is_option_writer?(dsl_method)
+      !has_namespace?(dsl_method.name) && dsl_method.has_args?
+    end
+
+    def error!(backtrace, exception)
+      exception.set_backtrace(backtrace); raise exception
+    end
+
+  end
+end

data/lib/ns-options/namespaces.rb

@@ -1,22 +1,33 @@
-module NsOptions
+require 'ns-options/namespace'
 
-  class Namespaces < Hash
+module NsOptions
+  class Namespaces
 
-    def [](name)
-      super(name.to_sym)
-    end
-    def []=(name, value)
-      super(name.to_sym, value)
+    def initialize
+      @hash = Hash.new
     end
 
-    def add(name, key, parent = nil, &block)
-      self[name] = NsOptions::Namespace.new(key, parent, &block)
+    # for hash with indifferent access behavior
+    def [](name);         @hash[name.to_s];         end
+    def []=(name, value); @hash[name.to_s] = value; end
+
+    def keys(*args, &block);   @hash.keys(*args, &block);   end
+    def each(*args, &block);   @hash.each(*args, &block);   end
+    def empty?(*args, &block); @hash.empty?(*args, &block); end
+
+    def add(name, ns); self[name] = ns;         end
+    def rm(name);      @hash.delete(name.to_s); end
+    def get(name);     self[name];              end
+
+    def required_set?
+      are_all_these_namespaces_set? @hash.values
     end
 
-    def get(name)
-      self[name]
+    private
+
+    def are_all_these_namespaces_set?(namespaces)
+      namespaces.inject(true) {|bool, ns| bool && ns.required_set?}
     end
 
   end
-
 end

data/lib/ns-options/option.rb

@@ -1,26 +1,38 @@
 module NsOptions
 
   class Option
-    attr_accessor :name, :value, :type_class, :rules
+
+    class CoerceError < ::ArgumentError
+      def initialize(type_class, value, err)
+        super("can't coerce `#{value.inspect}' to `#{type_class}': #{err.message}")
+        set_backtrace(err.backtrace)
+      end
+    end
 
     def self.rules(rules)
+      # make sure any given `:args` rule is an array
       (rules || {}).tap do |r|
         r[:args] = (r[:args] ? [*r[:args]] : [])
       end
     end
 
-    def self.args(*args)
+    def self.args(args, default_type_class=nil)
       [ self.rules(args.last.kind_of?(::Hash) ? args.pop : {}),
         # if a nil type_class is given, just use Object
         # this makes the option accept any value with no type coercion
-        (args[1] || Object),
+        (args[1] || default_type_class || Object),
         args[0].to_s
-      ]
+      ].reverse
     end
 
-    def initialize(*args)
-      self.rules, self.type_class, self.name = self.class.args(*args)
-      self.value = self.rules[:default]
+    attr_accessor :name, :value, :type_class, :rules
+
+    def initialize(name, type_class=nil, rules=nil)
+      @name, @rules = name, (rules || {})
+      @type_class = type_class || Object
+      @rules[:args] ||= []
+
+      self.reset
     end
 
     # if reading a lazy_proc, call the proc and return its coerced return val
@@ -35,10 +47,12 @@ module NsOptions
       end
     end
 
-    # if setting a lazy_proc, just store the proc off to be called when read
-    # otherwise, coerce and store the value being set
     def value=(new_value)
-      @value = self.lazy_proc?(new_value) ? new_value : self.coerce(new_value)
+      save_value(new_value)
+    end
+
+    def reset
+      save_value(self.rules[:default])
     end
 
     def is_set?
@@ -46,7 +60,7 @@ module NsOptions
     end
 
     def required?
-      !!self.rules[:required] || !!self.rules[:require]
+      !!self.rules[:required]
     end
 
     def ==(other)
@@ -57,6 +71,12 @@ module NsOptions
 
     protected
 
+    # if setting a lazy_proc, just store the proc off to be called when read
+    # otherwise, coerce and store the value being set
+    def save_value(new_value)
+      @value = self.lazy_proc?(new_value) ? new_value : self.coerce(new_value)
+    end
+
     # a value is considered to by a lazy eval proc if it some kind of a of
     # Proc and the option it is being set on is not explicitly defined as some
     # kind of Proc
@@ -67,24 +87,30 @@ module NsOptions
     end
 
     def coerce(value)
-      return value if (value.kind_of?(self.type_class)) || value.nil?
-
-      if [ Integer, Float, String ].include?(self.type_class)
-        # ruby type conversion, i.e. String(1)
-        Object.send(self.type_class.to_s.to_sym, value)
-      elsif self.type_class == Symbol
-        value.to_sym
-      elsif self.type_class == Hash
-        {}.merge(value)
-      else
-        begin
+      return value if no_coercing_needed?(value)
+
+      begin
+        if [ Integer, Float, String ].include?(self.type_class)
+          # ruby type conversion, i.e. String(1)
+          Object.send(self.type_class.to_s, value)
+        elsif self.type_class == Symbol
+          value.to_sym
+        elsif self.type_class == Hash
+          {}.merge(value)
+        else
           self.type_class.new(value, *self.rules[:args])
-        rescue ArgumentError => err
-          raise ArgumentError, "#{self.type_class} `initialize': #{err.message}"
         end
+      rescue Exception => err
+        raise CoerceError.new(self.type_class, value, err)
       end
     end
 
+    private
+
+    def no_coercing_needed?(value)
+      value.kind_of?(self.type_class) || value.nil?
+    end
+
   end
 
 end