parameters 0.1.0

data/History.txt

@@ -0,0 +1,7 @@
+=== 0.1.0 / 2008-12-03
+
+* Initial release.
+* Added Parameters.params= and Parameters#params= methods.
+* Allow Parameters#initialize to accept a Hash of parameter values.
+* Added more specs.
+

data/Manifest.txt

@@ -0,0 +1,19 @@
+History.txt
+Manifest.txt
+README.txt
+Rakefile
+lib/parameters.rb
+lib/parameters/exceptions.rb
+lib/parameters/exceptions/missing_param.rb
+lib/parameters/exceptions/param_not_found.rb
+lib/parameters/extensions.rb
+lib/parameters/extensions/meta.rb
+lib/parameters/extensions/meta/object.rb
+lib/parameters/class_param.rb
+lib/parameters/instance_param.rb
+lib/parameters/param.rb
+lib/parameters/parameters.rb
+lib/parameters/version.rb
+tasks/spec.rb
+spec/spec_helper.rb
+spec/parameters_spec.rb

data/README.txt

@@ -0,0 +1,70 @@
+= Parameters
+
+* http://parameters.rubyforge.org/
+* https://github.com/postmodern/parameters/tree
+* Postmodern (postmodern.mod3 at gmail.com)
+
+== DESCRIPTION:
+
+Parameters allows you to add annoted variables to your classes which may
+have configurable default values.
+
+== FEATURES:
+
+* Give parameters default values.
+* Change default values of parameters.
+* Give descriptions to parameters.
+
+== EXAMPLES:
+
+  class Octagon
+  
+    include Parameters
+  
+    parameter :x, :value => 0
+  
+    parameter :y, :value => 0.5
+  
+    parameter :radius, :description => 'The radius of the Octagon'
+  
+  end
+  
+  oct = Octagon.new
+  oct.x # => 0
+  oct.y # => 0.5
+  
+  oct = Octagon.new(:radius => 10)
+  oct.radius # => 10
+  
+  Octagon.radius = 33
+  oct = Octagon.new
+  oct.radius # => 33
+
+== INSTALL:
+
+  $ sudo gem install parameters
+
+== LICENSE:
+
+The MIT License
+
+Copyright (c) 2008 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/Rakefile

@@ -0,0 +1,14 @@
+# -*- ruby -*-
+
+require 'rubygems'
+require 'hoe'
+require './tasks/spec.rb'
+require './lib/parameters/version.rb'
+
+Hoe.new('parameters', Parameters::VERSION) do |p|
+  p.rubyforge_name = 'parameters'
+  p.developer('Postmodern','postmodern.mod3@gmail.com')
+  p.remote_rdoc_dir = '/'
+end
+
+# vim: syntax=Ruby

data/lib/parameters.rb

@@ -0,0 +1,4 @@
+require 'parameters/param'
+require 'parameters/class_param'
+require 'parameters/instance_param'
+require 'parameters/parameters'

data/lib/parameters/class_param.rb

@@ -0,0 +1,20 @@
+require 'parameters/param'
+
+module Parameters
+  class ClassParam < Param
+
+    # Default value of the class parameter
+    attr_accessor :value
+
+    #
+    # Creates a new ClassParam object with the specified _name_,
+    # given _description_ and _value_.
+    #
+    def initialize(name,description='',value=nil)
+      super(name,description)
+
+      @value = value
+    end
+
+  end
+end

data/lib/parameters/exceptions.rb

@@ -0,0 +1,2 @@
+require 'parameters/exceptions/param_not_found'
+require 'parameters/exceptions/missing_param'

data/lib/parameters/exceptions/missing_param.rb

@@ -0,0 +1,4 @@
+module Parameters
+  class MissingParam < RuntimeError
+  end
+end

data/lib/parameters/exceptions/param_not_found.rb

@@ -0,0 +1,4 @@
+module Parameters
+  class ParamNotFound < RuntimeError
+  end
+end

data/lib/parameters/extensions.rb

@@ -0,0 +1 @@
+require 'parameters/extensions/meta'

data/lib/parameters/extensions/meta.rb

@@ -0,0 +1 @@
+require 'parameters/extensions/meta/object'

data/lib/parameters/extensions/meta/object.rb

@@ -0,0 +1,24 @@
+# metaprogramming assistant -- metaid.rb
+class Object # :nodoc:
+  # The hidden singleton lurks behind everyone
+  def metaclass; class << self; self; end; end
+  def meta_eval(&blk); metaclass.instance_eval(&blk); end
+
+  # A class_eval version of meta_eval
+  def metaclass_eval(&blk); metaclass.class_eval(&blk); end
+
+  # A class_def version of meta_def
+  def metaclass_def(name, &blk)
+    metaclass_eval { define_method(name, &blk) }
+  end
+  
+  # Adds methods to a metaclass
+  def meta_def(name, &blk)
+    meta_eval { define_method(name, &blk) }
+  end
+  
+  # Defines an instance method within a class
+  def class_def(name, &blk)
+    class_eval { define_method(name, &blk) }
+  end
+end

data/lib/parameters/instance_param.rb

@@ -0,0 +1,39 @@
+module Parameters
+  class InstanceParam < Param
+
+    # Owning object
+    attr_reader :object
+
+    #
+    # Creates a new InstanceParam object with the specified _object_ and
+    # _name_, and the given _description_.
+    #
+    def initialize(object,name,description='')
+      super(name,description)
+
+      @object = object
+    end
+
+    #
+    # Returns the value of the instance param.
+    #
+    def value
+      @object.instance_variable_get("@#{@name}")
+    end
+
+    #
+    # Sets the value of the instance param.
+    #
+    def value=(value)
+      @object.instance_variable_set("@#{@name}",value)
+    end
+
+    #
+    # Inspects the instance params value.
+    #
+    def inspect
+      value.inspect
+    end
+
+  end
+end

data/lib/parameters/param.rb

@@ -0,0 +1,20 @@
+module Parameters
+  class Param
+
+    # Name of parameter
+    attr_reader :name
+
+    # Description of parameter
+    attr_reader :description
+
+    #
+    # Creates a new Param object with the specified _name_ and the given
+    # _description_.
+    #
+    def initialize(name,description='')
+      @name = name.to_sym
+      @description = description
+    end
+
+  end
+end

data/lib/parameters/parameters.rb

@@ -0,0 +1,290 @@
+require 'parameters/class_param'
+require 'parameters/instance_param'
+require 'parameters/exceptions'
+require 'parameters/extensions/meta'
+
+module Parameters
+  def self.included(base) # :nodoc:
+    base.metaclass_eval do
+      #
+      # Returns the +Hash+ of parameters for the class.
+      #
+      def params
+        @params ||= {}
+      end
+
+      #
+      # Sets the values of the class parameters described in the
+      # _values_ +Hash+.
+      #
+      #   Test.params = {:x => 5, :y => 2}
+      #   # => {:x=>5, :y=>2}
+      #
+      def params=(values)
+        values.each do |name,value|
+          if has_param?(name)
+            get_param(name).value = value
+          end
+        end
+      end
+
+      #
+      # Adds a new parameters with the specified _name_ and the given
+      # _options_ to the Class.
+      #
+      # _options_ may contain the following keys:
+      # <tt>:description</tt>:: The description of the parameter.
+      # <tt>:default</tt>:: The default value the parameter will have.
+      #
+      #   parameter 'var'
+      #
+      #   parameter 'var', :default => 3, :description => 'my variable' 
+      #
+      def parameter(name,options={})
+        name = name.to_sym
+
+        # add the parameter to the class params list
+        params[name] = Parameters::ClassParam.new(name,options[:description],options[:default])
+
+        # define the reader class method for the parameter
+        meta_def(name) do
+          params[name].value
+        end
+
+        # define the writer class method for the parameter
+        meta_def("#{name}=") do |value|
+          params[name].value = value
+        end
+
+        # define the getter/setter instance methods for the parameter
+        attr_accessor(name)
+      end
+
+      #
+      # Returns the class parameter with the specified _name_. If no
+      # such class parameter exists, a ParamNotFound exception will be
+      # raised.
+      #
+      def get_param(name)
+        name = name.to_sym
+
+        ancestors.each do |ancestor|
+          if ancestor.include?(Parameters)
+            if ancestor.params.has_key?(name)
+              return ancestor.params[name]
+            end
+          end
+        end
+
+        raise(ParamNotFound,"parameter #{name.to_s.dump} was not found in class #{self.name.dump}",caller)
+      end
+
+      #
+      # Returns +true+ if a class parameters with the specified _name_
+      # exists, returns +false+ otherwise.
+      #
+      def has_param?(name)
+        name = name.to_sym
+
+        ancestors.each do |ancestor|
+          if ancestor.include?(Parameters)
+            return true if ancestor.params.has_key?(name)
+          end
+        end
+
+        return false
+      end
+
+      #
+      # Iterates over all class parameters, passing each one to the
+      # specified _block_.
+      #
+      def each_param(&block)
+        ancestors.each do |ancestor|
+          if ancestor.include?(Parameters)
+            ancestor.params.each_value(&block)
+          end
+        end
+
+        return self
+      end
+
+      #
+      # Returns the description of the class parameters with the
+      # specified _name_. If no such class parameter exists, a
+      # ParamNotFound exception will be raised.
+      #
+      def describe_param(name)
+        get_param(name).description
+      end
+
+      #
+      # Returns the value of the class parameters with the specified
+      # _name_. If no such class parameter exists, a ParamNotFound
+      # exception will be raised.
+      #
+      def param_value(name)
+        get_param(name).value
+      end
+    end
+  end
+
+  #
+  # Initalizes the parameters of the object using the given
+  # _values_, which can override the default values of
+  # parameters.
+  #
+  def initialize_parameters
+    self.class.each_param do |param|
+      # do not override existing instance value if present
+      unless instance_variable_get("@#{param.name}")
+        begin
+          value = param.value.clone
+        rescue TypeError
+          value = param.value
+        end
+
+        instance_variable_set("@#{param.name}",value)
+      end
+
+      params[param.name] = InstanceParam.new(self,param.name,param.description)
+    end
+  end
+
+  #
+  # Initializes the parameters using initialize_parameters. If a +Hash+
+  # is passed in as the first argument, it will be used to set the values
+  # of parameters described within the Hash.
+  #
+  def initialize(*args,&block)
+    initialize_parameters
+
+    values = args.first
+
+    if values.kind_of?(Hash)
+      self.params = values
+    end
+  end
+
+  #
+  # Adds a new parameters with the specified _name_ and the given
+  # _options_ to the object.
+  #
+  # _options_ may contain the following keys:
+  # <tt>:description</tt>:: The description of the parameter.
+  # <tt>:default</tt>:: The default value the parameter will have.
+  #
+  #   obj.parameter('var')
+  #
+  #   obj.parameter('var',:default => 3, :description => 'my variable')
+  #
+  def parameter(name,options={})
+    name = name.to_sym
+
+    # set the instance variable
+    instance_variable_set("@#{name}",options[:default])
+
+    # add the new parameter
+    params[name] = InstanceParam.new(self,name,options[:description])
+
+    instance_eval %{
+      # define the reader method for the parameter
+      def #{name}
+        instance_variable_get("@#{name}")
+      end
+
+      # define the writer method for the parameter
+      def #{name}=(value)
+        instance_variable_set("@#{name}",value)
+      end
+    }
+
+    return params[name]
+  end
+
+  #
+  # Returns a +Hash+ of the classes params.
+  #
+  def class_params
+    self.class.params
+  end
+
+  #
+  # Returns a +Hash+ of the instance parameters.
+  #
+  def params
+    @params ||= {}
+  end
+
+  #
+  # Sets the values of the parameters described in the _values_ +Hash+.
+  #
+  #   obj.params = {:x => 5, :y => 2}
+  #   # => {:x=>5, :y=>2}
+  #
+  def params=(values)
+    values.each do |name,value|
+      if has_param?(name)
+        instance_variable_set("@#{name}",value)
+      end
+    end
+  end
+
+  #
+  # Returns +true+ if the a parameter with the specified _name_ exists,
+  # returns +false+ otherwise.
+  #
+  #   obj.has_param?('rhost') # => true
+  #
+  def has_param?(name)
+    params.has_key?(name.to_sym)
+  end
+
+  #
+  # Returns the parameter with the specified _name_. If no such parameter
+  # exists, a ParamNotFound exception will be raised.
+  #
+  #   obj.get_param('var') # => InstanceParam
+  #
+  def get_param(name)
+    name = name.to_sym
+
+    unless has_param?(name)
+      raise(ParamNotFound,"parameter #{name.to_s.dump} was not found within #{self.to_s.dump}",caller)
+    end
+
+    return params[name]
+  end
+
+  #
+  # Returns the description of the parameter with the specified _name_.
+  # If no such parameter exists, a ParamNotFound exception will be raised.
+  #
+  #   obj.describe_param('rhost') # => "remote host"
+  #
+  def describe_param(name)
+    get_param(name).description
+  end
+
+  #
+  # Returns the value of the parameter with the specified _name_. If no
+  # such parameter exists, a ParamNotFound exception will be raised.
+  #
+  #   obj.param_value('rhost') # => 80
+  #
+  def param_value(name)
+    get_param(name).value
+  end
+
+  #
+  # Sets the values of the parameters listed in the specified _values_.
+  #
+  #   obj.set_params(:rhost => 'www.example.com', :rport => 80)
+  #   # => {:rhost=>"www.example.com", :rport=>80}
+  #
+  def set_params(values={})
+    values.each do |name,value|
+      get_param(name).value = value
+    end
+  end
+end

data/lib/parameters/version.rb

@@ -0,0 +1,3 @@
+module Parameters
+  VERSION = '0.1.0'
+end

data/spec/parameters_spec.rb

@@ -0,0 +1,129 @@
+require 'parameters'
+
+require 'spec_helper'
+
+describe Parameters do
+  before(:all) do
+    class TestParameters
+      include Parameters
+
+      parameter :var, :description => 'Test parameter'
+
+      parameter :var_with_default,
+                :default => 'thing',
+                :description => 'This parameter has a default value'
+
+    end
+
+    class InheritedParameters < TestParameters
+
+      parameter :child_var, :description => 'Child parameter'
+
+    end
+  end
+
+  describe "in a Class" do
+    it "should provide parameters" do
+      TestParameters.params.should_not be_empty
+    end
+
+    it "can have default values for parameters" do
+      TestParameters.param_value(:var_with_default).should == 'thing'
+    end
+
+    it "should provide class methods for paremters" do
+      TestParameters.var = 1
+      TestParameters.var.should == 1
+    end
+
+    it "should inherite the super-classes parameters" do
+      InheritedParameters.has_param?(:var).should == true
+      InheritedParameters.has_param?(:child_var).should == true
+    end
+
+    it "should provide direct access to the parameter objects" do
+      param = TestParameters.get_param(:var)
+
+      param.should_not be_nil
+      param.name.should == :var
+    end
+
+    it "raise a ParamNotFound exception when directly accessing non-existent parameter objects" do
+      lambda { TestParameters.get_param(:unknown) }.should raise_error(Parameters::ParamNotFound)
+    end
+
+    it "should provide descriptions for parameters" do
+      TestParameters.describe_param(:var).should_not be_empty
+    end
+
+    it "should be able to create an object with initial parameter values" do
+      obj = TestParameters.new(:var => 2, :var_with_default => 'stuff')
+
+      obj.var.should == 2
+      obj.var_with_default.should == 'stuff'
+    end
+  end
+
+  describe "in an Object" do
+    before(:all) do
+      @test = TestParameters.new
+      @test_inherited = InheritedParameters.new
+    end
+
+    it "should provide direct access to all parameters" do
+      @test.params[:var].should_not be_nil
+      @test.params[:var_with_default].should_not be_nil
+    end
+
+    it "should allow for mass assignment of parameters" do
+      test2 = TestParameters.new
+      test2.params = {:var => 5, :var_with_default => 'hello'}
+
+      test2.var.should == 5
+      test2.var_with_default.should == 'hello'
+    end
+
+    it "can have default values for parameters" do
+      @test.param_value(:var_with_default).should == 'thing'
+    end
+
+    it "should provide instance methods for parameters" do
+      @test.var = 2
+      @test.var.should == 2
+    end
+
+    it "should set instance variables for paramters" do
+      @test.instance_variable_get('@var_with_default').should == 'thing'
+
+      @test.var = 3
+      @test.instance_variable_get('@var').should == 3
+    end
+
+    it "should contain the parameters from all ancestors" do
+      @test_inherited.has_param?(:var).should == true
+      @test_inherited.has_param?(:child_var).should == true
+    end
+
+    it "should provide direct access to the parameter objects" do
+      @param = @test.get_param(:var)
+
+      @param.should_not be_nil
+      @param.name.should == :var
+    end
+
+    it "should raise a ParamNotFound exception when directly accessing non-existent parameter objects" do
+      lambda { @test.get_param(:unknown) }.should raise_error(Parameters::ParamNotFound)
+    end
+
+    it "should allow for setting parameters en-mass" do
+      @test.set_params(:var => 3, :var_with_default => 7)
+
+      @test.param_value(:var).should == 3
+      @test.param_value(:var_with_default).should == 7
+    end
+
+    it "should provide descriptions for parameters" do
+      @test.describe_param(:var).should_not be_empty
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,5 @@
+require 'rubygems'
+gem 'rspec', '>=1.1.3'
+require 'spec'
+
+require 'parameters/version'

data/tasks/spec.rb

@@ -0,0 +1,9 @@
+require 'spec/rake/spectask'
+
+desc "Run all specifications"
+Spec::Rake::SpecTask.new(:spec) do |t|
+  t.libs += ['lib', 'spec']
+  t.spec_opts = ['--colour', '--format', 'specdoc']
+end
+
+task :default => :spec

metadata

@@ -0,0 +1,84 @@
+--- !ruby/object:Gem::Specification 
+name: parameters
+version: !ruby/object:Gem::Version 
+  version: 0.1.0
+platform: ruby
+authors: 
+- Postmodern
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2008-12-03 00:00:00 -08:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: hoe
+  type: :development
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 1.8.2
+    version: 
+description: Parameters allows you to add annoted variables to your classes which may have configurable default values.
+email: 
+- postmodern.mod3@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- History.txt
+- Manifest.txt
+- README.txt
+files: 
+- History.txt
+- Manifest.txt
+- README.txt
+- Rakefile
+- lib/parameters.rb
+- lib/parameters/exceptions.rb
+- lib/parameters/exceptions/missing_param.rb
+- lib/parameters/exceptions/param_not_found.rb
+- lib/parameters/extensions.rb
+- lib/parameters/extensions/meta.rb
+- lib/parameters/extensions/meta/object.rb
+- lib/parameters/class_param.rb
+- lib/parameters/instance_param.rb
+- lib/parameters/param.rb
+- lib/parameters/parameters.rb
+- lib/parameters/version.rb
+- tasks/spec.rb
+- spec/spec_helper.rb
+- spec/parameters_spec.rb
+has_rdoc: true
+homepage: http://parameters.rubyforge.org/
+post_install_message: 
+rdoc_options: 
+- --main
+- README.txt
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: parameters
+rubygems_version: 1.3.1
+signing_key: 
+specification_version: 2
+summary: Parameters allows you to add annoted variables to your classes which may have configurable default values.
+test_files: []
+