alf 0.9.3 → 0.10.0

data/lib/alf/operator/shortcut.rb

@@ -0,0 +1,53 @@
+module Alf
+  module Operator
+    #
+    # Specialization of Operator for operators that are shortcuts for longer 
+    # expressions.
+    # 
+    module Shortcut
+      include Operator
+
+      # 
+      # Sets the operator input
+      #
+      def pipe(input, env = environment)
+        self.environment = env
+        self.datasets = input
+        self
+      end
+
+      protected 
+
+      # (see Operator#_each)
+      def _each
+        longexpr.each(&Proc.new)
+      end
+      
+      #
+      # Compiles the longer expression and returns it.
+      #
+      # @return (Iterator) the compiled longer expression, typically another
+      #         Operator instance
+      #
+      def longexpr
+      end 
+      undef :longexpr
+
+      #
+      # This is an helper ala Lispy#chain for implementing (#longexpr).
+      #
+      # @param [Array] elements a list of Iterator-able 
+      # @return [Operator] the first element of the list, but piped with the 
+      #         next one, and so on.
+      #
+      def chain(*elements)
+        elements = elements.reverse
+        elements[1..-1].inject(elements.first) do |c, elm|
+          elm.pipe(c, environment)
+          elm
+        end
+      end
+      
+    end # module Shortcut
+  end # module Operator
+end # module Alf

data/lib/alf/operator/signature.rb

@@ -0,0 +1,262 @@
+module Alf
+  module Operator
+    # Provides an operator signature
+    class Signature
+
+      # @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 a signature instance
+      #
+      def initialize(operator)
+        @operator = operator
+        @arguments = []
+        @options = []
+        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
+
+      #
+      # 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
+      # @return [OptionParser] `opt`
+      #
+      def fill_option_parser(opt, receiver)
+        options.each do |option|
+          name, dom, defa, descr = option
+          opt.on(option_name(option), descr || "") do |val|
+            receiver.send(:"#{name}=", val)
+          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|
+          name, domain, = siginfo
+          clazz.send(:attr_reader, name)
+          clazz.send(:define_method, :"#{name}=") do |val|
+            instance_variable_set(:"@#{name}", Tools.coerce(val, domain))
+          end
+          clazz.send(:private, :"#{name}=")
+        }
+        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
+      #
+      def parse_args(args, receiver)
+        invalid_args!(args) if args.size > (1+arguments.size)
+
+        # Merge default and provided options
+        optargs = default_options
+        if args.size == (1+arguments.size)
+          invalid_args!(args) unless args.last.is_a?(Hash)
+          optargs = optargs.merge(args.pop)
+        end
+
+        # Set options
+        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)
+        end
+      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)
+        # 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])
+
+        # Remove operands
+        operands = argv.shift
+
+        # Parse the rest
+        parse_xxx(argv, :from_argv) do |name,val|
+          receiver.send(:"#{name}=", val)
+        end
+
+        operands
+      end
+
+      #
+      # Collects signature values on a given operator.
+      #
+      # This methods returns a triple `[datasets, arguments, options]` with
+      # the respective values collected on `op`.
+      #
+      # @param [Operator] op an operator, which should be an instance of 
+      #                   `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,_| 
+          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('-', '_')
+        oper = operator.nullary? ? "" :
+              (operator.unary? ? "operand" : "left, right")
+
+        args = arguments.collect{|name,dom,_| 
+          dom.to_s =~ /::([A-Za-z]+)$/
+          "#{name}:#{$1}" 
+        }.join(", ")
+        args = (args.empty? ? "#{oper}" : "#{oper}, #{args}").strip
+
+        opts = options.collect{|name,dom,_|
+          dom.to_s =~ /::([A-Za-z]+)$/
+          "#{name}: #{$1}" 
+        }.join(', ')
+        opts = opts.empty? ? "" : "{#{opts}}"
+
+        argopt = [args, opts].select{|s| !s.empty?}.join(', ')
+        "(#{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
+      end
+
+      private
+
+      def option_name(option)
+        name, domain, defa, = option
+        domain == Boolean ? "--#{name}" : "--#{name}=#{name.to_s.upcase}"
+      end
+
+      def parse_xxx(args, coercer)
+        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
+        end
+      end
+      
+      def invalid_args!(args)
+        raise ArgumentError, "Invalid `#{args.inspect}` for #{self}"
+      end
+      
+    end # class Signature
+  end # module Operator
+end # module Alf

data/lib/alf/operator/transform.rb

@@ -0,0 +1,27 @@
+module Alf
+  module Operator
+    #
+    # Specialization of Operator for operators that simply convert single tuples 
+    # to single tuples.
+    #
+    module Transform
+      include Unary
+  
+      protected 
+  
+      # (see Operator#_each)
+      def _each
+        each_input_tuple do |tuple|
+          yield _tuple2tuple(tuple)
+        end
+      end
+  
+      #
+      # Transforms an input tuple to an output tuple
+      #
+      def _tuple2tuple(tuple)
+      end
+  
+    end # module Transform
+  end # module Operator
+end # module Alf

data/lib/alf/operator/unary.rb

@@ -0,0 +1,38 @@
+module Alf
+  module Operator
+    # 
+    # Specialization of Operator for operators that work on a unary input
+    #
+    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)
+      end
+      
+    end # module Unary
+  end # module Operator
+end # module Alf

data/lib/alf/reader/alf_file.rb

@@ -0,0 +1,24 @@
+module Alf
+  class Reader
+    #
+    # Specialization of the Reader contrat 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.  
+    #
+    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
+end # module Alf

data/lib/alf/reader/base.rb

@@ -0,0 +1,119 @@
+module Alf
+  class Reader
+    module Base
+      
+      # Default reader options
+      DEFAULT_OPTIONS = {}
+      
+      # @return [Environment] Wired environment 
+      attr_accessor :environment
+    
+      # @return [String or IO] Input IO, or file name
+      attr_accessor :input
+      
+      # @return [Hash] Reader's options
+      attr_accessor :options
+    
+      #
+      # Creates a reader instance. 
+      #
+      # @param [String or IO] path to a file or IO object for input
+      # @param [Environment] environment wired environment, serving this reader
+      # @param [Hash] options Reader's options (see doc of subclasses) 
+      #
+      def initialize(*args)
+        @input, @environment, @options = case args.first
+        when String, IO, StringIO
+          Tools.varargs(args, [args.first.class, Environment, Hash])
+        else
+          Tools.varargs(args, [String, Environment, Hash])
+        end
+        @options = self.class.const_get(:DEFAULT_OPTIONS).merge(@options || {}) 
+      end
+    
+      #
+      # (see Iterator#pipe)
+      #
+      def pipe(input, env = environment)
+        @input = input
+        self
+      end
+      
+      #
+      # (see Iterator#each)
+      #
+      # @private the default implementation reads lines of the input stream and 
+      # yields the block with <code>line2tuple(line)</code> on each of them. This 
+      # method may be overriden if this behavior does not fit reader's needs.
+      #
+      def each
+        each_input_line do |line| 
+          tuple = line2tuple(line)
+          yield tuple unless tuple.nil?
+        end
+      end
+    
+      protected
+      
+      #
+      # Returns the input file path, or nil if this Reader is bound to an IO
+      # directly.
+      #
+      def input_path
+        input.is_a?(String) ? input : nil
+      end
+  
+      #
+      # Coerces the input object to an IO and yields the block with it.
+      #
+      # StringIO and IO input are yield directly while file paths are first
+      # opened in read mode and then yield.
+      #
+      def with_input_io
+        case input
+        when IO, StringIO
+          yield input
+        when String
+          File.open(input, 'r'){|io| yield io}
+        else
+          raise "Unable to convert #{input} to an IO object"
+        end
+      end
+      
+      #
+      # Returns the whole input text. 
+      #
+      # This feature should only be used by subclasses on inputs that are 
+      # small enough to fit in memory. Consider implementing readers without this
+      # feature on files that could be larger. 
+      #
+      def input_text
+        with_input_io{|io| io.readlines.join}
+      end
+      
+      #
+      # Yields the block with each line of the input text in turn.
+      #
+      # This method is an helper for files that capture one tuple on each input 
+      # line. It should be used in those cases, as the resulting reader will not
+      # load all input in memory but serve tuples on demand.  
+      #
+      def each_input_line
+        with_input_io{|io| io.each_line(&Proc.new)}
+      end
+    
+      #
+      # Converts a line previously read from the input stream to a tuple. 
+      #
+      # The line is simply ignored is this method return nil. Errors should be
+      # properly handled by raising exceptions. This method MUST be implemented 
+      # by subclasses unless each is overriden.
+      #
+      def line2tuple(line)
+      end
+      undef :line2tuple
+      
+    end # module Base
+    include Base
+  end # class Reader
+end # module Alf

data/lib/alf/reader/class_methods.rb

@@ -0,0 +1,82 @@
+module Alf
+  class Reader
+    module ClassMethods
+      
+      #
+      # Returns registered readers
+      #
+      def readers
+        @readers ||= []
+      end
+      
+      #      
+      # 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.
+      #
+      # @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 
+      #     
+      def register(name, extensions, clazz)
+        readers << [name, extensions, clazz]
+        (class << self; self; end).
+          send(:define_method, name) do |*args|
+            clazz.new(*args)
+          end
+      end
+    
+      #
+      # 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 [Array] args optional additional arguments that must be passed at
+      #        reader's class new method.
+      # @return [Reader] a reader instance
+      # 
+      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? 
+          coerce(filepath)
+        else
+          raise ArgumentError, "Unable to return a reader for #{filepath} and #{args}" 
+        end
+      end
+      
+      #
+      # 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.
+      #
+      def coerce(arg, environment = nil)
+        case arg
+        when Reader
+          arg
+        when IO
+          rash(arg, environment)
+        else
+          raise ArgumentError, "Unable to coerce #{arg.inspect} to a reader"
+        end
+      end
+      
+    end # module ClassMethods
+    extend(ClassMethods)
+  end # class Reader
+end # module Alf

data/lib/alf/reader/rash.rb

@@ -0,0 +1,28 @@
+module Alf
+  class Reader
+    #
+    # Specialization of the Reader contract for .rash files.
+    #
+    # A .rash file/stream contains one ruby hash literal on each line. This 
+    # reader simply decodes each of them in turn with Kernel.eval, providing a 
+    # state-less reader (that is, tuples are not all loaded in memory at once).
+    #
+    class Rash < Reader
+  
+      # (see Reader#line2tuple)
+      def line2tuple(line)
+        begin
+          h = Kernel.eval(line)
+          raise "hash expected, got #{h}" unless h.is_a?(Hash)
+        rescue Exception => ex
+          $stderr << "Skipping #{line.strip}: #{ex.message}\n"
+          nil
+        else
+          return h
+        end
+      end
+  
+      Reader.register(:rash, [".rash"], self)  
+    end # class Rash
+  end # class Reader
+end # module Alf

data/lib/alf/relation/class_methods.rb

@@ -0,0 +1,37 @@
+module Alf
+  class Relation
+    module ClassMethods
+      
+      #
+      # Coerces `val` to a relation.
+      #
+      # Recognized arguments are: Relation (identity coercion), Set of ruby hashes, 
+      # Array of ruby hashes, Alf::Iterator.
+      #
+      # @return [Relation] a relation instance for the given set of tuples
+      # @raise [ArgumentError] when `val` is not recognized
+      #
+      def coerce(val)
+        case val
+        when Relation
+          val
+        when Set
+          Relation.new(val)
+        when Array
+          Relation.new val.to_set
+        when Iterator
+          Relation.new val.to_set
+        else
+          raise ArgumentError, "Unable to coerce #{val} to a Relation"
+        end
+      end
+      
+      # (see Relation.coerce)
+      def [](*tuples)
+        coerce(tuples)
+      end
+      
+    end # module ClassMethods
+    extend(ClassMethods)
+  end # class Relation
+end # module Alf