alf-shell 0.13.0

data/lib/alf/shell/doc_manager.rb

@@ -0,0 +1,83 @@
+module Alf
+  module Shell
+    class DocManager
+
+      # Main documentation folder
+      DOC_FOLDER = Path.backfind("doc")
+
+      #
+      # Called by Quickl when it's time to generate documentation of `cmd`.
+      #
+      def call(cmd, options = {})
+        if File.exists?(file = find_file(cmd))
+          text = File.read(file)
+
+          # Replace occurences of #{signature} to #{signature.to_xxx}
+          # according to options
+          method = (options[:method] || "shell").to_s
+          text = text.gsub('#(signature)', '#(signature.to_' + method + ')')
+
+          # Replace occurences of #{...} on single lines
+          text = text.gsub(/^([ \t]*)#\(([^\)]+)\)/){|match|
+            spacing, invocation  = $1, $2
+            res = cmd.instance_eval(invocation).to_s
+            realign(res, spacing, true)
+          }
+
+          # Replace occurences of #{...} in other places
+          text = text.gsub(/#\(([^\)]+)\)/){|match|
+            cmd.instance_eval($1).to_s
+          }
+
+          # Replace occurences of !{...} by the execution of the example
+          text = text.gsub(/^([ \t]*)!\(([^\)]+)\)/){|match|
+            spacing, invocation  = $1, $2
+            args = Quickl.parse_commandline_args(invocation)[1..-1]
+            op   = run_alf_command(args)
+            res  = op.to_relation.to_s
+            res  = realign(res, spacing, false)[0...-1]
+            if options[:method] == :lispy
+              invocation = Alf::Support.to_lispy(op)
+            end
+            realign("$ #{invocation}\n\n#{res}", spacing, false)
+          }
+
+        else
+          "Sorry, no documentation available for #{cmd.command_name}"
+        end
+      end
+
+    private
+
+      def run_alf_command(argv, requester = nil)
+        argv = Quickl.parse_commandline_args(argv) if argv.is_a?(String)
+        argv = Quickl.split_commandline_args(argv, '|')
+        argv.inject(nil) do |cmd,arr|
+          arr.shift if arr.first == "alf"
+          main = Alf::Shell::Main.new(Alf.examples)
+          main.stdin_operand = cmd unless cmd.nil?
+          main.run(arr, requester)
+        end
+      end
+
+      def realign(txt, spacing, strip)
+        rx = strip ? /^[ \t]*/ : /^/
+        txt.gsub(rx, spacing)
+      end
+
+      def find_file(cmd)
+        where = if cmd.command?
+          "commands"
+        elsif cmd.operator? && cmd.relational?
+          File.join("operators", "relational")
+        elsif cmd.operator? && cmd.non_relational?
+          File.join("operators", "non_relational")
+        else
+          raise "Unexpected command #{cmd}"
+        end
+        File.join(DOC_FOLDER, where, "#{cmd.command_name}.md")
+      end
+
+    end # class DocManager
+  end # module Shell
+end # module Alf

data/lib/alf/shell/ext/signature.rb

@@ -0,0 +1,45 @@
+module Alf
+  module Algebra
+    class Signature
+
+      # Converts commandline arguments to operator constructor arguments
+      def argv2args(argv)
+        # First split over --
+        argv = Quickl.split_commandline_args(argv)
+
+        # Parse the options and replace argv[0] by remaining arguments
+        opts = {}
+        argv[0] = option_parser(opts).parse!(argv[0])
+        opts = default_options.merge(opts)
+
+        # Operands are argv[0], and can be removed
+        oper = argv.shift
+
+        # Coerce each remaining argument according to the signature
+        args = []
+        with_each_arg(argv) do |name,dom,value|
+          invalid_args!(args) if value.nil?
+          args << Shell.from_argv(Array(value), dom)
+        end
+
+        [oper, args, opts]
+      end
+
+      # Returns a shell synopsis for this signature.
+      #
+      # Example:
+      #
+      #     Alf::Algebra::Project.signature.to_shell
+      #     # => "alf project [--allbut] [OPERAND] -- ATTRIBUTES"
+      def to_shell
+        oper = operator.nullary? ? "" :
+              (operator.unary? ? "[OPERAND]" : "[LEFT] RIGHT")
+        opts =   options.map{|opt|   "[#{option_name(opt)}]" }.join(" ")
+        args = arguments.map{|arg,_| "#{arg.to_s.upcase}"    }.join(" -- ")
+        optargs = "#{opts} #{oper} " + (args.empty? ? "" : "-- #{args}")
+        "alf #{operator.rubycase_name} #{optargs.strip}".strip
+      end
+
+    end # class Signature
+  end # module Algebra
+end # module Alf

data/lib/alf/shell/from_argv.rb

@@ -0,0 +1,78 @@
+module Alf
+  module Shell
+
+    FROM_ARGV = Myrrha.coercions do |c|
+
+      # ARGV -> Boolean
+      c.coercion(Array, Boolean){|argv,_|
+        throw :next_rule if argv.size > 1
+        Alf::Support.coerce(argv.first || false, Boolean)
+      }
+
+      # ARGV -> Size
+      c.coercion(Array, Size){|argv,_|
+        throw :next_rule if argv.size > 1
+        Size.new(Integer(argv.first || 0))
+      }
+
+      # ARGV -> AttrName
+      c.coercion(Array, AttrName){|argv,_|
+        throw :next_rule if argv.size > 1
+        AttrName.coerce(argv.first)
+      }
+
+      # ARGV -> AttrList
+      c.coercion(Array, AttrList){|argv,_|
+        AttrList.coerce(argv)
+      }
+
+      # ARGV -> Heading
+      c.coercion(Array, Heading){|argv,_|
+        Heading.coerce(argv)
+      }
+
+      # ARGV -> Ordering
+      c.coercion(Array, Ordering){|argv,_|
+        Ordering.coerce(argv)
+      }
+
+      # ARGV -> Renaming
+      c.coercion(Array, Renaming){|argv,_|
+        Renaming.coerce(argv)
+      }
+
+      # ARGV -> Summarization
+      c.coercion(Array, Summarization){|argv,_|
+        Summarization.coerce(argv)
+      }
+
+      # ARGV -> TupleComputation
+      c.coercion(Array, TupleComputation){|argv,_|
+        TupleComputation.coerce(argv)
+      }
+
+      # ARGV -> TupleExpression
+      c.coercion(Array, TupleExpression){|argv,_|
+        throw :next_rule if argv.size != 1
+        TupleExpression.coerce(argv.first)
+      }
+
+      # ARGV -> Predicate
+      c.coercion(Array, Predicate){|argv,_|
+        if argv.size == 1
+          Predicate.coerce(argv.first)
+        elsif (argv.size % 2) == 0
+          Predicate.coerce(Hash[argv.each_slice(2).map{|k,v| [k.to_sym, eval(v)] }])
+        else
+          throw :next_rule
+        end
+      }
+
+    end
+
+    def self.from_argv(argv, target_domain)
+      FROM_ARGV.coerce(argv, target_domain)
+    end
+
+  end # module Shell
+end # module Alf

data/lib/alf/shell/loader.rb

@@ -0,0 +1,2 @@
+require "alf-core"
+require "quickl"

data/lib/alf/shell/operator.rb

@@ -0,0 +1,63 @@
+require 'forwardable'
+module Alf
+  module Shell
+    module Operator
+
+      module ClassMethods
+        extend Forwardable
+
+        attr_accessor  :operator_class
+        def_delegators :operator_class, :signature,
+                                        :relational?,
+                                        :non_relational?,
+                                        :experimental?,
+                                        :nullary?,
+                                        :unary?,
+                                        :binary?
+
+        def command?
+          false
+        end
+
+        def operator?
+          true
+        end
+      end
+
+      module InstanceMethods
+        extend Forwardable
+
+        def_delegators :"self.class", :signature, :operator_class
+
+        def run(argv, req = nil)
+          @requester = req
+          compile(argv)
+        end
+
+        def compile(argv)
+          operands, args, options = signature.argv2args(argv)
+          operands  = operands(operands, operator_class.arity)
+          init_args = [operands] + args + [options]
+          operator_class.new(*init_args)
+        end
+
+      end # module InstanceMethods
+
+
+      # Defines a command for `clazz`
+      def self.define_operator(op_name, op_class)
+        superclass = Shell::Operator() do |b|
+          b.callback do |cmd|
+            cmd.operator_class = op_class
+          end
+        end
+        Operator.const_set(::Alf::Support.class_name(op_class), Class.new(superclass))
+      end
+
+      Algebra::Operator.listen do |op_name, op_class|
+        define_operator(op_name, op_class)
+      end
+
+    end # module Operator
+  end # module Shell
+end # module Alf

data/lib/alf/shell/support.rb

@@ -0,0 +1,28 @@
+module Alf
+  module Shell
+    module Support
+
+      def database
+        requester && requester.database
+      end
+
+      def compiler
+        @compiler ||= (database && database.connection.compiler) || Engine::Compiler.new(nil)
+      end
+
+      def operands(argv, size = nil)
+        operands = [ stdin_operand ] + Array(argv)
+        operands = operands[(operands.size - size)..-1] if size
+        operands = operands.map{|arg|
+          arg = Algebra.named_operand(arg.to_sym, database) if arg.is_a?(String)
+          Algebra::Operand.coerce(arg)
+        }
+      end
+
+      def stdin_operand
+        requester.stdin_operand rescue $stdin
+      end
+
+    end # module Support
+  end # module Shell
+end # module Alf

data/lib/alf/shell/version.rb

@@ -0,0 +1,16 @@
+module Alf
+  module Shell
+    module Version
+
+      MAJOR = 0
+      MINOR = 13
+      TINY  = 0
+
+      def self.to_s
+        [ MAJOR, MINOR, TINY ].join('.')
+      end
+
+    end
+    VERSION = Version.to_s
+  end
+end

data/spec/integration/__database__/group.alf

@@ -0,0 +1,3 @@
+#!/usr/bin/env alf
+(group :supplies, [:pid, :qty], :supplying)
+(group :supplies, [:sid], :supplying, :allbut => true)

data/spec/integration/__database__/parts.rash

@@ -0,0 +1,6 @@
+{:pid => 'P1', :name => 'Nut',   :color => 'Red',   :weight => 12.0, :city => 'London'}
+{:pid => 'P2', :name => 'Bolt',  :color => 'Green', :weight => 17.0, :city => 'Paris'}
+{:pid => 'P3', :name => 'Screw', :color => 'Blue',  :weight => 17.0, :city => 'Oslo'}
+{:pid => 'P4', :name => 'Screw', :color => 'Red',   :weight => 14.0, :city => 'London'}
+{:pid => 'P5', :name => 'Cam',   :color => 'Blue',  :weight => 12.0, :city => 'Paris'}
+{:pid => 'P6', :name => 'Cog',   :color => 'Red',   :weight => 19.0, :city => 'London'}

data/spec/integration/__database__/suppliers.rash

@@ -0,0 +1,5 @@
+{:sid => 'S1', :name => 'Smith', :status => 20, :city => 'London'}
+{:sid => 'S2', :name => 'Jones', :status => 10, :city => 'Paris'}
+{:sid => 'S3', :name => 'Blake', :status => 30, :city => 'Paris'}
+{:sid => 'S4', :name => 'Clark', :status => 20, :city => 'London'}
+{:sid => 'S5', :name => 'Adams', :status => 30, :city => 'Athens'}

data/spec/integration/__database__/suppliers_csv.csv

@@ -0,0 +1,6 @@
+sid,name,status,city
+S1,Smith,20,London
+S2,Jones,10,Paris
+S3,Blake,30,Paris
+S4,Clark,20,London
+S5,Adams,30,Athens

data/spec/integration/__database__/supplies.rash

@@ -0,0 +1,12 @@
+{:sid => 'S1', :pid => 'P1', :qty => 300}
+{:sid => 'S1', :pid => 'P2', :qty => 200}
+{:sid => 'S1', :pid => 'P3', :qty => 400}
+{:sid => 'S1', :pid => 'P4', :qty => 200}
+{:sid => 'S1', :pid => 'P5', :qty => 100}
+{:sid => 'S1', :pid => 'P6', :qty => 100}
+{:sid => 'S2', :pid => 'P1', :qty => 300}
+{:sid => 'S2', :pid => 'P2', :qty => 400}
+{:sid => 'S3', :pid => 'P2', :qty => 200}
+{:sid => 'S4', :pid => 'P2', :qty => 200}
+{:sid => 'S4', :pid => 'P4', :qty => 300}
+{:sid => 'S4', :pid => 'P5', :qty => 400}

data/spec/integration/alf/alf_db.cmd

@@ -0,0 +1 @@
+alf --db=$(_("alf",__FILE__)) show --text rel

data/spec/integration/alf/alf_db.stdout

@@ -0,0 +1,5 @@
++--------+
+| :hello |
++--------+
+| world  |
++--------+

data/spec/integration/alf/alf_e.cmd

@@ -0,0 +1 @@
+alf -e "(restrict suppliers, lambda{ status > 10})"

data/spec/integration/alf/alf_e.stdout

@@ -0,0 +1,4 @@
+{:sid => "S1", :name => "Smith", :status => 20, :city => "London"}
+{:sid => "S3", :name => "Blake", :status => 30, :city => "Paris"}
+{:sid => "S4", :name => "Clark", :status => 20, :city => "London"}
+{:sid => "S5", :name => "Adams", :status => 30, :city => "Athens"}

data/spec/integration/alf/alf_help.cmd

@@ -0,0 +1 @@
+alf --help

data/spec/integration/alf/alf_help.stdout

@@ -0,0 +1,72 @@
+
+alf - Relational algebra at your fingertips
+
+SYNOPSIS
+
+    alf [--version] [--help]
+    alf -e '(lispy command)'
+    alf [FILE.alf]
+    alf [alf opts] OPERATOR [operator opts] ARGS ...
+    alf help OPERATOR
+
+OPTIONS
+
+    -e, --execute                    Execute one line of script (Lispy API)
+    --rash                       Render output as ruby hashes
+    --text                       Render output as a text table
+    --yaml                       Render output in YAML
+    --json                       Render output in JSON
+    --csv                        Render output in CSV
+    --examples                   Use the example database for database
+    --db=DB                      Set the database to use
+    --input-reader=READER        Specify the kind of reader when reading on $stdin (rash,csv,json)
+    -Idirectory                      Specify $LOAD_PATH directory (may be used more than once)
+    -rlibrary                        Require the library, before executing alf
+    --[no-]pretty                Enable/disable pretty print best effort
+    -h, --help                       Show help
+    -v, --version                    Show version
+
+RELATIONAL OPERATORS
+
+    extend           Relational extension (additional, computed attributes)
+    group            Relational grouping (relation-valued attributes)
+    intersect        Relational intersection (aka a logical and)
+    join             Relational join (and cartesian product)
+    matching         Relational matching (join + project back on left)
+    minus            Relational minus (aka difference)
+    not-matching     Relational not matching (inverse of matching)
+    project          Relational projection (clip + compact)
+    rank             Relational ranking (explicit tuple positions)
+    rename           Relational renaming (rename some attributes)
+    restrict         Relational restriction (aka where, predicate filtering)
+    summarize        Relational summarization (group-by + aggregate ops)
+    ungroup          Relational un-grouping (inverse of group)
+    union            Relational union
+    unwrap           Relational un-wrapping (inverse of wrap)
+    wrap             Relational wrapping (tuple-valued attributes)
+
+EXPERIMENTAL RELATIONAL OPERATORS
+
+    infer-heading     Relational heading inference (print the relation type)
+    quota             Generalized quota-queries (position, sum progression, etc.)
+
+NON-RELATIONAL OPERATORS
+
+    autonum       Extend its operand with an unique autonumber attribute
+    clip          Clip input tuples to a subset of attributes
+    coerce        Force attribute coercion according to a heading
+    compact       Remove tuple duplicates
+    defaults      Force default values on missing/nil attributes
+    generator     Generate a relation with an auto-numbered attribute
+    sort          Sort input tuples according to an order relation
+    type-safe     Check that input tuples are of a specified heading
+
+OTHER NON-RELATIONAL COMMANDS
+
+    exec     Executes an .alf file on current database
+    help     Show help about a specific command
+    show     Output input tuples through a specific renderer (text, yaml, ...)
+
+See 'alf help COMMAND' for details about a specific command.
+
+SystemExit