parameters 0.1.9 → 0.2.0

data/.gitignore

@@ -0,0 +1,9 @@
+doc
+pkg
+tmp/*
+.DS_Store
+.yardoc
+*.db
+*.log
+*.swp
+*~

data/.specopts

@@ -0,0 +1 @@
+--colour --format specdoc

data/.yardopts

@@ -0,0 +1 @@
+--markup markdown --title 'Parameters Documentation' --protected --files ChangeLog.md,LICENSE.txt

data/ChangeLog.md

@@ -0,0 +1,98 @@
+### 0.2.0 / 2010-02-18
+
+* Migrated to [Jeweler](http://github.com/technicalpickles/jeweler)
+  for packaging rubygems.
+* Added type enforcement / coercion to parameters:
+  * Added the `:type` option to the `parameter` method.
+  * Available types:
+    * Array[Class]
+    * Array
+    * Set[Class]
+    * Set
+    * URI
+    * Regexp
+    * DateTime
+    * Date
+    * Symbol
+    * String
+    * Integer
+    * Float
+    * true (for boolean types).
+  * Removed `Parameters::Parser` in favor of type enforcement / coercion.
+* Switched to MarkDown formatted YARD documentation.
+* Moved the YARD parameter handlers into
+  [yard-parameters](http://github.com/postmodern/yard-parameters) library.
+
+### 0.1.9 / 2009-01-30
+
+* Require RSpec >= 1.3.0.
+* Require YARD >= 0.5.3.
+* Added {Parameters::ClassMethods}.
+
+### 0.1.8 / 2009-09-21
+
+* Require Hoe >= 2.3.3.
+* Require YARD >= 0.2.3.5.
+* Require RSpec >= 1.2.8.
+* Use 'hoe/signing' for signed RubyGems.
+* Moved to YARD based documentation.
+* Added YARD handlers for documenting parameter method calls.
+* All specs pass on JRuby 1.3.1.
+
+### 0.1.7 / 2009-07-19
+
+* Renamed Parameters#initialize_parameters to
+  {Parameters#initialize_params}.
+* Adjust spacing in the output of {Parameters::ClassParam#to_s}
+  and {Parameters::InstanceParam#to_s}.
+* Specifically check if the instance variable is nil
+  before initializing it to the default value of the parameter.
+* Handle default value callbacks in {Parameters#parameter}.
+* Check the arity of all default value callbacks, before
+  passing self to them.
+* {Parameters#require_params} now specifically tests if
+  the instance variable of the parameter is nil.
+* Added more specs.
+
+### 0.1.6 / 2009-05-11
+
+* Fixed a bug in {Parameters::ClassMethods#params=} and {Parameters#params=},
+  where they were not handling {Parameters::ClassParam} or
+  {Parameters::InstanceParam} objects properly.
+* Added more specs.
+
+### 0.1.5 / 2009-05-06
+
+* Added Parameters::Parser for parsing parameter values passed in from
+  the command-line or the web.
+* Changed {Parameters::MissingParam} and {Parameters::ParamNotFound} to
+  inherit from StandardError.
+* All specs pass on Ruby 1.9.1-p0.
+
+### 0.1.4 / 2009-01-17
+
+* All specs now pass with RSpec 1.1.12.
+* All specs pass on Ruby 1.9.1-rc1.
+
+### 0.1.3 / 2009-01-14
+
+* Allow the use of lambdas to generate the default values of parameters.
+* Fixed typos in the README.txt.
+
+### 0.1.2 / 2009-01-06
+
+* When printing parameter values, print the inspected version of the value.
+
+### 0.1.1 / 2008-12-27
+
+* Added the require_params helper method.
+* Added print_params methods for displaying parameters of a class or an
+  object.
+
+### 0.1.0 / 2008-12-03
+
+* Initial release.
+* Added {Parameters::ClassMethods#params=} and {Parameters#params=} methods.
+* Allow Parameters#initialize to accept a Hash of parameter values.
+* Added more specs.
+

data/LICENSE.txt

@@ -0,0 +1,22 @@
+
+Copyright (c) 2008-2010 Hal Brodigan
+
+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/README.md

@@ -0,0 +1,90 @@
+# Parameters
+
+* [parameters.rubyforge.org](http://parameters.rubyforge.org/)
+* [github.com/postmodern/parameters](http://github.com/postmodern/parameters/)
+* Postmodern (postmodern.mod3 at gmail.com)
+
+## Description
+
+Parameters allows you to add annotated variables to your classes which may
+have configurable default values.
+
+## Features
+
+* Give parameters default values.
+  * Default values maybe either objects or lambdas used to generate the
+    default value.
+* Change default values of parameters.
+* Enforce types on the values of parameters.
+* Give descriptions to parameters.
+* Set parameters en-mass.
+
+## Examples
+
+    class Octagon
+  
+      include Parameters
+  
+      #
+      # A parameter with a default value
+      #
+      parameter :x, :default => 0
+  
+      #
+      # Another parameter with a default value
+      #
+      parameter :y, :default => 0.5
+  
+      #
+      # A parameter with an enforced type and description.
+      #
+      # Availble types are: Array[Class], Array, Set[Class], Set,
+      # URI, Regexp, DateTime, Date, Symbol, String, Integer, Float
+      # and true (for boolean types).
+      #
+      parameter :radius,
+                :type => Float,
+                :description => 'The radius of the Octagon'
+
+      #
+      # A parameter with a lambda for a default value
+      #
+      parameter :opacity,
+                :default => lambda { rand },
+                :description => 'The opacity of the Octagon'
+  
+    end
+  
+    # Create an object with default values for all parameters
+    oct = Octagon.new
+    oct.x # => 0
+    oct.y # => 0.5
+    oct.opacity # => 0.25
+  
+    # Create an object with the given parameter values.
+    oct = Octagon.new(:radius => 10)
+    oct.radius # => 10
+    oct.opacity # => 0.7
+  
+    # Set parameter values of a class
+    Octagon.radius = 33
+    Octagon.opacity = 0.3
+  
+    # Create an object with parameter defaulte values inherited from the
+    # class parameters
+    oct = Octagon.new
+    oct.radius # => 33
+    oct.opacity # => 0.3
+
+    # Coerce data from the command-line into the given parameter type
+    oct.radius = ARGV[2]
+    oct.radius # => 89.455
+
+## Install
+
+    $ sudo gem install parameters
+
+## License
+
+See {file:LICENSE.txt} for license information.
+

data/Rakefile

@@ -1,23 +1,41 @@
-# -*- ruby -*-
-
 require 'rubygems'
-require 'hoe'
-require 'hoe/signing'
+require 'rake'
+require './lib/parameters/version.rb'
 
-Hoe.plugin :yard
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gem|
+    gem.name = 'parameters'
+    gem.version = Parameters::VERSION
+    gem.summary = %Q{Allows you to add annotated variables to your classes}
+    gem.description = %Q{Parameters allows you to add annotated variables to your classes which may have configurable default values.}
+    gem.email = 'postmodern.mod3@gmail.com'
+    gem.homepage = 'http://github.com/postmodern/parameters'
+    gem.authors = ['Postmodern']
+    gem.add_development_dependency 'rspec', '>= 1.3.0'
+    gem.add_development_dependency 'yard', '>= 0.5.3'
+    gem.has_rdoc = 'yard'
+  end
+rescue LoadError
+  puts "Jeweler (or a dependency) not available. Install it with: gem install jeweler"
+end
 
-Hoe.spec('parameters') do
-  self.developer('Postmodern','postmodern.mod3@gmail.com')
+require 'spec/rake/spectask'
+Spec::Rake::SpecTask.new(:spec) do |spec|
+  spec.libs += ['lib', 'spec']
+  spec.spec_files = FileList['spec/**/*_spec.rb']
+  spec.spec_opts = ['--options', '.specopts']
+end
 
-  self.rspec_options += ['--colour', '--format', 'specdoc']
+task :spec => :check_dependencies
+task :default => :spec
 
-  self.yard_options += ['--protected']
-  self.remote_yard_dir = '/'
+begin
+  require 'yard'
 
-  self.extra_dev_deps += [
-    ['rspec', '>=1.3.0'],
-    ['yard', '>=0.5.3']
-  ]
+  YARD::Rake::YardocTask.new
+rescue LoadError
+  task :yard do
+    abort "YARD is not available. In order to run yard, you must: gem install yard"
+  end
 end
-
-# vim: syntax=Ruby

data/lib/parameters/class_methods.rb

@@ -43,12 +43,15 @@ module Parameters
     # @param [Hash] options
     #   Additional options.
     #
-    # @option options [String] :description
-    #   The description for the new parameter.
+    # @option options [Class, Array[Class]] :type
+    #   The type to enforce the parameter values to.
     #
     # @option options [Object, Proc] :default
     #   The default value for the new parameter.
     #
+    # @option options [String] :description
+    #   The description for the new parameter.
+    #
     # @example
     #   parameter 'var'
     #
@@ -59,7 +62,12 @@ module Parameters
       name = name.to_sym
 
       # add the parameter to the class params list
-      params[name] = Parameters::ClassParam.new(name,options[:description],options[:default])
+      params[name] = Parameters::ClassParam.new(
+        name,
+        options[:type],
+        options[:description],
+        options[:default]
+      )
 
       # define the reader class method for the parameter
       meta_def(name) do

data/lib/parameters/class_param.rb

@@ -4,7 +4,7 @@ module Parameters
   class ClassParam < Param
 
     # Default value of the class parameter
-    attr_accessor :value
+    attr_reader :value
 
     #
     # Creates a new ClassParam object.
@@ -12,18 +12,36 @@ module Parameters
     # @param [Symbol, String] name
     #   The name of the class parameter.
     #
+    # @param [Class, Array[Class]] type
+    #   The enforced type of the class parameter.
+    #
     # @param [String, nil] description
     #   The description of the class parameter.
     #
     # @param [Object, nil] value
     #   The default value of the class parameter.
     #
-    def initialize(name,description=nil,value=nil)
-      super(name,description)
+    def initialize(name,type=nil,description=nil,value=nil)
+      super(name,type,description)
 
       @value = value
     end
 
+    #
+    # Sets the value of the class param.
+    #
+    # @param [Object] value
+    #   The new value of the class param.
+    #
+    # @return [Object]
+    #   The new value of the class param.
+    #
+    # @since 0.2.0
+    #
+    def value=(new_value)
+      @value = coerce(new_value)
+    end
+
     #
     # @return [String]
     #   The representation of the class param.

data/lib/parameters/instance_param.rb

@@ -1,3 +1,5 @@
+require 'parameters/param'
+
 module Parameters
   class InstanceParam < Param
 
@@ -14,11 +16,14 @@ module Parameters
     # @param [Symbol, String] name
     #   The name of the instance parameter.
     #
+    # @param [Class, Array[Class]] type
+    #   The enforced type of the instance parameter.
+    #
     # @param [String, nil] description
     #   The description of the instance parameter.
     #
-    def initialize(object,name,description=nil)
-      super(name,description)
+    def initialize(object,name,type=nil,description=nil)
+      super(name,type,description)
 
       @object = object
     end
@@ -28,7 +33,7 @@ module Parameters
     #   The value of the instance param.
     #
     def value
-      @object.instance_variable_get("@#{@name}".to_sym)
+      @object.instance_variable_get(:"@#{@name}")
     end
 
     #
@@ -41,7 +46,7 @@ module Parameters
     #   The new value of the instance param.
     #
     def value=(value)
-      @object.instance_variable_set("@#{@name}".to_sym,value)
+      @object.instance_variable_set(:"@#{@name}",coerce(value))
     end
 
     #

data/lib/parameters/param.rb

@@ -1,9 +1,16 @@
+require 'set'
+require 'uri'
+require 'date'
+
 module Parameters
   class Param
 
     # Name of parameter
     attr_reader :name
 
+    # Enforced type of the parameter
+    attr_reader :type
+
     # Description of parameter
     attr_reader :description
 
@@ -13,13 +20,321 @@ module Parameters
     # @param [Symbol, String] name
     #   The name of the parameter.
     #
+    # @param [Class] type
+    #   The enforced type of the parameter.
+    #
     # @param [String, nil] description
     #   The description of the parameter.
     #
-    def initialize(name,description=nil)
+    def initialize(name,type=nil,description=nil)
       @name = name.to_sym
+      @type = type
       @description = description
     end
 
+    protected
+
+    # Type classes and their coercion methods
+    TYPE_COERSION = {
+      Set => :coerce_set,
+      Array => :coerce_array,
+      URI => :coerce_uri,
+      Regexp => :coerce_regexp,
+      DateTime => :coerce_date,
+      Date => :coerce_date,
+      Symbol => :coerce_symbol,
+      String => :coerce_string,
+      Integer => :coerce_integer,
+      Float => :coerce_float,
+      true => :coerce_boolean
+    }
+
+    #
+    # Coerces a given value into a specific type.
+    #
+    # @param [Class] type
+    #   The type to coerce the value into.
+    #
+    # @param [Object] value
+    #   The value to coerce.
+    #
+    # @return [Object]
+    #   The coerced value.
+    #
+    # @since 0.2.0
+    #
+    def coerce_type(type,value)
+      if value.nil?
+        nil
+      elsif type.kind_of?(Set)
+        coerce_array(Array,value).map { |element|
+          coerce_type(type.first,element)
+        }.to_set
+      elsif type.kind_of?(Array)
+        coerce_array(Array,value).map do |element|
+          coerce_type(type.first,element)
+        end
+      elsif (method_name = TYPE_COERSION[type])
+        self.send(method_name,type,value)
+      else
+        value
+      end
+    end
+
+    #
+    # Coerces a given value into the `type` of the param.
+    #
+    # @param [Object] value
+    #   The value to coerce.
+    #
+    # @return [Object]
+    #   The coerced value.
+    #
+    # @since 0.2.0
+    #
+    def coerce(value)
+      coerce_type(@type,value)
+    end
+
+    #
+    # Coerces a given value into a `Set`.
+    #
+    # @param [Set[Class]] type
+    #   An optional `Set` containing the type to coerce the elements
+    #   of the given value to.
+    #
+    # @param [Enumerable, Object] value
+    #   The value to coerce into a `Set`.
+    #
+    # @return [Set]
+    #   The coerced value.
+    #
+    # @since 0.2.0
+    #
+    def coerce_set(type,value)
+      if value.kind_of?(Set)
+        value
+      elsif (value.kind_of?(Enumerable) || value.respond_to?(:to_set))
+        value.to_set
+      else
+        Set[value]
+      end
+    end
+
+    #
+    # Coerces a given value into an `Array`.
+    #
+    # @param [Array[Class]] type
+    #   An optional `Array` containing the type to coerce the elements
+    #   of the given value to.
+    #
+    # @param [Enumerable, Object] value
+    #   The value to coerce into an `Array`.
+    #
+    # @return [Array]
+    #   The coerced value.
+    #
+    # @since 0.2.0
+    #
+    def coerce_array(type,value)
+      if value.kind_of?(Array)
+        value
+      elsif (value.kind_of?(Enumerable) || value.respond_to?(:to_a))
+        value.to_a
+      else
+        [value]
+      end
+    end
+
+    #
+    # Coerces a given value into a `URI`.
+    #
+    # @param [Class] type
+    #   The `URI` type to coerce to.
+    #
+    # @param [URI::Generic, #to_s] value
+    #   The value to coerce into a `URI`.
+    #
+    # @return [URI::Generic]
+    #   The coerced value.
+    #
+    # @since 0.2.0
+    #
+    def coerce_uri(type,value)
+      if value.kind_of?(type)
+        value
+      else
+        URI.parse(value.to_s)
+      end
+    end
+
+    #
+    # Coerces a given value into a `Regexp`.
+    #
+    # @param [Class] type
+    #   The `Regexp` type to coerce to.
+    #
+    # @param [Regexp, #to_s] value
+    #   The value to coerce into a `Regexp`.
+    #
+    # @return [Regexp]
+    #   The coerced value.
+    #
+    # @since 0.2.0
+    #
+    def coerce_regexp(type,value)
+      if value.kind_of?(Regexp)
+        value
+      else
+        Regexp.new(value.to_s)
+      end
+    end
+
+    #
+    # Coerces a given value into a `Symbol`.
+    #
+    # @param [Class] type
+    #   The `Symbol` class.
+    #
+    # @param [#to_s] value
+    #   The value to coerce.
+    #
+    # @return [Symbol]
+    #   The coerced value.
+    #
+    # @since 0.2.0
+    #
+    def coerce_symbol(type,value)
+      if value.kind_of?(type)
+        value
+      else
+        value.to_s.to_sym
+      end
+    end
+
+    #
+    # Coerces a given value into a `String`.
+    #
+    # @param [Class] type
+    #   The `String` class.
+    #
+    # @param [#to_s] value
+    #   The value to coerce into a `String`.
+    #
+    # @return [String]
+    #   The coerced value.
+    #
+    # @since 0.2.0
+    #
+    def coerce_string(type,value)
+      if value.kind_of?(type)
+        value
+      else
+        value.to_s
+      end
+    end
+
+    #
+    # Coerces a given value into an `Integer`.
+    #
+    # @param [Class]
+    #   The Integer class.
+    #
+    # @param [String, #to_i] value
+    #   The value to coerce into an `Integer`.
+    #
+    # @return [Integer]
+    #   The coerced value.
+    #
+    # @since 0.2.0
+    #
+    def coerce_integer(type,value)
+      if value.kind_of?(type)
+        value
+      elsif value.kind_of?(String)
+        base = if value[0..1] == '0x'
+                 16
+               elsif value[0..0] == '0'
+                 8
+               else
+                 10
+               end
+
+        value.to_i(base)
+      elsif value.respond_to?(:to_i)
+        value.to_i
+      else
+        0
+      end
+    end
+
+    #
+    # Coerces a given value into a `Float`.
+    #
+    # @param [Class] type
+    #   The `Float` class.
+    #
+    # @param [String, #to_f] value
+    #   The value to coerce into a `Float`.
+    #
+    # @return [Float]
+    #   The coerced value.
+    #
+    # @since 0.2.0
+    #
+    def coerce_float(type,value)
+      if value.kind_of?(type)
+        value
+      elsif (value.kind_of?(String) || value.respond_to?(:to_f))
+        value.to_f
+      else
+        0.0
+      end
+    end
+
+    #
+    # Coerces a given value into a `DateTime` or `Date`.
+    #
+    # @param [Class] type
+    #   The `DateTime` or `Date` class.
+    #
+    # @param [#to_s] value
+    #   The value to coerce into either a `Date` or `DateTime` object.
+    #
+    # @return [DateTime, Date]
+    #   The coerced value.
+    #
+    # @since 0.2.0
+    #
+    def coerce_date(type,value)
+      if value.kind_of?(type)
+        value
+      else
+        type.parse(value.to_s)
+      end
+    end
+
+    #
+    # Coerces a given value into either a `true` or `false` value.
+    #
+    # @param [true] type
+    #
+    # @param [TrueClass, FalseClass, String, Symbol] value
+    #   The value to coerce into either a `true` or `false` value.
+    #
+    # @return [TrueClass, FalseClass]
+    #   The coerced value.
+    #
+    # @since 0.2.0
+    #
+    def coerce_boolean(type,value)
+      case value
+      when FalseClass, NilClass, 'false', :false
+        false
+      else
+        true
+      end
+    end
+
   end
 end