oval 0.0.5 → 0.0.6

data/CHANGELOG

@@ -1,4 +1,9 @@
+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

data/Modulefile

@@ -1,5 +1,5 @@
 name    'ptomulik-oval'
-version '0.0.5'
+version '0.0.6'
 source 'git://github.com/ptomulik/rubygems-oval.git'
 author 'ptomulik'
 license 'Apache License, Version 2.0'

data/README.md

@@ -18,17 +18,18 @@
 
 ##<a id="overview"></a>Overview
 
-Validate option hashes when passed to methods.
+Validate arguments and option hashes when passed to methods.
 
 [[Table of Contents](#table-of-contents)]
 
 ##<a id="module-description"></a>Module Description
 
-Using hashes to pass options to methods is a very common ruby practice. With
-**Oval** method authors may restrict callers to pass only declared options that
-meet requirements described in a hash declaration.
+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 hashes is described by a simple grammar. The validation
+The shape of acceptable data is described by a simple grammar. The validation
 is then carried out by a recursive-descent parser that matches the actual
 values provided by caller against [declarators](#declarators) that comprise the
 hash declaration.
@@ -38,28 +39,27 @@ declarators are created by methods of `Oval` module which have names starting
 with `ov_` prefix. 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](#ov_collection)).
+matching criteria (see for example [ov\_collection](#ov_collection)).
 
-**Oval** raises **Oval::DeclError** if the declaration is not well-formed, that
-is if the description of options shape is erroneous. 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 takes the options as an argument.
+**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](#table-of-contents)]
 
 ##<a id="usage"></a>Usage
 
 The usage is basically a two-step procedure. The first step is to declare
-options shape. This would create a validator object. The second step is to
-validate options within a method using the previously constructed validator.
-For simple hashes the entire construction may fit to a single line. Let's start
-with such a simple example.
+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.
 
 ###<a id="example-1-declaring-simple-options"></a>Example 1: Declaring Simple Options
 
 The method `foo` in the following code accepts only `{}` and `{:foo => value}`
-as `ops`, where `value` is arbitrary:
+as `ops` hash, and the `value` may be anything:
 
 ```ruby
 # Options validator
@@ -67,7 +67,7 @@ require 'oval'
 class C
   extend Oval
   def self.foo(ops = {})
-    ov_options[ :foo => ov_anything ].validate(ops, 'ops')
+    Oval.validate(ops, ov_options[ :foo => ov_anything ], 'ops')
   end
 end
 ```
@@ -80,12 +80,13 @@ 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](#declarators). The
-[ov_options](#ov_options) method should always be at the top level. Then 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](#declarators) or terminal declarators (any other ruby values).
+Options are declared with [ov\_xxx declarators](#declarators). The
+[ov\_options](#ov_options), for example, declares a hash of options. In
+[ov\_options](#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](#declarators) or terminal declarators (any other
+ruby values).
 
 In [Example 1](#example-1-declaring-simple-options) we have declared options
 inside of a method for simplicity. This isn't an optimal technique. Usually
@@ -112,7 +113,7 @@ class C
   end
   # use ov to validate ops
   def self.foo(ops = {})
-    ov.validate(ops, 'ops')
+    Oval.validate(ops, ov, 'ops')
   end
 end
 ```
@@ -123,36 +124,30 @@ end
 
 ###<a id="declarators"></a>Declarators
 
-A declaration of options consists entirely of what we call here
-**declarators**. The [ov_options](#ov_options) should be used as a root of
-every declaration (starting symbol in grammar terms). It accepts a Hash of the
-form 
+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](#declarators) methods of **Oval** module, for example
+[ov\_options](#ov_options). General syntax for non-terminal declarator is
+`ov_xxx[ args ]`, where `args` are declarator-specific arguments. 
 
-```
-{optname1 => optdecl1, optname2 => optdecl2, ... }
-```
-
-as an argument. The **optname#** is an option name, and **optdecl#** is a
-declarator restricting the option's value. Each option name (key) must be
-convertible to a `String`. Option value declarators are non-terminal
-declarators (defined later in this section) or terminals (any other ruby
-values). The simple declaration
-
-```ruby
-ov_options[ :foo => :bar ]
-```
+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.
 
-uses only terminals inside of **ov_options** and literary permits only the
-`{:foo => :bar}` or the empty hash `{}` as options (and nothing else). This is
-how terminal declarators (`:foo` and `:bar` in this example) work. More freedom
-may be introduced with non-terminal declarators, for example:
+In what follows, we'll document all the core declarators implemented in
+**Oval**.
 
-```ruby
-ov_options[ :foo => ov_anything ]
-```
+###<a id="index-of-declarators"></a>Index of Declarators
 
-defines an option `:foo` which accepts any value. In what follows, we'll
-document all the core non-terminal declarators implemented in **Oval**.
+- [ov\_anything](#ov_anything)
+- [ov\_collection](#ov_collection)
+- [ov\_instance\_of](#ov_instance_of)
+- [ov\_kind\_of](#ov_kind_of)
+- [ov\_match](#ov_match)
+- [ov\_one\_of](#ov_one_of)
+- [ov\_options](#ov_options)
+- [ov\_subclass_of](#ov_subclass_of)
 
 ####<a id="ov\_anything"></a>ov\_anything
 
@@ -174,10 +169,12 @@ document all the core non-terminal declarators implemented in **Oval**.
   ```ruby
   ov = ov_options[ :bar => ov_anything ]
   def foo(ops = {})
-    ov.validate(ops, 'ops')
+    Oval.validate(ops, ov, 'ops')
   end
   ```
 
+[[Table of Contents](#table-of-contents)|[Index of Declarators](#index-of-declarators)]
+
 
 ####<a id="ov\_collection"></a>ov\_collection
 
@@ -206,10 +203,12 @@ document all the core non-terminal declarators implemented in **Oval**.
     :geez => ov_collection [ Array, instance_of[String] ]
   ]
   def foo(ops = {})
-    ov.validate(ops, 'ops')
+    Oval.validate(ops, ov, 'ops')
   end
   ```
 
+[[Table of Contents](#table-of-contents)|[Index of Declarators](#index-of-declarators)]
+
 ####<a id="ov\_instance\_of"></a>ov\_instance\_of
 
 - Declaration
@@ -225,10 +224,12 @@ document all the core non-terminal declarators implemented in **Oval**.
   ```ruby
   ov = ov_options[ :bar => ov_instance_of[String] ]
   def foo(ops = {})
-    ov.validate(ops,'ops')
+    Oval.validate(ops, ov, 'ops')
   end
   ```
 
+[[Table of Contents](#table-of-contents)|[Index of Declarators](#index-of-declarators)]
+
 ####<a id="ov\_kind\_of"></a>ov\_kind\_of                                       
 
 - Declaration
@@ -244,10 +245,12 @@ document all the core non-terminal declarators implemented in **Oval**.
   ```ruby
   ov = ov_options[ :bar => ov_kind_of[Numeric] ]
   def foo(ops = {})
-    ov.validate(ops,'ops')
+    Oval.validate(ops, ov, 'ops')
   end
   ```
   
+[[Table of Contents](#table-of-contents)|[Index of Declarators](#index-of-declarators)]
+
 ####<a id="ov\_match"></a>ov\_match                                       
 
 - Declaration
@@ -264,10 +267,12 @@ document all the core non-terminal declarators implemented in **Oval**.
   # Only valid identifiers are allowed as :bar option
   ov = ov_options[ :bar => ov_match[/^[a-z_]\w+$/] ]
   def foo(ops = {})
-    ov.validate(ops,'ops')
+    Oval.validate(ops, ov, 'ops')
   end
   ```
   
+[[Table of Contents](#table-of-contents)|[Index of Declarators](#index-of-declarators)]
+
 ####<a id="ov\_one\_of"></a>ov\_one\_of   
 
 - Declaration
@@ -284,10 +289,12 @@ document all the core non-terminal declarators implemented in **Oval**.
     :bar => ov_one_of[ ov_instance_of[String], ov_kind_of[Numeric], nil ]
   ]
   def foo(ops = {})
-    ov.validate(ops,'ops')
+    Oval.validate(ops, ov, 'ops')
   end
   ```
   
+[[Table of Contents](#table-of-contents)|[Index of Declarators](#index-of-declarators)]
+
 ####<a id="ov\_options"></a>ov\_options       
 
 - Declaration
@@ -308,10 +315,12 @@ document all the core non-terminal declarators implemented in **Oval**.
     # ...
   ]
   def foo(ops = {})
-    ov.validate(ops,'ops')
+    Oval.validate(ops, ov, 'ops')
   end 
   ```
   
+[[Table of Contents](#table-of-contents)|[Index of Declarators](#index-of-declarators)]
+
 ####<a id="ov\_subclass\_of"></a>ov\_subclass\_of                               
 
 - Declaration
@@ -327,7 +336,7 @@ document all the core non-terminal declarators implemented in **Oval**.
   ```ruby
   ov = ov_options[ :bar => ov_subclass_of[Numeric] ]
   def foo(ops = {})
-    ov.validate(ops,'ops')
+    Oval.validate(ops, ov, 'ops')
   end
   ```
   

data/oval.gemspec

@@ -3,7 +3,7 @@ $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
 
 Gem::Specification.new do |gem|
   gem.name          = 'oval'
-  gem.version       = '0.0.5'
+  gem.version       = '0.0.6'
   gem.authors       = ["Pawel Tomulik"]
   gem.email         = ["ptomulik@meil.pw.edu.pl"]
   gem.description   = %q{Validate options when passed to methods}

data/spec/unit/oval/base_spec.rb

@@ -15,7 +15,7 @@ describe Oval::Base do
   end
 
   context "an instance" do
-    let(:subject) { described_class[:shape0] }
+    let(:subject) { described_class[:decl0] }
     [
       :validate,
     ].each do |method|
@@ -36,18 +36,18 @@ describe Oval::Base do
         expect { described_class.validate(:foo,:bar,'subj1') }.to_not raise_error
       end
     end
-    context "validate(:foo,shape)" do
-      let(:shape) { described_class[:shape0] }
-      it "should invoke shape.validate(:foo,nil) once" do
-        shape.expects(:validate).once.with(:foo,nil)
-        expect { described_class.validate(:foo,shape) }.to_not raise_error
+    context "validate(:foo,decl)" do
+      let(:decl) { described_class[:decl0] }
+      it "should invoke decl.validate(:foo,nil) once" do
+        decl.expects(:validate).once.with(:foo,nil)
+        expect { described_class.validate(:foo,decl) }.to_not raise_error
       end
     end
-    context "validate(:foo,shape,'subj1')" do
-      let(:shape) { described_class[:shape0] }
-      it "should invoke shape.validate(:foo,'subj1') once" do
-        shape.expects(:validate).once.with(:foo,'subj1')
-        expect { described_class.validate(:foo,shape,'subj1') }.to_not raise_error
+    context "validate(:foo,decl,'subj1')" do
+      let(:decl) { described_class[:decl0] }
+      it "should invoke decl.validate(:foo,'subj1') once" do
+        decl.expects(:validate).once.with(:foo,'subj1')
+        expect { described_class.validate(:foo,decl,'subj1') }.to_not raise_error
       end
     end
   end
@@ -65,7 +65,7 @@ describe Oval::Base do
   end
 
   describe "#validate" do
-    let(:subject) { described_class[:shape0] }
+    let(:subject) { described_class[:decl0] }
     let(:msg) { "This method should be overwritten by a subclass" }
     [ [], [:arg1,:arg2,:arg3] ].each do |args|
       context "validate(#{args.map{|x| x.inspect}.join(', ')})" do
@@ -82,52 +82,20 @@ describe Oval::Base do
     end
   end
 
-##  describe "#validate_shape" do
-##    let(:subject) { described_class[:shape0] }
-##    let(:msg) { "This method should be overwritten by a subclass" }
-##    [ [:arg1,:arg2] ].each do |args|
-##      context "validate_shape(#{args.map{|x| x.inspect}.join(', ')})" do
-##        let(:args) { args }
-##        it { expect { subject.validate_shape(*args) }.to raise_error ArgumentError }
-##      end
-##    end
-##    context "validate_shape()" do
-##      it { expect { subject.validate_shape() }.to raise_error NotImplementedError, msg}
-##    end
-##    context "validate_shape(:subj1)" do
-##      it { expect { subject.validate_shape(:subj1) }.to raise_error NotImplementedError, msg}
-##    end
-##  end
-
-
-##  describe "shape" do
-####    before { described_class.stubs(:validate_shape) }
-##    context "new(:shape0).shape" do
-##      it { described_class.new(:shape0).shape.should be :shape0 }
-##    end
-##    context "when @shape == :shape1" do
-##      let(:subject) { described_class.new(:shape0) }
-##      before { subject.instance_variable_set(:@shape,:shape1) }
-##      it { subject.shape.should be :shape1 }
-##    end
-##  end
-##
-##  describe "#shape=" do
-####    before { described_class.stubs(:validate_shape) }
-##    let(:subject) { described_class.new(:shape0) }
-##    context "#shape = :shape1" do
-####      it "should call self.class.validate_shape(:shape1) once" do
-####        subject # reference before re-stubbing validate_shape
-####        described_class.stubs(:validate_shape).never
-####        described_class.stubs(:validate_shape).once.with(:shape1,'Base')
-####        expect { subject.send(:shape=,:shape1) }.to_not raise_error
-####      end
-##      it "should assign @shape = :shape1" do
-##        subject.send(:shape=, :shape1)
-##        subject.instance_variable_get(:@shape).should be :shape1
-##      end
-##    end
-##  end
+  describe "#it_should" do
+    let(:subject) { described_class[:decl0] }
+    let(:msg) { "This method should be overwritten by a subclass" }
+    [ [:arg1], [:arg1,:arg2] ].each do |args|
+      context "it_should(#{args.map{|x| x.inspect}.join(', ')})" do
+        let(:args) { args }
+        before { described_class.expects(:it_should).never }
+        it { expect { subject.it_should(*args) }.to raise_error ArgumentError }
+      end
+    end
+    context "it_should" do
+      it { expect { subject.it_should }.to raise_error NotImplementedError, msg}
+    end
+  end
 
   describe "for_subject" do
     [
@@ -144,8 +112,7 @@ describe Oval::Base do
   end
 
   describe "#for_subject" do
-##    before { described_class.stubs(:validate_shape) }
-    let(:subject) { described_class.new(:shape0) }
+    let(:subject) { described_class.new(:decl0) }
     context "for_subject(:subj1)" do
       it "should == self.class.for_subject(subject)" do
         described_class.expects(:for_subject).once.with(:subj1).returns :ok
@@ -170,8 +137,7 @@ describe Oval::Base do
   end
 
   describe "#enumerate" do
-##    before { described_class.stubs(:validate_shape) }
-    let(:subject) { described_class.new(:shape0) }
+    let(:subject) { described_class.new(:decl0) }
     context "enumerate([],'and')" do
       it "should == self.class.enumerate(subject)" do
         described_class.expects(:enumerate).once.with([],'and').returns :ok

data/spec/unit/oval_spec.rb

@@ -47,7 +47,7 @@ describe Oval do
       Class.new do
         extend Oval
         def self.foo(ops = {})
-          ov_options[ :foo => ov_anything ].validate(ops, 'ops')
+          Oval.validate(ops, ov_options[ :foo => ov_anything ], 'ops')
         end
       end
     end
@@ -73,7 +73,7 @@ describe Oval do
         end
         # use ov to validate ops
         def self.foo(ops = {})
-          ov.validate(ops, 'ops')
+          Oval.validate(ops, ov, 'ops')
         end
       end
     end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: oval
 version: !ruby/object:Gem::Version
-  version: 0.0.5
+  version: 0.0.6
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-02-03 00:00:00.000000000 Z
+date: 2014-02-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake
@@ -202,7 +202,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: 2837400115143885778
+      hash: 3909914024463358041
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements:
@@ -211,7 +211,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: 2837400115143885778
+      hash: 3909914024463358041
 requirements: []
 rubyforge_project: 
 rubygems_version: 1.8.23