oval

#Oval - Options Validator

####Table of Contents

1. Overview
2. Module Description
3. Usage
   • Example 1: Declaring simple options
   • Example 2: Separating declaration from validation
4. Reference
   • Declarators
   • API Reference
5. Limitations

##Overview

Validate arguments and option hashes when passed to methods.

[Table of Contents]

##Module Description

This module implements simple to use data validators. It was initially thought to validate option hashes (so the name Oval stands for Options' Validator), but it appeared early that it's suitable to validate arbitrary parameters (variables).

The shape of acceptable data is described by a simple grammar. The validation is then carried out by a recursive-descent parser which matches actual values provided by caller to declarators that comprise the declaration of acceptable values.

A declaration consists of terminal and non-terminal declarators. Most Oval methods with ov_xxx names are non-terminal declarators. All other values (such as :symbol, 'string', nil, or Class) are terminals. Terminals use == operator to match the values provided by caller. Non-terminal use its own logic introducing more elaborate matching criteria (see for example ov_collection).

Oval raises Oval::DeclError if the declaration is not well-formed. This is raised from the point of declaration. Other, more common exception is the Oval::ValueError which is raised each time the validation fails. This one is raised from within a method which validates its arguments.

[Table of Contents]

##Usage

The usage is basically a two-step procedure. The first step is to declare data to be validated. This would create a validator object. The second step is to validate data using the previously constructed validator. For simple cases the entire construction may fit to a single line. Let's start with such a simple example.

###Example 1: Declaring Simple Options

The method foo in the following code accepts only {} and {:foo => value} as ops hash, and the value may be anything:

# Options validator
require 'oval'
class C
  extend Oval
  def self.foo(ops = {})
    Oval.validate(ops, ov_options[ :foo => ov_anything ], 'ops')
  end
end

What does it do? Just try it out:

C.foo # should pass
C.foo :foo => 10 # should pass
C.foo :foo => 10, :bar => 20 # Oval::ValueError "Invalid option :bar for ops. Allowed options are :foo"

Options are declared with ov_xxx declarators. The ov_options, for example, declares a hash of options. In ov_options all the allowed options should be listed inside of [] square brackets. Keys may be any values convertible to strings (i.e. a key given in declaration must respond_to? :to_s). Values are declared recursively using ov_xxx declarators or terminal declarators (any other ruby values).

In Example 1 we have declared options inside of a method for simplicity. This isn't an optimal technique. Usually options' declaration remains same for the entire lifetime of an application, so it is unnecessary to recreate the declaration each time function is called. In other words, we should move the declaration outside of the method, convert it to a singleton and only validate options inside of a function. For that purpose, the Example 1 could be modified to the following form

###Example 2: Separating declaration from validation

In this example we separate options declaration from the validation to reduce costs related to options declaration:

# Options validator
require 'oval'
class C
  extend Oval
  # create a singleton declaration ov
  def self.ov
    @ov ||= ov_options[ :foo => ov_anything ]
  end
  # use ov to validate ops
  def self.foo(ops = {})
    Oval.validate(ops, ov, 'ops')
  end
end

[Table of Contents]

##Reference

###Declarators

A declaration of data being validated consists entirely of what we call declarators. The grammar for defining acceptable data uses non-terminal and terminal declarators. Non-terminal declarators are most of the ov_xxx methods of Oval module, for example ov_options. General syntax for non-terminal declarator is ov_xxx[ args ], where args are declarator-specific arguments.

Terminal declarators include all the other ruby values, for example nil. They are matched exactly against data being validated, so if the data doesn't equal the given value an exception is raised.

In what follows, we'll document all the core declarators implemented in Oval.

###Index of Declarators

• ov_anything
• ov_collection
• ov_instance_of
• ov_kind_of
• ov_match
• ov_one_of
• ov_options
• ov_subclass_of

####ov_anything

• Declaration

  ov_anything
  

  or

  ov_anything[]
  

• Validation - permits any value

• Example

  require 'oval'
  class C
    extend Oval
    def self.ov
      @oc = ov_options[ :bar => ov_anything ]
    end
    def self.foo(ops = {})
      Oval.validate(ops, ov, 'ops')
    end
  end
  C.foo() # should pass
  C.foo :bar => 10 # should pass
  C.foo :bar => nil # should pass
  C.foo :bar => 'bar' # should pass
  C.foo :foo => 10, :bar => 20 # Oval::ValueError "Invalid option :foo for ops. Allowed options are :bar"
  

[Table of Contents|Index of Declarators]

####ov_collection

• Declaration

  ov_collection[ class_decl, item_decl ]
  

• Validation - permits only collections of type class_decl with items matching item_decl declaration

• Allowed values for class_decl are:

  • Hash or Array or any subclass of Hash or Array,
  • ov_subclass_of[klass] where klass is Hash or Array or a subclass of any of them.

• Allowed values for item_decl:

  • if class_decl is Array-like, then any value is allowed as item_decl,
  • if class_decl is Hash-like, then item_decl should be a one-element Hash in form { key_decl => val_decl }.

• Example

  require 'oval'
  class C
    extend Oval
    def self.ov_h
      ov_collection[ Hash, { ov_instance_of[Symbol] => ov_anything } ]
    end
    def self.ov_a
      ov_collection[ Array, ov_instance_of[String] ]
    end
    def self.foo(h, a)
      Oval.validate(h, ov_h, 'h')
      Oval.validate(a, ov_a, 'a')
    end
  end
  C.foo({:x => 10}, ['xxx']) # Should bass
  C.foo({:x => 10, :y => nil}, ['xxx', 'zzz']) # Should pass
  C.foo(10,['xxx']) # Oval::ValueError, "Invalid value Fixnum for h.class. Should be equal Hash"
  C.foo({:x => 10, 'y' => 20}, [ 'xxx' ]) # Oval::ValueError, 'Invalid object "y" of type String for h key. Should be an instance of Symbol'
  C.foo({:x => 10}, 20) # Invalid value Fixnum for a.class. Should be equal Array
  C.coo({:x => 10}, [ 'ten', 20 ]) # Oval::ValueError, "Invalid object 20 of type Fixnum for a[1]. Should be an instance of String"
  

[Table of Contents|Index of Declarators]

####ov_instance_of

• Declaration

  ov_instance_of[klass]
  

• Validation - permits only instances of a given class klass

• Allowed values for klass - only class names, for example String, Hash, etc.

• Example

  require 'oval'
  class C
    extend Oval
    def self.ov
      ov_instance_of[String]
    end
    def self.foo(s)
      Oval.validate(s, ov, 's')
    end
  end
  C.foo('bar') # Should pass
  C.foo(10) # Oval::ValueError, "Invalid object 10 for s. Should be an instance of String"
  

[Table of Contents|Index of Declarators]

####ov_kind_of

• Declaration

  ov_kind_of[klass]
  

• Validation - permits only values that are a kind of given class klass

• Allowed values for klass - only class names, for example String, Hash, etc.

• Example

  require 'oval'
  class C
    extend Oval
    def self.ov
      ov_kind_of[Numeric]
    end
    def self.foo(n)
      Oval.validate(n, ov, 'n')
    end
  end
  C.foo(10) # Should pass
  C.foo(10.0) # Should pass
  C.foo('10') # Oval::ValueError, 'Invalid object "10" of type String for n. Should be a kind of Numeric'
  

[Table of Contents|Index of Declarators]

####ov_match

• Declaration

  ov_match[re]
  

• Validation - permits only values matching regular expression re,

• Allowed values for re - must be a kind of Regexp.

• Example

  require 'oval'
  class C
    extend Oval
    def self.ov
      # Only valid identifiers are allowed as :bar option
      ov_match[/^[a-z_]\w+$/]
    end
    def self.foo(name)
      Oval.validate(name, ov, 'name')
    end
  end
  C.foo('var_23') # Should pass
  C.foo(10) # Oval::ValueError, "Invalid value 10 for name. Should match /^[a-z_]\\w+$/ but it's not even convertible to String"
  C.foo('10abc_') # Oval::ValueError, 'Invalid value "10abc_" for name. Should match /^[a-z_]\\w+$/'
  

[Table of Contents|Index of Declarators]

####ov_one_of

• Declaration

  ov_one_of[decl1,decl2,...]
  

• Validation - permits only values matching one of declarations decl, decl2, ...

• Example

  require 'oval'
  class C
    extend Oval
    def self.ov
      ov_one_of[ ov_instance_of[String], ov_kind_of[Numeric], nil ]
    end
    def self.foo(x)
      Oval.validate(x, ov, 'x')
    end
  end
  C.foo('str')  # Should pass
  C.foo(10)     # Should pass
  C.foo(10.0)   # Should pass
  C.foo(nil)    # Should pass
  C.foo([])     # Oval::ValueError, "Invalid value [] for x. Should be an instance of String, be a kind of Numeric or be equal nil"
  

[Table of Contents|Index of Declarators]

####ov_options

• Declaration

  ov_options[ optkey_decl1 => optval_decl1, ... ]
  

• Validation - permits only declared options and their values.

• Allowed values for optkey_declN - anything that is convertible to string (namely, anything that responds to to_s method).

• Example:

  ov = ov_options[ 
    :bar => ov_anything,
    :geez => ov_instance_of[String],
    # ...
  ]
  def foo(ops = {})
    Oval.validate(ops, ov, 'ops')
  end 
  

[Table of Contents|Index of Declarators]

####ov_subclass_of

• Declaration

  ov_subclass_of[klass]
  

• Validation - permits only subclasses of klass

• Allowed values for klass - only class names, for example String, Hash, etc.

• Example

  require 'oval'
  class C
    extend Oval
    def self.ov
      ov_options[ :bar => ov_subclass_of[Numeric] ]
    end
    def self.foo(ops = {})
      Oval.validate(ops, ov, 'ops')
    end
  end
  C.foo :bar => Integer   # Should pass
  C.foo :bar => Fixnum    # Should pass
  C.foo([])               # Oval::ValueError, "Invalid options [] of type Array. Should be a Hash
  C.foo :foo => Fixnum    # Oval::ValueError, "Invalid option :foo for ops. Allowed options are :bar"
  C.foo :bar => 10        # Oval::ValueError, "Invalid class 10 for ops[:bar]. Should be subclass of Numeric"
  

###API Reference

API reference may be generated with

bundle exec rake yard

The generated documentation goes to doc/ directory. Note that this works only under ruby >= 1.9.

The API documentation is also available online.

[Table of Contents]

##Limitations

• API documentation is currently very poor,

[Table of Contents]

2014-02-09 Pawel Tomulik ptomulik@meil.pw.edu.pl

• release 0.0.7
• fixed match_spec.rb to work on 1.8 and 2.0
• revised examples in README.md and added specs to cover them
• fixed Oval::Match#validate to handle non-string TypeError 2014-02-08 Pawel Tomulik ptomulik@meil.pw.edu.pl
• release 0.0.6
• documented a way for validating arbitrary arguments 2014-02-03 Pawel Tomulik ptomulik@meil.pw.edu.pl
• added more navigation links to README.md
• added specs for Oval::Base.it_should
• release 0.0.5
• refactored ensure_match -> validate
• added Oval::Match declarator
• fixed error message in OneOf to be more verbose
• added it_should method to declarators
• release 0.0.4 2014-02-02 Pawel Tomulik ptomulik@meil.pw.edu.pl
• corrections to README.md
• small refactoring
• removed dead code from class_decl_base.rb
• release 0.0.3
• fixed dependencies in oval.gemspec
• release 0.0.2
• fixed Modulefile
• release 0.0.1
• added note to README.md
• corrected typos in README.md
• fixed .travis.yml to reduce matrix size
• fixed coveralls badge
• fixed some specs for ruby 2.0
• removed dead code from lib/oval/collection.rb
• fixed build-puppet-module script
• initial commit