alf 0.10.1 → 0.11.0

data/lib/alf/types/summarization.rb

@@ -1,76 +1,138 @@
 module Alf
   module Types
     #
-    # Encapsulates a Summarization information
+    # Encapsulates a Summarization information.
     #
     class Summarization
-      
+
       # @return [Hash] the hash of aggregations, AttrName -> Aggregators
       attr_reader :aggregations
-      
-      #
+
       # Creates a Summarization instance
       #
       # @param [Hash] aggs, aggregations as a mapping AttrName -> Aggregators
-      #
       def initialize(aggs)
         @aggregations = aggs
       end
-      
-      #
-      # Coerces `arg` to an Aggregator
-      #
-      def self.coerce(arg)
-        case arg
-        when Summarization
-          arg
-        when Array
-          coerce(Hash[*arg])
-        when Hash
-          h = Tools.tuple_collect(arg) do |k,v|
-            [Tools.coerce(k, AttrName), Tools.coerce(v, Aggregator)]
+
+      class << self
+
+        # Coerces `arg` to an Summarization
+        #
+        # Implemented coercions are:
+        # - Summarization        -> self
+        # - [attr1, agg1, ...]   -> {AttrName(attr1) -> Aggregator(agg1), ...}
+        # - {attr1 => agg1, ...} -> {AttrName(attr1) -> Aggregator(agg1), ...}
+        # 
+        # @param [Object] arg any ruby object to coerce to an Summarization
+        # @return [Summarization] the coerced summarization
+        # @raise [ArgumentError] is the coercion fails
+        def coerce(arg)
+          case arg
+          when Summarization
+            arg
+          when Array
+            coerce(Hash[*arg])
+          when Hash
+            Summarization.new Hash[arg.map{|k,v|
+              [ Tools.coerce(k, AttrName), 
+                Tools.coerce(v, Aggregator) ]
+            }]
+          else
+            raise ArgumentError, "Invalid arg `#{arg}` for Summarization()"
           end
-          Summarization.new(h)
-        else
-          raise ArgumentError, "Invalid arg `#{arg}` for Summarization()"
         end
+        alias :[] :coerce
+
+        # Coerces commandline arguments to a Summarization
+        #
+        # This method reuses `coerce(Array)` and therefore shares its spec.
+        #
+        # @params [Array<String>] argv commandline arguments
+        # @params [Hash] opts coercion options (not used)
+        # @return [Summarization] the coerced summarization
+        # @raise [ArgumentError] is the coercion fails
+        def from_argv(argv, opts = {})
+          coerce(argv)
+        end
+
       end
-      
-      def self.from_argv(argv, opts = {})
-        coerce(argv)
-      end
-      
-      #
-      # Computes the least tuple
+
+      # Computes the least tuple.
       #
+      # @return [Tuple] a tuple with least values for each attribute
       def least
-        Tools.tuple_collect(@aggregations){|k,v| 
+        Hash[@aggregations.map{|k,v| 
           [k, v.least]
-        }
+        }]
       end
-      
-      #
-      # Computes the resulting aggregation from aggs if tuple happens. 
+
+      # Computes the resulting aggregation from aggs if tuple happens.
       #
+      # @return [Tuple] the new aggregated tuple
       def happens(aggs, tuple)
-        Tools.tuple_collect(@aggregations){|k,v|
+        Hash[@aggregations.map{|k,v|
           [k, v.happens(aggs[k], tuple)]
-        }
+        }]
       end
-      
-      #
-      # Finalizes the summarization `aggs` 
+
+      # Finalizes the summarization
       #
+      # @return [Tuple] the finalized aggregated tuple
       def finalize(aggs)
-        Tools.tuple_collect(@aggregations){|k,v|
+        Hash[@aggregations.map{|k,v|
           [k, v.finalize(aggs[k])]
-        }
+        }]
       end
-      
+
+      # Summarizes an enumeration of tuples.
+      #
+      # @param [Enumerable] enum an enumeration of tuples
+      # @returns [Tuple] The summarization of `enum`
+      def summarize(enum)
+        finalize(enum.inject(least){|m,t| happens(m,t)})
+      end
+
+      # Returns a hash code.
+      #
+      # @return [Integer] a hash code for this expression
+      def hash
+        aggregations.hash
+      end
+
+      # Checks equality with another summarization
+      #
+      # @param [Summarization] another summariation
+      # @return [Boolean] true is self and other are equal, false otherwise
       def ==(other)
         other.is_a?(Summarization) && (other.aggregations == aggregations)
       end
-      
+      alias :eql? :==
+
+      # Converts to an attribute list.
+      #
+      # @return [AttrList] a list of computed attribute names
+      def to_attr_list
+        AttrList.new(aggregations.keys)
+      end
+
+      # Returns a ruby literal for this expression.
+      #
+      # @return [String] a literal s.t. `eval(self.to_ruby_literal) == self`
+      def to_ruby_literal
+        map = Hash[aggregations.map{|k,v| 
+          [k.to_s, "#{v.has_source_code!}"]
+        }]
+        "Alf::Summarization[#{Tools.to_ruby_literal(map)}]"
+      end
+
+      # Returns a string representation of this expression
+      def inspect
+        to_ruby_literal
+      rescue NotImplementedError
+        super
+      end
+
     end # class Summarization
   end # module Types
-end # module Alf
+end # module Alf

data/lib/alf/types/tuple_computation.rb

@@ -1,13 +1,21 @@
 module Alf
   module Types
     # 
-    # Encapsulates a tuple computation from other tuples expressions
+    # Defines the computation of a tuple from expressions mapped to names.
+    #
+    # Example:
+    #   computation = TupleComputation[
+    #     :big? => lambda{ status > 20 }
+    #     :who  => lambda{ "#{first} #{last}" }
+    #   ]
+    #   computation.call(:last => "Jones", :first => "Bill", :status => 10)
+    #   # => {:big? => false, :who => "Bill Jones"}
     #
     class TupleComputation
-      
+
       # @return [Hash] a computation hash, mapping AttrName -> TupleExpression
       attr_reader :computation
-      
+
       #
       # Creates a TupleComputation instance
       #
@@ -16,46 +24,113 @@ module Alf
       def initialize(computation)
         @computation = computation
       end
-      
-      # 
-      # Coerces `arg` to a tuple computation
-      #
-      def self.coerce(arg)
-        case arg
-        when TupleComputation
-          arg
-        when Hash
-          h = Tools.tuple_collect(arg){|k,v|
-            if AttrName === k
-              v = TupleExpression.coerce(v) if v.is_a?(Proc)
-              [k, v] 
-            else
-              [Tools.coerce(k, AttrName), Tools.coerce(v, TupleExpression)]
-            end
-          }
-          TupleComputation.new(h)
-        when Array
-          coerce(Hash[*arg])
-        else
-          raise ArgumentError, "Invalid argument `arg` for TupleComputation()"
+
+      class << self
+
+        # Coerces `arg` to a tuple computation
+        #
+        # Implemented coercions are
+        # - TupleComputation    -> self
+        # - {name => expr, ...} -> {AttrName[name] => TupleExpression[expr], ...}
+        # - [name, expr, ...]   -> {AttrName[name] => TupleExpression[expr], ...}
+        #
+        # @param [Object] arg the value to coerce to a tuple computation
+        # @return [TupleComputation] the computation when the coercion succeeds
+        def coerce(arg)
+          case arg
+          when TupleComputation
+            arg
+          when Hash
+            TupleComputation.new Hash[arg.map{|k,v|
+              if AttrName === k
+                v = TupleExpression.coerce(v) if v.is_a?(Proc)
+                [k, v] 
+              else
+                [ Tools.coerce(k, AttrName), 
+                  Tools.coerce(v, TupleExpression) ]
+              end
+            }]
+          when Array
+            coerce(Hash[*arg])
+          else
+            raise ArgumentError, "Invalid argument `arg` for TupleComputation()"
+          end
         end
-      end
-      
-      # Coerce from ARGV
-      def self.from_argv(argv, opts = {})
-        coerce(argv)
-      end
-      
+        alias :[] :coerce
+
+        # Convert commandline arguments to a tuple computation
+        #
+        # This method reuses `coerce(Array)` and therefore shares its spec.
+        #
+        # @param [Array] args commandline arguments
+        # @param [Hash] opts coercion options (not used).
+        # @return [TupleExpression] the expression if coercion succeeds
+        # @raise [ArgumentError] if the coercion fails.
+        def from_argv(argv, opts = {})
+          coerce(argv)
+        end
+
+      end # class << self
+
+      # Makes the computation in the context of a tuple
       #
-      # Computes the result, given `tuple` as context and `handle` to
-      # evaluate expressions. 
+      # This is a convenient method for the following, longer expression:
+      #
+      #     evaluate(TupleHandle.new.set(tuple))
+      # 
+      # Note, however, using a Handle as in the example above is much more 
+      # efficient when evaluating the same computation on multiple tuples
+      # in sequence.
+      #
+      # @param [Hash] tuple a Tuple instance
+      # @return [Object] the resulting tuple
+      def call(tuple)
+        evaluate(Tools::TupleHandle.new.set(tuple))
+      end
+      alias :[] :call
+
+      # Computes the resulting tuple when expressions are evaluated in the 
+      # context of `handle`
       #
-      def evaluate(obj = nil)
+      # @param [TupleHandle] handle a tuple handle instance.
+      # @return [Hash] the resulting tuple
+      def evaluate(handle = nil)
         Tools.tuple_collect(@computation){|k,v| 
-          [k, v.is_a?(TupleExpression) ? v.evaluate(obj) : v]
+          [k, v.is_a?(TupleExpression) ? v.evaluate(handle) : v]
         }
       end
-      
+
+      # Returns a hash code.
+      #
+      # @return [Integer] a hash code for this expression
+      def hash
+        @computation.hash
+      end
+
+      # Checks equality with another computation
+      #
+      # @param [TupleComputation] another computation
+      # @return [Boolean] true if self and other are equal, false otherwise
+      def ==(other)
+        other.is_a?(TupleComputation) && (computation == other.computation)
+      end
+      alias :eql? :==
+
+      # Converts to an attribute list.
+      #
+      # @return [AttrList] a list of computed attribute names
+      def to_attr_list
+        AttrList.new(computation.keys)
+      end
+
+      # Returns a ruby literal for this expression.
+      #
+      # @return [String] a literal s.t. `eval(self.to_ruby_literal) == self`
+      def to_ruby_literal
+        "Alf::TupleComputation[#{Tools.to_ruby_literal(computation)}]"
+      end
+      alias :inspect :to_ruby_literal
+
     end # class TupleComputation
   end # module Types
-end # module Alf
+end # module Alf

data/lib/alf/types/tuple_expression.rb

@@ -1,61 +1,152 @@
 module Alf
   module Types
     #
-    # Encapsulates the notion of tuple expression, which is a Ruby expression
-    # whose evaluates in the context and scope of a specific tuple.
+    # A tuple expression is a Ruby expression whose evaluates in the scope of a 
+    # specific tuple handle.
+    #
+    # Example:
+    #   expr = TupleExpression["status * 10"]
+    #   expr.call(:status => 20)
+    #   # => 200
     #
     class TupleExpression
-      
+
       # @return [Proc] the lambda expression
       attr_reader :expr_lambda
-      
-      # @return [String] the expression source code 
+
+      # @return [String] the expression source code (may be nil)
       attr_reader :source
-      
-      #
+
       # Creates a tuple expression from a Proc object
       #
       # @param [Proc] expr a Proc for the expression 
-      #
+      # @param [String] source the source code of the expression (optional)
       def initialize(expr, source = nil)
         @expr_lambda = expr
         @source = source
       end
-      
-      # 
-      # Coerces `arg` to a tuple expression
-      # 
-      def self.coerce(arg)
-        case arg
-        when TupleExpression
-          arg
-        when Proc
-          TupleExpression.new(arg, nil)
-        when String, Symbol
-          lamb = eval("lambda{ #{arg} }")
-          TupleExpression.new(lamb, arg.to_s)
+
+      class << self
+
+        # Coerces `arg` to a tuple expression.
+        #
+        # Implemented coercions are:
+        # - TupleExpression -> self
+        # - Proc            -> TupleExpression.new(arg, nil)
+        # - String          -> TupleExpression.new(..., arg)
+        # - Symbol          -> TupleExpression.new(..., arg)
+        #
+        # @param [Object] arg a value to convert to a tuple expression
+        # @return [TupleExpression] the expression if coercion succeeds
+        # @raise [ArgumentError] if the coercion fails
+        def coerce(arg)
+          case arg
+          when TupleExpression
+            arg
+          when Proc
+            TupleExpression.new(arg, nil)
+          when String, Symbol
+            TupleExpression.new(eval("lambda{ #{arg} }"), arg)
+          else
+            raise ArgumentError, "Invalid argument `#{arg}` for TupleExpression()"
+          end
+        end
+        alias :[] :coerce
+
+        # Convert commandline arguments to a tuple expression
+        #
+        # Arguments should either be empty or a singleton. In the former case,
+        # `opts[:default]` is used. In the latter case, the unique argument is
+        # taken as the expression source code and `coerce` is called on it.
+        #
+        # @param [Array] args commandline arguments
+        # @param [Hash] opts coercion options.
+        # @return [TupleExpression] the expression if coercion succeeds
+        # @raise [ArgumentError] if the coercion fails.
+        def from_argv(argv, opts = {})
+          raise ArgumentError if argv.size > 1
+          coerce(argv.first || opts[:default])
+        end
+
+      end # class << self
+
+      # Evaluates the expression in the context of a TupleHandle
+      #
+      # @param [TupleHandle] handle a tuple handle instance.
+      # @return [Object] the result of evaluating the expression in the context
+      #         of `handle`
+      def evaluate(handle = nil)
+        if RUBY_VERSION < "1.9"
+          handle.instance_eval(&@expr_lambda)
         else
-          raise ArgumentError, "Invalid argument `#{arg}` for TupleExpression()"
+          handle.instance_exec(&@expr_lambda)
         end
       end
 
-      # Coerces from ARGV 
-      def self.from_argv(argv, options = {})
-        raise ArgumentError if argv.size > 1
-        coerce(argv.first || options[:default])
+      # Evaluates the expression on a tuple
+      #
+      # This is a convenient method for the following, longer expression:
+      #
+      #     evaluate(TupleHandle.new.set(tuple))
+      # 
+      # Note, however, using a Handle as in the example above is much more 
+      # efficient when evaluating the same expression on multiple tuples
+      # in sequence.
+      #
+      # @param [Hash] tuple a Tuple instance
+      # @return [Object] the result of evaluating the expression on `tuple`
+      def call(tuple)
+        evaluate(Tools::TupleHandle.new.set(tuple))
       end
+      alias :[] :call
 
+      # Returns a hash code.
       #
-      # Evaluates in the context of obj
+      # @return [Integer] a hash code for this expression
+      def hash
+        @source.nil? ? @expr_lambda.hash : @source.hash
+      end
+
+      # Checks equality with another expression
       #
-      def evaluate(obj = nil)
-        if RUBY_VERSION < "1.9"
-          obj.instance_eval(&@expr_lambda)
+      # @param [TupleExpression] another expression.
+      # @return [Boolean] true if self and other are equal, false otherwise
+      def ==(other)
+        return false unless other.is_a?(TupleExpression)
+        if source.nil? || other.source.nil?
+          expr_lambda == other.expr_lambda
         else
-          obj.instance_exec(&@expr_lambda)
+          source == other.source
         end
       end
+      alias :eql? :==
+
+      # Returns a ruby literal for this expression.
+      #
+      # @return [String] a literal s.t. `eval(self.to_ruby_literal) == self`
+      def to_ruby_literal
+        "Alf::#{Tools.class_name(self.class)}[#{Tools.to_ruby_literal(has_source_code!)}]"
+      end
       
+      # Returns a string representation of this expression
+      def inspect
+        to_ruby_literal
+      rescue NotImplementedError
+        super
+      end
+
+      # Asserts that this expression knows its source code or raises a 
+      # NotImplementedError.
+      #
+      # @return [String] the source code when known
+      def has_source_code!
+        if source.nil?
+          raise NotImplementedError, "No known source code for this expression"
+        else
+          source
+        end
+      end
+
     end # class TupleExpression
   end # module Types
 end # module Alf

data/lib/alf/types/tuple_predicate.rb

@@ -1,49 +1,73 @@
 module Alf
   module Types
     # 
-    # Specialization of TupleExpression to boolean expressions 
-    # specifically
+    # Specialization of TupleExpression to boolean expressions.
     #
     class TuplePredicate < TupleExpression
-      
-      # 
-      # Coerces `arg` to a TuplePredicate
-      #
-      def self.coerce(arg)
-        case arg
-        when TuplePredicate
-          arg
-        when TupleExpression
-          TuplePredicate.new arg.expr_lambda, arg.source
-        when TrueClass, FalseClass
-          TuplePredicate.new lambda{ arg }, arg.to_s
-        when Proc
-          TuplePredicate.new arg, nil
-        when String, Symbol
-          l = eval("lambda{ #{arg} }")
-          TuplePredicate.new l, arg.to_s
-        when Hash
-          h = Tools.tuple_collect(arg){|k,v|
-            (AttrName === k) ? 
-              [k,v] : [Tools.coerce(k, AttrName), Kernel.eval(v)]
-          }
-          source = h.each_pair.collect{|k,v|
-            "(self.#{k} == #{Tools.to_ruby_literal(v)})"
-          }.join(" && ")
-          coerce(source.empty? ? true : source)
-        when Array
-          (arg.size <= 1) ?
-            coerce(arg.first || true) :
-            coerce(Hash[*arg])
-        else
-          raise ArgumentError, "Invalid argument `#{arg}` for TupleExpression()"
+
+      class << self
+
+        # Coerces `arg` to a TuplePredicate
+        #
+        # Implemented coercions are:
+        # - TuplePredicate    -> self
+        # - TupleExpression   -> Renewed on this class
+        # - true and false    -> true and false predicates
+        # - Proc              -> TuplePredicate(arg, nil)
+        # - String and Symbol -> as for TupleExpression
+        # - empty Array       -> coerce(true)
+        # - singleton Array   -> coerce(arg.first)
+        # - {"attr" => "value", ...} -> equal predicate with coercions
+        # - {:attr  => ...value..., ...} -> equal predicate without coercions
+        #
+        # @param [Object] arg the value to coerce to a TuplePredicate
+        # @return [TuplePredicate] the predicate if coercion succeeds
+        # @raise [ArgumentError] if coercion fails
+        def coerce(arg)
+          case arg
+          when TuplePredicate
+            arg
+          when TupleExpression
+            TuplePredicate.new arg.expr_lambda, arg.source
+          when TrueClass, FalseClass
+            TuplePredicate.new lambda{ arg }, arg.to_s
+          when Proc
+            TuplePredicate.new arg, nil
+          when String, Symbol
+            TuplePredicate.new eval("lambda{ #{arg} }"), arg
+          when Hash
+            h = Hash[arg.map{|k,v|
+              (AttrName === k) ? 
+                [k,v] : [Tools.coerce(k, AttrName), Kernel.eval(v)]
+            }]
+            source = h.map{|k,v|
+              "(self.#{k} == #{Tools.to_ruby_literal(v)})"
+            }.join(" && ")
+            TuplePredicate.new eval("lambda{ #{source} }"), source
+          when Array
+            (arg.size <= 1) ?
+              coerce(arg.first || true) :
+              coerce(Hash[*arg])
+          else
+            raise ArgumentError, "Invalid argument `#{arg}` for TupleExpression()"
+          end
         end
-      end
-      
-      def self.from_argv(argv)
-        coerce(argv)
-      end
-      
+        alias :[] :coerce
+
+        # Convert commandline arguments to a tuple predicate
+        #
+        # This method reuses `coerce(Array)` and therefore shares its spec.
+        #
+        # @param [Array] args commandline arguments
+        # @param [Hash] opts coercion options (not used).
+        # @return [TuplePredicate] the predicate if coercion succeeds
+        # @raise [ArgumentError] if the coercion fails.
+        def from_argv(argv)
+          coerce(argv)
+        end
+
+      end # class << self
+
     end # class TuplePredicate
   end # module Types
 end # module Alf