alf 0.10.1 → 0.11.0

data/lib/alf/operator/signature.rb

@@ -5,16 +5,16 @@ module Alf
 
       # @return [Class] the operator class to which this signature belongs
       attr_reader :operator
-      
+
       # @return [Array] signature arguments
       attr_reader :arguments
 
       # @return [Array] signature options
       attr_reader :options
 
+      # Creates an empty signature instance
       #
-      # Creates a signature instance
-      #
+      # @param [Class] the operator class to which this signature belongs
       def initialize(operator)
         @operator = operator
         @arguments = []
@@ -22,73 +22,50 @@ module Alf
         yield(self) if block_given?
       end
 
-      #
       # Adds an argument to the signature
       #
       # @param [Symbol] name argument name
       # @param [Class] domain argument domain
       # @param [Object] default (optional) default value
-      #
       def argument(name, domain, default = nil, descr = nil)
         arguments << [name, domain, default, descr]
       end
 
-      #
       # Adds an option to the signature
       # 
       # @param [Symbol] name argument name
       # @param [Class] domain argument domain
       # @param [Object] default (optional) default value
-      #
       def option(name, domain, default = nil, descr = nil)
         options << [name, domain, default, descr]
       end
 
+      # Builds an option parser instance `opt` prepared for installing options on
+      # `receiver`.
       #
-      # Returns default options as a Hash
-      #
-      # @return [Hash] the default options
-      #
-      def default_options
-        @default_options ||=
-          Hash[options.select{|opt| !opt[2].nil? }.
-                       collect{|opt| [opt[0], opt[2]]}]
-      end
-
-      #
-      # Fills an OptionParser instance according to signature options.
-      #
-      # @param [OptionParser] opt an parser instance, to fill with parse options
+      # @param [Hash|Operator] a receiver for option values
+      # @param [OptionParser] opt the parser to fill with options
       # @return [OptionParser] `opt`
-      #
-      def fill_option_parser(opt, receiver)
+      def option_parser(receiver, opt = OptionParser.new)
         options.each do |option|
           name, dom, defa, descr = option
           opt.on(option_name(option), descr || "") do |val|
-            receiver.send(:"#{name}=", val)
+            if receiver.is_a?(Hash)
+              receiver[name] = val
+            else
+              receiver.send(:"#{name}=", val)
+            end
           end
         end
         opt
       end
 
-      #
-      # Returns an option parser instance bound to a given `receiver` object
-      #
-      # @return [OptionParser] an parser instance, ready to parse options and
-      #         install them on `receiver` 
-      #
-      def option_parser(receiver)
-        fill_option_parser(OptionParser.new, receiver)
-      end
-      
-      #
       # Installs the signature on the operator class
       #
       # This method installs an attr reader and an attr writer for each
       # signature argument and each signature option.
       #
       # @return [Hash] the default options to use
-      #
       def install
         clazz = operator
         code = (arguments + options).each{|siginfo|
@@ -101,64 +78,67 @@ module Alf
         }
         default_options
       end
-      
-      #
+
       # Parses arguments `args` passed to the operator `initialize` and 
       # sets attributes accordingly on `receiver`.
       #
       # @param [Array] args an array of initialize arguments
       # @param [Operator] receiver an operator instance
-      #
+      # @return [Operator] installed `receiver`
       def parse_args(args, receiver)
-        invalid_args!(args) if args.size > (1+arguments.size)
 
-        # Merge default and provided options
+        # 1) Check and set operands, passed as an array as first argument
+        invalid_args!(args) unless args.first.is_a?(Array)
+        receiver.operands = args.shift
+
+        # 2) Extract options if provided
         optargs = default_options
         if args.size == (1+arguments.size)
+          # options are passed as last argument
           invalid_args!(args) unless args.last.is_a?(Hash)
           optargs = optargs.merge(args.pop)
+        elsif args.size > arguments.size
+          # too many arguments here
+          invalid_args!(args)
         end
 
-        # Set options
+        # 3) Set options now, including default ones
         optargs.each_pair do |name,val|
           receiver.send(:"#{name}=", val)
         end
         
-        # Parse other arguments now
-        parse_xxx(args, :coerce) do |name,val|
-          receiver.send(:"#{name}=", val)
+        # 4) Parse other arguments now
+        with_each_arg(args) do |name,dom,value|
+          invalid_args!(args) if value.nil?
+          receiver.send(:"#{name}=", value)
         end
+
+        receiver
       end
-      
-      #
-      # Parses arguments `args` used to create an operator initialize from
-      # commandline arguments and sets attributes accordingly on `receiver`.
-      #
-      # @param [Array] argv an array of commandline arguments
-      # @param [Operator] receiver an operator instance
-      #
-      def parse_argv(argv, receiver)
+
+      # Converts commandline arguments to operator constructor arguments
+      def argv2args(argv)
         # First split over --
         argv = Quickl.split_commandline_args(argv)
 
-        # Set default options then parse those in first group
-        default_options.each_pair do |name,val|
-          receiver.send(:"#{name}=", val)
-        end
-        argv[0] = option_parser(receiver).parse!(argv[0])
+        # Parse the options and replace argv[0] by remaining arguments
+        opts = {}
+        argv[0] = option_parser(opts).parse!(argv[0])
+        opts = default_options.merge(opts)
 
-        # Remove operands
-        operands = argv.shift
+        # Operands are argv[0], and can be removed
+        oper = argv.shift
 
-        # Parse the rest
-        parse_xxx(argv, :from_argv) do |name,val|
-          receiver.send(:"#{name}=", val)
+        # Coerce each remaining argument according to the signature
+        args = []
+        with_each_arg(argv) do |name,dom,value|
+          invalid_args!(args) if value.nil?
+          args << dom.from_argv(Array(value))
         end
 
-        operands
+        [oper, args, opts]
       end
 
-      #
       # Collects signature values on a given operator.
       #
       # This methods returns a triple `[datasets, arguments, options]` with
@@ -168,28 +148,24 @@ module Alf
       #                   `self.operator`
       # @return [Array] a triple [datasets, arguments, options] with operands, 
       #                 then signature values
-      #
       def collect_on(op)
-        oper = op.datasets
-        oper = [oper] unless oper.is_a?(Array)
-        args = arguments.collect{|name,_| op.send(name) }
-        opts = Hash[options.collect{|name,dom,defa,_| 
+        oper = op.operands
+        args = arguments.map{|name,_| op.send(name) }
+        opts = Hash[options.map{|name,dom,defa,_| 
           val = op.send(name)
           (val == defa) ? nil : [name, val]
         }.compact]
         [oper, args, opts]
       end
 
-      #
       # Returns a lispy synopsis for this signature
       #
       # Example:
       #
       #     Alf::Operator::Relational::Project.signature.to_shell
       #     # => "(project operand, attributes:AttrList, {allbut: Boolean})"
-      #
       def to_lispy
-        cmd  = operator.command_name.to_s.gsub('-', '_')
+        cmd  = operator.rubycase_name
         oper = operator.nullary? ? "" :
               (operator.unary? ? "operand" : "left, right")
 
@@ -209,54 +185,49 @@ module Alf
         "(#{cmd} #{argopt}".strip + ")"
       end
 
-      #
       # Returns a shell synopsis for this signature.
       #
       # Example:
       #
       #     Alf::Operator::Relational::Project.signature.to_shell
       #     # => "alf project [--allbut] [OPERAND] -- ATTRIBUTES"
-      #
       def to_shell
         oper = operator.nullary? ? "" :
               (operator.unary? ? "[OPERAND]" : "[LEFT] RIGHT")
         opts =   options.collect{|opt|   "[#{option_name(opt)}]" }.join(" ")
         args = arguments.collect{|arg,_| "#{arg.to_s.upcase}"    }.join(" -- ")
         optargs = "#{opts} #{oper} " + (args.empty? ? "" : "-- #{args}")
-        "alf #{operator.command_name} #{optargs.strip}".strip
+        "alf #{operator.rubycase_name} #{optargs.strip}".strip
       end
 
       private
 
+      # @return the default options as a Hash
+      def default_options
+        @default_options ||=
+          Hash[options.select{|opt| !opt[2].nil? }.
+                       map{|opt| [opt[0], opt[2]]}]
+      end
+
+      # @return the name to use in shell for `option`
       def option_name(option)
         name, domain, defa, = option
         domain == Boolean ? "--#{name}" : "--#{name}=#{name.to_s.upcase}"
       end
 
-      def parse_xxx(args, coercer)
+      # Yields `(name,dom,value)` triples for each argument value
+      def with_each_arg(args)
         arguments.zip(args).collect do |sigpart,subargs|
           name, dom, default = sigpart
-          
-          # coercion
-          val = if Array(subargs).empty?
-            Tools.coerce(default, dom)
-          else
-            dom.send(coercer, subargs)
-          end
-          
-          # check and yield
-          if val.nil?
-            raise ArgumentError, "Invalid `#{subargs.inspect}` for #{sigpart.inspect}"
-          else
-            yield(name, val)
-          end
+          val = Array(subargs).empty? ? default : subargs
+          yield(name, dom, val)
         end
       end
-      
-      def invalid_args!(args)
-        raise ArgumentError, "Invalid `#{args.inspect}` for #{self}"
+
+      def invalid_args!(args, msg = "Invalid `#{args.inspect}` for #{self}")
+        raise ArgumentError, msg, caller
       end
-      
+
     end # class Signature
   end # module Operator
 end # module Alf

data/lib/alf/operator/unary.rb

@@ -5,34 +5,12 @@ module Alf
     #
     module Unary
       include Operator 
-      
-      # 
-      # Sets the operator input
-      #
-      def pipe(input, env = environment)
-        self.environment = env
-        self.datasets = [ input ]
-        self
-      end
 
-      protected
-    
-      #
-      # Simply returns the first dataset
-      #
-      def input
-        Iterator.coerce(datasets.first, environment)
-      end
-      
-      # 
-      # Yields the block with each input tuple.
-      #
-      # This method should be preferred to <code>input.each</code> when possible.
-      #
-      def each_input_tuple
-        input.each(&Proc.new)
+      # Simply returns the first operand
+      def operand
+        operands.first
       end
-      
+
     end # module Unary
   end # module Operator
 end # module Alf

data/lib/alf/operator.rb

@@ -0,0 +1,68 @@
+module Alf
+  #
+  # Namespace for all operators, relational and non-relational ones.
+  # 
+  module Operator
+    include Iterator, Tools
+
+    require 'alf/operator/class_methods'
+    require 'alf/operator/signature'
+    require 'alf/operator/instance_methods'
+    require 'alf/operator/nullary'
+    require 'alf/operator/unary'
+    require 'alf/operator/binary'
+    require 'alf/operator/experimental'
+
+    # Namespace for non relational operators
+    module NonRelational
+      require 'alf/operator/non_relational/autonum'
+      require 'alf/operator/non_relational/defaults'
+      require 'alf/operator/non_relational/compact'
+      require 'alf/operator/non_relational/sort'
+      require 'alf/operator/non_relational/clip'
+      require 'alf/operator/non_relational/coerce'
+      require 'alf/operator/non_relational/generator'
+
+      # Yields the block with each operator module in turn
+      def self.each
+        constants.each do |c|
+          val = const_get(c)
+          yield(val) if val.ancestors.include?(Operator::NonRelational)
+        end
+      end
+    end # NonRelational
+    
+    #
+    # Marker module and namespace for relational operators
+    #
+    module Relational
+      require 'alf/operator/relational/extend'
+      require 'alf/operator/relational/project'
+      require 'alf/operator/relational/restrict'
+      require 'alf/operator/relational/rename'
+      require 'alf/operator/relational/union'
+      require 'alf/operator/relational/minus'
+      require 'alf/operator/relational/intersect'
+      require 'alf/operator/relational/join'
+      require 'alf/operator/relational/matching'
+      require 'alf/operator/relational/not_matching'
+      require 'alf/operator/relational/wrap'
+      require 'alf/operator/relational/unwrap'
+      require 'alf/operator/relational/group'
+      require 'alf/operator/relational/ungroup'
+      require 'alf/operator/relational/summarize'
+      require 'alf/operator/relational/rank'
+      require 'alf/operator/relational/quota'
+      require 'alf/operator/relational/heading'
+
+      # Yields the block with each operator module in turn
+      def self.each
+        constants.each do |c|
+          val = const_get(c)
+          yield(val) if val.ancestors.include?(Operator::Relational)
+        end
+      end
+    end # module Relational
+    
+  end # module Operator
+end # module Alf

data/lib/alf/reader/alf_file.rb

@@ -1,23 +1,23 @@
 module Alf
   class Reader
     #
-    # Specialization of the Reader contrat for .alf files.
+    # Specialization of the Reader contract for .alf files.
     #
     # A .alf file simply contains a query expression in the Lispy DSL. This
     # reader decodes and compiles the expression and delegates the enumeration
     # to the obtained operator.
     #
-    # Note that an Environment must be wired at creation or piping time. 
-    # NoSuchDatasetError will certainly occur otherwise.  
+    # Note that an Environment must be wired at creation time. A 
+    # NoSuchDatasetError will certainly occur otherwise.
     #
     class AlfFile < Reader
-      
+
       # (see Reader#each)
       def each
         op = Alf.lispy(environment).compile(input_text, input_path)
         op.each(&Proc.new)
       end
-      
+
       Reader.register(:alf, [".alf"], self)
     end # module AlfFile
   end # class Reader

data/lib/alf/reader/class_methods.rb

@@ -1,28 +1,24 @@
 module Alf
   class Reader
     module ClassMethods
-      
-      #
-      # Returns registered readers
-      #
+
+      # @return [Array<Reader>] registered readers
       def readers
         @readers ||= []
       end
-      
-      #      
-      # Registers a reader class associated with specific file extensions
+
+      # Registers a reader class associated with specific file extensions.
       #
       # Registered class must provide a constructor with the following signature 
-      # <code>new(path_or_io, environment = nil)</code>. The name must be a symbol
-      # which can safely be used as a ruby method name. A factory class method of 
-      # that name and same signature is automatically installed on the Reader 
-      # class.
+      # `new(path_or_io, environment = nil, options = {})`. The registration 
+      # name must be a symbol which can safely be used as a ruby method name. 
+      # A factory method of that name and signature is automatically installed 
+      # on the Reader class.
       #
       # @param [Symbol] name a name for the kind of data decoded
       # @param [Array] extensions file extensions mapped to the registered reader 
       #                class (should include the '.', e.g. '.foo')
-      # @param [Class] class Reader subclass used to decode this kind of files 
-      #     
+      # @param [Class] class Reader subclass used to decode this kind of files
       def register(name, extensions, clazz)
         readers << [name, extensions, clazz]
         (class << self; self; end).
@@ -30,41 +26,38 @@ module Alf
             clazz.new(*args)
           end
       end
-    
+
+      # When filepath looks like a String or a path, returns a reader instance 
+      # for the source it denotes. Otherwise, delegates the call to 
+      # `coerce(filepath)`.
       #
-      # When filepath is a String, returns a reader instance for a specific file 
-      # whose path is given as argument. Otherwise, delegate the call to
-      # <code>coerce(filepath)</code>
-      #
-      # @param [String] filepath path to a file for which extension is recognized
+      # @param [:to_str|:to_path] filepath path to a file for which extension 
+      #        is recognized
       # @param [Array] args optional additional arguments that must be passed at
       #        reader's class new method.
-      # @return [Reader] a reader instance
-      # 
+      # @return [Reader] a reader instance built from arguments
+      # @raise [ArgumentError] if `filepath` is not recognized or no reader can
+      #        be found for this extension.
       def reader(filepath, *args)
-        if filepath.is_a?(String)
-          ext = File.extname(filepath)
-          if registered = readers.find{|r| r[1].include?(ext)}
-            registered[2].new(filepath, *args)
-          else
-            raise "No registered reader for #{ext} (#{filepath})"
-          end
-        elsif args.empty? 
+        if looks_a_path?(filepath)
+          ext = File.extname(filepath.to_s)
+          has_reader_for_ext!(ext).new(filepath.to_s, *args)
+        elsif args.empty?
           coerce(filepath)
         else
           raise ArgumentError, "Unable to return a reader for #{filepath} and #{args}" 
         end
       end
-      
+
+      # Coerces `arg` to a Reader instance, using an optional environment to 
+      # convert named datasets.
       #
-      # Coerces an argument to a reader, using an optional environment to convert 
-      # named datasets.
-      #
-      # This method automatically provides readers for Strings and Symbols through
-      # passed environment (**not** through the reader factory) and for IO objects 
-      # (through Rash reader). It is part if Alf's internals and should be used 
-      # with care.
+      # This method automatically provides readers for Strings and Symbols 
+      # through `environment` (**not** through the reader factory) and for IO 
+      # objects through a Rash reader.
       #
+      # @param [Object] arg any value to coerce to a Reader instance
+      # @param [Environment] environment to resolved named datasets (optional)
       def coerce(arg, environment = nil)
         case arg
         when Reader
@@ -75,7 +68,23 @@ module Alf
           raise ArgumentError, "Unable to coerce #{arg.inspect} to a reader"
         end
       end
-      
+
+      private
+
+      # Checks if `path` looks like a usable path
+      def looks_a_path?(path)
+        return false if path.is_a?(StringIO) 
+        path.respond_to?(:to_str) or path.respond_to?(:to_path)
+      end
+
+      # @return [Class] the reader class to use for `ext` file extension.
+      # @raise [ArgumentError] if no such reader class can be found
+      def has_reader_for_ext!(ext)
+        entry = readers.find{|r| r[1].include?(ext)}
+        return entry[2] if entry
+        raise ArgumentError, "No registered reader for #{ext}"
+      end
+
     end # module ClassMethods
     extend(ClassMethods)
   end # class Reader