Module: NamedParameters::ClassMethods

Defined in:
lib/named-parameters/module.rb

Constant Summary collapse

ALIAS_PREFIX = 
:__intercepted__

Instance Method Summary collapse

Instance Method Details

#has_named_parameters(method, spec, mode = :strict) {|spec| ... } ⇒ Object

Declares that method will enforce named parameters behavior as described in spec; a method declared with :required and/or :optional parameters will raise an ArgumentError if it is invoked without its required parameters or receives an unrecognized parameter.

Sample usage:

has_named_parameters :point, :required => [ :x, :y ], :optional => :color

Parameters:

  • method (Symbol) —

    the name of the method that is supposed to enforce named parameters behavior.

  • spec (Hash) —

    a Hash to specify the list of required and optional parameters for the method. Use either the :required, :optional, or :oneof key to specify the lists of parameters. The list is expected to be an Array of symbols matching the names of the expected and optional parameters.

    Parameters are evaluated according their classification:

    • :required means that all of these parameters must be specified.

    • :optional means that all or none of these parameters may be used.

    • :oneof means that one of these parameters must be specified.

  • mode (Symbol) (defaults to: :strict) —

    enforces that only parameters that were named in either the :required, :optional, and :oneof list may be allowed. Set it to :permissive to relax the requirement - :required and :oneof parameters will still be expected.

Yields:

  • (spec) 


219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
 
# File 'lib/named-parameters/module.rb', line 219

def has_named_parameters method, spec, mode = :strict
  # ensure spec entries are initialized and the proper types
  [ :required, :optional, :oneof ].each{ |k| spec[k] ||= [] }
  
  # assemble/normalize method spec; the following code should 
  # just be:
  # 
  #   spec = Hash[ spec.map{ |k, v| 
  #     v = [ v ] unless v.instance_of? Array
  #     v.map!{ |entry| entry.instance_of?(Array) ? Hash[*entry] : entry }
  #     [ k, v ] 
  #   } ] 
  #
  # but we have to play nice with ruby 1.8.6, so we'll have to be content
  # with the ugliness for now...
  #
  pairs = spec.map{ |k, v| 
    v = [ v ] unless v.instance_of? Array
    v.map!{ |entry| entry.instance_of?(Array) ? Hash[*entry] : entry  }
    [ k, v ]
  }

  spec = { }
  pairs.each{ |x| spec[x[0]] = x[1] }
  spec = Hash[ spec ] 

  spec[:mode] = mode
  __method_specs[__key_for(method)] = spec
  yield spec if block_given?
end

#recognizes(*params, &block) ⇒ Object

Convenience method, equivalent to declaring:

has_named_parameters :'self.new', :optional => params, :strict
has_named_parameters :initialize, :optional => params, :strict

Parameters:

  • params (Array<Symbol>) —

    the lists of parameters. The list is expected to be an Array of symbols matching the names of the optional parameters.



279
280
281
282
283
284
285
286
287
288
 
# File 'lib/named-parameters/module.rb', line 279

def recognizes *params, &block
  #raise ArgumentError,    #  "You must specify at least one parameter when declaring a recognizes clause"    #  if params.empty?
  [ :'self.new', :initialize ].each do |method|
    spec = __method_specs[__key_for(method)] || { }
    spec.merge!(:optional => Array(spec[:optional]) + params)
    has_named_parameters method, spec, :strict, &block
  end
end

#requires(*params, &block) ⇒ Object

Convenience method, equivalent to declaring:

has_named_parameters :'self.new', :required => params, :strict
has_named_parameters :initialize, :required => params, :strict

Parameters:

  • params (Array<Symbol>) —

    the lists of parameters. The list is expected to be an Array of symbols matching the names of the required parameters.



259
260
261
262
263
264
265
266
267
268
 
# File 'lib/named-parameters/module.rb', line 259

def requires *params, &block
  #raise ArgumentError,    #  "You must specify at least one parameter when declaring a requiring clause"    #  if params.empty?
  [ :'self.new', :initialize ].each do |method|
    spec = __method_specs[__key_for(method)] || { }
    spec.merge!(:required => Array(spec[:required]) + params)
    has_named_parameters method, spec, :strict, &block
  end
end