ns-options 0.1.0

data/.gitignore

@@ -0,0 +1,17 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

data/Gemfile

@@ -0,0 +1,8 @@
+source 'http://rubygems.org'
+
+# Specify your gem's dependencies in ns-options.gemspec
+gemspec
+
+gem 'rake', '~>0.9.2'
+
+gem 'assert-mocha', :git => "git@github.com:jcredding/assert-mocha.git"

data/README.markdown

@@ -0,0 +1,151 @@
+# Namespace Options
+
+Namespace Options provides a clean interface for defining, organizing and using options. Options are defined through a clean syntax that clearly shows what can be set and read. Options can be organized into namespaces as well. This allows multiple libraries to share common options but still have their own specific options separated. Reading and writing options is as simple as if they were accessors. Furthermore, you can provide your own _type_ class that allows you to provide extended functionality to a simple option.
+
+## Installation
+
+Add the following to your Gemfile and `bundle install`:
+
+    gem 'ns-options'
+
+## Usage
+
+### Defining Options
+
+The basic usage of Namespace Options is to be able to define options for a module or class:
+
+```ruby
+module App
+  include NsOptions::HasOptions
+  options(:settings) do
+    option :root, Pathname
+    option :stage
+  end
+end
+```
+
+The code above makes the `App` module now have options, accessible through the settings method. The options can be read and written to like a normal accessor:
+
+```ruby
+App.settings.root = "/a/path/to/the/root"
+App.settings.root.join("log", "test.log") # => "/a/path/to/the/root/log/test.log" (a Pathname instance)
+
+App.settings.stage = "development"
+App.settings.stage # => "development"
+```
+
+Because the `root` option specified `Pathname` as it's type, the option will always return an instance of `Pathname`. Since the `stage` option did not specify a type, it defaulted to a `String`. You can define you're own type classes as well and use them:
+
+```ruby
+class Stage < String
+
+  def initialize(value)
+    super(value.to_s)
+  end
+
+  def development?
+    self == "development"
+  end
+
+end
+
+
+App.settings.define do
+  option :stage, Stage
+end
+
+App.settings.stage = "development"
+App.settings.stage.development? # => true
+App.settings.stage = "test"
+App.settings.stage.development? # => false
+```
+
+This allows you to add extended functionality to your options. The only condition is that the `initialize` accepts a single argument. This argument is always the value that was used with the writer. For the above, the `Stage` class received `"development"` and `"test"` in it's initialize method.
+
+### Namespaces
+
+Namespaces allow you to organize and share options. With the previously mentioned `App` module and it's options you could create a namespace for another library:
+
+```ruby
+module Data # data is a library for retrieving persisted data from some resource
+
+  App.settings.namespace(:data) do
+    option :server
+  end
+
+  def self.config
+    App.settings.data
+  end
+
+end
+```
+
+Now I can set a server option for data that is separate from the main `App` settings:
+
+```ruby
+Data.config.server = "127.0.0.1:1234"
+
+App.server # => NoMethodError
+```
+
+Since the data namespace was created from the `App` settings (which is also a namespace) it can access it's parent's options:
+
+```ruby
+Data.config.stage # => "test", or whatever App.settings.stage would return
+```
+
+Namespaces and their ability to read their parent's options is internally used by Namespace Options. When you add options to a class like so:
+
+```ruby
+class User
+  include NsOptions::HasOptions
+  options(:preferences) do
+    option :home_page
+  end
+
+end
+```
+
+A namespace will be created for the `User` class itself. Which can have options added and even set. Once a user instance is created, it will create a child namespace from the classes. Thus, it will be able to access and use any options on the class:
+
+```ruby
+user = User.new
+user.preferences.home_page = "/home"
+```
+
+### Dynamically Defined Options
+
+Not all options have to be defined formally. Though defining an option through the `option` method allows the most functionality and allows for quickly seeing what can be used, Namespace Options allows you to write options that have not been defined:
+
+```ruby
+App.settings.logger = Logger.new(App.settings.root.join("log", "test.log"))
+
+App.settings.logger.info("Hello World")
+```
+
+Writing to a namespace with a previously undefined option will create a new option. The type class will be pulled from whatever object you write with. In the above case, the option defined would have it's type class set to `Logger` and would try to convert any new values to an instance of `Logger`.
+
+## License
+
+Copyright (c) 2011 Collin Redding and Team Insight
+
+Permission is hereby granted, free of charge, to any person
+obtaining a copy of this software and associated documentation
+files (the "Software"), to deal in the Software without
+restriction, including without limitation the rights to use,
+copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the
+Software is furnished to do so, subject to the following
+conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
+OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
+HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+OTHER DEALINGS IN THE SOFTWARE.

data/Rakefile

@@ -0,0 +1,5 @@
+#!/usr/bin/env rake
+require "bundler/gem_tasks"
+
+require 'assert/rake_tasks'
+Assert::RakeTasks.for :test

data/lib/ns-options/has_options.rb

@@ -0,0 +1,36 @@
+module NsOptions
+
+  module HasOptions
+    class << self
+
+      def included(klass)
+        klass.class_eval do
+          extend NsOptions::HasOptions::DSL
+        end
+      end
+
+    end
+
+    module DSL
+
+      def options(name, key = nil, &block)
+        key ||= name.to_s
+        self.class_eval <<-DEFINE_METHOD
+
+          def #{name}(&block)
+            @#{name} ||= NsOptions::Helper.new_child_namespace(self, '#{name}', &block)
+          end
+
+          def self.#{name}(&block)
+            @#{name} ||= NsOptions::Helper.new_namespace('#{key}', &block)
+          end
+
+        DEFINE_METHOD
+        self.send(name, &block)
+      end
+
+    end
+
+  end
+
+end

data/lib/ns-options/helper.rb

@@ -0,0 +1,34 @@
+module NsOptions
+
+  module Helper
+    module_function
+
+    # Common method for creating a new namespace
+    def new_namespace(key, parent = nil, &block)
+      namespace = NsOptions::Namespace.new(key, parent)
+      namespace.define(&block)
+    end
+
+    # Common method for creating a new child namespace, using the owner's class's options as the
+    # parent.
+    def new_child_namespace(owner, name, &block)
+      parent = owner.class.send(name)
+      method = "#{name}_key"
+      key = if owner.respond_to?(method)
+        owner.send(method)
+      else
+        "#{owner.class.to_s.split('::').last.downcase}_#{owner.object_id}"
+      end
+      namespace = parent.namespace(name, key)
+      namespace.define(&block)
+    end
+
+    def fetch_and_define_option(namespace, option_name)
+      option = namespace.options.fetch(option_name)
+      namespace.option(option.name, option.type_class, option.rules)
+      option
+    end
+
+  end
+
+end

data/lib/ns-options/namespace.rb

@@ -0,0 +1,136 @@
+module NsOptions
+
+  class Namespace
+    attr_accessor :options, :metaclass
+
+    def initialize(key, parent = nil)
+      self.metaclass = (class << self; self; end)
+      self.options = NsOptions::Options.new(key, parent)
+    end
+
+    def required_set?
+      self.options.required_set?
+    end
+
+    # 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)
+      option = self.options.add(*args)
+
+      self.metaclass.class_eval <<-DEFINE_METHOD
+
+        def #{option.name}(*args)
+          if !args.empty?
+            self.send("#{option.name}=", *args)
+          else
+            self.options.get(:#{option.name})
+          end
+        end
+
+        def #{option.name}=(*args)
+          value = args.size == 1 ? args.first : args
+          self.options.set(:#{option.name}, value)
+        end
+
+      DEFINE_METHOD
+
+      option
+    end
+
+    # 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)}"
+      namespace = self.options.namespaces.add(name, key, self, &block)
+
+      self.metaclass.class_eval <<-DEFINE_METHOD
+
+        def #{name}(&block)
+          namespace = self.options.namespaces.get("#{name}")
+          namespace.define(&block) if block
+          namespace
+        end
+
+      DEFINE_METHOD
+
+      namespace
+    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
+    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. 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.
+    # 3. 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.fetch_and_define_option(self, option_name)
+        self.send(option.name)
+      elsif !args.empty? && self.respond_to?(option_name)
+        option = NsOptions::Helper.fetch_and_define_option(self, option_name)
+        self.send("#{option.name}=", value)
+      elsif !args.empty?
+        option = self.option(option_name, value.class)
+        self.send("#{option.name}=", value)
+      else
+        super
+      end
+    end
+
+    def respond_to?(method)
+      super || self.options.is_defined?(method.to_s.gsub("=", ""))
+    end
+
+  end
+
+end

data/lib/ns-options/namespaces.rb

@@ -0,0 +1,22 @@
+module NsOptions
+
+  class Namespaces < Hash
+
+    def [](name)
+      super(name.to_sym)
+    end
+    def []=(name, value)
+      super(name.to_sym, value)
+    end
+
+    def add(name, key, parent = nil, &block)
+      self[name] = NsOptions::Helper.new_namespace(key, parent, &block)
+    end
+
+    def get(name)
+      self[name]
+    end
+
+  end
+
+end

data/lib/ns-options/option/boolean.rb

@@ -0,0 +1,27 @@
+module NsOptions
+  class Option
+
+    class Boolean
+      attr_accessor :actual
+
+      def initialize(value)
+        self.actual = value
+      end
+
+      def actual=(new_value)
+        @actual = self.convert(new_value)
+      end
+
+      protected
+
+      def convert(value)
+        if [ nil, 0, '0', false, 'false' ].include?(value)
+          false
+        elsif value
+          true
+        end
+      end
+    end
+
+  end
+end

data/lib/ns-options/option.rb

@@ -0,0 +1,70 @@
+module NsOptions
+
+  class Option
+    autoload :Boolean, 'ns-options/option/boolean'
+
+    attr_accessor :name, :value, :type_class, :rules
+
+    def initialize(name, type_class, rules = {})
+      self.name = name.to_s
+      self.type_class = self.usable_type_class(type_class)
+      self.rules = rules
+      self.value = rules[:default]
+    end
+    
+    def value
+      if self.type_class == NsOptions::Option::Boolean
+        @value and @value.actual
+      else
+        @value
+      end
+    end
+
+    def value=(new_value)
+      @value = if (new_value.class == self.type_class) || new_value.nil?
+        new_value
+      else
+        self.coerce(new_value)
+      end
+    end
+    
+    def is_set?
+      self.value.respond_to?(:is_set?) ? self.value.is_set? : !self.value.nil?
+    end
+    
+    def required?
+      !!self.rules[:required] || !!self.rules[:require]
+    end
+
+    def ==(other)
+      [ :name, :type_class, :rules, :value ].inject(true) do |bool, attribute|
+        bool && (self.send(attribute) == other.send(attribute))
+      end
+    end
+
+    protected
+
+    def coerce(new_value)
+      if [ Integer, Float, String ].include?(self.type_class)
+        # ruby type conversion, i.e. String(1)
+        Object.send(self.type_class.to_s.to_sym, new_value)
+      elsif self.type_class == Hash
+        {}.merge(new_value)
+      else
+        self.type_class.new(new_value)
+      end
+    end
+
+    def usable_type_class(type_class)
+      if type_class == Fixnum
+        Integer
+      elsif [ TrueClass, FalseClass ].include?(type_class)
+        NsOptions::Option::Boolean
+      else
+        (type_class || String)
+      end
+    end
+
+  end
+
+end

data/lib/ns-options/options.rb

@@ -0,0 +1,65 @@
+module NsOptions
+
+  class Options < Hash
+    attr_accessor :key, :parent, :children
+    alias :namespaces :children
+
+    def initialize(key, parent = nil)
+      self.key = key.to_s
+      self.parent = parent
+      self.children = NsOptions::Namespaces.new
+    end
+
+    def [](name)
+      super(name.to_sym)
+    end
+    def []=(name, value)
+      super(name.to_sym, value)
+    end
+
+    def add(*args)
+      options = args.last.kind_of?(Hash) ? args.pop : {}
+      option = NsOptions::Option.new(args[0], args[1], options)
+      self[option.name] = option
+    end
+
+    def del(name)
+      self[name] = nil
+    end
+    alias :remove :del
+
+    def get(name)
+      option = self[name]
+      if option && !option.value.nil?
+        option.value
+      elsif self.parent_options
+        self.parent_options.get(name)
+      end
+    end
+
+    def set(name, new_value)
+      self[name].value = new_value
+      self[name]
+    end
+
+    def fetch(name)
+      self[name] || (self.parent_options && self.parent_options.fetch(name))
+    end
+
+    def is_defined?(name)
+      !!self[name] || !!(self.parent_options && self.parent_options.is_defined?(name))
+    end
+
+    def parent_options
+      self.parent and self.parent.options
+    end
+
+    def required_set?
+      self.values.reject{|option| !option.required? }.inject(true) do |bool, option|
+        bool && option.is_set?
+      end
+    end
+
+  end
+
+end

data/lib/ns-options/version.rb

@@ -0,0 +1,3 @@
+module NsOptions
+  VERSION = "0.1.0"
+end

data/lib/ns-options.rb

@@ -0,0 +1,9 @@
+module NsOptions
+  autoload :HasOptions,     'ns-options/has_options'
+  autoload :Helper,         'ns-options/helper'
+  autoload :Namespace,      'ns-options/namespace'
+  autoload :Namespaces,     'ns-options/namespaces'
+  autoload :Option,         'ns-options/option'
+  autoload :Options,        'ns-options/options'
+  autoload :VERSION,        'ns-options/version'
+end

data/ns-options.gemspec

@@ -0,0 +1,19 @@
+# -*- encoding: utf-8 -*-
+require File.expand_path('../lib/ns-options/version', __FILE__)
+
+Gem::Specification.new do |gem|
+  gem.authors       = ["Collin Redding"]
+  gem.email         = ["collin.redding@reelfx.com"]
+  gem.description   = %q{Define and use namespaced options with a clean interface.}
+  gem.summary       = %q{Define and use namespaced options with a clean interface.}
+
+  gem.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  gem.files         = `git ls-files`.split("\n")
+  gem.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  gem.name          = "ns-options"
+  gem.require_paths = ["lib"]
+  gem.version       = NsOptions::VERSION
+
+  gem.add_development_dependency("assert",        ["~>0.6.0"])
+  #gem.add_development_dependency("assert-mocha",  ["~>0.1.0"])
+end

data/test/helper.rb

@@ -0,0 +1,14 @@
+require 'logger'
+
+root_path = File.expand_path("../..", __FILE__)
+if !$LOAD_PATH.include?(root_path)
+  $LOAD_PATH.unshift(root_path)
+end
+require 'ns-options'
+
+require 'test/support/app'
+require 'test/support/user'
+
+if defined?(Assert)
+  require 'assert-mocha'
+end

data/test/integration/app_test.rb

@@ -0,0 +1,63 @@
+require 'assert'
+
+module App
+
+  class BaseTest < Assert::Context
+    desc "the App module"
+    setup do
+      @module = App
+    end
+    subject{ @module }
+
+    should have_instance_methods :options, :settings
+
+  end
+
+  class DefineTest < BaseTest
+    desc "defined"
+    setup do
+      stage = @stage = "test"
+      root_path = @root_path = File.expand_path("../../..", __FILE__)
+      logger = @logger = Logger.new(File.join(@root_path, "log", "test.log"))
+      run = @run = true
+      @module.settings.define do |namespace|
+        namespace.stage stage
+        namespace.root = root_path
+        namespace.logger = logger
+
+        namespace.sub do
+          run_commands run
+        end
+      end
+    end
+    subject{ @module.settings }
+
+    should have_instance_methods :namespace, :option, :define, :options, :metaclass
+    should have_accessors :stage, :root, :logger
+    should have_instance_methods :sub
+
+    should "have set the stage to 'test'" do
+      assert_equal @stage, subject.stage
+    end
+    should "have set the root to this gem's dir" do
+      assert_equal Pathname.new(@root_path), subject.root
+    end
+    should "have set the logger to the passed logger" do
+      assert_equal @logger, subject.logger
+      assert_same @logger, subject.logger
+    end
+  end
+  
+  class SubNamespaceTest < DefineTest
+    desc "the sub namespace"
+    subject{ @module.settings.sub }
+    
+    should "have set the run_commands option" do
+      assert_equal @run, subject.run_commands
+    end
+    should "have access to it's parent's options" do
+      assert_equal @stage, subject.stage
+    end
+  end
+
+end