qrb 0.1.0

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+# 0.1.0 / 2014-03-03
+
+* Enhancements
+
+  * Birthday!

data/Gemfile

@@ -0,0 +1,12 @@
+source 'http://rubygems.org'
+
+gem "citrus", "~> 2.4"
+
+group :development do
+  gem "rake", "~> 10.0"
+  gem "rspec", "~> 2.14"
+  gem "cucumber", "~> 1.3"
+  gem "path", "~> 1.3"
+  gem "awesome_print", "~> 1.2"
+  gem 'coveralls', require: false
+end

data/Gemfile.lock

@@ -0,0 +1,58 @@
+GEM
+  remote: http://rubygems.org/
+  specs:
+    awesome_print (1.2.0)
+    builder (3.2.2)
+    citrus (2.4.1)
+    coveralls (0.7.0)
+      multi_json (~> 1.3)
+      rest-client
+      simplecov (>= 0.7)
+      term-ansicolor
+      thor
+    cucumber (1.3.8)
+      builder (>= 2.1.2)
+      diff-lcs (>= 1.1.3)
+      gherkin (~> 2.12.1)
+      multi_json (>= 1.7.5, < 2.0)
+      multi_test (>= 0.0.2)
+    diff-lcs (1.2.5)
+    docile (1.1.3)
+    gherkin (2.12.2)
+      multi_json (~> 1.3)
+    mime-types (2.1)
+    multi_json (1.8.4)
+    multi_test (0.0.2)
+    path (1.3.3)
+    rake (10.1.1)
+    rest-client (1.6.7)
+      mime-types (>= 1.16)
+    rspec (2.14.1)
+      rspec-core (~> 2.14.0)
+      rspec-expectations (~> 2.14.0)
+      rspec-mocks (~> 2.14.0)
+    rspec-core (2.14.7)
+    rspec-expectations (2.14.4)
+      diff-lcs (>= 1.1.3, < 2.0)
+    rspec-mocks (2.14.4)
+    simplecov (0.8.2)
+      docile (~> 1.1.0)
+      multi_json
+      simplecov-html (~> 0.8.0)
+    simplecov-html (0.8.0)
+    term-ansicolor (1.3.0)
+      tins (~> 1.0)
+    thor (0.18.1)
+    tins (1.0.0)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  awesome_print (~> 1.2)
+  citrus (~> 2.4)
+  coveralls
+  cucumber (~> 1.3)
+  path (~> 1.3)
+  rake (~> 10.0)
+  rspec (~> 2.14)

data/LICENCE.md

@@ -0,0 +1,22 @@
+# The MIT Licence
+
+    Copyright (c) 2014 - Bernard Lambeau
+
+    Permission is hereby granted, free of charge, to any person obtaining
+    a copy of this software and associated documentation files (the
+    "Software"), to deal in the Software without restriction, including
+    without limitation the rights to use, copy, modify, merge, publish,
+    distribute, sublicense, and/or sell copies of the Software, and to
+    permit persons to whom the Software is furnished to do so, subject to
+    the following conditions:
+
+    The above copyright notice and this permission notice shall be
+    included in all copies or substantial portions of the Software.
+
+    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+    EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+    MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+    NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+    LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+    OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+    WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/Manifest.txt

@@ -0,0 +1,11 @@
+CHANGELOG.md
+Gemfile
+Gemfile.lock
+lib/**/*
+LICENCE.md
+Manifest.txt
+qrb.gemspec
+Rakefile
+README.md
+spec/**/*
+tasks/**/*

data/README.md

@@ -0,0 +1,118 @@
+[![Build Status](https://travis-ci.org/blambeau/qrb.png)](https://travis-ci.org/blambeau/qrb)
+[![Dependency Status](https://gemnasium.com/blambeau/qrb.png)](https://gemnasium.com/blambeau/qrb)
+[![Code Climate](https://codeclimate.com/github/blambeau/qrb.png)](https://codeclimate.com/github/blambeau/qrb)
+[![Coverage Status](https://coveralls.io/repos/blambeau/qrb/badge.png?branch=master)](https://coveralls.io/r/blambeau/qrb)
+
+# Qrb
+
+*Q* is a language for capturing information structure. Think "JSON/XML schema"
+but the correct way. For more information about *Q* itself, see [www.q-lang.io](http://www.q-lang.io)
+
+Qrb is the ruby binding of *Q*. It allows defining Q schemas and validating
+and coercing data against them in an idiomatic ruby way.
+
+## Example
+
+```ruby
+require 'qrb'
+require 'json'
+
+# Let load a Q schema
+schema = Qrb::DEFAULT_SYSTEM.parse <<-Q
+  {
+    name: String( s | s.strip.size > 0 ),
+    at: DateTime
+  }
+Q
+
+# Let load some JSON document
+data = JSON.parse <<-JSON
+  { "name": "Q", "at": "20142-03-01" }
+JSON
+
+# And try dressing that data
+puts schema.dress(data)
+```
+
+## About this Q binding
+
+Qrb tries to provide an idiomatic binding for ruby developers. In particular,
+it uses a simple convention-over-configuration protocol for information
+contracts. This protocol is easily described through an example. The following
+ADT definition:
+
+```ruby
+Color = .Color <rgb> {r: Byte, g: Byte, b: Byte}
+```
+
+expects the following ruby class:
+
+```ruby
+class Color
+
+  # Constructor & internal representation
+  def initialize(r, g, b)
+    @r, @g, @b = r, g, b
+  end
+  attr_reader :r, :g, :b
+
+  # Public dresser for the RGB information contract on the class
+  def self.rgb(tuple)
+    new(tuple[:r], tuple[:g], tuple[:b])
+  end
+
+  # Public undresser on the instance
+  def to_rgb
+    { r: @r, g: @g, b: @b }
+  end
+
+  # ...
+
+end
+```
+
+## About representations
+
+The `Rep` representation function mapping Q types to ruby classes is as
+follows:
+
+```ruby
+# Builtins are represented by the corresponding ruby class
+Rep(.Builtin) = Builtin
+
+# Sub types are represented by the same representation as the super type
+Rep(SuperType( s | ... )) = Rep(SuperType)
+
+# Unions are represented by the corresponding classes. The guaranteed result
+# class is thus the least common super class (^) of the corresponding
+# representations of candidate types
+Rep(T1 | ... | Tn) = Rep(T1) ^ ... ^ Rep(Tn)
+
+# Sequences are represented through ::Array.
+Rep([ElmType]) = Array<Rep(ElmType)>
+
+# Sets are represented through ::Set.
+Rep({ElmType}) = Set<Rep(ElmType)>
+
+# Tuples are represented through ruby ::Hash. Attribute names are always
+# symbolized
+Rep({Ai => Ti}) = Hash<Symbol => Rep(Ti)>
+
+# Relations are represented through ruby ::Set of ::Hash.
+Rep({{Ai => Ti}}) = Set<Hash<Symbol => Rep(Ti)>>
+
+# Abstract data types are represented through the corresponding class when
+# specified. ADTs behave as Union types if no class is bound.
+Rep(.Builtin <rep> ...) = Builtin
+```
+
+## About the default system
+
+See `lib/qrb/Q/default.q` for the precise definition of the default system.
+In summary,
+
+* Most ruby native (data) classes are already aliased to avoid explicit use of
+  builtins. In particular, `Integer`, `String`, etc.
+* A `Boolean` union type also hides the TrueClass and FalseClass distinction.
+* Date, Time and DateTime ADTs are also provided that perform common
+  conversions from JSON strings, through iso8601.

data/Rakefile

@@ -0,0 +1,11 @@
+# We run tests by default
+task :default => :test
+
+#
+# Install all tasks found in tasks folder
+#
+# See .rake files there for complete documentation.
+#
+Dir["tasks/*.rake"].each do |taskfile|
+  load taskfile
+end

data/lib/qrb/Q/default.q

@@ -0,0 +1,29 @@
+# Nil
+NilClass = .NilClass
+Nil      = .NilClass
+
+# Booleans
+TrueClass  = .TrueClass
+FalseClass = .TrueClass
+True       = .TrueClass
+False      = .FalseClass
+Boolean    = .TrueClass|.FalseClass
+
+# Numbers
+Numeric = .Numeric
+Fixnum  = .Fixnum
+Bignum  = .Bignum
+Integer = .Integer
+Float   = .Float
+Real    = .Float
+
+# String
+String  = .String
+
+# Date, Time, DateTime
+Date     = .Date     <iso8601> .String \( s | Date.iso8601(s) )
+                                       \( d | d.iso8601       )
+Time     = .Time     <iso8601> .String \( s | Time.iso8601(s) )
+                                       \( t | t.iso8601       )
+DateTime = .DateTime <iso8601> .String \( s | DateTime.iso8601(s) )
+                                       \( t | t.iso8601           )

data/lib/qrb/data_type.rb

@@ -0,0 +1,23 @@
+module Qrb
+  module DataType
+
+    def dress(value, handler = DressHelper.new)
+      ad_type.dress(value, handler)
+    end
+
+    def contract(name, infotype)
+      ad_contracts[name] = [ Qrb.type(infotype) , method(name) ]
+    end
+
+  private
+
+    def ad_type
+      @ad_type ||= Qrb.adt(self, ad_contracts)
+    end
+
+    def ad_contracts
+      @ad_contracts ||= {}
+    end
+
+  end # module DataType
+end # module Qrb

data/lib/qrb/errors.rb

@@ -0,0 +1,23 @@
+module Qrb
+
+  class Error < StandardError
+
+    def initialize(msg, cause = nil)
+      super(msg)
+      @cause = cause
+    end
+    attr_reader :cause
+
+  end # class Error
+
+  class TypeError < Error
+
+    def initialize(msg, cause = nil, location = nil)
+      super(msg, cause)
+      @location = location || ''
+    end
+    attr_reader :location
+
+  end # class TypeError
+
+end # module Qrb

data/lib/qrb/support/attribute.rb

@@ -0,0 +1,53 @@
+module Qrb
+  #
+  # Helper class for tuple and relation attributes.
+  #
+  # An attribute is simply a `(name: AttrName, type: Type)` pair, where the
+  # type is a Q type.
+  #
+  class Attribute
+
+    def initialize(name, type)
+      unless name.is_a?(Symbol)
+        raise ArgumentError, "Symbol expected for attribute name, got `#{name}`"
+      end
+
+      unless type.is_a?(Type)
+        raise ArgumentError, "Type expected for attribute domain, got `#{type}`"
+      end
+
+      @name, @type = name, type
+    end
+    attr_reader :name, :type
+
+    # Fetch the attribute on `arg`, which is expected to be a Hash object.
+    #
+    # This method allows working with ruby hashes having either Symbols or
+    # Strings as keys. It ensures that no Symbol is created by the rest of the
+    # code, since this would provide a DoS attack vector under MRI.
+    #
+    def fetch_on(arg, &bl)
+      unless arg.respond_to?(:fetch)
+        raise ArgumentError, "Object responding to `fetch` expected"
+      end
+      arg.fetch(name) do
+        arg.fetch(name.to_s, &bl)
+      end
+    end
+
+    def to_name
+      "#{name}: #{type}"
+    end
+
+    def ==(other)
+      return nil unless other.is_a?(Attribute)
+      name==other.name and type==other.type
+    end
+    alias :eql? :==
+
+    def hash
+      name.hash ^ type.hash
+    end
+
+  end # class Attribute
+end # module Qrb

data/lib/qrb/support/collection_type.rb

@@ -0,0 +1,25 @@
+module Qrb
+  module CollectionType
+
+    def initialize(elm_type, name = nil)
+      unless elm_type.is_a?(Type)
+        raise ArgumentError, "Qrb::Type expected, got `#{elm_type}`"
+      end
+
+      super(name)
+      @elm_type = elm_type
+    end
+    attr_reader :elm_type
+
+    def ==(other)
+      return false unless other.is_a?(self.class)
+      elm_type == other.elm_type
+    end
+    alias :eql? :==
+
+    def hash
+      self.class.hash ^ self.elm_type.hash
+    end
+
+  end # module CollectionType
+end # module Qrb

data/lib/qrb/support/dress_helper.rb

@@ -0,0 +1,68 @@
+module Qrb
+  class DressHelper
+
+    def initialize
+      @stack = []
+    end
+
+    def iterate(value)
+      value.each.each_with_index do |elm, index|
+        deeper(index) do
+          yield(elm, index)
+        end
+      end
+    end
+
+    def deeper(location)
+      @stack.push(location.to_s)
+      res = yield
+    ensure
+      @stack.pop
+      res
+    end
+
+    def just_try(rescue_on = TypeError)
+      [ true, yield ]
+    rescue rescue_on => cause
+      [ false, nil ]
+    end
+
+    def try(type, value)
+      yield
+    rescue TypeError => cause
+      failed!(type, value, cause)
+    end
+
+    def failed!(type, value, cause = nil)
+      msg = default_error_message(type, value)
+      raise TypeError.new(msg, cause, location)
+    end
+
+    def fail!(msg, cause = nil)
+      raise TypeError.new(msg, cause, location)
+    end
+
+    def default_error_message(type, value)
+      value_s, type_s = value_to_s(value), type_to_s(type)
+      "Invalid value `#{value_s}` for #{type_s}"
+    end
+
+    def location
+      @stack.join('/')
+    end
+
+  private
+
+    def value_to_s(value)
+      return 'nil' if value.nil?
+      s = value.to_s
+      s = "#{s[0..25]}..." if s.size>25
+      s
+    end
+
+    def type_to_s(type)
+      type.name.to_s
+    end
+
+  end # class DressHelper
+end # module Qrb

data/lib/qrb/support/heading.rb

@@ -0,0 +1,57 @@
+module Qrb
+  #
+  # Helper class for tuple and relation types.
+  #
+  # A heading is a set of attributes, with the constraint that no two
+  # attributes have the same name.
+  #
+  class Heading
+    include Enumerable
+
+    def initialize(attributes)
+      unless attributes.is_a?(Enumerable) and \
+             attributes.all?{|a| a.is_a?(Attribute) }
+        raise ArgumentError, "Enumerable[Attribute] expected"
+      end
+
+      @attributes = {}
+      attributes.each do |attr|
+        if @attributes[attr.name]
+          raise ArgumentError, "Attribute names must be unique"
+        end
+        @attributes[attr.name] = attr
+      end
+      @attributes.freeze
+    end
+
+    def size
+      @attributes.size
+    end
+
+    def empty?
+      size == 0
+    end
+
+    def each(&bl)
+      return to_enum unless bl
+      @attributes.values.each(&bl)
+    end
+
+    def to_name
+      map(&:to_name).join(', ')
+    end
+
+    def ==(other)
+      return nil unless other.is_a?(Heading)
+      attributes == other.attributes
+    end
+
+    def hash
+      self.class.hash ^ attributes.hash
+    end
+
+    attr_reader :attributes
+    protected   :attributes
+
+  end # class Heading
+end # class Qrb

data/lib/qrb/support/type_factory.rb

@@ -0,0 +1,178 @@
+module Qrb
+  class TypeFactory
+
+    ################################################################## Factory
+
+    def type(type, name = nil, &bl)
+      return subtype(type(type, name), bl) if bl
+      case type
+      when Type
+        type
+      when Module
+        BuiltinType.new(type, name || type.name.to_s)
+      when Hash
+        tuple(type, name)
+      when Array
+        fail!("Array of arity 1 expected, got `#{type}`") unless type.size==1
+        seq(type.first, name)
+      when Set
+        fail!("Set of arity 1 expected, got `#{type}`") unless type.size==1
+        sub = type(type.first)
+        sub.is_a?(TupleType) ? relation(sub.heading, name) : set(sub, name)
+      when Range
+        clazz = [type.begin, type.end].map(&:class).uniq
+        fail!("Unsupported range `#{type}`") unless clazz.size==1
+        subtype(clazz.first, type)
+      when Regexp
+        subtype(String, type)
+      else
+        fail!("Unable to factor a Qrb::Type from `#{type}`")
+      end
+    end
+
+    ########################################################### Type Arguments
+
+    def ruby_type(type)
+      unless type.is_a?(Module)
+        fail!("Ruby module expected, got `#{type}`")
+      end
+
+      type
+    end
+
+    def name(name)
+      unless name.nil? or (name.is_a?(String) and name.strip.size > 1)
+        fail!("Wrong type name `#{name}`")
+      end
+
+      name.nil? ? nil : name.strip
+    end
+
+    def constraints(constraints = nil, &bl)
+      constrs = {}
+      constrs[:predicate] = bl if bl
+      constrs[:predicate] = constraints unless constraints.is_a?(Hash)
+      constrs.merge!(constraints)       if constraints.is_a?(Hash)
+      constrs
+    end
+
+    def attribute(name, type)
+      Attribute.new(name, type(type))
+    end
+
+    def attributes(attributes)
+      case attributes
+      when Hash
+        attributes.each_pair.map do |name, type|
+          attribute(name, type)
+        end
+      else
+        fail!("Hash expected, got `#{attributes}`")
+      end
+    end
+
+    def heading(heading)
+      case heading
+      when Heading
+        heading
+      when TupleType, RelationType
+        heading.heading
+      when Hash
+        Heading.new(attributes(heading))
+      else
+        fail!("Heading expected, got `#{heading}`")
+      end
+    end
+
+    def contracts(contracts)
+      unless contracts.is_a?(Hash)
+        fail!("Hash expected, got `#{contracts}`")
+      end
+      unless (invalid = contracts.keys.reject{|k| k.is_a?(Symbol) }).empty?
+        fail!("Invalid contract names `#{invalid}`")
+      end
+
+      contracts
+    end
+
+    ########################################################## Type generators
+
+    def builtin(ruby_type, name = nil)
+      ruby_type = ruby_type(ruby_type)
+      name      = name(name)
+
+      BuiltinType.new(ruby_type, name)
+    end
+
+    def adt(ruby_type, contracts, name = nil)
+      ruby_type = ruby_type(ruby_type) if ruby_type
+      contracts = contracts(contracts)
+      name      = name(name)
+
+      AdType.new(ruby_type, contracts, name)
+    end
+
+    ### Sub and union
+
+    def subtype(super_type, constraints = nil, name = nil, &bl)
+      super_type  = type(super_type)
+      constraints = constraints(constraints, &bl)
+      name        = name(name)
+
+      SubType.new(super_type, constraints, name)
+    end
+
+    def union(*args)
+      candidates, name = [], nil
+      args.each do |arg|
+        case arg
+        when Array  then candidates = arg.map{|t| type(t) }
+        when String then name = name(arg)
+        else
+          candidates << type(arg)
+        end
+      end
+
+      UnionType.new(candidates, name)
+    end
+
+    ### Collections
+
+    def seq(elm_type, name = nil)
+      elm_type = type(elm_type)
+      name     = name(name)
+
+      SeqType.new(elm_type, name)
+    end
+
+    def set(elm_type, name = nil)
+      elm_type = type(elm_type)
+      name     = name(name)
+
+      SetType.new(elm_type, name)
+    end
+
+    ### Tuples and relations
+
+    def tuple(heading, name = nil)
+      heading = heading(heading)
+      name    = name(name)
+
+      TupleType.new(heading, name)
+    end
+
+    def relation(heading, name = nil)
+      heading = heading(heading)
+      name    = name(name)
+
+      RelationType.new(heading, name)
+    end
+
+  private
+
+    def fail!(message)
+      raise ArgumentError, message, caller
+    end
+
+  end # class TypeBuilder
+end # module Qrb