ns-options 0.1.1 → 0.2.0

data/README.markdown

@@ -16,7 +16,7 @@ The basic usage of Namespace Options is to be able to define options for a modul
 
 ```ruby
 module App
-  include NsOptions::HasOptions
+  include NsOptions
   options(:settings) do
     option :root, Pathname
     option :stage
@@ -34,7 +34,7 @@ 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:
+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 an `Object` which allows it to accept any value. You can define you're own type classes as well and use them:
 
 ```ruby
 class Stage < String
@@ -60,11 +60,11 @@ 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.
+This allows you to add extended functionality to your options and is where a lot of nice usability can be added. Defining your own type classes is explained in more detail later.
 
 ### 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:
+Namespaces allow you to organize your 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
@@ -85,20 +85,17 @@ Now I can set a server option for data that is separate from the main `App` sett
 ```ruby
 Data.config.server = "127.0.0.1:1234"
 
-App.server # => NoMethodError
+App.settings.server # => NoMethodError
+App.settings.data.server # => 127.0.0.1:1234
 ```
 
-Since the data namespace was created from the `App` settings (which is also a namespace) it can access it's parent's options:
+#### With Classes
 
-```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:
+Using `NsOptions` on a `Class` uses namespaces to create separate sets of options for every instance of your class created. This allows every instance to have different values for the set of options and not interfere with each other. For example with the following:
 
 ```ruby
 class User
-  include NsOptions::HasOptions
+  include NsOptions
   options(:preferences) do
     option :home_page
   end
@@ -106,11 +103,43 @@ class User
 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:
+A namespace is created for the `User` class in the same way it works for modules:
+
+```ruby
+User.preferences # => NsOptions::Namespace instance
+User.preferences.home_page = "/home" # you can set options at this level, though I'm not sure why you would
+```
+
+Additionally, `NsOptions` will setup instances of a class to have a _copy_ of their class's namespace.
+
+```ruby
+user = User.new
+user.preferences.home_page = "/home" # makes a lot more sense to do this
+user2 = User.new
+user2.preferences.home_page = "/not_home"
+user.preferences.home_page == user2.preferences.home_page # => false, they are completely separate
+```
+
+The instance level namespaces are deep copies of the class one. This means every option and sub-namespaces will be included. Only values are not copied.
 
 ```ruby
+class User
+  include NsOptions
+  options(:preferences) do
+    option :home_page
+    namespace :view do
+      option :background_color, ViewColor
+    end
+  end
+
+end
+
+User.preferences.home_page = "/home"
 user = User.new
-user.preferences.home_page = "/home"
+user.preferences.home_page # => nil, does not return '/home'
+user.preferences.object_id != User.preferences.object_id # => true, they are different objects, just with the same definition
+user.preferences.view.background_color = "green"
+user.preferences.view.background_color # => returns an instance of ViewColor
 ```
 
 ### Dynamically Defined Options
@@ -123,7 +152,235 @@ 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`.
+Writing to a namespace with a previously undefined option will create a new option. The type class will be defaulted to `Object` as if you didn't provide it. This will allow you to set any value for the option so you have no guarantee on what it's value is and how it can be used.
+
+### Mass Assigning Options
+
+Sometimes, it's convenient to be able to set many options at once. This can be done by calling the `apply` method and giving it a hash of option names with values:
+
+```ruby
+class Project
+  include NsOptions
+  options(:settings) do
+    option :file_path
+    option :home_page
+
+    namespace(:movie_resolution) do
+      option :height, Integer
+      option :width, Integer
+    end
+  end
+end
+
+project = Project.new
+project.settings.apply({
+  :file_path => "/path/to/project",
+  :movie_resolution => { :height => 800, :width => 600 }
+})
+
+project.settings.file_path                # => "/path/to/project"
+project.settings.movie_resolution.height  # => 800
+project.settings.movie_resolution.width   # => 600
+```
+
+As the example shows, if you have a namespace and have a matching hash, it will automatically apply those values to that namespace. Also, if you include keys that are not defined options for your namespace, new options will be created for the values:
+
+```ruby
+project = Project.new
+project.settings.apply({ :stereoscopic => true, :not_a_namespace => { :yes => true } })
+
+project.settings.stereoscopic     # => true
+project.settings.not_a_namespace  # => { :yes => true }
+```
+
+The reverse is also supported, so if you want a `Hash` version of your namespace, just ask your options for it.
+
+```ruby
+# a continuation of the previous block of code...
+project.settings.to_hash # => { :stereoscopic => true, :not_a_namespace => { :yes => true } }
+project.settings.each do |name, value|
+  # iterating over your options works as well
+end
+```
+
+### Lazily eval'd options
+
+Sometimes, you may want to set an option to a value that shouldn't (couldn't) be evaluated until the option is read.  If you set an option equal to a Proc, the value of the option will be whatever the return value of the Proc is at the time the option is read.  Here are some examples:
+
+```ruby
+# dynamic value
+options(:dynamic) do
+  option :rand, :default => Proc.new { rand(1000) }
+end
+
+dynamic.rand #=> 347
+dynamic.rand #=> 529
+
+# same goes for dynamically defined options
+dynamic.not_originally_defined = Proc.new { rand(1000) }
+dynamic.not_originally_defined #=> 110
+dynamic.not_originally_defined #=> 931
+```
+
+```ruby
+# self referential value
+options(:selfref) do
+  option :something, :default => "123"
+  option :else, :default => Proc.new { self.something }
+end
+
+selfref.something #=> "123"
+selfref.else #=> "123"
+```
+
+If you really want your option to read and write Procs and not do this lazy eval behavior, just define the option as a Proc option
+
+```ruby
+options(:explicit) do
+  option :a_proc, Proc, :default => Proc.new { rand(1000) }
+end
+
+explicit.a_proc #=> <the proc obj>
+```
+
+### Custom Type Classes
+
+As stated previously, type classes is where you can add a lot of functionality and usability to your options. To do this though, understanding what `NsOptions` will do with your type class is important. First, it's important to understand when `NsOptions` will try to _coerce_ a value. This is only done when a value is not a _kind of_ the option's type class or when the value is nil. For example:
+
+```ruby
+module App
+  include NsOptions
+  options :settings do
+    option :stage, Stage
+  end
+end
+
+App.settings.stage = Stage.new("development") # no type coercion is done here, the value is already a Stage
+
+class BetterStage < Stage
+  # do something better
+end
+
+App.settings.stage = BetterStage.new("test") # again, no type coercion is done, as BetterStage is a kind of Stage
+
+App.setting.stage = nil # nil is never coerced, if you set a value to nil, it's just nil
+```
+
+Next, when `NsOptions` chooses to coerce a value with your class, it will always create a new instance of your type class and pass the value as the first argument. Your `initialize` method needs to be defined to handle this:
+
+```ruby
+class Root < Pathname
+  def initialize(path, app_name)
+    super("#{path}/#{app_name}")
+  end
+end
+```
+
+`Root`'s `initialize` method will not work for type coercion. The `app_name` argument will not be provided and Ruby will get angry. To solve this, make the `app_name` not required:
+
+```ruby
+class Root < Pathname
+  def initialize(path, app_name = nil)
+    app_name ||= App.settings.name # this might be one way to solve this
+    super("#{path}/#{app_name}")
+  end
+end
+```
+
+With the revised `initialize` method, `NsOptions` will have no problems coercing values for your the type class. In some cases the above solution may not work for you, but don't worry. See the _Option Rules_ section for another way to solve this, specifically about the args rule. For an example of a custom type class, the included `NsOptions::Boolean` can be looked at. This is a special case, but it works as a type class with `NsOptions`.
+
+### Ruby Classes As A Type Class
+
+`NsOptions` will allow you to use many of Ruby's standard objects as type classes and still handle coercing values appropriately. Typically this is done with ruby's type casting:
+
+```ruby
+module Example
+  include NsOptions
+  options :stuff do
+    option :string, String
+    option :integer, Integer
+    option :float, Float
+    option :symbol, Symbol
+    option :hash, Hash
+    option :array, Array
+  end
+end
+
+Example.stuff.string = 1
+Example.stuff.string # => "1", the same as doing String(1)
+Example.stuff.integer = 5.0
+Example.stuff.integer # => 5, this time it's Integer(5.0)
+Example.stuff.float = "5.0"
+Example.stuff.float # => 5.0, same as Float("5.0")
+```
+
+`Symbol`, `Hash` and `Array` work, but ruby doesn't provide a built in type casting for these.
+
+```ruby
+Example.stuff.symbol = "awesome"
+Example.stuff.symbol # => :awesome, watch out, this will try calling to_sym on the passed value, so it can error
+Example.stuff.hash = { :a => 'b' }
+Example.stuff.hash # => returns the same hash, does Hash.new.merge(value)
+Example.stuff.array = [ 1, 2, 3 ]
+Example.stuff.array # => returns the same array, Array is the only one that works without anything special, Array.new(value)
+```
+
+### Option Rules
+
+An option can be defined with certain rules (through a hash) that will extend the behavior of the option.
+
+#### Default Value
+
+The first rule is setting a default value.
+
+```ruby
+App.settings do
+  option :stage, Stage, :default => "development"
+end
+App.settings.stage # => instead of nil this will be 'development'
+```
+
+A default value runs through the same logic as if you set the value manually, so it will be coerced if necessary.
+
+#### Required
+
+It's also possible to flag an option as _required_.
+
+```ruby
+App.settings do
+  option :root, :required => true
+end
+
+App.settings.required_set? # => false, asking if the required options are set
+App.settings.root = "/path/to/somewhere"
+App.settings.required_set? # => true
+```
+
+To check if an option is set it will simply check if the value is not `nil`. If you are using a custom type class though, you can define an `is_set?` method and this will be used to check if an option is set.
+
+#### Args
+
+Another rule that you can specify is args. This allows you to pass more arguments to a type class.
+
+```ruby
+class Root < Pathname
+  def initialize(path, app_name = nil)
+    app_name = app_name.respond_to?(:call) ? app_name.call : app_name
+    super("#{path}/#{app_name}")
+  end
+end
+
+App.settings do
+  option :name
+  option :root, Root, :args => lambda{ App.settings.name }
+end
+
+App.settings.name = "example"
+App.settings.root = "/path/to"
+App.settings.root # => /path/to/example, uses the args rule to build the path
+```
+
+With the args rule, you can have a type class accept more than one argument. The first argument will always be the value to coerce. Any more arguments will be appended on after the value.
 
 ## License
 
@@ -148,4 +405,4 @@ 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.
+OTHER DEALINGS IN THE SOFTWARE.

data/lib/ns-options/boolean.rb

@@ -0,0 +1,25 @@
+module NsOptions
+  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', 'f', 'F' ].include?(value)
+        false
+      elsif value
+        true
+      end
+    end
+
+  end
+end

data/lib/ns-options/errors/invalid_name.rb

@@ -0,0 +1,15 @@
+module NsOptions
+  module Errors
+
+    class InvalidName < StandardError
+      attr_accessor :message
+
+      def initialize(message, backtrace)
+        self.message = message
+        self.set_backtrace(backtrace)
+      end
+
+    end
+
+  end
+end

data/lib/ns-options/has_options.rb

@@ -13,19 +13,45 @@ module NsOptions
 
     module DSL
 
+      # This is the main DSL method for creating a namespace of options for your class/module. This
+      # will define a class method for both classes and modules and an additional instance method
+      # for classes. The namespace is then created and returned by calling the class method version.
+      # For classes, the instance method will build an entirely new namespace from the class level
+      # namespace. This is so when you define options at the class level:
+      #
+      # class Something
+      #   include NsOptions
+      #   options(:settings) do
+      #      option :root
+      #   end
+      # end
+      #
+      # the namespaces at the instance level still get all the defined options, but are completely
+      # separate objects from the class and other instances. Modules only deal with a single
+      # namespace at the module level.
       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
+        method_definitions = <<-CLASS_METHOD
 
           def self.#{name}(&block)
-            @#{name} ||= NsOptions::Helper.new_namespace('#{key}', &block)
+            @#{name} ||= NsOptions::Namespace.new('#{key}', &block)
           end
 
-        DEFINE_METHOD
+        CLASS_METHOD
+        if self.kind_of?(Class)
+          method_definitions += <<-INSTANCE_METHOD
+
+            def #{name}(&block)
+              unless @#{name}
+                @#{name} = NsOptions::Namespace.new('#{key}', &block)
+                @#{name}.options.build_from(self.class.#{name}.options, @#{name})
+              end
+              @#{name}
+            end
+
+          INSTANCE_METHOD
+        end
+        self.class_eval(method_definitions)
         self.send(name, &block)
       end
 

data/lib/ns-options/helper/advisor.rb

@@ -0,0 +1,68 @@
+module NsOptions
+  module Helper
+
+    class Advisor
+      attr_accessor :namespace
+
+      def initialize(namespace)
+        self.namespace = namespace
+      end
+
+      def is_this_ok?(kind, name, from)
+        display = (kind == :option ? "option" : "sub-namespace")
+        if self.bad_methods.include?(name.to_sym)
+          message = self.bad_method_message(display, name)
+          exception = NsOptions::Errors::InvalidName.new(message, from)
+          raise(exception)
+        elsif self.is_already_defined?(name)
+          puts self.duplicate_message(name)
+        elsif self.not_recommended_methods.include?(name.to_sym)
+          puts self.not_recommended_method_message(display, name)
+        else
+          return false
+        end
+        puts "From: #{from.first}"
+        true
+      end
+
+      def is_this_option_ok?(name, from = nil)
+        self.is_this_ok?(:option, name, (from || caller))
+      end
+
+      def is_this_namespace_ok?(name, from = nil)
+        self.is_this_ok?(:namespace, name, (from || caller))
+      end
+
+      def is_already_defined?(name)
+        self.namespace.options.is_defined?(name) ||
+        self.namespace.options.is_namespace_defined?(name)
+      end
+
+      def bad_methods
+        @bad_methods ||= [ :option, :namespace, :define, :options ]
+      end
+
+      def not_recommended_methods
+        @not_recommended_methods ||= NsOptions::Namespace.instance_methods(false).map(&:to_sym)
+      end
+
+      def bad_method_message(kind, name)
+        [ "The #{kind} '#{name}' overwrites a namespace method that NsOptions depends on.",
+          "Please choose a different name for your #{kind}."
+        ].join(" ")
+      end
+      def duplicate_message(name)
+        [ "WARNING! '#{name}' has already been defined and will be overwritten.",
+          "It's likely that it will not behave as expected."
+        ].join(" ")
+      end
+      def not_recommended_method_message(kind, name)
+        [ "WARNING! The #{kind} '#{name}' overwrites a namespace method.",
+          "This will limit some of the functionality of NsOptions."
+        ].join(" ")
+      end
+
+    end
+
+  end
+end

data/lib/ns-options/helper.rb

@@ -1,34 +1,57 @@
 module NsOptions
 
   module Helper
+    autoload :Advisor, 'ns-options/helper/advisor'
+
     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)
+    def find_and_define_namespace(namespace, name)
+      sub_namespace = namespace.options.get_namespace(name)
+      self.define_namespace_methods(namespace, name)
+      sub_namespace
     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)
+    def define_namespace_methods(namespace, name)
+      namespace.metaclass.class_eval <<-DEFINE_METHOD
+
+        def #{name}(&block)
+          namespace = self.options.namespaces.get("#{name}")
+          namespace.define(&block) if block
+          namespace
+        end
+
+      DEFINE_METHOD
     end
 
-    def fetch_and_define_option(namespace, option_name)
-      option = namespace.options.fetch(option_name)
-      namespace.option(option.name, option.type_class, option.rules)
+    def find_and_define_option(namespace, option_name)
+      option = namespace.options[option_name]
+      self.define_option_methods(namespace, option)
       option
     end
 
+    def define_option_methods(namespace, option)
+      namespace.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
+    end
+
+    def advisor(namespace)
+      NsOptions::Helper::Advisor.new(namespace)
+    end
+
   end
 
 end