membrane 0.0.2 → 0.0.4

data/NOTICE

@@ -0,0 +1,10 @@
+cf-membrane
+
+Copyright (c) 2013 Pivotal Software Inc. All Rights Reserved. 
+
+This product is licensed to you under the Apache License, Version 2.0 (the "License").  
+You may not use this product except in compliance with the License.  
+
+This product may include a number of subcomponents with separate copyright notices 
+and license terms. Your use of these subcomponents is subject to the terms and 
+conditions of the subcomponent's license, as noted in the LICENSE file. 

data/README.md

@@ -1,3 +1,5 @@
+[![Build Status](https://travis-ci.org/cloudfoundry/membrane.png)](https://travis-ci.org/cloudfoundry/membrane)
+
 # Membrane
 
 Membrane provides an easy to use DSL for specifying validators declaratively.
@@ -7,38 +9,137 @@ decide what data to let in and what to keep out.
 
 ## Overview
 
-The core concept behind Membrane is the ```schema```. A ```schema```
-represents an invariant about a piece of data (similar to a type) and is
-capable of verifying whether or not a supplied datum satisfies the
-invariant. Schemas may be composed together to produce more expressive
-constructs.
+The core concept behind Membrane is the ```schema```. A ```schema``` represents
+an invariant about a piece of data (similar to a type) and is capable of
+verifying whether or not a supplied datum satisfies the invariant. Schemas may
+be composed to produce more expressive constructs.
 
 Membrane provides a handful of useful schemas out of the box. You should be
 able to construct the majority of your schemas using only what is provided
-by default. The provided schemas are:
-
-* _Any_        - Accepts all values. Use it sparingly. It is synonymous to
-  class Object in Ruby.
-* _Bool_       - Accepts ```true``` and ```false```.
-* _Class_      - Accepts instances of a supplied class.
-* _Dictionary_ - Accepts hashes whose keys and values validate against their
-  respective schemas.
-* _Enum_       - Accepts values that validate against _any_ of the supplied
-  schemas. Similar to a sum type.
-* _List_       - Accepts arrays where each element of the array validates
-  against a supplied schema.
-* _Record_     - Accepts hashes with known keys. Each key has a supplied schema,
-  against which its value must validate.
-* _Regexp_     - Accepts strings that match a supplied regular expression.
-* _Tuple_      - Accepts arrays of a given length whose elements validate
-  against their respective schemas.
-* _Value_      - Accepts values using ```==```.
+by default.
+
+
+*Any*
+
+The ```Any``` schema accepts all values; use it sparingly. It is synonymous to
+the Object class in Ruby.
+
+*Bool*
+
+The ```Bool``` schema accepts only the values ```true``` and ```false```.
+
+*Class*
+
+The ```Class``` schema is parameterized by an instance of
+```Class```. It accepts any values that are instances of the supplied class.
+This is verified using ```kind_of?```.
+
+*Dictionary*
+
+The ```Dictionary``` schema is parameterized by a key schema and a
+value schema.  It accepts hashes whose keys and values validate against their
+respective schemas.
+
+*Enum*
+
+The ```Enum``` parameterized by an arbitrary number of value schemas. It
+accepts any values that are accepted by at least one of the supplied schemas.
+
+*List*
+
+The ```List``` schema is parameterized by a single element schema. It accepts
+arrays whose elements are accepted by the supplied schema.
+
+*Record*
+
+The ```Record``` schema is parameterized by a set of known keys and their
+respective schemas. It accepts hashes that contain all the supplied keys,
+assuming the corresponding values are accepted by their respective schemas.
+
+*Regexp*
+
+The ```Regexp``` schema is parameterized by a regular expression. It accepts
+strings that match the supplied regular expression.
+
+*Tuple*
+
+The ```Tuple``` schema is parameterized by a fixed number of schemas. It accepts
+arrays of the same length, where each element is accepted by its associated
+schema.
+
+*Value*
+
+The ```Value``` schema is parameterized by a single value. It accepts values
+who are equal to the parameterizing value using ```==```.
+
+## DSL
+
+Membrane schemas are typically created using a concise DSL. The aforementioned
+schemas are represented in the DSL as follows:
+
+*Any*
+
+The ```Any``` schema is represented by the keyword ```any```.
+
+*Bool*
+
+The ```Bool``` schema is represented by the keyword ```bool```.
+
+*Class*
+
+The ```Class``` schema is represented by the parameterizing instance of ```Class```.
+For example, an instance of the Class schema that validates strings would be
+represented as ```String```.
+
+*Dictionary*
+
+The ```Dictionary``` schema is represented by ```dict(key_schema,
+value_schema```, where ```key_schema``` is the schema used to validate keys,
+and ```value_schema``` is the schema used to validate values.
+
+*Enum*
+
+The ```Enum``` schema is represented by ```enum(schema1, ..., schemaN)```
+where ```schema1``` through ```schemaN``` are the possible value schemas.
+
+*List*
+
+The ```List``` schema is represented by ```[elem_schema]```, where
+```elem_schema``` is the schema that all list elements must validate against.
+
+*Record*
+
+The ```Record``` schema is represented as follows:
+
+    { "key1"           => value1_schema,
+      optional("key2") => value2_schema,
+      ...
+    }
+
+Here ```key1``` must be contained in the hash and the corresponding value must
+be accepted by ```value1_schema```. Note that ```key2``` is marked as optional.
+If present, its corresponding value must be accepted by ```value2_schema```.
+
+*Regexp*
+
+The ```Regexp``` schema is represented by regexp literals. For example,
+```/foo|bar/``` matches strings containing "foo" or "bar".
+
+*Tuple*
+
+The ```Tuple``` schema is represented as ```tuple(schema0, ..., schemaN)```,
+where the Ith element of an array must be accepted by ```schemaI```.
+
+*Value*
+
+The ```Value``` schema is represented by the value to be validated. For example,
+```"foo"``` accepts only the string "foo".
 
 ## Usage
 
-Membrane schemas are typically created using a concise DSL. For example, the
-following creates a schema that will validate a hash where the key "ints"
-maps to a list of integers and the key "string" maps to a string.
+While the previous section was a bit abstract, the DSL is fairly intuitive.
+For example, the following creates a schema that will validate a hash where the
+key "ints" maps to a list of integers and the key "string" maps to a string.
 
     schema = Membrane::SchemaParser.parse do
       { "ints"   => [Integer],
@@ -58,8 +159,8 @@ maps to a list of integers and the key "string" maps to a string.
       "ints" => "invalid",
     })
 
-This is a more complicated example that illustrate the entire DSL. It should
-be self-explanatory.
+This is a more complicated example that illustrate the entire DSL. Hopefully
+it is self-explanatory:
 
     Membrane::SchemaParser.parse do
       { "ints"          => [Integer]
@@ -87,5 +188,4 @@ can be used as a schema:
     def validate(object)
 
 If you wish to include your new schema as part of the DSL, you'll need to
-modify ```membrane/schema_parser.rb``` and have your class inherit from
-```Membrane::Schema::Base```
+modify ```membrane/schema_parser.rb``` and have your class inherit from ```Membrane::Schemas::Base```

data/lib/membrane/schema_parser.rb

@@ -1,4 +1,4 @@
-require "membrane/schema"
+require "membrane/schemas"
 
 module Membrane
 end
@@ -13,11 +13,11 @@ class Membrane::SchemaParser
     TupleMarker       = Struct.new(:elem_schemas)
 
     def any
-      Membrane::Schema::Any.new
+      Membrane::Schemas::Any.new
     end
 
     def bool
-      Membrane::Schema::Bool.new
+      Membrane::Schemas::Bool.new
     end
 
     def enum(*elem_schemas)
@@ -53,31 +53,31 @@ class Membrane::SchemaParser
 
   def deparse(schema)
     case schema
-    when Membrane::Schema::Any
+    when Membrane::Schemas::Any
       "any"
-    when Membrane::Schema::Bool
+    when Membrane::Schemas::Bool
       "bool"
-    when Membrane::Schema::Class
+    when Membrane::Schemas::Class
       schema.klass.name
-    when Membrane::Schema::Dictionary
+    when Membrane::Schemas::Dictionary
       "dict(%s, %s)" % [deparse(schema.key_schema),
                         deparse(schema.value_schema)]
-    when Membrane::Schema::Enum
+    when Membrane::Schemas::Enum
       "enum(%s)" % [schema.elem_schemas.map { |es| deparse(es) }.join(", ")]
-    when Membrane::Schema::List
+    when Membrane::Schemas::List
       "[%s]" % [deparse(schema.elem_schema)]
-    when Membrane::Schema::Record
+    when Membrane::Schemas::Record
       deparse_record(schema)
-    when Membrane::Schema::Regexp
+    when Membrane::Schemas::Regexp
       schema.regexp.inspect
-    when Membrane::Schema::Tuple
+    when Membrane::Schemas::Tuple
       "tuple(%s)" % [schema.elem_schemas.map { |es| deparse(es) }.join(", ")]
-    when Membrane::Schema::Value
+    when Membrane::Schemas::Value
       schema.value.inspect
-    when Membrane::Schema::Base
+    when Membrane::Schemas::Base
       schema.inspect
     else
-      emsg = "Expected instance of Membrane::Schema::Base, given instance of" \
+      emsg = "Expected instance of Membrane::Schemas::Base, given instance of" \
              + " #{schema.class}"
       raise ArgumentError.new(emsg)
     end
@@ -92,22 +92,22 @@ class Membrane::SchemaParser
     when Array
       parse_list(object)
     when Class
-      Membrane::Schema::Class.new(object)
+      Membrane::Schemas::Class.new(object)
     when Regexp
-      Membrane::Schema::Regexp.new(object)
+      Membrane::Schemas::Regexp.new(object)
     when Dsl::DictionaryMarker
-      Membrane::Schema::Dictionary.new(do_parse(object.key_schema),
+      Membrane::Schemas::Dictionary.new(do_parse(object.key_schema),
                                        do_parse(object.value_schema))
     when Dsl::EnumMarker
       elem_schemas = object.elem_schemas.map { |s| do_parse(s) }
-      Membrane::Schema::Enum.new(*elem_schemas)
+      Membrane::Schemas::Enum.new(*elem_schemas)
     when Dsl::TupleMarker
       elem_schemas = object.elem_schemas.map { |s| do_parse(s) }
-      Membrane::Schema::Tuple.new(*elem_schemas)
-    when Membrane::Schema::Base
+      Membrane::Schemas::Tuple.new(*elem_schemas)
+    when Membrane::Schemas::Base
       object
     else
-      Membrane::Schema::Value.new(object)
+      Membrane::Schemas::Value.new(object)
     end
   end
 
@@ -118,7 +118,7 @@ class Membrane::SchemaParser
       raise ArgumentError.new("Lists can only match a single schema.")
     end
 
-    Membrane::Schema::List.new(do_parse(schema[0]))
+    Membrane::Schemas::List.new(do_parse(schema[0]))
   end
 
   def parse_record(schema)
@@ -139,7 +139,7 @@ class Membrane::SchemaParser
       parsed[key] = do_parse(value_schema)
     end
 
-    Membrane::Schema::Record.new(parsed, optional_keys)
+    Membrane::Schemas::Record.new(parsed, optional_keys)
   end
 
   def deparse_record(schema)
@@ -153,6 +153,7 @@ class Membrane::SchemaParser
         dep_key = key.inspect
       end
 
+      dep_key = DEPARSE_INDENT + dep_key
       dep_val_schema_lines = deparse(val_schema).split("\n")
 
       dep_val_schema_lines.each_with_index do |line, line_idx|

data/lib/membrane/schemas/any.rb

@@ -0,0 +1,8 @@
+require "membrane/errors"
+require "membrane/schemas/base"
+
+class Membrane::Schemas::Any < Membrane::Schemas::Base
+  def validate(object)
+    nil
+  end
+end

data/lib/membrane/{schema → schemas}/base.rb

@@ -1,9 +1,4 @@
-module Membrane
-  module Schema
-  end
-end
-
-class Membrane::Schema::Base
+class Membrane::Schemas::Base
   # Verifies whether or not the supplied object conforms to this schema
   #
   # @param [Object]  The object being validated

data/lib/membrane/schemas/bool.rb

@@ -0,0 +1,31 @@
+require "set"
+
+require "membrane/errors"
+require "membrane/schemas/base"
+
+class Membrane::Schemas::Bool < Membrane::Schemas::Base
+  def validate(object)
+    BoolValidator.new(object).validate
+  end
+
+  class BoolValidator
+    TRUTH_VALUES = Set.new([true, false])
+
+    def initialize(object)
+      @object = object
+    end
+
+    def validate
+      if !TRUTH_VALUES.include?(@object)
+        fail!
+      end
+    end
+
+    private
+
+    def fail!
+      emsg = "Expected instance of true or false, given #{@object}"
+      raise Membrane::SchemaValidationError.new(emsg)
+    end
+  end
+end

data/lib/membrane/schemas/class.rb

@@ -0,0 +1,35 @@
+require "membrane/errors"
+require "membrane/schemas/base"
+
+class Membrane::Schemas::Class < Membrane::Schemas::Base
+  attr_reader :klass
+
+  def initialize(klass)
+    @klass = klass
+  end
+
+  # Validates whether or not the supplied object is derived from klass
+  def validate(object)
+    ClassValidator.new(@klass, object).validate
+  end
+
+  class ClassValidator
+
+    def initialize(klass, object)
+      @klass = klass
+      @object = object
+    end
+
+    def validate
+      fail! if !@object.kind_of?(@klass)
+    end
+
+    private
+
+    def fail!
+      emsg = "Expected instance of #{@klass}," \
+             + " given an instance of #{@object.class}"
+      raise Membrane::SchemaValidationError.new(emsg)
+    end
+  end
+end

data/lib/membrane/schemas/dictionary.rb

@@ -0,0 +1,69 @@
+require "membrane/errors"
+require "membrane/schemas/base"
+
+module Membrane
+  module Schema
+  end
+end
+
+class Membrane::Schemas::Dictionary < Membrane::Schemas::Base
+  attr_reader :key_schema
+  attr_reader :value_schema
+
+  def initialize(key_schema, value_schema)
+    @key_schema = key_schema
+    @value_schema = value_schema
+  end
+
+  def validate(object)
+    HashValidator.new(object).validate
+    MembersValidator.new(@key_schema, @value_schema, object).validate
+  end
+
+  class HashValidator
+    def initialize(object)
+      @object = object
+    end
+
+    def validate
+      fail!(@object.class) if !@object.kind_of?(Hash)
+    end
+
+    private
+
+    def fail!(klass)
+      emsg = "Expected instance of Hash, given instance of #{klass}."
+      raise Membrane::SchemaValidationError.new(emsg)
+    end
+  end
+
+  class MembersValidator
+    def initialize(key_schema, value_schema, object)
+      @key_schema = key_schema
+      @value_schema = value_schema
+      @object = object
+    end
+
+    def validate
+      errors = {}
+
+      @object.each do |k, v|
+        begin
+          @key_schema.validate(k)
+          @value_schema.validate(v)
+        rescue Membrane::SchemaValidationError => e
+          errors[k] = e.to_s
+        end
+      end
+
+      fail!(errors) if errors.size > 0
+    end
+
+    private
+
+    def fail!(errors)
+      emsg = "{ " + errors.map { |k, e| "#{k} => #{e}" }.join(", ") + " }"
+      raise Membrane::SchemaValidationError.new(emsg)
+    end
+  end
+end

data/lib/membrane/schemas/enum.rb

@@ -0,0 +1,49 @@
+require "membrane/errors"
+require "membrane/schemas/base"
+
+module Membrane
+  module Schema
+  end
+end
+
+class Membrane::Schemas::Enum < Membrane::Schemas::Base
+  attr_reader :elem_schemas
+
+  def initialize(*elem_schemas)
+    @elem_schemas = elem_schemas
+  end
+
+  def validate(object)
+    EnumValidator.new(@elem_schemas, object).validate
+  end
+
+  class EnumValidator
+    def initialize(elem_schemas, object)
+      @elem_schemas = elem_schemas
+      @object = object
+    end
+
+    def validate
+      @elem_schemas.each do |schema|
+        begin
+          schema.validate(@object)
+          return nil
+        rescue Membrane::SchemaValidationError
+        end
+      end
+
+      fail!(@elem_schemas)
+    end
+
+    private
+
+    def fail!(elem_schemas)
+      elem_schema_str = elem_schemas.map { |s| s.to_s }.join(", ")
+
+      emsg = "Object #{@object} doesn't validate" \
+           + " against any of #{elem_schema_str}"
+      raise Membrane::SchemaValidationError.new(emsg)
+    end
+  end
+
+end

data/lib/membrane/schemas/list.rb

@@ -0,0 +1,63 @@
+require "membrane/errors"
+require "membrane/schemas/base"
+
+module Membrane
+  module Schema
+  end
+end
+
+class Membrane::Schemas::List < Membrane::Schemas::Base
+  attr_reader :elem_schema
+
+  def initialize(elem_schema)
+    @elem_schema = elem_schema
+  end
+
+  def validate(object)
+    ArrayValidator.new(object).validate
+    MemberValidator.new(@elem_schema, object).validate
+  end
+
+  class ArrayValidator
+    def initialize(object)
+      @object = object
+    end
+
+    def validate
+      fail! if !@object.kind_of?(Array)
+    end
+
+    private
+
+    def fail!
+      emsg = "Expected instance of Array, given instance of #{@object.class}"
+      raise Membrane::SchemaValidationError.new(emsg)
+    end
+  end
+
+  class MemberValidator
+    def initialize(elem_schema, object)
+      @elem_schema = elem_schema
+      @object = object
+    end
+
+    def validate
+      errors = {}
+
+      @object.each_with_index do |elem, ii|
+        begin
+          @elem_schema.validate(elem)
+        rescue Membrane::SchemaValidationError => e
+          errors[ii] = e.to_s
+        end
+      end
+
+      fail!(errors) if errors.size > 0
+    end
+
+    def fail!(errors)
+      emsg = errors.map { |ii, e| "At index #{ii}: #{e}" }.join(", ")
+      raise Membrane::SchemaValidationError.new(emsg)
+    end
+  end
+end

data/lib/membrane/schemas/record.rb

@@ -0,0 +1,96 @@
+require "set"
+
+require "membrane/errors"
+require "membrane/schemas/base"
+
+module Membrane
+  module Schema
+  end
+end
+
+class Membrane::Schemas::Record < Membrane::Schemas::Base
+  attr_reader :schemas
+  attr_reader :optional_keys
+
+  def initialize(schemas, optional_keys = [], strict_checking = false)
+    @optional_keys = Set.new(optional_keys)
+    @schemas = schemas
+    @strict_checking = strict_checking
+  end
+
+  def validate(object)
+    HashValidator.new(object).validate
+    KeyValidator.new(@optional_keys, @schemas, @strict_checking, object).validate
+  end
+
+  def parse(&blk)
+    other_record = Membrane::SchemaParser.parse(&blk)
+    @schemas.merge!(other_record.schemas)
+    @optional_keys << other_record.optional_keys
+
+    self
+  end
+
+  class KeyValidator
+    def initialize(optional_keys, schemas, strict_checking, object)
+      @optional_keys = optional_keys
+      @schemas = schemas
+      @strict_checking = strict_checking
+      @object = object
+    end
+
+    def validate
+      key_errors = {}
+      schema_keys = []
+      @schemas.each do |k, schema|
+        if @object.has_key?(k)
+          schema_keys << k
+          begin
+            schema.validate(@object[k])
+          rescue Membrane::SchemaValidationError => e
+            key_errors[k] = e.to_s
+          end
+        elsif !@optional_keys.include?(k)
+          key_errors[k] = "Missing key"
+        end
+      end
+
+      key_errors.merge!(validate_extra_keys(@object.keys - schema_keys)) if @strict_checking
+
+      fail!(key_errors) if key_errors.size > 0
+    end
+
+    private
+
+    def validate_extra_keys(extra_keys)
+      extra_key_errors = {}
+      extra_keys.each do |k|
+        extra_key_errors[k] = "was not specified in the schema"
+      end
+
+      extra_key_errors
+    end
+
+    def fail!(errors)
+      emsg = "{ " + errors.map { |k, e| "#{k} => #{e}" }.join(", ") + " }"
+      raise Membrane::SchemaValidationError.new(emsg)
+    end
+  end
+
+  class HashValidator
+    def initialize(object)
+      @object = object
+    end
+
+    def validate
+      fail! unless @object.kind_of?(Hash)
+    end
+
+    private
+
+    def fail!
+      emsg = "Expected instance of Hash, given instance of #{@object.class}"
+      raise Membrane::SchemaValidationError.new(emsg)
+    end
+  end
+end