qrb 0.1.0

data/lib/qrb/type/ad_type.rb

@@ -0,0 +1,111 @@
+require 'set'
+module Qrb
+  #
+  # The Abtract/Algebraic Data Type is a generator to build user-defined
+  # information types in a more abstract way than using sub types. For
+  # instance, a Color could be defined as follows:
+  #
+  #     Color := <Rgb> {r: Byte, g: Byte, b: Byte},
+  #              <Hex> String( s | s =~ /^#[0-9a-f]{6}$/i )
+  #
+  # Such a declaration does not define a new type by *subtyping* but instead
+  # declares so-called possible representations for the color. Here, two
+  # possible representations are defined: one is a rgb triple through a Tuple
+  # type, the other is an hexadecimal notation through a subset of String.
+  #
+  # Given an AdType, Q requires special dress/undress function pairs to
+  # encode/decode from the type to the concrete representations and vice versa.
+  # This pair of functions is called the "information contract".
+  #
+  # This class allows capturing such information types. For instance,
+  #
+  #     # This is the concrete representation of Q's Color, through a usual
+  #     # Ruby ADT (we call it ColorImpl here to avoid confusion, but in
+  #     # practice one would simply call it Color).
+  #     class ColorImpl
+  #       # ... your usual color implementation
+  #     end
+  #
+  #     # The RGB info type: {r: Byte, g: Byte, b: Byte}
+  #     rgb_infotype  = TupleType.new(...)
+  #
+  #     # The RGB contract converter, an object that responds to `call` to
+  #     # convert from a valid Hash[r: Fixnum, ...] to a ColorImpl instance.
+  #     rgb_contract = ...
+  #
+  #     AdType.new(ColorImpl, rgb: [rgb_infotype, rgb_contract], hex: ...)
+  #
+  # The ruby ADT class is of course used as concrete representation of the
+  # AdType, that is,
+  #
+  #     R(Color) = ColorImpl
+  #
+  # Accordingly, the `dress` transformation function has the following
+  # signature:
+  #
+  #     dress :: Alpha  -> Color     throws TypeError
+  #     dress :: Object -> ColorImpl throws TypeError
+  #
+  class AdType < Type
+
+    def initialize(ruby_type, contracts, name = nil)
+      unless ruby_type.nil? or ruby_type.is_a?(Module)
+        raise ArgumentError, "Module expected, got `#{ruby_type}`"
+      end
+      unless contracts.is_a?(Hash)
+        raise ArgumentError, "Hash expected, got `#{contracts}`"
+      end
+      invalid = contracts.values.reject{|v|
+        v.is_a?(Array) and v.size == 2 and v.first.is_a?(Type) and v.last.respond_to?(:call)
+      }
+      unless invalid.empty?
+        raise ArgumentError, "Invalid contracts `#{invalid}`"
+      end
+
+      super(name)
+      @ruby_type = ruby_type
+      @contracts = contracts.freeze
+    end
+    attr_reader :ruby_type, :contracts
+
+    def contract_names
+      contracts.keys
+    end
+
+    def default_name
+      (ruby_type && ruby_type.name.to_s) || "Anonymous"
+    end
+
+    def include?(value)
+      ruby_type === value
+    end
+
+    def dress(value, handler = DressHelper.new)
+      # Up should be idempotent with respect to the ADT
+      return value if ruby_type and value.is_a?(ruby_type)
+
+      # Try each contract in turn. Do nothing on TypeError as
+      # the next candidate could be the good one! Return the
+      # first successfully uped.
+      contracts.each_pair do |name, (infotype,upper)|
+
+        # First make the dress transformation on the information type
+        success, uped = handler.just_try do
+          infotype.dress(value, handler)
+        end
+        next unless success
+
+        # Seems nice, just try to get one stage higher now
+        success, uped = handler.just_try(StandardError) do
+          upper.call(uped)
+        end
+        return uped if success
+
+      end
+
+      # No one succeeded, just fail
+      handler.failed!(self, value)
+    end
+
+  end # class AdType
+end # module Qrb

data/lib/qrb/type/builtin_type.rb

@@ -0,0 +1,56 @@
+module Qrb
+  #
+  # A BuiltinType generator allows capuring an information type to a type of
+  # the host language, here a Ruby class. For instance,
+  #
+  #     Int := BuiltinType(ruby.Fixnum)
+  #
+  # The set of values captured by the information type is the same set of
+  # values that can be represented by the host type. In the example, `Int`
+  # captures the same set of numbers as ruby's Fixnum.
+  #
+  # The ruby class is used as concrete representation of the information type.
+  # In the example:
+  #
+  #     R(Int) = Fixnum
+  #
+  # Accordingly, the `dress` transformation function has the following signature:
+  #
+  #     dress :: Alpha  -> Int    throws TypeError
+  #     dress :: Object -> Fixnum throws TypeError
+  #
+  class BuiltinType < Type
+
+    def initialize(ruby_type, name = nil)
+      super(name)
+      @ruby_type = ruby_type
+    end
+    attr_reader :ruby_type
+
+    def default_name
+      @ruby_type.name.to_s
+    end
+
+    def include?(value)
+      ruby_type === value
+    end
+
+    # Check that `value` is a valid instance of `ruby_type` through `===` or
+    # raise an error.
+    def dress(value, handler = DressHelper.new)
+      handler.failed!(self, value) unless ruby_type===value
+      value
+    end
+
+    def ==(other)
+      return false unless other.is_a?(BuiltinType)
+      other.ruby_type==ruby_type
+    end
+    alias :eql? :==
+
+    def hash
+      self.class.hash ^ ruby_type.hash
+    end
+
+  end # class BuiltinType
+end # module Qrb

data/lib/qrb/type/relation_type.rb

@@ -0,0 +1,81 @@
+module Qrb
+  #
+  # The Relation type generator allows capturing sets of information facts,
+  # i.e. sets of tuples (of same heading). E.g.
+  #
+  #     ColoredPoints = {{ point: Point, color: Color }}
+  #
+  # This class allows capturing relation types, in a way similar to TupleType:
+  #
+  #     ColoredPoints = RelationType.new( Heading[...] )
+  #
+  # A ruby Set is used as concrete representation, and will contain hashes
+  # that are valid representations of the associated tuple type:
+  #
+  #     R(ColoredPoints) = Set[ R({...}) ] = Set[Hash[...]]
+  #
+  # Accordingly, the dress transformation function has the signature below.
+  # It expects an Enumerable as input and fails if any duplicate is found
+  # (after tuple transformation), or if any tuple fails at being transformed.
+  #
+  #     dress :: Alpha  -> ColoredPoints   throws TypeError
+  #     dress :: Object -> Set[Hash[...]]  throws TypeError
+  #
+  class RelationType < Type
+
+    def initialize(heading, name = nil)
+      unless heading.is_a?(Heading)
+        raise ArgumentError, "Heading expected, got `#{heading}`"
+      end
+
+      super(name)
+      @heading = heading
+    end
+    attr_reader :heading
+
+    def default_name
+      "{{#{heading.to_name}}}"
+    end
+
+    def include?(value)
+      value.is_a?(Set) && value.all?{|tuple|
+        tuple_type.include?(tuple)
+      }
+    end
+
+    # Apply the corresponding TupleType's `dress` to every element of `value`
+    # (any enumerable). Return a Set of transformed tuples. Fail if anything
+    # goes wrong transforming tuples or if duplicates are found.
+    def dress(value, handler = DressHelper.new)
+      handler.failed!(self, value) unless value.respond_to?(:each)
+
+      # Up every tuple and keep results in a Set
+      set = Set.new
+      handler.iterate(value) do |tuple, index|
+        tuple = tuple_type.dress(tuple, handler)
+        handler.fail!("Duplicate tuple") if set.include?(tuple)
+        set << tuple
+      end
+
+      # Return built tuples
+      set
+    end
+
+    def ==(other)
+      return false unless other.is_a?(RelationType)
+      heading == other.heading
+    end
+    alias :eql? :==
+
+    def hash
+      self.class.hash ^ heading.hash
+    end
+
+  private
+
+    def tuple_type
+      @tuple_type ||= TupleType.new(heading)
+    end
+
+  end # class RelationType
+end # module Qrb

data/lib/qrb/type/seq_type.rb

@@ -0,0 +1,51 @@
+module Qrb
+  #
+  # The Seq type generator allows capturing sequences of values. For example,
+  # a (implicitely temporal) series of temperature measures could be written
+  # as:
+  #
+  #     Measures = [Temperature]
+  #
+  # This class allows capturing those sequence types, e.g.:
+  #
+  #     Temperature = BuiltinType.new(Float)
+  #     Measures    = SeqType.new(Temperature)
+  #
+  # An array of values is used as concrete representation for such sequences:
+  #
+  #     R(Measures) = Array[R(Temperature)] = Array[Float]
+  #
+  # Accordingly, the `dress` transformation function has the signature below.
+  # It expects it's Alpha/Object argument to be a object responding to
+  # `each` (with the ruby idiomatic semantics that such a `each` returns
+  # an Enumerator when invoked without block).
+  #
+  #     dress :: Alpha  -> Measures      throws TypeError
+  #     dress :: Object -> Array[Float]  throws TypeError
+  #
+  class SeqType < Type
+    include CollectionType
+
+    def include?(value)
+      value.is_a?(::Array) and value.all?{|v| elm_type.include?(v) }
+    end
+
+    # Apply the element type's `dress` transformation to each element of
+    # `value` (expected to respond to `each`). Return converted values in a
+    # ruby Array.
+    def dress(value, handler = DressHelper.new)
+      handler.failed!(self, value) unless value.respond_to?(:each)
+
+      array = []
+      handler.iterate(value) do |elm, index|
+        array << elm_type.dress(elm, handler)
+      end
+      array
+    end
+
+    def default_name
+      "[#{elm_type.name}]"
+    end
+
+  end # class SeqType
+end # module Qrb

data/lib/qrb/type/set_type.rb

@@ -0,0 +1,52 @@
+module Qrb
+  #
+  # The Set type generator allows capturing an unordered set of values (i.e.
+  # with no duplicates). For example, a set of emails could be captured with:
+  #
+  #     Adresses = {Email}
+  #
+  # This class allows capturing those set types, e.g.:
+  #
+  #     Email    = BuiltinType.new(String)
+  #     Adresses = SetType.new(Email)
+  #
+  # A ruby Set of values is used as concrete representation for such sets:
+  #
+  #     R(Adresses) = Set[R(Email)] = Set[String]
+  #
+  # Accordingly, the `dress` transformation function has the signature below.
+  # It expects it's Alpha/Object argument to be a object responding to
+  # `each` (with the ruby idiomatic semantics that such a `each` returns
+  # an Enumerator when invoked without block).
+  #
+  #     dress :: Alpha  -> Adresses     throws TypeError
+  #     dress :: Object -> Set[String]  throws TypeError
+  #
+  class SetType < Type
+    include CollectionType
+
+    def default_name
+      "{#{elm_type.name}}"
+    end
+
+    def include?(value)
+      value.is_a?(::Set) and value.all?{|v| elm_type.include?(v) }
+    end
+
+    # Apply the element type's `dress` transformation to each element of
+    # `value` (expected to respond to `each`). Return converted values in a
+    # ruby Set.
+    def dress(value, handler = DressHelper.new)
+      handler.failed!(self, value) unless value.respond_to?(:each)
+
+      set = Set.new
+      handler.iterate(value) do |elm, index|
+        elm = elm_type.dress(elm, handler)
+        handler.fail!("Duplicate value `#{elm}`") if set.include?(elm)
+        set << elm
+      end
+      set
+    end
+
+  end # class SetType
+end # module Qrb

data/lib/qrb/type/sub_type.rb

@@ -0,0 +1,94 @@
+module Qrb
+  #
+  # A sub type generator, through specialization by constraints.
+  #
+  # A sub type captures a subset of the values of a super type, through a
+  # constraint. For instance, a Byte type can be defined as a subset of all
+  # integers, as follows:
+  #
+  #     Byte := Integer( i | i >= 0 and i <= 255 )
+  #
+  # This class allows defining such sub types with multiple named constraints.
+  # For instance,
+  #
+  #     Int  = BuiltinType.new(Integer)
+  #     Byte = SubType.new(Int, positive: ->(i){ i >= 0 },
+  #                             small:    ->(i){ i <= 255 })
+  #
+  # The concrete representation of the super type is kept as representation
+  # of the sub type. In other words:
+  #
+  #     R(Byte) = R(Int) = Fixnum
+  #
+  # Accordingly, the `dress` transformation function has the following signature:
+  #
+  #     dress :: Alpha  -> Byte   throws TypeError
+  #     dress :: Object -> Fixnum throws TypeError
+  #
+  class SubType < Type
+
+    DEFAULT_CONSTRAINT_NAMES = [:default, :predicate].freeze
+
+    def initialize(super_type, constraints, name = nil)
+      unless super_type.is_a?(Type)
+        raise ArgumentError, "Qrb::Type expected, got #{super_type}"
+      end
+
+      unless constraints.is_a?(Hash)
+        raise ArgumentError, "Hash expected for constraints, got #{constraints}"
+      end
+
+      super(name)
+      @super_type, @constraints = super_type, constraints.freeze
+    end
+    attr_reader :super_type, :constraints
+
+    def default_name
+      constraints.keys.first.to_s.capitalize
+    end
+
+    def include?(value)
+      super_type.include?(value) && constraints.all?{|_,c| c===value }
+    end
+
+    # Check that `value` can be uped through the supertype, then verify all
+    # constraints. Raise an error if anything goes wrong.
+    def dress(value, handler = DressHelper.new)
+      # Check that the supertype is able to dress the value.
+      # Rewrite and set cause to any encountered TypeError.
+      uped = handler.try(self, value) do
+        super_type.dress(value, handler)
+      end
+
+      # Check each constraint in turn
+      constraints.each_pair do |name, constraint|
+        next if constraint===uped
+        msg = handler.default_error_message(self, value)
+        msg << " (not #{name})" unless default_constraint?(name)
+        handler.fail!(msg)
+      end
+
+      # seems good, return the uped value
+      uped
+    end
+
+    def ==(other)
+      return false unless other.is_a?(SubType)
+      other.super_type == super_type and \
+      set_equal?(constraints.values, other.constraints.values)
+    end
+    alias :eql? :==
+
+    def hash
+      self.class.hash ^ super_type.hash ^ set_hash(constraints.values)
+    end
+
+  private
+
+    def default_constraint?(name)
+      DEFAULT_CONSTRAINT_NAMES.include?(name) or \
+        name.to_s.capitalize == self.name
+    end
+
+  end # class BuiltinType
+end # module Qrb

data/lib/qrb/type/tuple_type.rb

@@ -0,0 +1,99 @@
+module Qrb
+  #
+  # The Tuple type generator allows capturing information *facts*. For
+  # instance, a Point type could be defined as follows:
+  #
+  #     Point = {r: Length, theta: Angle}
+  #
+  # This class allows capturing those information types, as in:
+  #
+  #     Length = BuiltinType.new(Fixnum)
+  #     Angle  = BuiltinType.new(Float)
+  #     Point  = TupleType.new(Heading.new([
+  #                Attribute.new(:r, Length),
+  #                Attribute.new(:theta, Angle)
+  #              ]))
+  #
+  # A Hash with Symbol as keys is used as concrete ruby representation for
+  # tuples. The values map to the concrete representations of each attribute
+  # type:
+  #
+  #     R(Point) = Hash[r: R(Length), theta: R(Angle)]
+  #              = Hash[r: Fixnum, theta: Float]
+  #
+  # Accordingly, the `dress` transformation function has the signature below.
+  # It expects it's Alpha/Object argument to be a Hash with all and only the
+  # expected keys (either as Symbols or Strings). The `dress` function
+  # applies on every attribute value according to their respective type.
+  #
+  #     dress :: Alpha  -> Point                         throws TypeError
+  #     dress :: Object -> Hash[r: Fixnum, theta: Float] throws TypeError
+  #
+  class TupleType < Type
+
+    def initialize(heading, name = nil)
+      unless heading.is_a?(Heading)
+        raise ArgumentError, "Heading expected, got `#{heading}`"
+      end
+
+      super(name)
+      @heading = heading
+    end
+    attr_reader :heading
+
+    def default_name
+      "{#{heading.to_name}}"
+    end
+
+    def include?(value)
+      return false unless value.is_a?(Hash)
+      return false if value.size > heading.size
+      heading.all? do |attribute|
+        attr_val = value.fetch(attribute.name){
+          return false
+        }
+        attribute.type.include?(attr_val)
+      end
+    end
+
+    # Convert `value` (supposed to be Hash) to a Tuple, by checking attributes
+    # and applying `dress` on them in turn. Raise an error if any attribute
+    # is missing or unrecognized, as well as if any sub transformation fails.
+    def dress(value, handler = DressHelper.new)
+      handler.failed!(self, value) unless value.is_a?(Hash)
+
+      # Uped values, i.e. tuple under construction
+      uped = {}
+
+      # Check the tuple arity and fail fast if extra attributes
+      # (missing attributes are handled just after)
+      if value.size > heading.size
+        extra = value.keys.map(&:to_s) - heading.map{|attr| attr.name.to_s }
+        handler.fail!("Unrecognized attribute `#{extra.first}`")
+      end
+
+      # Up each attribute in turn now. Fail on missing ones.
+      heading.each do |attribute|
+        val = attribute.fetch_on(value) do
+          handler.fail!("Missing attribute `#{attribute.name}`")
+        end
+        handler.deeper(attribute.name) do
+          uped[attribute.name] = attribute.type.dress(val, handler)
+        end
+      end
+
+      uped
+    end
+
+    def ==(other)
+      return false unless other.is_a?(TupleType)
+      heading == other.heading
+    end
+    alias :eql? :==
+
+    def hash
+      self.class.hash ^ heading.hash
+    end
+
+  end # class TupleType
+end # module Qrb

data/lib/qrb/type/union_type.rb

@@ -0,0 +1,78 @@
+require 'set'
+module Qrb
+  #
+  # A union type (aka algebraic type) allows capturing information types
+  # through generalization/disjunction. For instance,
+  #
+  #     Numeric = Int|Real
+  #
+  # This class allows capturing such union types, as follows:
+  #
+  #     Int     = BuiltinType.new(Fixnum)
+  #     Real    = BuiltinType.new(Float)
+  #     Numeric = UnionType.new([ Int, Real ])
+  #
+  # When transforming a value through `dress`, the different candidate types
+  # are tried in specified order. The first one that succeeds at building the
+  # value ends the process and the value is simply returned. Accordingly,
+  # the concrete representation will be
+  #
+  #     R(Numeric) = R(Int) ^ R(Real) = Fixnum ^ Float = Numeric
+  #
+  # where `^` denotes the `least common super type` operator on ruby classes.
+  #
+  # Accordingly, the `dress` transformation function has the following
+  # signature:
+  #
+  #     dress :: Alpha  -> Numeric throws TypeError
+  #     dress :: Object -> Numeric throws TypeError
+  #
+  class UnionType < Type
+
+    def initialize(candidates, name = nil)
+      unless candidates.all?{|c| c.is_a?(Type) }
+        raise ArgumentError, "[Qrb::Type] expected, got #{candidates}"
+      end
+
+      super(name)
+      @candidates = candidates.freeze
+    end
+    attr_reader :candidates
+
+    def include?(value)
+      candidates.any?{|c| c.include?(value) }
+    end
+
+    # Invoke `dress` on each candidate type in turn. Return the value
+    # returned by the first one that does not fail. Fail with an TypeError if no
+    # candidate succeeds at tranforming `value`.
+    def dress(value, handler = DressHelper.new)
+
+      # Do nothing on TypeError as the next candidate could be the good one!
+      candidates.each do |c|
+        success, uped = handler.just_try do
+          c.dress(value, handler)
+        end
+        return uped if success
+      end
+
+      # No one succeed, just fail
+      handler.failed!(self, value)
+    end
+
+    def default_name
+      candidates.map(&:name).join('|')
+    end
+
+    def ==(other)
+      return false unless other.is_a?(UnionType)
+      set_equal?(candidates, other.candidates)
+    end
+    alias :eql? :==
+
+    def hash
+      self.class.hash ^ set_hash(self.candidates)
+    end
+
+  end # class UnionType
+end # module Qrb

data/lib/qrb/type.rb

@@ -0,0 +1,63 @@
+module Qrb
+  #
+  # Abstract class for Q type (generators).
+  #
+  class Type
+
+    def initialize(name)
+      unless name.nil? or name.is_a?(String)
+        raise ArgumentError, "String expected for type name, got `#{name}`"
+      end
+      @name = name
+    end
+
+    def name
+      @name || default_name
+    end
+
+    def name=(n)
+      raise Error, "Name already set to `#{@name}`" unless @name.nil?
+      @name = n
+    end
+
+    def to_s
+      name.to_s
+    end
+
+    # Check if `value` belongs to this type. Returns true if it's the case,
+    # false otherwise.
+    #
+    # For belonging to the type, `value` MUST be a valid representation, not
+    # an 'approximation' or some 'similar' representation. In particular,
+    # returning true means that no dressing is required for using `value` as a
+    # proper one. Similarly, the method MUST always return true on a value
+    # directly obtained through `dress`.
+    #
+    def include?(value)
+      raise NotImplementedError, "Missing #{self.class.name}#include?"
+    end
+
+    def dress(*args)
+      raise NotImplementedError, "Missing #{self.class.name}#dress"
+    end
+
+  protected
+
+    def set_equal?(s1, s2)
+      s1.size == s2.size and (s1-s2).empty?
+    end
+
+    def set_hash(arg)
+      arg.map(&:hash).reduce(:^)
+    end
+
+  end # class Type
+end # module Qrb
+require_relative 'type/builtin_type'
+require_relative 'type/union_type'
+require_relative 'type/sub_type'
+require_relative 'type/seq_type'
+require_relative 'type/set_type'
+require_relative 'type/tuple_type'
+require_relative 'type/relation_type'
+require_relative 'type/ad_type'

data/lib/qrb/version.rb

@@ -0,0 +1,14 @@
+module Qrb
+  module Version
+
+    MAJOR = 0
+    MINOR = 1
+    TINY  = 0
+
+    def self.to_s
+      [ MAJOR, MINOR, TINY ].join('.')
+    end
+
+  end
+  VERSION = Version.to_s
+end