membrane 0.0.1

data/README.md

@@ -0,0 +1,90 @@
+# Membrane
+
+Membrane provides an easy to use DSL for specifying validators declaratively.
+It's intended to be used to validate data received from external sources,
+such as API endpoints or config files. Use it at the edges of your process to
+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.
+
+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.
+* _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 ```==```.
+
+## 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.
+
+    schema = Membrane::SchemaParser.parse do
+      { "ints"   => [Integer],
+        "string" => String,
+      }
+    end
+
+    # Validates successfully
+    schema.validate({
+      "ints"   => [1],
+      "string" => "hi",
+    })
+
+    # Fails validation. The key "string" is missing and the value for "ints"
+    # isn't the correct type.
+    schema.validate({
+      "ints" => "invalid",
+    })
+
+This is a more complicated example that illustrate the entire DSL. It should
+be self-explanatory.
+
+    Membrane::SchemaParser.parse do
+      { "ints"          => [Integer]
+        "true_or_false" => bool,
+        "anything"      => any,
+        optional("_")   => any,
+        "one_or_two"    => enum(1, 2),
+        "strs_to_ints"  => dict(String, Integer),
+        "foo_prefix"    => /^foo/,
+        "three_ints"    => tuple(Integer, Integer, Integer),
+      }
+    end
+
+## Adding new schemas
+
+Adding a new schema is trivial. Any class implementing the following "interface"
+can be used as a schema:
+
+    # @param [Object] The object being validated.
+    #
+    # @raise [Membrane::SchemaValidationError] Raised when a supplied object is
+    # invalid.
+    #
+    # @return [nil]
+    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```

data/Rakefile

@@ -0,0 +1,14 @@
+#!/usr/bin/env rake
+require "ci/reporter/rake/rspec"
+require "rspec/core/rake_task"
+
+desc "Run all specs"
+RSpec::Core::RakeTask.new("spec") do |t|
+  t.rspec_opts = %w[--color --format documentation]
+end
+
+desc "Run all specs and provide output for ci"
+RSpec::Core::RakeTask.new("spec:ci" => "ci:setup:rspec") do |t|
+  t.rspec_opts = %w[--no-color --format documentation]
+end
+

data/lib/membrane/errors.rb

@@ -0,0 +1,3 @@
+module Membrane
+  class SchemaValidationError < StandardError; end
+end

data/lib/membrane/schema/any.rb

@@ -0,0 +1,13 @@
+require "membrane/errors"
+require "membrane/schema/base"
+
+module Membrane
+  module Schema
+  end
+end
+
+class Membrane::Schema::Any < Membrane::Schema::Base
+  def validate(object)
+    nil
+  end
+end

data/lib/membrane/schema/base.rb

@@ -0,0 +1,17 @@
+module Membrane
+  module Schema
+  end
+end
+
+class Membrane::Schema::Base
+  # Verifies whether or not the supplied object conforms to this schema
+  #
+  # @param [Object]  The object being validated
+  #
+  # @raise [Membrane::SchemaValidationError]
+  #
+  # @return [nil]
+  def validate(object)
+    raise NotImplementedError
+  end
+end

data/lib/membrane/schema/bool.rb

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

data/lib/membrane/schema/class.rb

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

data/lib/membrane/schema/dictionary.rb

@@ -0,0 +1,40 @@
+require "membrane/errors"
+require "membrane/schema/base"
+
+module Membrane
+  module Schema
+  end
+end
+
+class Membrane::Schema::Dictionary
+  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)
+    if !object.kind_of?(Hash)
+      emsg = "Expected instance of Hash, given instance of #{object.class}."
+      raise Membrane::SchemaValidationError.new(emsg)
+    end
+
+    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
+
+    if errors.size > 0
+      emsg = "{ " + errors.map { |k, e| "#{k} => #{e}" }.join(", ") + " }"
+      raise Membrane::SchemaValidationError.new(emsg)
+    end
+  end
+end

data/lib/membrane/schema/enum.rb

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

data/lib/membrane/schema/list.rb

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

data/lib/membrane/schema/record.rb

@@ -0,0 +1,45 @@
+require "set"
+
+require "membrane/errors"
+require "membrane/schema/base"
+
+module Membrane
+  module Schema
+  end
+end
+
+class Membrane::Schema::Record < Membrane::Schema::Base
+  attr_reader :schemas
+  attr_reader :optional_keys
+
+  def initialize(schemas, optional_keys = [])
+    @optional_keys = Set.new(optional_keys)
+    @schemas = schemas
+  end
+
+  def validate(object)
+    unless object.kind_of?(Hash)
+      emsg = "Expected instance of Hash, given instance of #{object.class}"
+      raise Membrane::SchemaValidationError.new(emsg)
+    end
+
+    key_errors = {}
+
+    @schemas.each do |k, schema|
+      if object.has_key?(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
+
+    if key_errors.size > 0
+      emsg = "{ " + key_errors.map { |k, e| "#{k} => #{e}" }.join(", ") + " }"
+      raise Membrane::SchemaValidationError.new(emsg)
+    end
+  end
+end

data/lib/membrane/schema/regexp.rb

@@ -0,0 +1,29 @@
+require "membrane/errors"
+require "membrane/schema/base"
+
+module Membrane
+  module Schema
+  end
+end
+
+class Membrane::Schema::Regexp < Membrane::Schema::Base
+  attr_reader :regexp
+
+  def initialize(regexp)
+    @regexp = regexp
+  end
+
+  def validate(object)
+    if !object.kind_of?(String)
+      emsg = "Expected instance of String, given instance of #{object.class}"
+      raise Membrane::SchemaValidationError.new(emsg)
+    end
+
+    if !regexp.match(object)
+      emsg = "Value #{object} doesn't match regexp #{@regexp}"
+      raise Membrane::SchemaValidationError.new(emsg)
+    end
+
+    nil
+  end
+end

data/lib/membrane/schema/tuple.rb

@@ -0,0 +1,48 @@
+require "membrane/errors"
+require "membrane/schema/base"
+
+module Membrane
+  module Schema
+  end
+end
+
+class Membrane::Schema::Tuple < Membrane::Schema::Base
+  attr_reader :elem_schemas
+
+  def initialize(*elem_schemas)
+    @elem_schemas = elem_schemas
+  end
+
+  def validate(object)
+    if !object.kind_of?(Array)
+      emsg = "Expected instance of Array, given instance of #{object.class}"
+      raise Membrane::SchemaValidationError.new(emsg)
+    end
+
+    expected = @elem_schemas.length
+    actual = object.length
+
+    if actual != expected
+      emsg = "Expected #{expected} element(s), given #{actual}"
+      raise Membrane::SchemaValidationError.new(emsg)
+    end
+
+    errors = {}
+
+    @elem_schemas.each_with_index do |schema, ii|
+      begin
+        schema.validate(object[ii])
+      rescue Membrane::SchemaValidationError => e
+        errors[ii] = e
+      end
+    end
+
+    if errors.size > 0
+      emsg = "There were errors at the following indices: " \
+             + errors.map { |ii, err| "#{ii} => #{err}" }.join(", ")
+      raise Membrane::SchemaValidationError.new(emsg)
+    end
+
+    nil
+  end
+end

data/lib/membrane/schema/value.rb

@@ -0,0 +1,22 @@
+require "membrane/errors"
+require "membrane/schema/base"
+
+module Membrane
+  module Schema
+  end
+end
+
+class Membrane::Schema::Value < Membrane::Schema::Base
+  attr_reader :value
+
+  def initialize(value)
+    @value = value
+  end
+
+  def validate(object)
+    if object != @value
+      emsg = "Expected #{@value}, given #{object}"
+      raise Membrane::SchemaValidationError.new(emsg)
+    end
+  end
+end

data/lib/membrane/schema.rb

@@ -0,0 +1,17 @@
+require "membrane/schema/any"
+require "membrane/schema/base"
+require "membrane/schema/bool"
+require "membrane/schema/class"
+require "membrane/schema/dictionary"
+require "membrane/schema/enum"
+require "membrane/schema/list"
+require "membrane/schema/record"
+require "membrane/schema/regexp"
+require "membrane/schema/tuple"
+require "membrane/schema/value"
+
+module Membrane
+  module Schema
+    ANY = Membrane::Schema::Any.new
+  end
+end

data/lib/membrane/schema_parser.rb

@@ -0,0 +1,186 @@
+require "membrane/schema"
+
+module Membrane
+end
+
+class Membrane::SchemaParser
+  DEPARSE_INDENT = "  ".freeze
+
+  class Dsl
+    OptionalKeyMarker = Struct.new(:key)
+    DictionaryMarker  = Struct.new(:key_schema, :value_schema)
+    EnumMarker        = Struct.new(:elem_schemas)
+    TupleMarker       = Struct.new(:elem_schemas)
+
+    def any
+      Membrane::Schema::Any.new
+    end
+
+    def bool
+      Membrane::Schema::Bool.new
+    end
+
+    def enum(*elem_schemas)
+      EnumMarker.new(elem_schemas)
+    end
+
+    def dict(key_schema, value_schema)
+      DictionaryMarker.new(key_schema, value_schema)
+    end
+
+    def optional(key)
+      Dsl::OptionalKeyMarker.new(key)
+    end
+
+    def tuple(*elem_schemas)
+      TupleMarker.new(elem_schemas)
+    end
+  end
+
+  def self.parse(&blk)
+    new.parse(&blk)
+  end
+
+  def self.deparse(schema)
+    new.deparse(schema)
+  end
+
+  def parse(&blk)
+    intermediate_schema = Dsl.new.instance_eval(&blk)
+
+    do_parse(intermediate_schema)
+  end
+
+  def deparse(schema)
+    case schema
+    when Membrane::Schema::Any
+      "any"
+    when Membrane::Schema::Bool
+      "bool"
+    when Membrane::Schema::Class
+      schema.klass.inspect
+    when Membrane::Schema::Dictionary
+      "dict(%s, %s)" % [deparse(schema.key_schema),
+                        deparse(schema.value_schema)]
+    when Membrane::Schema::Enum
+      "enum(%s)" % [schema.elem_schemas.map { |es| deparse(es) }.join(", ")]
+    when Membrane::Schema::List
+      "[%s]" % [deparse(schema.elem_schema)]
+    when Membrane::Schema::Record
+      deparse_record(schema)
+    when Membrane::Schema::Regexp
+      schema.regexp.inspect
+    when Membrane::Schema::Tuple
+      "tuple(%s)" % [schema.elem_schemas.map { |es| deparse(es) }.join(", ")]
+    when Membrane::Schema::Value
+      schema.value.inspect
+    when Membrane::Schema::Base
+      if schema.respond_to?(:deparse)
+        schema.deparse
+      else
+        schema.inspect
+      end
+    else
+      emsg = "Expected instance of Membrane::Schema::Base, given instance of" \
+             + " #{schema.class}"
+      raise ArgumentError.new(emsg)
+    end
+  end
+
+  private
+
+  def do_parse(object)
+    case object
+    when Hash
+      parse_record(object)
+    when Array
+      parse_list(object)
+    when Class
+      Membrane::Schema::Class.new(object)
+    when Regexp
+      Membrane::Schema::Regexp.new(object)
+    when Dsl::DictionaryMarker
+      Membrane::Schema::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)
+    when Dsl::TupleMarker
+      elem_schemas = object.elem_schemas.map { |s| do_parse(s) }
+      Membrane::Schema::Tuple.new(*elem_schemas)
+    when Membrane::Schema::Base
+      object
+    else
+      Membrane::Schema::Value.new(object)
+    end
+  end
+
+  def parse_list(schema)
+    if schema.empty?
+      raise ArgumentError.new("You must supply a schema for elements.")
+    elsif schema.length > 1
+      raise ArgumentError.new("Lists can only match a single schema.")
+    end
+
+    Membrane::Schema::List.new(do_parse(schema[0]))
+  end
+
+  def parse_record(schema)
+    if schema.empty?
+      raise ArgumentError.new("You must supply at least one key-value pair.")
+    end
+
+    optional_keys = []
+
+    parsed = {}
+
+    schema.each do |key, value_schema|
+      if key.kind_of?(Dsl::OptionalKeyMarker)
+        key = key.key
+        optional_keys << key
+      end
+
+      parsed[key] = do_parse(value_schema)
+    end
+
+    Membrane::Schema::Record.new(parsed, optional_keys)
+  end
+
+  def deparse_record(schema)
+    lines = ["{"]
+
+    schema.schemas.each do |key, val_schema|
+      dep_key = nil
+      if schema.optional_keys.include?(key)
+        dep_key = "optional(%s)" % [key.inspect]
+      else
+        dep_key = key.inspect
+      end
+
+      dep_val_schema_lines = deparse(val_schema).split("\n")
+
+      dep_val_schema_lines.each_with_index do |line, line_idx|
+        to_append = nil
+
+        if 0 == line_idx
+          to_append = "%s => %s" % [dep_key, line]
+        else
+          # Indent continuation lines
+          to_append = DEPARSE_INDENT + line
+        end
+
+        # This concludes the deparsed schema, append a comma in preparation
+        # for the next k-v pair.
+        if dep_val_schema_lines.size - 1 == line_idx
+          to_append += ","
+        end
+
+        lines << to_append
+      end
+    end
+
+    lines << "}"
+
+    lines.join("\n")
+  end
+end

data/lib/membrane/version.rb

@@ -0,0 +1,3 @@
+module Membrane
+  VERSION = "0.0.1"
+end

data/lib/membrane.rb

@@ -0,0 +1,4 @@
+require "membrane/errors"
+require "membrane/schema"
+require "membrane/schema_parser"
+require "membrane/version"

data/membrane.gemspec

@@ -0,0 +1,25 @@
+# -*- encoding: utf-8 -*-
+require File.expand_path('../lib/membrane/version', __FILE__)
+
+Gem::Specification.new do |gem|
+  gem.name          = "membrane"
+  gem.version       = Membrane::VERSION
+  gem.date          = "2012-07-09"
+  gem.summary       = "A DSL for validating data."
+  gem.homepage      = "http://www.cloudfoundry.org"
+  gem.authors       = ["mpage"]
+  gem.email         = ["support@cloudfoundry.org"]
+  gem.description   =<<-EOT
+      Membrane provides an easy to use DSL for specifying validation
+      logic declaratively.
+      EOT
+
+  gem.files         = `git ls-files`.split($\)
+  gem.executables   = gem.files.grep(%r{^bin/}).map{ |f| File.basename(f) }
+  gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
+  gem.require_paths = ["lib"]
+
+  gem.add_development_dependency("ci_reporter")
+  gem.add_development_dependency("rake")
+  gem.add_development_dependency("rspec")
+end