Methodic

Content

Description

Methodic is a macro-like utility to help test, validate, control options passed by an Hash param to a method, it could help you to merge with defaults values,
It raise explained exceptions and return false if the validations steps failed.

Installation

In a valid Ruby environment :

$ sudo zsh
  1. gem ins methodic

Implementation

  • [Methodic]
  • [Methodic::Options]

Example

Without known options control

  require 'rubygems'                                                                                                                                                                             
  require 'methodic'
  [...]                                                                                                                                                                                          
  # in a method                                                                                                                                                                                  
  def amethod ( _options = {})                                                                                                                                                                   
    myOptions = Methodic::get_options(_options) do |m|                                                                                                                                           
      m.specify_default_value_of :country => 'France'
      aCond = Proc::new {|option| case options when 'Doe' then true else false end }
      m.specify_condition_for :name => aCond                                                                                                                                            
      m.specify_classes_of :name => String, :surname => String, :age => Fixnum, :country => String                                                                                               
      m.specify_presence_of :name                                                                                                                                                                
      m.specify_presence_of :surname                                                                                                                                                             
      m.specify_formats_of :name => /\w+/, :surname => /\w+/, :country => /\w+/                                                                                                                  
      m.merge!                                                                                                                                                                                   
    end                                                                                                                                                                                          
    # processing method                                                                                                                                                                          
  end                                                                                                                                                                                    
  [...]  

With known options control

  require 'rubygems'                                                                                                                                                                             
  require 'methodic'
  [...]                                                                                                                                                                                          
  # in a method                                                                                                                                                                                  
  def amethod ( _options = {})                                                                                                                                                                   
    myOptions = Methodic::get_options(_options,true) do |m|
      # all others definitions MUST be included in known options list (explained in Spec), so :                                                                                                               
      m.specify_known_options [:country,:name,:surname, :age]          
      m.specify_default_value_of :country => 'France'                                                                     
      aCond = Proc::new {|option| case options when 'Doe' then true else false end }
      m.specify_condition_for :name => aCond                                                                       
      m.specify_classes_of :name => String, :surname => String, :age => Fixnum, :country => String                                                                                               
      m.specify_presence_of :name                                                                                                                                                                
      m.specify_presence_of :surname                                                                                                                                                             
      m.specify_formats_of :name => /\w+/, :surname => /\w+/, :country => /\w+/                                                                                                                  
      m.merge!                                                                                                                                                                                   
    end                                                                                                                                                                                          
    # processing method                                                                                                                                                                          
  end                                                                                                                                                                                    
  [...]  

Remarque about conditions

  • Condition MUST :

- be ruby code
- be a Proc Object
- have an argument |option| who provide the option symbol, like :an_option
- return true or false

  • Make your condition like
   aCond = Proc::new do |option|
           case options
             when .... then ...
             when .... then ...
             else ...
           end
   end

Copyright

Methodic (c) 2012-2013 Romain GEORGES <romain@ultragreen.net> for Ultragreen Software 

Specification result RSpec

Methodic
  should be an instance of Module
  Methodic::Options
    should be an instance of Class
    should respond to all methods of a Hash
    #new(_options) (initialization)
      Exception case
        should raise ArgumentError if _options is not a Hash
        should not raise ArgumentError if no arg is passed to initializer
        should not raise ArgumentError if an Hash arg is passed to initializer
        should raise ArgumentError if an Hash arg is passed to initializer but with keys different of Symbol
        should not raise ArgumentError if two arg is passed to initializer, second arg has a boolean value, must be object
        should raise ArgumentError if more than two arg is passed to initializer
    Instance Attributs
      #classes R/W
        should respond to #classes
        should respond to #classes=
        should be true that #classes must return a Hash
        #classes[] affectation must be possible and #classes must respond this affectation
      #defaults R/W
        should respond to #defaults
        should respond to #defaults=
        should be true that #defaults must return a Hash
        #defaults[] affectation must be possible and #defaults must respond this affectation
      #formats R/W
        should respond to #formats
        should respond to #formats=
        should be true that #formats must return a Hash
        #formats[] affectation must be possible and #formats must respond this affectation
      #conditions R/W
        should respond to #conditions
        should respond to #conditions=
        should be true that #conditions must return a Hash
        #formats[] affectation must be possible and #formats must respond this affectation
      #mandatories R/W
        should respond to #mandatories
        should respond to #mandatories=
        should be true that #mandatories must return a List < Array
        #mandatories.push affectation must be possible and #mandatories must respond this affectation
        #mandatories.push
          should not duplicate entry
      #known R/W
        should respond to #known
        should respond to #known=
        should be true that #known must return a List < Array
        #known.push affectation must be possible and #known must respond this affectation
        #known.push
          should not duplicate entry
    Instance methods
      #options
        should respond to #options
        should be true that #options must return a Array
        should respond an Array of options keys
      #specify_default_value
        should respond to #specify_default_value
        should respond to #specify_defaults_values
        should merge default value hash record in defaults attribut
        should redefine a new default value for a previous key
      #specify_class_of
        should respond to #specify_class_of
        should respond to #specify_classes_of
        should merge class hash record in classes attribut
        should redefine a new class value for a previous key
      #specify_condition_for
        should respond to #specify_condition_for
        should respond to #specify_conditions_for
        should merge condition hash record in conditions attribut
        should redefine a new class value for a previous key
      #specify_format_of
        should respond to #specify_format_of
        should respond to #specify_formats_of
        should merge format hash record in formats attribut
        should redefine a new format value for a previous format key
      #specify_presence_of
        should respond to #specify_presence_of
        should respond to #specify_presences_of
        should merge presence Array record in mandatories attribut
        should be possible to give arguments list of symbols
      #specify_known_option
        should respond to #specify_known_option
        should respond to #specify_known_options
        should merge known Array record in known attribut
        should be possible to give arguments list of symbols
      #validate
        should respond to #validate
        should respond to #validate!
        1/ validate known options
          @validate_known_options = false (default)
            should not raise ArgumentError if mandatories is not fully include in the known options list
            should not raise ArgumentError if an option in options list not in the known options list
            should not raise if all given options in options list is in known options
            should not raise ArgumentError if formats made a reference to an unknown options
            should not raise ArgumentError if classes made a reference to an unknown options
            should not raise ArgumentError if default made a reference to an unknown options
          @validate_known_options = true
            should raise ArgumentError if mandatories is not fully include in the known options list
            should raise ArgumentError if an option in options list not in the known options list
            should not raise if all given options in options list is in known options
            should raise ArgumentError if formats made a reference to an unknown options
            should raise ArgumentError if classes made a reference to an unknown options
            should raise ArgumentError if default made a reference to an unknown options
        2/ validate classes
          should raise ArgumentError if an options don't match a class definition
          should not raise if options match class definition
        3/ validate mandatories
          should raise ArgumentError if a mandatory option not in options list
          should not raise if mandatory options and options list match
        4/ validate formats
          should raise ArgumentError if an option in options list not have the good registered formats
          should not raise if all options in options list match formats definitions
        5/ validate conditions
          should raise ArgumentError if an option in options list not validate a registered condition
          should not raise if all options in options list match formats definitions
      #merge_with_defaults
        should respond to #merge_with_defaults
        should respond to #merge
        should merge defaults values and don't override with options
  Methodic::get_options
    should return a Methodic::Options Object