alf-shell 0.14.0 → 0.15.0

data/doc/txt/sum.txt

@@ -0,0 +1,22 @@
+# Sum
+
+Arithmetic sum
+
+## Signature
+
+sum(expr: AttrName|(Tuple->Numeric)) -> Aggregator
+
+## Examples
+sum(:qty)
+sum{|t| t.qty * t.price }
+sum(->(t){ t.qty * t.price })
+
+## Description
+
+Computes `v1 + v2 + ... + vn`.
+
+## Implementation notes
+
+This aggregate function should only be used with numeric types. As of
+current Alf version, it does not aggregate empty sets correctly on
+non-numeric data types.

data/doc/txt/summarize.txt

@@ -0,0 +1,33 @@
+# Summarize
+
+Aggregate and compute
+
+## Signature
+
+summarize(operand: Relation, by: AttrList, aggs: Summarization) -> Relation
+
+## Examples
+
+summarize(supplies, [:sid], total: sum(:qty))
+
+summarize(supplies, [:sid], total: sum{|t| t.qty * 2 })
+
+summarize(supplies, [:pid, :qty], {total: sum{|t| t.qty * 2 }}, allbut: true)
+
+## Description
+
+Computes the relation obtained by taking the projection of `operand`
+on `by` attributes then extending each tuple `t` with the result of
+aggregations defined by `aggs` on the tuples from `operand` matching `t`.
+
+In SQL terms, `SELECT [by], [agg] FROM operand GROUP BY [by]`.
+
+## Implementation notes
+
+As of current Alf version, this operator cannot be translated to SQL code.
+That means that all computations are done in ruby, which may seriously
+hurt performance.
+
+Similarly, as `summarize` tends to be a showstopper during compilation, it
+is strongly recommanded to use it as high as possible in query expressions
+trees so as to delegate the largest possible query parts to data engines.

data/doc/txt/tautology.txt

@@ -0,0 +1,15 @@
+# Tautology
+
+TRUE
+
+## Signature
+
+tautology() -> Predicate
+
+## Examples
+true
+tautology
+
+## Description
+
+This predicate always return true. It is equivalent to `->(t){ true }`.

data/doc/txt/ungroup.txt

@@ -0,0 +1,26 @@
+# Ungroup
+
+Inverse of group
+
+## Signature
+
+ungroup(operand: Relation, rva: AttrName) -> Relation
+
+## Examples
+
+ungroup(group(suppliers, [:city], :suppliers, allbut: true), :suppliers)
+
+## Description
+
+Computes the relation obtained by ungrouping a relation-valued attribute
+`rva`. Ungrouping `rva` leads as many tuples as in `rva`, each extended
+with the other attributes of `operand`.
+
+`rva` must be a relation-valued attribute. It should not itself contain
+any attribute whose name clashes with an attribute of `operand`.
+
+## Implementation notes
+
+This operator does not compile to SQL so far. Contributions are welcome
+to provide it with a SQL compilation for SQL DBMSs that support this kind
+of feature (e.g. PostgreSQL with JSON data type)

data/doc/txt/union.txt

@@ -0,0 +1,43 @@
+# Union
+
+Logical OR
+
+## Signature
+
+union(left: Relation, right: Relation) -> Relation
+
+## Examples
+
+union(project(suppliers, [:city]), project(parts, [:city]))
+
+## Description
+
+Computes the relation as the set union of `left` and `right`.
+
+The `left` and `right` relations must be union-compatible, meaning that they
+must have same heading (type inheritance is partly supported through ruby's
+own type system, so that the actual behavior is slighlty more permissive).
+
+## Implementation notes
+
+Unlike SQL, this operator ALWAYS remove duplicates. There is no way, in
+Alf, to compute _bags_ of tuples and therefore no way to express something
+such as SQL's UNION ALL.
+
+The optimizer is not smart enough so far to discover when operands are
+actually disjoint and duplicate removal not needed (e.g. the SQL compiler
+never generates UNION ALL). Any patch improving this is welcome!
+
+Similarly, it is sometimes idiomatic in Alf to use `union` as a logical OR,
+as illustrated below. So far, the optimizer/compiler is not smart enough to
+translate the former in the latter (which is likely to have a better query
+plan, especially when using faithful SQL compilation and usual SQL DBMSs).
+Any patch is welcome here too!
+
+union(
+  restrict(suppliers, city: 'Paris'),
+  restrict(suppliers, city: 'London'))
+
+is equivalent to
+
+restrict(suppliers, eq(:city, 'Paris') | eq(:city, 'London'))

data/doc/txt/unwrap.txt

@@ -0,0 +1,29 @@
+# Unwrap
+
+Inverse of wrap
+
+## Signature
+
+unwrap(operand: Relation, tva: AttrName) -> Relation
+
+## Examples
+
+unwrap(wrap(suppliers, [:city, :status], :extra), :extra)
+
+## Description
+
+Computes the relation obtained by unwrapping a tuple-valued attribute `tva`.
+Unwrapping of `tva` on an input tuple `t` consists in removing `tva` from
+`t` and extending the result with `tva`'s own attributes:
+
+Tuple(x: 1, tva: Tuple(y: 2, z: 3)) -> Tuple(x: 1, y: 2, z: 3)
+
+`tva` must be a tuple-valued attribute. It should not itself contain any
+attribute whose name clashes with an attribute of `operand`. In the examples
+above, `tva` may not contain an attribute called `x`.
+
+## Implementation notes
+
+This operator does not compile to SQL so far. Contributions are welcome to
+provide it with a SQL compilation for SQL DBMSs that support this kind of
+feature (e.g. PostgreSQL with JSON data type)

data/doc/txt/variance.txt

@@ -0,0 +1,22 @@
+# Variance
+
+Variance
+
+## Signature
+
+variance(expr: AttrName|(Tuple->Numeric)) -> Aggregator
+
+## Examples
+variance(:qty)
+variance{|t| t.qty * t.price }
+variance(->(t){ t.qty * t.price })
+
+## Description
+
+Computes how far the set of input values is spread out.
+
+## Implementation notes
+
+This aggregate function should only be used with numeric types. As of
+current Alf version, it does not aggregate empty sets correctly on
+non-numeric data types.

data/doc/txt/wrap.txt

@@ -0,0 +1,29 @@
+# Wrap
+
+Tuple-valued attribute
+
+## Signature
+
+wrap(operand: Relation, attributes: AttrList, as: AttrName) -> Relation
+
+## Examples
+
+wrap(suppliers, [:city, :status], :extra)
+
+wrap(suppliers, [:city, :status], :extra, allbut: true)
+
+## Description
+
+Computes the relation obtained by removing `attributes` and replacing them
+by a single attribute (`as`). The latter is a tuple-valued attribute
+obtained by projecting the input tuple on `attributes`.
+
+This operators supports an ALL BUT variant, through the `allbut` option.
+When set to true, the operator keeps specified attributes and wraps all the
+remaining ones as a tuple-valued attribute.
+
+## Implementation notes
+
+This operator does not compile to SQL so far. Contributions are welcome to
+provide it with a SQL compilation for SQL DBMSs that support this kind of
+feature (e.g. PostgreSQL with JSON data type)

data/lib/alf/shell.rb

@@ -1,52 +1,22 @@
 require_relative 'shell/version'
 require_relative 'shell/loader'
-require_relative 'shell/ext/signature'
 require_relative 'shell/alfrc'
-require_relative 'shell/doc_manager'
 module Alf
   module Shell
 
-    # This is the main documentation extractor
-    DOC_EXTRACTOR = DocManager.new
-
     # This is the default configuration to be forked from
     DEFAULT_CONFIG = Alfrc.new
 
-    # Delegator command factory
-    def self.Delegator()
-      Quickl::Delegator(){|builder|
-        builder.doc_extractor = DOC_EXTRACTOR
-        builder.class_module Command::ClassMethods
-        yield(builder) if block_given?
-      }
-    end
-
     # Command factory
-    def self.Command()
-      Quickl::Command(){|builder|
-        builder.command_parent = Alf::Shell::Main
-        builder.doc_extractor  = DOC_EXTRACTOR
-        builder.class_module Command::ClassMethods
-        builder.instance_module Shell::Support
-        yield(builder) if block_given?
-      }
-    end
-
-    # Operator factory
-    def self.Operator()
-      Quickl::Command(){|builder|
+    def self.Command(*args)
+      Quickl::Command(*args){|builder|
         builder.command_parent = Alf::Shell::Main
-        builder.doc_extractor  = DOC_EXTRACTOR
-        builder.class_module    Operator::ClassMethods
         builder.instance_module Shell::Support
-        builder.instance_module Operator::InstanceMethods
         yield(builder) if block_given?
       }
     end
 
   end # module Shell
 end # module Alf
-require_relative 'shell/from_argv'
 require_relative 'shell/support'
 require_relative 'shell/command'
-require_relative 'shell/operator'

data/lib/alf/shell/alfrc.rb

@@ -11,6 +11,9 @@ module Alf
       # Default renderer to use for outputting relations
       option :default_renderer, Class, ->{ $stdout.tty? ? Renderer::Text : Renderer::Rash }
 
+      # Default reader name to use for reading on stdin
+      option :stdin_reader, Symbol, :rash
+
       # Float format to use
       option :float_format, String, "%.3f"
 

data/lib/alf/shell/command.rb

@@ -1,21 +1,5 @@
-module Alf
-  module Command
-    module ClassMethods
-
-      # @return true
-      def command?
-        true
-      end
-
-      # @return false
-      def operator?
-        false
-      end
-
-    end # module ClassMethods
-  end # module Command
-end # module Alf
 require_relative 'command/main'
-require_relative 'command/exec'
 require_relative 'command/help'
 require_relative 'command/show'
+require_relative 'command/metadata'
+require_relative 'command/explain'

data/lib/alf/shell/command/explain.rb

@@ -0,0 +1,37 @@
+module Alf
+  module Shell
+    class Explain < Shell::Command(__FILE__,__LINE__)
+
+      options do |opt|
+
+        opt.on_tail('-h', "--help", "Show help") do
+          show_help("alf-explain")
+        end
+
+      end
+
+      def run(argv, requester)
+        # set requester and parse options
+        @requester = requester
+        argv = parse_options(argv, :split)
+
+        operand = compile(argv)
+
+        puts "Logical plan:"
+        puts
+        puts operand.to_ascii_tree.gsub(/^/, "  ")
+
+        puts
+
+        puts "Physical plan:"
+        puts
+        puts operand.to_cog.to_ascii_tree.gsub(/^/, "  ")
+      end
+
+      def compile(argv)
+        operand(argv.shift)
+      end
+
+    end # class Explain
+  end # module Shell
+end # module Alf

data/lib/alf/shell/command/help.rb

@@ -1,30 +1,12 @@
 module Alf
   module Shell
-    class Help < Shell::Command()
-      
-      # Let NoSuchCommandError be passed to higher stage
-      no_react_to Quickl::NoSuchCommand
-      
-      options do |opt|
-        @dialect = :shell
-        opt.on('--lispy', 
-               'Display operator signatures in lispy DSL') do
-          @dialect = :lispy
-        end
-        opt.on('--shell', 
-               'Display operator signatures in shell DSL') do
-          @dialect = :shell
-        end
-      end
+    class Help < Shell::Command(__FILE__, __LINE__)
 
       # Command execution
       def execute(args)
-        sup = Quickl.super_command(self)
-        sub = (args.size != 1) ? sup : Quickl.sub_command!(sup, args.first)
-        doc = sub.documentation(:method => @dialect)
-        puts doc
+        show_help(args.first.strip)
       end
-      
+
     end # class Help
   end # module Shell
 end # module Alf

data/lib/alf/shell/command/main.rb

@@ -1,49 +1,7 @@
 module Alf
   module Shell
-    class Main < Shell::Delegator()
-
-      class << self
-
-        def relational_operators(sort_by_name = true)
-          ops = subcommands.select{|cmd|
-             cmd.operator? and cmd.relational? and !cmd.experimental?
-          }
-          sort_operators(ops, sort_by_name)
-        end
-
-        def experimental_operators(sort_by_name = true)
-          ops = subcommands.select{|cmd|
-            cmd.operator? and cmd.relational? and cmd.experimental?
-          }
-          sort_operators(ops, sort_by_name)
-        end
-
-        def non_relational_operators(sort_by_name = true)
-          ops = subcommands.select{|cmd|
-            cmd.operator? and !cmd.relational?
-          }
-          sort_operators(ops, sort_by_name)
-        end
-
-        def other_non_relational_commands(sort_by_name = true)
-          ops = subcommands.select{|cmd|
-            cmd.command?
-          }
-          sort_operators(ops, sort_by_name)
-        end
-
-        private
-
-        def sort_operators(ops, sort_by_name)
-          sort_by_name ? ops.sort{|op1,op2|
-            op1.command_name.to_s <=> op2.command_name.to_s
-          } : ops
-        end
-
-      end # class << self
-
-      # The reader to use when stdin is used as operand
-      attr_accessor :stdin_operand
+    class Main < Quickl::Delegator(__FILE__, __LINE__)
+      include Support
 
       # Creates a command instance
       def initialize(config = load_config)
@@ -55,11 +13,6 @@ module Alf
       options do |opt|
         @rendering_options = {}
 
-        @execute = false
-        opt.on("-e", "--execute", "Execute one line of script (Lispy API)") do
-          @execute = true
-        end
-
         Renderer.each do |name,descr,clazz|
           opt.on("--#{name}", "Render output #{descr}"){
             config.default_renderer = clazz
@@ -75,12 +28,11 @@ module Alf
           config.adapter = value
         end
 
-        @input_reader = :rash
-        readers = Reader.all.map{|r| r.first}
-        opt.on('--input-reader=READER', readers,
-               "Specify the kind of reader when reading on $stdin "\
+        readers = Reader.all.map{|r| r.first }
+        opt.on('--stdin=READER', readers,
+               "Specify the kind of reader when reading on standard input "\
                "(#{readers.join(',')})") do |value|
-          @input_reader = value.to_sym
+          config.stdin_reader = value.to_sym
         end
 
         opt.on("-Idirectory",
@@ -104,9 +56,7 @@ module Alf
         end
 
         opt.on_tail('-h', "--help", "Show help") do
-          install_load_path
-          install_requires
-          raise Quickl::Help
+          show_help("alf")
         end
 
         opt.on_tail('-v', "--version", "Show version") do
@@ -115,26 +65,17 @@ module Alf
         end
       end # Alf's options
 
-      def stdin_operand
-        @stdin_operand || Reader.send(@input_reader, $stdin)
-      end
-
       def connection
-        @connection ||= config.database.connection(viewpoint: config.viewpoint)
+        @connection ||= config.database.connection(viewpoint: build_viewpoint)
       end
 
       def execute(argv)
         install_load_path
         install_requires
 
-        # special case where a .alf file is provided
-        if argv.empty? or (argv.size == 1 && Path(argv.first).file?)
-          argv.unshift("exec")
-        end
-
         # compile the operator, render and returns it
-        compile(argv){ super }.tap do |op|
-          render(connection.compile(op)) if op && requester
+        super.tap do |op|
+          render(connection.relvar(op)) if op && requester
         end
       end
 
@@ -160,19 +101,20 @@ module Alf
         config
       end
 
-      def compile(argv)
-        if @execute
-          connection.query(argv.first)
-        else
-          op = yield
-          op = op.bind(connection) if op
-          op
-        end
+      def build_viewpoint
+        config = self.config
+        Module.new{
+          include Alf::Viewpoint
+          include config.viewpoint
+          def stdin
+            Algebra::Operand.coerce Reader.send(contextual_params[:reader], $stdin)
+          end
+        }[reader: config.stdin_reader]
       end
 
       def rendering_options
         options = { float_format: config.float_format }
-        if config.pretty? and (hl = highline)
+        if config.pretty? and (hl = highline) and (hl.output_cols)
           options[:pretty]  = config.pretty?
           options[:trim_at] = hl.output_cols - 1
         end