alf 0.10.1 → 0.11.0

data/lib/alf/tools/to_lispy.rb

@@ -1,85 +1,87 @@
 module Alf
   module Tools
 
+    # Converts `value` to a lispy expression.
+    #
+    # Example:
+    #
+    #     expr = Alf.lispy.compile{ 
+    #       (project :suppliers, [:name])
+    #     }
+    #     Tools.to_lispy(expr)
+    #     # => (project :suppliers, [:name])
+    #
+    # @param [Object] expr any ruby object denoting a lispy expression
+    # @return [String] a lispy expression for `value`
+    def to_lispy(expr)
+      ToLispy.apply(expr)
+    end
+
     # Myrrha rules for converting to ruby literals
     ToLispy = Myrrha::coercions do |r|
-      
+
       # Delegate to #to_lispy if it exists
       lispy_able = lambda{|v,rd| v.respond_to?(:to_lispy)}
       r.upon(lispy_able) do |v,rd|
         v.to_lispy
       end
 
-      # On AttrList
+      # AttrList -> [:sid, :sname, ...]
       r.upon(Types::AttrList) do |v, rd|
         Tools.to_ruby_literal(v.attributes)
       end
 
-      # On Heading
+      # Heading -> {:sid => String, ...}
       r.upon(Types::Heading) do |v, rd|
-        Tools.to_ruby_literal(v.attributes)
+        Tools.to_ruby_literal(v.to_h)
       end
 
-      # On Ordering
+      # Ordering -> [[:sid, :asc], ...]
       r.upon(Types::Ordering) do |v, rd|
         Tools.to_ruby_literal(v.ordering)
       end
 
-      # On Renaming
+      # Renaming -> {:old => :new, ...}
       r.upon(Types::Renaming) do |v, rd|
         Tools.to_ruby_literal(v.renaming)
       end
 
-      # On Renaming
+      # Iterator::Proxy -> :suppliers
       r.upon(lambda{|v,rd| Iterator::Proxy === v}) do |v, rd|
-        Tools.to_ruby_literal(v.dataset)
+        Tools.to_ruby_literal(v.name)
       end
 
-      # On TupleExpression
+      # TupleExpression -> ->(){ ... }
       r.upon(Types::TupleExpression) do |v, rd|
-        unless src = v.source
-          raise NotImplementedError, "TupleExpression #{v} has no source"
-        end
-        "->(){ #{src} }"
+        "->(){ #{v.has_source_code!} }"
       end
 
-      # On TuplePredicate
-      r.upon(Types::TuplePredicate) do |v, rd|
-        unless src = v.source
-          raise NotImplementedError, "TuplePredicate #{v} has no source"
-        end
-        "->(){ #{src} }"
-      end
-
-      # On TupleComputation
+      # TupleComputation -> { :big => -(){ ... }, ... }
       r.upon(Types::TupleComputation) do |v, rd|
-        "{" + v.computation.collect{|name,compu|
+        "{" + v.computation.map{|name,compu|
           [name.inspect, r.coerce(compu)].join(" => ")
         }.join(', ') + "}"
       end
 
-      # On Aggregator
+      # Aggregator -> agg.source
       r.upon(lambda{|v,_| Aggregator === v}) do |v, rd|
-        unless src = v.source
-          raise NotImplementedError, "Aggregator #{v} has no source"
-        end
-        src
+        v.has_source_code!
       end
 
-      # On Summarization
+      # Summarization -> { :total => ->(){ ... } }
       r.upon(Types::Summarization) do |v, rd|
-        "{" + v.aggregations.collect{|name,compu|
+        "{" + v.aggregations.map{|name,compu|
           [name.inspect, r.coerce(compu)].join(" => ")
         }.join(', ') + "}"
       end
 
-      # On Command and Operator
+      # Command and Operator -> (operator operands, args, options)
       cmd = lambda{|v,_| (Command === v) || (Operator === v)}
       r.upon(cmd) do |v,rd|
-        cmdname  = v.class.command_name.to_s.gsub('-', '_')
+        cmdname  = v.class.rubycase_name
         oper, args, opts = v.class.signature.collect_on(v)
         args = opts.empty? ? (oper + args) : (oper + args + [ opts ])
-        args = args.collect{|arg| r.coerce(arg)}
+        args = args.map{|arg| r.coerce(arg)}
         "(#{cmdname} #{args.join(', ')})"
       end
 
@@ -88,12 +90,7 @@ module Alf
         Tools.to_ruby_literal(v)
       end
 
-    end
-    
-    # Delegated to ToLispy
-    def to_lispy(value)
-      ToLispy.apply(value)
-    end
-    
+    end # ToLispy
+
   end # module Tools
 end # module Alf

data/lib/alf/tools/to_ruby_literal.rb

@@ -1,14 +1,31 @@
 module Alf
   module Tools
 
-    # Myrrha rules for converting to ruby literals
-    ToRubyLiteral = Myrrha::ToRubyLiteral.dup.append do
-    end
-    
-    # Delegated to ToRubyLiteral
+    # Converts `value` to a ruby literal
+    #
+    # This method is provided for code generation mechanisms used by Alf in
+    # various places (such as .rash files). The to_ruby_literal contract is
+    # such that the following invariant holds:
+    #
+    #     eval(to_ruby_literal(value)) == value
+    #
+    # This contract is ensured by Myrrha::ToRubyLiteral for various ruby values.
+    # Myrrha delegates the job to `value.to_ruby_literal` provided this method 
+    # exists. In such case, the implementation must be such that the invariant
+    # above is met.
+    #
+    # In every case, an invocation to this method only makes sense provided that
+    # `value` denotes a pure value, with the obvious semantics (from TTM).
+    #
+    # @param [Object] value any ruby object that denotes a pure value.
+    # @return [String] a ruby literal for `value`
     def to_ruby_literal(value)
       ToRubyLiteral.apply(value)
     end
-    
+
+    # Myrrha rules for converting to ruby literals
+    ToRubyLiteral = Myrrha::ToRubyLiteral.dup.append do
+    end
+
   end # module Tools
-end # module Alf
+end # module Alf

data/lib/alf/tools/tuple_handle.rb

@@ -1,42 +1,52 @@
 module Alf
   module Tools
     #
-    # Provides a handle, implementing a flyweight design pattern on tuples.
+    # Provides a handle for implementing a flyweight design pattern on tuples.
+    #
+    # This class works hand-in-hand with TupleExpression as it provides a scope
+    # for their evaluation on tuples.
+    #
+    # Example:
+    #
+    #   handle = TupleHandle.new
+    #   expr   = TupleExpression["status > 10"]
+    #   relation.each do |tuple|
+    #     expr.evaluate(handle.set(tuple))
+    #   end
     #
     class TupleHandle
-    
-      # Creates an handle instance
+
+      # Creates a handle instance
       def initialize
         @tuple = nil
       end
-    
-      #
+
       # Sets the next tuple to use.
       #
-      # This method installs the handle as a side effect 
-      # on first call. 
+      # On first call, this method installs the handle as a side effect.
       #
+      # @param [Tuple] tuple the current iterated tuple
+      # @return [TupleHandle] self
       def set(tuple)
         build(tuple) if @tuple.nil?
         @tuple = tuple
         self
       end
-    
-      #
+
       # Evaluates a tuple expression on the current tuple.
       # 
+      # @param [Object] expr a tuple expression (coercions apply)
+      # @return [Object] the result of evaluting `expr` on self
       def evaluate(expr)
         TupleExpression.coerce(expr).evaluate(self)
       end
-    
+
       private
-    
-      #
+
       # Builds this handle with a tuple.
       #
-      # This method should be called only once and installs 
-      # instance methods on the handle with keys of _tuple_.
-      #
+      # This method should be called only once and installs instance methods on 
+      # the handle with keys of _tuple_.
       def build(tuple)
         tuple.keys.each do |k|
           (class << self; self; end).send(:define_method, k) do
@@ -44,7 +54,7 @@ module Alf
           end
         end
       end
-    
+
     end # class TupleHandle
   end # module Tools
-end # module Alf
+end # module Alf

data/lib/alf/tools.rb

@@ -0,0 +1,14 @@
+module Alf
+  #
+  # Provides tooling methods that are used here and there in Alf.
+  # 
+  module Tools
+    require 'alf/tools/coerce'
+    require 'alf/tools/to_ruby_literal'
+    require 'alf/tools/to_lispy'
+    require 'alf/tools/tuple_handle'
+    require 'alf/tools/miscellaneous'
+
+    extend Tools
+  end # module Tools
+end # module Alf

data/lib/alf/types/attr_list.rb

@@ -1,43 +1,94 @@
 module Alf
   module Types
     #
-    # Defines a projection key
-    # 
+    # An attribute list is an ordered collection of attribute names (see 
+    # AttrName).
+    #
+    # Example:
+    #
+    #     list = AttrList[:name, :city]
+    #
     class AttrList
-    
-      # Projection attributes
+
+      # @return [Array<AttrName>] the list of attribute names
       attr_accessor :attributes
-    
+
+      # Creates an AttrList instance.
+      #
+      # @param [Array<AttrName>] the list of attribute names
       def initialize(attributes)
         @attributes = attributes
       end
-    
-      def self.coerce(arg)
-        case arg
-        when AttrList
-          arg
-        when Ordering
-          AttrList.new(arg.attributes)
-        when Array
-          AttrList.new(arg.collect{|s| Tools.coerce(s, AttrName)})
-        else
-          raise ArgumentError, "Unable to coerce #{arg} to a projection key"
+
+      class << self
+
+        # Coerces `arg` to an AttrList.
+        #
+        # Recognizes coercions are:
+        # - AttrList -> self
+        # - Ordering -> the underlying list of attributes
+        # - Array    -> through AttrName coercion of its elements
+        #
+        # @param [Object] arg the value to coerce to an AttrList
+        # @return [AttrList] an attribute list if coercion succeeds
+        # @raise [ArgumentError] if the coercion fails
+        def coerce(arg)
+          return arg.to_attr_list if arg.respond_to?(:to_attr_list)
+          case arg
+          when Array
+            AttrList.new(arg.collect{|s| Tools.coerce(s, AttrName)})
+          else
+            raise ArgumentError, "Unable to coerce #{arg} to a projection key"
+          end
         end
-      end
 
-      def self.from_argv(argv, opts = {})
-        coerce(argv)
-      end
-          
-      def to_ordering
-        Ordering.new attributes.collect{|arg| [arg, :asc]}
-      end
-    
-      def project(tuple, allbut = false)
-        split(tuple, allbut).first
+        # Coerces a list of names to an AttrList.
+        #
+        # @param [Array] args a list of names (Symbol or String)
+        # @return [AttrList] an attribute list
+        def [](*args)
+          coerce(args)
+        end
+
+        # Builds an AttrList from commandline arguments.
+        #
+        # This method relies on `coerce` and therefore shares its spec.
+        #
+        # @param [Array] argv an array of commandline arguments
+        # @param [Hash] opts convertion options (unused)
+        # @return [AttrList] an attribute list if coercion succeeds
+        # @raise [ArgumentError] if the coercion fails
+        def from_argv(argv, opts = {})
+          coerce(argv)
+        end
+
+      end # class << self
+
+      # Converts this attribute list to an ordering.
+      #
+      # @param [Symbol] :asc or :desc for ordering direction
+      # @return [Ordering] an ordering instance
+      def to_ordering(order = :asc)
+        Ordering.new attributes.map{|arg| [arg, order]}
       end
-    
-      def split(tuple, allbut = false)
+
+      # Splits a tuple in two parts according `allbut`.
+      #
+      # Example:
+      #   list = AttrList.new([:name])
+      #   tuple = {:name => "Jones", :city => "London"}
+      #
+      #   list.split_tuple(tuple)
+      #   # => [{:name => "Jones"}, {:city => "London"}]
+      #
+      #   list.split_tuple(tuple, true)
+      #   # => [{:city => "London"}, {:name => "Jones"}]
+      #
+      # @param [Hash] tuple a tuple to split
+      # @param [Boolean] allbut unknown attributes as first result?
+      # @return [Array<Hash>] an array containing two tuples, according to known
+      #         attributes and `allbut`
+      def split_tuple(tuple, allbut = false)
         projection, rest = {}, tuple.dup
         attributes.each do |a|
           projection[a] = tuple[a]
@@ -46,11 +97,64 @@ module Alf
         allbut ? [rest, projection] : [projection, rest]
       end
 
+      # Projects `tuple` on known (or unknown) attributes.
+      # 
+      # Example:
+      #   list = AttrList.new([:name])
+      #   tuple = {:name => "Jones", :city => "London"}
+      #
+      #   list.project_tuple(tuple)
+      #   # => {:name => "Jones"}
+      #
+      #   list.project_tuple(tuple, true)
+      #   # => {:city => "London"}
+      #
+      # @param [Hash] tuple a tuple to project
+      # @param [Boolean] allbut projection?
+      # @return Hash the projected tuple
+      def project_tuple(tuple, allbut = false)
+        split_tuple(tuple, allbut).first
+      end
+
+      # Checks equality with another attribute list.
+      #
+      # @param [Object] other another attribute list
+      # @return [Boolean] true if `other` is an attribute list and contains
+      #         the same attributes, in the same order
       def ==(other)
-        other.is_a?(AttrList) && (other.attributes == attributes)          
+        other.is_a?(AttrList) && (other.attributes == attributes)
       end
       alias :eql? :==
-      
+
+      # Returns an hash code.
+      #
+      # @return [Integer] an hash code for this attribute list
+      def hash
+        attributes.hash
+      end
+
+      # Converts to an array of attribute names.
+      #
+      # @return [Array<AttrName>] and array of attribute names
+      def to_a
+        attributes.dup
+      end
+
+      # Converts to an attribute list.
+      #
+      # @return [AttrList] return self
+      def to_attr_list
+        self
+      end
+
+      # Returns a ruby literal for this attribute list.
+      #
+      # @return [String] a literal s.t. `eval(self.to_ruby_literal) == self`
+      def to_ruby_literal
+        "Alf::AttrList#{Tools.to_ruby_literal(attributes)}"
+      end
+      alias :inspect :to_ruby_literal
+
     end # class AttrList
   end # module Types
 end # module Alf

data/lib/alf/types/attr_name.rb

@@ -1,28 +1,66 @@
 module Alf
   module Types
     #
-    # Data type for being a valid attribute name
-    #  
+    # Attribute name.
+    #
+    # Attribute names are ruby symbols that match the following regular 
+    # expression:
+    #
+    #     /^[a-zA-Z0-9_]+[?!]?$/
+    #
+    # Example:
+    #
+    #     AttrName["city"]
+    #     # => :city
+    #
     class AttrName < Symbol
       extend Myrrha::Domain
-      
-      def self.predicate
-        @predicate ||= lambda{|s| s.to_s =~ /^[a-zA-Z0-9_]+$/}
-      end
-            
-      def self.coerce(arg)
-        if arg.respond_to?(:to_sym)
-          sym = arg.to_sym
-          return sym if self.===(sym) 
+
+      class << self
+
+        # The domain predicate
+        PREDICATE = lambda{|s| s.to_s =~ /^[a-zA-Z0-9_]+[?!]?$/}
+
+        # Returns the domain predicate.
+        #
+        # @return [Proc] the domain predicate as a Proc obbject
+        def predicate
+          PREDICATE
         end
-        raise ArgumentError, "Unable to coerce `#{arg.inspect}` to AttrName"
-      end
-      
-      def self.from_argv(argv, opts = {})
-        raise ArgumentError if argv.size > 1
-        coerce(argv.first || opts[:default]) 
+
+        # Coerces `arg` to an AttrName.
+        #
+        # All objects that respond to :to_sym and match PREDICATE are
+        # valid coercion arguments.
+        #
+        # @param [Object] arg and argument to coerce to an AttrName
+        # @return [AttrName] an AttrName instance
+        # @raise [ArgumentError] is the coercion fails
+        def coerce(arg)
+          if arg.respond_to?(:to_sym)
+            sym = arg.to_sym
+            return sym if self.===(sym) 
+          end
+          raise ArgumentError, "Unable to coerce `#{arg.inspect}` to AttrName"
+        end
+        alias :[] :coerce
+
+        # Converts commandline arguments to an AttrName.
+        #
+        # This method requires `argv` to be either empty or a singleton array.
+        # When empty, `opts[:default]` is used. The value must be coercable
+        # with `coerce` for this method to suceed.
+        #
+        # @param [Array] argv commandline arguments
+        # @params [Hash] opts options (not used)
+        # @raise [ArgumentError] is the coercion fails
+        def from_argv(argv, opts = {})
+          raise ArgumentError if argv.size > 1
+          coerce(argv.first || opts[:default]) 
+        end
+
       end
-      
+
     end # class AttrName
   end # module Types
 end # module Alf

data/lib/alf/types/boolean.rb

@@ -1,12 +1,25 @@
 module Alf
   module Types
-    
+
+    # Defines the Boolean type which is missing to ruby.
     Boolean = Myrrha::Boolean
-    
+
+    # Converts commandline arguments to a Boolean.
+    #
+    # This method requires `argv` to be either empty or a singleton array.
+    # When empty, `opts[:default]` is used. The value must be coercable
+    # to a Boolean, according to Myrrha::Boolean coercions.
+    #
+    # @param [Array] argv commandline arguments
+    # @params [Hash] opts options (not used)
+    # @raise [ArgumentError] is the coercion fails
     def Boolean.from_argv(argv, opts={})
       raise ArgumentError if argv.size > 1
-      Tools.coerce(argv.first, Boolean)
+      value = argv.first || opts[:default] || false
+      Tools.coerce(value, Boolean)
+    rescue CoercionError
+      raise ArgumentError, "Unable to coerce `#{value.inspect}` to Boolean"
     end
-        
+
   end
-end
+end