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