Module: NamedArguments

Includes:
HashExtendedTools
Defined in:
lib/named_arguments.rb

Overview

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.

Constant Summary collapse

VERSION = 
'0.0.1'

Class Method Summary collapse

Instance Method Summary collapse

Methods included from HashExtendedTools

#attributes_as_hash, #exclude, #slice, #switch_keys

Class Method Details

.included(target) ⇒ Object

:nodoc:



84
85
86
87
88
89
90
91
 
# File 'lib/named_arguments.rb', line 84

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

Instance Method Details

#attribute_defaults ⇒ Object

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 => {}



80
81
82
 
# File 'lib/named_arguments.rb', line 80

def attribute_defaults
  # Dummy for rdoc
end

#attributes_set(args) ⇒ Object

Set the attributes for this object. Normally called by initialize.



96
97
98
99
100
101
102
103
 
# File 'lib/named_arguments.rb', line 96

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

#check_required_field(fields_set) ⇒ Object

Checks to make sure all the required fields are passed in.

See also: required_fields



142
143
144
145
146
147
 
# File 'lib/named_arguments.rb', line 142

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

#check_required_kind ⇒ Object

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



156
157
158
159
160
161
 
# File 'lib/named_arguments.rb', line 156

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

#check_required_respond_to ⇒ Object

:nodoc:



163
164
165
166
167
168
 
# File 'lib/named_arguments.rb', line 163

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

#initialize(args = {}) {|_self| ... } ⇒ Object

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

Yields:

  • (_self)

Yield Parameters:



179
180
181
182
183
184
185
186
187
 
# File 'lib/named_arguments.rb', line 179

def initialize args = {}
  if kind_of? ActiveRecord::Base
    super
  else
    super()
  end
  attributes_set args
  yield self if block_given?
end

#option_attr_get(k) ⇒ Object

:nodoc:



189
190
191
 
# File 'lib/named_arguments.rb', line 189

def option_attr_get k  # :nodoc:
  option_attr_storage[k]
end

#option_attr_set(k, v) ⇒ Object

:nodoc:



193
194
195
 
# File 'lib/named_arguments.rb', line 193

def option_attr_set k, v # :nodoc:
  option_attr_storage[k] = v
end

#option_attr_storage ⇒ Object

:nodoc:



197
198
199
 
# File 'lib/named_arguments.rb', line 197

def option_attr_storage # :nodoc:
  self.options ||= {}
end

#option_attrs_keys ⇒ Object

:nodoc:



201
202
203
 
# File 'lib/named_arguments.rb', line 201

def option_attrs_keys # :nodoc:
  option_attr_storage.keys
end

#option_attrs_keys_set ⇒ Object

:nodoc:



205
206
207
208
209
 
# File 'lib/named_arguments.rb', line 205

def option_attrs_keys_set # :nodoc:
  option_attrs_keys.select do |k|
    option_attr_storage.include? k
  end
end

#required_fields ⇒ Object

Requires that the given arguments be present on the call to new.

required_fields [:snark, :boojum]

or

required_fields :snark



54
55
56
 
# File 'lib/named_arguments.rb', line 54

def required_fields
  # Dummy for rdoc
end

#required_kind_of ⇒ Object

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



42
43
44
 
# File 'lib/named_arguments.rb', line 42

def required_kind_of
  # Dummy for rdoc
end

#required_respond_to ⇒ Object

Requires that the given objects respond to the method call.

required_respond_to :snark => 'hunt'

Raises a NamedArgumentException on failure.



64
65
66
 
# File 'lib/named_arguments.rb', line 64

def required_respond_to
  # Dummy for rdoc
end

#set_default_attributes(args) ⇒ Object

:nodoc:



105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
 
# File 'lib/named_arguments.rb', line 105

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