namedarguments 0.0.1

data/History.txt

@@ -0,0 +1,4 @@
+== 0.0.1 / 2006-12-04
+
+* 1 major enhancement
+  * L� breithe!

data/Manifest.txt

@@ -0,0 +1,10 @@
+History.txt
+Manifest.txt
+README.txt
+Rakefile
+bin/named_arguments
+lib/named_arguments.rb
+lib/hash_extended_tools.rb
+lib/singleton_creator_mixin.rb
+lib/class_settings_mixin.rb
+test/test_named_arguments.rb

data/README.txt

@@ -0,0 +1,52 @@
+NamedArguments
+    by James M. Moore
+
+== DESCRIPTION:
+
+Adds the ability to call class constructors with a hash of arguments to
+initialize attributes in the new object.
+
+== FEATURES/PROBLEMS:
+  
+  class Snark
+    include NamedArguments
+    
+    attr_accessor :color, :size, :name
+    
+    attribute_defaults :color => 'blue', :size => lambda {|s| some_method_call(s)}
+    required_fields :color, :name
+    required_respond_to :name => :to_s
+    required_kind_of? :size => Fixnum
+    type_conversion :size => Fixnum
+  end
+
+  s = Snark.new :boojum => 7, :color => red
+
+== INSTALL:
+
+gem install namedarguments
+
+== LICENSE:
+
+(The MIT License)
+
+Copyright (c) 2006 James M. Moore
+
+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,12 @@
+require 'rubygems'
+require 'hoe'
+require './lib/named_arguments.rb'
+
+Hoe.new('namedarguments', NamedArguments::VERSION) do |p|
+  p.summary = 'Provide named arguments (hashes) to constructors to initialize attributes.'
+  p.author = "James M Moore"
+  p.email = 'james@phonesonrails.com'
+  p.description = p.paragraphs_of('README.txt', 2..5).join("\n\n")
+  # p.url = p.paragraphs_of('README.txt', 0).first.split(/\n/)[1..-1]
+  p.changes = p.paragraphs_of('History.txt', 0..1).join("\n\n")
+end

data/lib/class_settings_mixin.rb

@@ -0,0 +1,113 @@
+require File.dirname(__FILE__) + '/singleton_creator_mixin'
+
+module ClassSettingsMixin
+  def self.included target
+    target.send :extend, ClassSettingsMixinClassMethods
+  end
+end
+
+module ClassSettingsMixinClassMethods
+  include SingletonMethodCreatorMixin
+  
+  # Allow you to define 
+  # methods that set a class value hash
+  # and an accessor for that hash.
+  # 
+  # Example:
+  # 
+  #   create_class_settings_method :settings
+  # 
+  # creates:
+  # 
+  # settings:: A class method that allows
+  #            you to set variables
+  # settings?:: The current value of those variables
+  # 
+  #   class BlueCar
+  #     create_class_settings_method :settings
+  #     create_class_settings_method :has_these
+  #   
+  #     settings :color => :blue, :another_settting => 10
+  #     settings :painted => true
+  #     has_these :doors, :windows
+  #     has_these :wheels
+  #   end
+  # 
+  #   class Convertable < BlueCar
+  #     has_these :poptop
+  #   end
+  # 
+  #   BlueCar.color
+  #     => :blue
+  # 
+  #   BlueCar.new.settings?
+  #     => {:color => :blue, :painted => true, :another_settting => 10}
+  def create_class_settings_method name
+    # Build the class methods first
+    l = class_setting_lambda name
+    create_singleton_method name, l
+    
+    # Allow #name? to be called as an instance method
+    # and default its return value to nil.
+    # This will be replaced on any call to the 
+    # setter.
+    value_name = value_field_identifier(name)
+    instance_method = lambda {nil}
+    define_method value_name, instance_method
+  end
+  
+  protected 
+  
+  # Returns a lambda that will create
+  # two methods:
+  # 
+  # A singleton method on the current object
+  #   that takes multiple parameters and 
+  #   stores their values.  This allows
+  #   you to define methods on the class
+  #   that will save their parameters.
+  # An instance method that returns those
+  #   saved parameters
+  def class_setting_lambda name #:nodoc:
+    value_field_id = value_field_identifier name
+    result = lambda do
+      # Note that this lambda is called
+      # either with a single argument
+      # containing a hash, or an array 
+      # of arguments.
+      |*args|
+      
+      if args.first.kind_of? Hash
+        args = args.first
+      end
+      
+      begin
+        current_value = self.send value_field_id
+        case current_value
+        when Array then val = merge_arrays_of_symbols current_value, args
+        when Hash then val = current_value.merge args
+        else
+          raise RuntimeError.new("Attempting to merge two different kinds of data")
+        end
+      rescue NoMethodError
+        val = args
+      end
+      
+      # Define the class method
+      create_singleton_value_method value_field_id, val
+      
+      # Define the instance method
+      define_method value_field_id, lambda {val}
+    end
+    result
+  end
+  
+  def value_field_identifier name #:nodoc:
+    return "#{name}?"
+  end
+  
+  def merge_arrays_of_symbols a, b #:nodoc:
+    result = a.map(&:to_sym) + b.map(&:to_sym)
+    result.uniq
+  end
+end

data/lib/hash_extended_tools.rb

@@ -0,0 +1,81 @@
+# Provides several hash utilities.
+# 
+# Note that you need to extend your hash with this module:
+# 
+#   hash = {}
+#   hash.extend HashExtendedTools
+#   hash = hash.exclude :foo, :bar
+# 
+# Or create a new class:
+# 
+#   class HashWithExtendedTools < Hash
+#     include HashExtendedTools
+#   end
+module HashExtendedTools
+  # Change keys in a hash.
+  # 
+  # Pass in a hash of:
+  # 
+  #   old_key => new_key
+  # 
+  # Any keys matching +old_key+ will be
+  # deleted and a new entry created with
+  # the same value and the new key.
+  def switch_keys args = {}
+    args.each_pair do
+      |old_key, new_key|
+      if self.has_key?(old_key)
+        self[new_key] = self[old_key]
+        delete(old_key)
+      end
+    end
+  end
+  
+  # Return a new hash not including
+  # keys that are contained in 
+  # +keys_to_exclude+.
+  # 
+  # Keys that match entries in 
+  # +keys_to_exclude+ are deleted if
+  # either they match as string or a 
+  # symbol (created with to_sym).
+  def exclude *keys_to_exclude
+    result = self.dup
+    keys_to_exclude.each do |k|
+      result.delete k.to_s
+      result.delete k.to_sym
+    end
+    result
+  end
+  
+  # Given an array of keys,
+  # return a hash containing
+  # the key/value pairs
+  # for the matching keys.
+  # 
+  # Values that are nil are not
+  # returned.
+  def slice *slice_keys
+    result = {}
+    slice_keys.each do |k|
+      result[k] = self[k] unless self[k].nil?
+    end
+    result
+  end
+  
+  # Return the given attributes as a hash containing
+  # attribute => value pairs.
+  # 
+  #  obj.a = 10
+  #  obj.b = 20
+  #  attributes_as_hash(:a, :b) 
+  #    => {:a => 10, :b => 20}
+  def attributes_as_hash *attrs
+    result = {}
+    attrs.each do |a|
+      v = self.send a
+      result[a] = v unless v.nil?
+    end
+    result
+  end
+end

data/lib/named_arguments.rb

@@ -0,0 +1,249 @@
+require File.dirname(__FILE__) + '/class_settings_mixin'
+require File.dirname(__FILE__) + '/hash_extended_tools'
+require File.dirname(__FILE__) + '/singleton_creator_mixin'
+
+# Adds the following features to a class:
+# 
+# * Pass a hash to new and matching attributes
+#   will be set.
+# * Set default values for arguments (attribute_defaults)
+# * Require arguments (required_fields)
+# * Require kind_of? tests for arguments (required_kind_of)
+# * Change the type of the object passed in (type_conversion)
+# 
+# =Sample
+#
+#  class Snark
+#    include NamedArguments
+#    
+#    attr_accessor :color, :size, :name
+#    
+#    attribute_defaults :color => 'blue', :size => lambda {|s| some_method_call(s)}
+#    required_fields :color, :name
+#    required_respond_to :name => :to_s
+#    required_kind_of? :size => Fixnum
+#    type_conversion :size => Fixnum
+#  end
+#  
+# = See also
+# 
+# See NamedArgumentsClassMethods for more methods.
+module NamedArguments
+  VERSION = '0.0.1'
+  
+  include HashExtendedTools
+  
+  # Requires that object.snark.kind_of? String be true
+  # on the call to initialize.
+  # 
+  # Throws a NamedArgumentException if that test fails.
+  # 
+  #  required_kind_of :snark => String, :boojum => Fixnum
+  def required_kind_of
+    # Dummy for rdoc
+  end
+  
+  # Requires that the given arguments be present on the 
+  # call to new.
+  # 
+  #  required_fields [:snark, :boojum]
+  # 
+  # or
+  #   
+  #   required_fields :snark
+  def required_fields
+    # Dummy for rdoc
+  end
+  
+  # Requires that the given objects respond to the
+  # method call.
+  # 
+  #  required_respond_to :snark => 'hunt'
+  #  
+  # Raises a NamedArgumentException on failure.
+  def required_respond_to
+    # Dummy for rdoc
+  end
+  
+  # Set defaults for the given attributes.
+  # 
+  # Values can be:
+  # 
+  # * A class.  The #new method is called with no arguments.
+  # * A Proc.  The proc is called with one argument.
+  # * [].  A new array is created.
+  # * {}.  A new hash is created.
+  # 
+  #  attribute_defaults :snark => lambda {|s| String.new s.to_s}
+  #  attribute_defaults :snark => [], :boojum => ObjectTypeFromSomewhereElse
+  #  attribute_defaults :snark => {}
+  def attribute_defaults
+    # Dummy for rdoc
+  end
+  
+  def self.included target # :nodoc:
+    target.send :include, ClassSettingsMixin
+    target.send :extend, NamedArgumentsClassMethods
+    target.send :create_class_settings_method, :required_fields
+    target.send :create_class_settings_method, :required_kind_of
+    target.send :create_class_settings_method, :required_respond_to
+    target.send :create_class_settings_method, :attribute_defaults
+  end
+  
+  # Set the attributes for this object.  Normally called
+  # by initialize.
+  
+  def attributes_set(args) # :nodoc:
+    set_default_attributes(args)
+    
+    args_plus_defaults = (attribute_defaults? || {}).merge(args)
+    check_required_field args_plus_defaults
+    check_required_kind
+    check_required_respond_to
+  end
+  
+  def set_default_attributes(args) # :nodoc:
+    defaults = {}
+     (attribute_defaults? || {}).each_pair do |k, v|
+      if v.kind_of? Class
+        result = v.new
+      elsif v.kind_of? Proc
+        result = v.call self
+      elsif v.class == Array and v.empty?
+        result = Array.new
+      elsif v.class == Hash and v.empty?
+        result = Hash.new
+      else
+        result = v
+      end
+      defaults[k] = result
+    end
+    args = defaults.merge args
+    args.each_pair do
+      |k, v|
+      self.send("#{k}=", v)
+    end
+  end
+  
+  # An array of field names.  When an object is created
+  # all of these attributes must be passed.  (They can be
+  # set to nil)
+  # 
+  # Note that this can only be called as a class method.
+  
+  # A hash of :fieldname => klass pairs that specify the
+  # required class of each of the attributes.
+  
+  # Checks to make sure all the required fields
+  # are passed in.  
+  # 
+  # See also: required_fields
+  
+  def check_required_field(fields_set) # :nodoc:
+   (required_fields? || []).each do
+      |f|
+      raise NamedArgumentException.new("Must set parameter: " + f.to_s) unless fields_set.has_key? f.to_sym
+    end
+  end
+  
+  # Checks to make sure all the fields specifed in required_kind_of
+  # have the right kind of objects.
+  # 
+  # See also: 
+  # * #required_kind_of
+  # * #set_default_attributes
+  
+  def check_required_kind # :nodoc:
+   (required_kind_of? || {}).each_pair do
+      |k, v|
+      raise NamedArgumentException.new("Wrong class: #{k.to_s}; should have been #{v.to_s}, object is #{self.send(k).inspect}") unless self.send(k).kind_of?(v)
+    end
+  end
+  
+  def check_required_respond_to # :nodoc:
+   (required_respond_to? || {}).each_pair do
+      |k, v|
+      raise NamedArgumentException.new("#{k} must respond to #{v}; the object is #{self.send(k).inspect}") unless self.send(k).respond_to?(v)
+    end
+  end
+  
+  # For every key/value pair in +args+, set the
+  # value of the attribute +key+ to +value+.
+  # 
+  #  class Snark
+  #    include NamedArguments
+  #    attr_accessor :boojum
+  #  end
+  #  
+  #  s = Snark.new :boojum => 7
+  def initialize args = {}
+    if kind_of? ActiveRecord::Base
+      super
+    else
+      super()
+    end
+    attributes_set args
+    yield self if block_given?
+  end
+  
+  def option_attr_get k  # :nodoc:
+    option_attr_storage[k]
+  end
+  
+  def option_attr_set k, v # :nodoc:
+    option_attr_storage[k] = v
+  end
+  
+  def option_attr_storage # :nodoc:
+    self.options ||= {}
+  end
+  
+  def option_attrs_keys # :nodoc:
+    option_attr_storage.keys
+  end
+  
+  def option_attrs_keys_set # :nodoc:
+    option_attrs_keys.select do |k|
+      option_attr_storage.include? k
+    end
+  end
+end
+
+module NamedArgumentsClassMethods
+  def option_attr *array_of_names
+    array_of_names.each { |n| 
+      define_method n, lambda {
+        option_attr_get n
+      }
+      define_method "#{n}=", lambda { |v|
+        option_attr_set n, v
+      }
+    }
+  end
+  
+  def type_converter field, new_klass
+    alias_name = ('attribute_setter_for_' + field.to_s).to_sym
+    setter_method_name = (field.to_s + '=').to_sym
+    alias_method alias_name, setter_method_name
+    send :define_method, setter_method_name do |rhs|
+      if [Fixnum].member? new_klass
+        v = rhs.to_i
+      elsif new_klass == String
+        v = rhs.to_s
+      elsif new_klass == Symbol
+        v = rhs.to_sym
+      elsif new_klass == :boolean
+        v = !!rhs
+      elsif new_klass.kind_of? Proc
+        v = new_klass.call v
+      else
+        v = new_klass.new rhs
+      end
+      self.send alias_name, v
+    end
+  end
+end
+
+# Exception class thrown by NamedArguments methods.
+class NamedArgumentException < Exception
+end

data/lib/singleton_creator_mixin.rb

@@ -0,0 +1,29 @@
+module SingletonMethodCreatorMixin
+  # Create a method out of a
+  # name and a lambda.
+  # 
+  # Example:
+  # 
+  #   my_lambda = lambda {13}
+  #   create_singleton_method :return_13, my_lambda
+  # 
+  #   assert 13 == self.return_13
+  def create_singleton_method method_name, lambda_obj
+    sclass = class << self; self end
+    sclass.send(:define_method, method_name, lambda_obj)
+    sclass.send(:public, method_name)
+  end
+  
+  # Create a method out of a
+  # value and a name
+  # The method will return the value.
+  # 
+  # Example:
+  # 
+  #   create_singleton_value_method :return_14, 14
+  # 
+  #   assert 14 == self.return_14
+  def create_singleton_value_method name, value
+    create_singleton_method(name, lambda { value })
+  end
+end

metadata

@@ -0,0 +1,62 @@
+--- !ruby/object:Gem::Specification 
+rubygems_version: 0.8.11
+specification_version: 1
+name: namedarguments
+version: !ruby/object:Gem::Version 
+  version: 0.0.1
+date: 2006-12-06 00:00:00 -08:00
+summary: Provide named arguments (hashes) to constructors to initialize attributes.
+require_paths: 
+- lib
+email: james@phonesonrails.com
+homepage: http://www.zenspider.com/ZSS/Products/namedarguments/
+rubyforge_project: namedarguments
+description: "Adds the ability to call class constructors with a hash of arguments to initialize attributes in the new object.  == FEATURES/PROBLEMS:  class Snark include NamedArguments  attr_accessor :color, :size, :name  attribute_defaults :color => 'blue', :size => lambda {|s| some_method_call(s)} required_fields :color, :name required_respond_to :name => :to_s required_kind_of? :size => Fixnum type_conversion :size => Fixnum end  s = Snark.new :boojum => 7, :color => red  == INSTALL:"
+autorequire: 
+default_executable: 
+bindir: bin
+has_rdoc: true
+required_ruby_version: !ruby/object:Gem::Version::Requirement 
+  requirements: 
+  - - ">"
+    - !ruby/object:Gem::Version 
+      version: 0.0.0
+  version: 
+platform: ruby
+signing_key: 
+cert_chain: 
+authors: 
+- James M Moore
+files: 
+- History.txt
+- Manifest.txt
+- README.txt
+- Rakefile
+- bin/named_arguments
+- lib/named_arguments.rb
+- lib/hash_extended_tools.rb
+- lib/singleton_creator_mixin.rb
+- lib/class_settings_mixin.rb
+- test/test_named_arguments.rb
+test_files: 
+- test/test_named_arguments.rb
+rdoc_options: []
+
+extra_rdoc_files: []
+
+executables: 
+- named_arguments
+extensions: []
+
+requirements: []
+
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: hoe
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Version::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 1.1.6
+    version: