alf 0.10.1 → 0.11.0

data/lib/alf/aggregator/{base.rb → instance_methods.rb}

@@ -1,7 +1,11 @@
 module Alf
   class Aggregator
-    module Base
-      
+    #
+    # This module defines methods for the default implementation of Alf's 
+    # aggregators.
+    #
+    module InstanceMethods
+
       # @return [Hash] Aggregation options 
       attr_reader :options
 
@@ -11,7 +15,6 @@ module Alf
       # @return [String] source code of the aggregator, if any
       attr_accessor :source
 
-      #
       # Creates an Aggregator instance.
       #
       # Example:
@@ -23,26 +26,25 @@ module Alf
         @options = default_options.merge(options)
         @functor = Tools.coerce(block, TupleExpression)
       end
-    
-      #
+
       # Returns the default options to use
       #
+      # @return [Hash] the default aggregation options
       def default_options
         {}
       end
-    
-      #
+
       # Returns the least value, which is the one to use on an empty
       # set.
       #
       # This method is intended to be overriden by subclasses; default 
       # implementation returns nil.
-      # 
+      #
+      # @return [Object] the least value for this aggregator
       def least
         nil
       end
-    
-      # 
+
       # This method is called on each aggregated tuple and must return
       # an updated _memo_ value. It can be seen as the block typically
       # given to Enumerable.inject.
@@ -50,46 +52,68 @@ module Alf
       # The default implementation collects the pre-value on the tuple 
       # and delegates to _happens.
       #
+      # @param [Object] memo the current aggregation value
+      # @param [Hash] tuple the current iterated tuple
+      # @return [Object] updated memo value
       def happens(memo, tuple)
         _happens(memo, @functor.evaluate(@handle.set(tuple)))
       end
-    
-      #
-      # This method finalizes a computation.
+
+      # This method finalizes an aggregation.
       #
       # Argument _memo_ is either _least_ or the result of aggregating 
       # through _happens_. The default implementation simply returns
       # _memo_. The method is intended to be overriden for complex 
-      # aggregations that need statefull information. See Avg for an 
-      # example 
+      # aggregations that need statefull information such as `avg`.
       #
+      # @param [Object] memo the current aggregation value
+      # @return [Object] the aggregation value, as finalized
       def finalize(memo)
         memo
       end
-    
-      #
-      # Aggregates over an enumeration of tuples. 
+
+      # Aggregates over an enumeration of tuples.
       #
+      # @param [Enumerable<Tuple>] an enumerable of tuples
+      # @return [Object] the computed aggregation value
       def aggregate(enum)
-        finalize(
-          enum.inject(least){|memo,tuple| 
-            happens(memo, tuple)
-          })
+        finalize(enum.inject(least){|m,t| happens(m, t)})
+      end
+
+      # Asserts that this aggregator 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 aggregator"
+        else
+          source
+        end
+      end
+
+      # Checks equality with another aggregator
+      #
+      # @param [Aggregator] other another aggregator
+      # @return [Boolean] true is self and other are equal, false otherwise
+      def ==(other)
+        return false unless other.is_a?(Aggregator)
+        has_source_code! == other.has_source_code!
+      rescue NotImplementedError
+        super
       end
-    
+
       protected
-    
-      #
+
       # @see happens.
       #
       # This method is intended to be overriden and returns _value_
-      # by default, making this aggregator a "Last" one...
-      #
+      # by default, making this aggregator a "Last(...)" aggregator.
       def _happens(memo, value)
         value
       end
-      
-    end # module Base
-    include(Base)
+
+    end # module InstanceMethods
+    include(InstanceMethods)
   end # class Aggregator
 end # module Alf

data/lib/alf/aggregator/max.rb

@@ -0,0 +1,32 @@
+module Alf
+  class Aggregator
+    #
+    # Defines a `max()` aggregation operator.
+    #
+    # Example:
+    #
+    #   # direct ruby usage
+    #   Alf::Aggregator.max{ qty }.aggregate(...)
+    #
+    #   # lispy 
+    #   (summarize :supplies, [:sid], :max => max{ qty })
+    #
+    class Max < Aggregator
+
+      # Returns nil as least value.
+      #
+      # @see Aggregator::InstanceMethods#least
+      def least()
+        nil
+      end
+
+      # Aggregates on a tuple occurence through `memo > val ? memo : val`
+      #
+      # @see Aggregator::InstanceMethods#_happens
+      def _happens(memo, val) 
+        memo.nil? ? val : (memo > val ? memo : val) 
+      end
+
+    end # class Max
+  end # class Aggregator
+end # module Alf

data/lib/alf/aggregator/min.rb

@@ -0,0 +1,32 @@
+module Alf
+  class Aggregator
+    #
+    # Defines a `min()` aggregation operator.
+    #
+    # Example:
+    #
+    #   # direct ruby usage
+    #   Alf::Aggregator.min{ qty }.aggregate(...)
+    #
+    #   # lispy 
+    #   (summarize :supplies, [:sid], :max => min{ qty })
+    #
+    class Min < Aggregator
+
+      # Returns nil as least value.
+      #
+      # @see Aggregator::InstanceMethods#least
+      def least()
+        nil
+      end
+
+      # Aggregates on a tuple occurence through `memo < val ? memo : val`
+      #
+      # @see Aggregator::InstanceMethods#_happens
+      def _happens(memo, val) 
+        memo.nil? ? val : (memo < val ? memo : val)
+      end
+
+    end # class Min
+  end # class Aggregator
+end # module Alf

data/lib/alf/aggregator/stddev.rb

@@ -0,0 +1,25 @@
+module Alf
+  class Aggregator
+    #
+    # Defines a `stddev()` aggregation operator.
+    #
+    # Example:
+    #
+    #   # direct ruby usage
+    #   Alf::Aggregator.stddev{ qty }.aggregate(...)
+    #
+    #   # lispy 
+    #   (summarize :supplies, [:sid], :stddev => stddev{ qty })
+    #
+    class Stddev < Variance
+
+      # Finalizes the computation.
+      #
+      # @see Aggregator::InstanceMethods#finalize
+      def finalize(memo) 
+        Math.sqrt(super(memo))
+      end
+
+    end # class Stddev
+  end # class Aggregator
+end # module Alf

data/lib/alf/aggregator/sum.rb

@@ -0,0 +1,32 @@
+module Alf
+  class Aggregator
+    #
+    # Defines a `sum()` aggregation operator.
+    #
+    # Example:
+    #
+    #   # direct ruby usage
+    #   Alf::Aggregator.sum{ qty }.aggregate(...)
+    #
+    #   # lispy 
+    #   (summarize :supplies, [:sid], :total => sum{ qty })
+    #
+    class Sum < Aggregator
+
+      # Returns 0 as least value.
+      #
+      # @see Aggregator::InstanceMethods#least
+      def least()
+        0
+      end
+
+      # Aggregates on a tuple occurence through `memo + val`
+      #
+      # @see Aggregator::InstanceMethods#_happens
+      def _happens(memo, val) 
+        memo + val
+      end
+
+    end # class Sum
+  end # class Aggregator
+end # module Alf

data/lib/alf/aggregator/variance.rb

@@ -0,0 +1,45 @@
+module Alf
+  class Aggregator
+    #
+    # Defines a `variance()` aggregation operator.
+    #
+    # Example:
+    #
+    #   # direct ruby usage
+    #   Alf::Aggregator.variance{ qty }.aggregate(...)
+    #
+    #   # lispy 
+    #   (summarize :supplies, [:sid], :total => variance{ qty })
+    #
+    class Variance < Aggregator
+
+      # Returns the least value.
+      #
+      # @see Aggregator::InstanceMethods#least
+      def least()
+        [0, 0.0, 0.0]
+      end
+
+      # Aggregates on a tuple occurence.
+      #
+      # @see Aggregator::InstanceMethods#_happens
+      def _happens(memo, val) 
+        count, mean, m2 = memo
+        count += 1
+        delta = val - mean
+        mean  += (delta / count)
+        m2    += delta*(val - mean)
+        [count, mean, m2]
+      end
+
+      # Finalizes the computation.
+      #
+      # @see Aggregator::InstanceMethods#finalize
+      def finalize(memo) 
+        count, mean, m2 = memo
+        m2 / count
+      end
+
+    end # class Variance
+  end # class Aggregator
+end # module Alf

data/lib/alf/aggregator.rb

@@ -0,0 +1,51 @@
+module Alf
+  #
+  # Aggregation operator.
+  #
+  # This class provides a basis for implementing aggregation operators. It 
+  # should always be used as a superclass for such implementations. See 
+  # ClassMethods and InstanceMethods for implementing your own aggregation 
+  # operators.
+  #
+  # Aggregation operators are made available through factory methods on the 
+  # Aggregator class itself:
+  #
+  #     Aggregator.count
+  #     Aggregator.sum{ qty }
+  #
+  # The coercion method should always be used for building aggregators from 
+  # lispy source code:
+  #
+  #     Aggregator.coerce("count")
+  #     Aggregator.coerce("sum{ qty }")
+  #
+  # Once built, aggregators can be used either in black-box or white-box modes.
+  #
+  #     relation = ...
+  #     agg = Aggregator.sum{ qty }
+  #
+  #     # Black box mode:
+  #     result = agg.aggregate(relation)
+  #
+  #     # White box mode:
+  #     memo = agg.least
+  #     relation.each do |tuple|
+  #       memo = agg.happens(memo, tuple)
+  #     end
+  #     result = agg.finalize(memo)
+  #
+  class Aggregator
+    require 'alf/aggregator/class_methods'
+    require 'alf/aggregator/instance_methods'
+    require 'alf/aggregator/count'
+    require 'alf/aggregator/sum'
+    require 'alf/aggregator/min'
+    require 'alf/aggregator/max'
+    require 'alf/aggregator/avg'
+    require 'alf/aggregator/variance'
+    require 'alf/aggregator/stddev'
+    require 'alf/aggregator/collect'
+    require 'alf/aggregator/concat'
+
+  end # class Aggregator
+end # module Alf

data/lib/alf/environment/class_methods.rb

@@ -1,25 +1,32 @@
 module Alf
   class Environment
+    #
+    # Installs class-level methods for Alf environments.
+    #
     module ClassMethods
 
-      #
       # Returns registered environments
       #
+      # @return [Array<Environment>] registered environments.
       def environments
         @environments ||= []
       end
-      
-      #
+
       # Register an environment class under a specific name. 
       #
       # Registered class must implement a recognizes? method that takes an array
-      # of arguments; it must returns true if an environment instance can be built
-      # using those arguments, false otherwise. Please be very specific in the 
-      # implementation for returning true. See also autodetect and recognizes?
+      # of arguments; it must returns true if an environment instance can be 
+      # built using those arguments, false otherwise.
+      #
+      # Example:
+      #
+      #     Environment.register(:sqlite, MySQLiteEnvClass)
+      #     Environment.sqlite(...)        # MySQLiteEnvClass.new(...)
+      #     Environment.autodetect(...)    # => MySQLiteEnvClass.new(...)
       #
+      # @see also autodetect and recognizes?
       # @param [Symbol] name name of the environment kind
       # @param [Class] clazz class that implemented the environment
-      #
       def register(name, clazz)
         environments << [name, clazz]
         (class << self; self; end).
@@ -27,36 +34,28 @@ module Alf
             clazz.new(*args)
           end
       end
-      
-      #
+
       # Auto-detect the environment to use for specific arguments.
       #
-      # This method returns an instance of the first registered Environment class 
-      # that returns true to an invocation of recognizes?(args). It raises an 
-      # ArgumentError if no such class can be found.    
+      # This method returns an instance of the first registered Environment 
+      # class that returns true to an invocation of recognizes?(args). It raises 
+      # an ArgumentError if no such class can be found.
       #
+      # @param [Array] args arguments for the Environment constructor
       # @return [Environment] an environment instance
       # @raise [ArgumentError] when no registered class recognizes the arguments
-      #
       def autodetect(*args)
-        if (args.size == 1) && args.first.is_a?(Environment)
+        if (args.size == 1) and args.first.is_a?(Environment)
           return args.first
         else
-          environments.each do |name,clazz|
-            return clazz.new(*args) if clazz.recognizes?(args)
-          end
+          name, clazz = environments.find{|nc| nc.last.recognizes?(args)}
+          return clazz.new(*args) if clazz
         end
-        raise ArgumentError, "Unable to auto-detect Environment with #{args.inspect}"
+        envs = environments.map{|r| r.last.name}.join(', ')
+        raise ArgumentError, "Unable to auto-detect Environment with #{args.inspect} [#{envs}]"
       end
-      
-      #
-      # (see Environment.autodetect)
-      #
-      def coerce(*args)
-        autodetect(*args)
-      end
-      
-      #
+      alias :coerce :autodetect
+
       # Returns true _args_ can be used for building an environment instance,
       # false otherwise.
       #
@@ -69,25 +68,28 @@ module Alf
       # registered environments for a chain and each of them should have a 
       # chance of being selected.
       #
+      # @param [Array] args arguments for the Environment constructor
+      # @return [Boolean] true if an environment may be built using `args`,
+      #         false otherwise.
       def recognizes?(args)
         false
       end
-      
-      #
-      # Returns the default environment
+
+      # Returns Alf's default environment
       #
+      # @return [Environment] the default environment instance.
       def default
         examples
       end
-      
-      #
-      # Returns the examples environment
+
+      # Returns an environment on Alf's examples
       #
+      # @return [Environment] an environment on Alf's examples.
       def examples
         folder File.expand_path('../../../../examples/operators', __FILE__)
       end
-    
+
     end # module ClassMethods
     extend(ClassMethods)
   end # class Environment
-end # module Alf
+end # module Alf

data/lib/alf/environment/folder.rb

@@ -9,28 +9,28 @@ module Alf
     # This environment then serves reader instances.
     #
     class Folder < Environment
-      
-      # 
-      # (see Environment.recognizes?)
-      #
-      # Returns true if args contains onely a String which is an existing
-      # folder.
-      #
-      def self.recognizes?(args)
-        (args.size == 1) && 
-        args.first.is_a?(String) && 
-        File.directory?(args.first.to_s)
-      end
-      
-      #
+
+      class << self
+
+        # (see Environment.recognizes?)
+        #
+        # @return [Boolean] true if args contains one String only, which denotes 
+        #         an existing folder; false otherwise
+        def recognizes?(args)
+          (args.size == 1) && 
+          args.first.is_a?(String) && 
+          File.directory?(args.first.to_s)
+        end
+
+      end # class << self
+
       # Creates an environment instance, wired to the specified folder.
       #
-      # @param [String] folder path to the folder to use as dataset source
-      #
+      # @param [String] folder path to the folder to use as dataset source.
       def initialize(folder)
         @folder = folder
       end
-      
+
       # (see Environment#dataset)
       def dataset(name)
         if file = find_file(name)
@@ -39,23 +39,21 @@ module Alf
           raise NoSuchDatasetError, "No such dataset #{name} (#{@folder})"
         end
       end
-      
+
       protected
-      
+
+      # Finds a specific file by name
+      #
+      # @param [String] name the name of a dataset
+      # @return [String] path to an existing file if it exists, nil otherwise.
       def find_file(name)
-        # TODO: refactor this, because it allows getting out of the folder
-        if File.exists?(name.to_s)
-          name.to_s
-        elsif File.exists?(explicit = File.join(@folder, name.to_s)) &&
-              File.file?(explicit)
+        if File.file?(explicit = File.join(@folder, name.to_s))
           explicit
         else
-          Dir[File.join(@folder, "#{name}.*")].find do |f|
-            File.file?(f)
-          end
+          Dir[File.join(@folder, "#{name}.*")].find{|f| File.file?(f)}
         end
       end
-      
+
       Environment.register(:folder, self)
     end # class Folder
   end # class Environment

data/lib/alf/environment/{base.rb → instance_methods.rb}

@@ -1,8 +1,12 @@
 module Alf
   class Environment
-    module Base
+    #
+    # This methods provides base methods for implementing the Environment 
+    # contract. The Environment class already includes it and should be used
+    # as a superclass of specific implementations.
+    #
+    module InstanceMethods
 
-      #
       # Returns a dataset whose name is provided.
       #
       # This method resolves named datasets to tuple enumerables. When the 
@@ -12,26 +16,11 @@ module Alf
       # @param [Symbol] name the name of a dataset
       # @return [Iterator] an iterator, typically a Reader instance
       # @raise [NoSuchDatasetError] when the dataset does not exists
-      #
       def dataset(name)
       end
       undef :dataset
-      
-      #
-      # Branches this environment and puts some additional explicit 
-      # definitions.
-      #
-      # This method is provided for (with ...) expressions and should not
-      # be overriden by subclasses.
-      #
-      # @param [Hash] a set of (name, Iterator) pairs.
-      # @return [Environment] an environment instance with new definitions set
-      #
-      def branch(defs)
-        Explicit.new(defs, self)
-      end
 
-    end # module Base
-    include(Base)
+    end # module InstanceMethods
+    include(InstanceMethods)
   end # class Environment
 end # module Alf

data/lib/alf/environment.rb

@@ -0,0 +1,34 @@
+module Alf
+  #
+  # An environment encapsulates the interface with the outside world, providing 
+  # base iterators for named datasets.
+  #
+  # An environment is typically obtained through the factory defined by this
+  # class:
+  #
+  #   # Returns the default environment (examples, for now)
+  #   Alf::Environment.default
+  #
+  #   # Returns an environment on Alf's examples
+  #   Alf::Environment.examples
+  #
+  #   # Returns an environment on a specific folder, automatically
+  #   # resolving datasources via recognized file extensions (see Reader)
+  #   Alf::Environment.folder('path/to/a/folder')
+  #
+  # You can implement your own environment by subclassing this class and 
+  # implementing the {#dataset} method. As additional support is implemented 
+  # in the base class, Environment should never be mimiced.
+  #
+  # This class provides an extension point allowing to participate to auto 
+  # detection and resolving of the --env=... option when alf is used in shell.
+  # See Environment.register, Environment.autodetect and Environment.recognizes?
+  # for details. 
+  # 
+  class Environment
+    require 'alf/environment/class_methods'
+    require 'alf/environment/instance_methods'
+    require 'alf/environment/folder'
+
+  end # class Environment
+end # module Alf

data/lib/alf/errors.rb

@@ -1,4 +1,5 @@
 module Alf
   class Error < StandardError; end
   class NoSuchDatasetError < Error; end
+  class CoercionError < Error; end
 end

data/lib/alf/iterator/class_methods.rb

@@ -2,9 +2,7 @@ module Alf
   module Iterator
     module ClassMethods
 
-      # 
       # Coerces something to an iterator
-      #
       def coerce(arg, environment = nil)
         case arg
         when Iterator, Array