Module: ParameterValidator

ParameterValidator is a mixin module providing parameter validation for functions and methods that employ Ruby’s "keyword arguments" implemention.

To use it in a class:

require ‘parmvalid’
include ParameterValidator
in your method definition, invoke ParameterValidator#validate_parameters, passing in the hash of the actual parameters, and a hash of valid parameters ( name=>default_value pairs, with default_value==REQUIRED if the parameter is not optional). The return value from validate_parameters will be a hash of the parameters, both the optional ones that weren’t passed in, and the ones that were.
if you want each parameter validated and then set as an instance variable of the class, use validate_and_instantiate_parameters.
if you want each parameter validated and then set using similarly-named setters in the class, use validate_and_set_parameters.

Example:

  require 'parmvalid'

  class Demo
    include ParameterValidator

    def initialize( args )
      validate_and_instantiate_parameters( args,
        { :name=>REQUIRED, :date=>Time.now, :location=nil, :memo=>REQUIRED } )

      p @name
      p @date
      p @location
      p @memo
    end
  end

  d = Demo.new( :name=>"Jamis", :memo=>"Some memo" )

Author: Jamis Buck (jgb3@email.byu.edu)

Methods

instantiate_parameters
set_parameters
validate_and_instantiate_parameters
validate_and_set_parameters
validate_parameters

Classes and Modules

Class ParameterValidator::InvalidParameterException
Class ParameterValidator::MissingParameterException

Public Instance methods

instantiate_parameters( parms )

For each key in the given hash, create an identically-named instance variable and set its value to the value of the given key.

[ show source ]

     # File lib/parmvalid.rb, line 115
115:   def instantiate_parameters( parms )
116:     parms.each_pair do |key, value|
117:       eval "@#{key} = value"
118:     end
119:   end

set_parameters( parms )

For each key in the given hash, assign its value to an identically-named setter in the current class.

[ show source ]

     # File lib/parmvalid.rb, line 123
123:   def set_parameters( parms )
124:     parms.each_pair do |key, value|
125:       eval "self.#{key} = value"
126:     end
127:   end

validate_and_instantiate_parameters( actual_parms, valid_parms )

Validate and instantiate the given parameters by calling both validate_parameters and instantiate_parameters. Return the hash of all parameters.

[ show source ]

     # File lib/parmvalid.rb, line 131
131:   def validate_and_instantiate_parameters( actual_parms, valid_parms )
132:     parms = validate_parameters( actual_parms, valid_parms )
133:     instantiate_parameters( parms )
134:     parms
135:   end

validate_and_set_parameters( actual_parms, valid_parms )

Validate and set the given parameters by calling both validate_parameters and set_parameters. Return the hash of all parameters.

[ show source ]

     # File lib/parmvalid.rb, line 139
139:   def validate_and_set_parameters( actual_parms, valid_parms )
140:     parms = validate_parameters( actual_parms, valid_parms )
141:     set_parameters( parms )
142:     parms
143:   end

validate_parameters( actual_parms, valid_parms )

Validates a hash of actual parameters (as created by Ruby’s pseudo-"keyword arguments" feature) against a list of valid parameters.

Parameters:

actual_parms: the hash of actual parameters that were given by Ruby’s pseudo-"keyword arguments" feature.
valid_parameters: the hash of valid parameters, where the key for each entry in the hash is a symbol naming the acceptable parameter, and the value is the default value for that parameter. If the default value for any entry is the constant REQUIRED, then the parameter must not be absent from the actual_parms hash.

Returns: a hash of all parameters, together with either the actual value that was passed in, or (in the case of optional parameters that were not passed in) the default value.

[ show source ]

     # File lib/parmvalid.rb, line 86
 86:   def validate_parameters( actual_parms, valid_parms )
 87:     parms = Hash.new
 88: 
 89:     # set the default values
 90:     valid_parms.each_pair do |key,value|
 91:       next if value == REQUIRED
 92:       parms[ key ] = value
 93:     end
 94: 
 95:     # set the actual values
 96:     actual_parms.each_pair do |key,value|
 97:       if not valid_parms.include? key
 98:         raise InvalidParameterException, "'#{key}' is invalid"
 99:       end
100:       parms[ key ] = value
101:     end
102: 
103:     # check required parameters
104:     valid_parms.each_pair do |key,value|
105:       if value==REQUIRED and not parms.include? key
106:         raise MissingParameterException, "'#{key}' is required"
107:       end
108:     end
109: 
110:     parms
111:   end