alf-shell 0.13.0 → 0.13.1

data/CHANGELOG.md

@@ -1,3 +1,7 @@
+# 0.13.1 / 2013-07-29
+
+* Embed the documentation so as to --help to work.
+
 # 0.13.0 / 2013-07-29
 
 The 0.13.0 version is a new birthday for alf. See `alf` main for CHANGELOG

data/Manifest.txt

@@ -4,6 +4,7 @@ CHANGELOG.md
 Gemfile
 Gemfile.lock
 bin/**/*
+doc/**/*
 lib/**/*
 LICENCE.md
 Manifest.txt

data/doc/commands/exec.md

@@ -0,0 +1,16 @@
+
+Executes an .alf file on current database
+
+SYNOPSIS
+
+    alf #(command_name) [FILE]
+
+OPTIONS
+
+    #(summarized_options)
+
+DESCRIPTION
+
+This command executes the .alf file passed as first argument (or what comes
+on standard input) as a alf query to be executed on the current database.
+

data/doc/commands/help.md

@@ -0,0 +1,11 @@
+
+Show help about a specific command
+
+SYNOPSIS
+
+    alf #(command_name) COMMAND
+
+OPTIONS
+
+    #(summarized_options)
+

data/doc/commands/main.md

@@ -0,0 +1,33 @@
+
+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
+
+    #(summarized_options)
+
+RELATIONAL OPERATORS
+
+    #(summarized_subcommands relational_operators)
+
+EXPERIMENTAL RELATIONAL OPERATORS
+
+    #(summarized_subcommands experimental_operators)
+
+NON-RELATIONAL OPERATORS
+
+    #(summarized_subcommands non_relational_operators)
+
+OTHER NON-RELATIONAL COMMANDS
+
+    #(summarized_subcommands other_non_relational_commands)
+
+See 'alf help COMMAND' for details about a specific command.
+

data/doc/commands/show.md

@@ -0,0 +1,19 @@
+
+Output input tuples through a specific renderer (text, yaml, ...)
+
+SYNOPSIS
+
+    alf #(command_name) NAME -- [ORDERING]
+
+OPTIONS
+
+    #(summarized_options)
+
+DESCRIPTION
+
+When a name is specified as commandline arg, request the database to
+provide the corresponding relation variable and prints its value.
+Otherwise, take what comes on standard input.
+
+Note that this command is not an operator and should not be piped
+anymore.

data/doc/operators/non_relational/autonum.md

@@ -0,0 +1,23 @@
+
+Extend its operand with an unique autonumber attribute
+
+SYNOPSIS
+
+    #(signature)
+
+DESCRIPTION
+
+This non-relational operator guarantees uniqueness of output tuples by adding 
+an attribute called AS whose value is an auto-numbered Integer. 
+
+If the presence of duplicates was the only "non-relational" aspect of the input, 
+the result is a valid relation for which AS is a candidate key.
+
+EXAMPLE
+
+    # Autonumber suppliers with default attribute name
+    !(alf autonum suppliers)
+
+    # Autonumber suppliers with a `unique_id` attribute
+    !(alf autonum suppliers -- unique_id)
+

data/doc/operators/non_relational/clip.md

@@ -0,0 +1,31 @@
+
+Clip input tuples to a subset of attributes
+
+SYNOPSIS
+
+    #(signature)
+
+OPTIONS
+
+    #(summarized_options)
+
+DESCRIPTION
+
+This operator clips tuples on attributes whose names are specified in 
+ATTRIBUTES. This is similar to the relational PROJECT operator, expect 
+that CLIP does not remove duplicates afterwards.
+
+Clipping may therefore lead to bags of tuples instead of sets. The result
+is therefore **not** a valid relation unless a candidate key is preserved.
+
+With the allbut option, the operator keeps attributes in ATTRIBUTES, instead 
+of projecting them away. 
+
+EXAMPLE
+
+    # Clip suppliers on `name` and `city`
+    !(alf clip suppliers -- name city)
+
+    # Clip suppliers on all other attributes
+    !(alf clip suppliers --allbut -- name city)
+

data/doc/operators/non_relational/coerce.md

@@ -0,0 +1,15 @@
+
+Force attribute coercion according to a heading
+
+SYNOPSIS
+
+    #(signature)
+
+DESCRIPTION
+
+This operator coerces attributes of the input tuples according to HEADING.
+
+EXAMPLE
+
+  alf coerce parts -- weight Float color Color
+

data/doc/operators/non_relational/compact.md

@@ -0,0 +1,20 @@
+
+Remove tuple duplicates
+
+SYNOPSIS
+
+    #(signature)
+
+DESCRIPTION
+
+This non-relational operator removes duplicates from its input operand.
+In other words, it converts a bag of tuples to a set of tuples in a 
+brute-force manner.
+
+If the presence of duplicates was the only "non-relational" aspect of 
+the operand, the result is a valid relation.
+
+EXAMPLE
+
+  alf compact suppliers
+

data/doc/operators/non_relational/defaults.md

@@ -0,0 +1,32 @@
+
+Force default values on missing/nil attributes
+
+SYNOPSIS
+
+    #(signature)
+
+OPTIONS
+
+    #(summarized_options)
+
+DESCRIPTION
+
+This non-relational operator rewrites input tuples to ensure that all values 
+for attribute names specified in DEFAULTS are present and not nil. Missing or 
+nil attributes are replaced by the specified default value.
+
+A value specified in DEFAULTS may be any tuple expression. This allows computing 
+the default value as an expression on the current tuple.
+
+With the strict option, the operator projects resulting tuples on attributes for 
+which a default value has been specified. Using the strict mode guarantees that 
+the heading of all tuples is the same, and that no nil value ever remains. 
+
+Note that this operator never removes duplicates. Even in strict mode the result 
+might be an invalid relation. 
+
+EXAMPLE
+
+  alf defaults suppliers -- country "'Belgium'"
+  alf defaults --strict suppliers -- country "'Belgium'"
+

data/doc/operators/non_relational/generator.md

@@ -0,0 +1,20 @@
+
+Generate a relation with an auto-numbered attribute
+
+SYNOPSIS
+
+    #(signature)
+
+DESCRIPTION
+
+This non-relational operator generates a relation of one attribute called AS, 
+whose value is an auto-number ranging from 1 to SIZE, inclusively.
+
+EXAMPLE
+
+    # Default behavior: AS is `num` and SIZE is 10
+    !(alf generator)
+
+    # That you can override
+    !(alf generator -- 5 -- id)
+

data/doc/operators/non_relational/sort.md

@@ -0,0 +1,24 @@
+
+Sort input tuples according to an order relation
+
+SYNOPSIS
+
+    #(signature)
+
+DESCRIPTION
+
+This non-relational operator sorts input tuples according to ORDERING. 
+
+This is, of course, a non relational operator as relations are unordered 
+sets. It is provided for displaying purposes and normalization of 
+non-relational inputs.
+
+EXAMPLE
+
+  # Sort suppliers by name
+  !(alf sort suppliers -- name asc)
+
+  # Sort suppliers by city in descending order, then on name on ascending 
+  # order
+  !(alf sort suppliers -- city desc name asc)
+

data/doc/operators/non_relational/type-safe.md

@@ -0,0 +1,20 @@
+
+Check that input tuples are of a specified heading
+
+SYNOPSIS
+
+    #(signature)
+
+DESCRIPTION
+
+This non-relational ensures that input tuples match a given heading (in strict mode),
+or a projection (in non-strict mode). This is useful when connecting to data-sources whose
+relation representations must absolutely be checked for type safety.
+
+EXAMPLE
+
+  # Check that the suppliers have the correct heading (since is missing, but ok)
+  !(alf type-safe suppliers -- sid String name String status Integer city String since Date)
+
+  # Strict, no attribute can be missing
+  !(alf type-safe --strict suppliers -- sid String name String status Integer city String)

data/doc/operators/relational/extend.md

@@ -0,0 +1,18 @@
+
+Relational extension (additional, computed attributes)
+
+SYNOPSIS
+
+    #(signature)
+
+DESCRIPTION
+
+This operator extends its operand with new attributes whose value is the result 
+of evaluating tuple expressions specified in EXT. The latter are specified as 
+(name, expression) pairs.
+
+EXAMPLE
+
+    # Compute a few attributes on suppliers by extension
+    !(alf extend supplies -- big "qty > 100"  price "qty * 12.2")
+

data/doc/operators/relational/group.md

@@ -0,0 +1,27 @@
+
+Relational grouping (relation-valued attributes)
+
+SYNOPSIS
+
+    #(signature)
+
+OPTIONS
+
+    #(summarized_options)
+
+DESCRIPTION
+
+This operator groups attributes in ATTRIBUTES as a new, relation-valued 
+attribute named AS.
+
+With the allbut option, it groups all attributes not specified in ATTRIBUTES
+instead.
+
+EXAMPLE
+
+    # Group pid and qty as a relation-valued attribute names supplying
+    !(alf group supplies -- pid qty -- supplying)
+
+    # Group all but pid ...
+    !(alf group supplies --allbut -- pid -- supplying)
+

data/doc/operators/relational/infer-heading.md

@@ -0,0 +1,20 @@
+
+Relational heading inference (print the relation type)
+
+SYNOPSIS
+
+    #(signature)
+
+DESCRIPTION
+
+This operator simply outputs a relation containing one tuple: the heading of 
+its operand. 
+
+EXAMPLE
+
+    # What is the heading of the `suppliers` relation?
+    !(alf infer-heading suppliers)
+
+    # What is the heading of the following join?
+    !(alf join suppliers supplies | alf infer-heading)
+

data/doc/operators/relational/intersect.md

@@ -0,0 +1,13 @@
+
+Relational intersection (aka a logical and)
+
+SYNOPSIS
+
+    #(signature)
+
+DESCRIPTION
+
+This operator computes the relational intersection of its operands. Such
+intersection is simply the set of tuples that appear both in LEFT and in 
+RIGHT.
+

data/doc/operators/relational/join.md

@@ -0,0 +1,28 @@
+
+Relational join (and cartesian product)
+
+SYNOPSIS
+
+    #(signature)
+
+DESCRIPTION
+
+This operator computes the (natural) join of its operands. 
+
+Natural join means that, unlike what is commonly used in SQL, joining is based 
+on equality of all attributes that are shared between LEFT and RIGHT performed 
+on common attribute names. You can use the `rename` operator if this  behavior 
+does not fit your needs.
+
+When operands have no attribute in common, this operator naturally "degenerates" 
+to a cartesian product.
+
+EXAMPLE
+
+    # Computes natural join of suppliers and supplies (on sid, the only 
+    # attribute they have in common)
+    !(alf join suppliers supplies)
+
+    # The following example demontrates the cartesian product with a generated 
+    # relation
+    !(alf generator -- 3 -- num | alf join cities)

data/doc/operators/relational/matching.md

@@ -0,0 +1,24 @@
+
+Relational matching (join + project back on left)
+
+SYNOPSIS
+
+    #(signature)
+
+DESCRIPTION
+
+This operator restricts its LEFT operand to tuples for which there exists at 
+least one tuple in RIGHT that (naturally) joins. This is a shortcut operator 
+for the following longer expression:
+
+    (project (join xxx, yyy), [xxx's attributes])
+
+Or equivalently,
+
+    (join xxx, (project xxx, [common attributes]))
+
+EXAMPLE
+
+    # Which suppliers supply at least one part?
+    !(alf matching suppliers supplies)
+

data/doc/operators/relational/minus.md

@@ -0,0 +1,12 @@
+
+Relational minus (aka difference)
+
+SYNOPSIS
+
+    #(signature)
+
+DESCRIPTION
+
+This operator computes the difference between its two operands. The 
+difference is simply the set of LEFT tuples non present in RIGHT.
+

data/doc/operators/relational/not-matching.md

@@ -0,0 +1,20 @@
+
+Relational not matching (inverse of matching)
+
+SYNOPSIS
+
+    #(signature)
+
+DESCRIPTION
+
+This operator restricts LEFT tuples to those for which there does not 
+exist any tuple in RIGHT that (naturally) joins. This is a shortcut 
+operator for the following longer expression: 
+
+    (minus xxx, (matching xxx, yyy))
+
+EXAMPLE
+
+    # Which suppliers do not supply any part?
+    !(alf not-matching suppliers supplies)
+

data/doc/operators/relational/project.md

@@ -0,0 +1,28 @@
+
+Relational projection (clip + compact)
+
+SYNOPSIS
+
+    #(signature)
+
+OPTIONS
+
+    #(summarized_options)
+
+DESCRIPTION
+
+This operator projects tuples on attributes whose names are specified in 
+ATTRIBUTES. Unlike SQL, this operator **always** removes duplicates in the
+result so that the output is a set of tuples, that is, a relation.
+
+With the allbut option, the operator projects ATTRIBUTES away instead of 
+keeping them. 
+
+EXAMPLE
+
+    # What are supplier cities ?
+    !(alf project suppliers -- city)
+
+    # What are all but supplier's id and name
+    !(alf project --allbut suppliers -- sid name)
+

data/doc/operators/relational/quota.md

@@ -0,0 +1,21 @@
+
+Generalized quota-queries (position, sum progression, etc.)
+
+SYNOPSIS
+
+    #(signature)
+
+DESCRIPTION
+
+**This operator is a work in progress and should be used with care.**
+
+This operator is an attempt to generalize RANK in two directions:
+
+* Use a full SUMMARIZATION instead of hard-coding a ranking attribute via count()
+* Providing a BY key so that summarizations can actually be done on sub-groups
+
+EXAMPLE
+
+    # Compute linear progression of quantities by supplier number
+    !(alf quota supplies -- sid -- qty -- position count  sum_qty "sum{ qty }")
+

data/doc/operators/relational/rank.md

@@ -0,0 +1,27 @@
+
+Relational ranking (explicit tuple positions)
+
+SYNOPSIS
+
+    #(signature)
+
+DESCRIPTION
+
+This operator computes the ranking of input tuples, according to ORDER. 
+
+Precisely, it extends its operand with an attribute called AS whose value 
+is the number of tuples which are considered strictly less according to the
+order relation denoted by ORDER.
+
+Note that, unless the ordering includes a candidate key for the input relation, 
+the new AS attribute is not necessarily a candidate key for the output. 
+
+EXAMPLE
+
+    # Rank parts by weight 
+    !(alf rank parts -- weight -- position)
+
+    # Rank parts by weight in descending order. Ensure that position is a 
+    # candidate key by including a key in ordering
+    !(alf rank parts -- weight desc pid asc -- position)
+

data/doc/operators/relational/rename.md

@@ -0,0 +1,17 @@
+
+Relational renaming (rename some attributes)
+
+SYNOPSIS
+
+    #(signature)
+
+DESCRIPTION
+
+This command renames attributes as specified in RENAMING, taken as successive 
+(old name, new name) pairs
+
+EXAMPLE
+
+    # Rename a few supplier attributes
+    !(alf rename suppliers -- name supplier_name  city supplier_city)
+

data/doc/operators/relational/restrict.md

@@ -0,0 +1,25 @@
+
+Relational restriction (aka where, predicate filtering)
+
+SYNOPSIS
+
+    #(signature)
+
+DESCRIPTION
+
+This command restricts restricts relations to those tuples for which PREDICATE 
+evaluates to true.
+
+PREDICATE must be a valid tuple expression that returns a truth-value. It 
+may be specified as a ruby code literal, or a mapping between (name, value) 
+pairs. In the latter case, PREDICATE is built as a conjunction of attribute 
+equalities.
+
+EXAMPLE
+
+    # Who are suppliers with a status greater than 20?
+    !(alf restrict suppliers -- "status > 20")
+
+    # Which suppliers live in London?
+    !(alf restrict suppliers -- city "'London'")
+

data/doc/operators/relational/summarize.md

@@ -0,0 +1,25 @@
+
+Relational summarization (group-by + aggregate ops)
+
+SYNOPSIS
+
+    #(signature)
+
+OPTIONS
+
+    #(summarized_options)
+
+DESCRIPTION
+
+This operator summarizes input tuples over a projection given by BY. 
+SUMMARIZATION is a mapping between attribute names and summarizing 
+expressions.
+
+With the allbut option, the operator uses all attributes not specified 
+in BY as the projection key.
+
+EXAMPLE
+
+    # Compute the sum of supplied quantities, by supplier id
+    !(alf summarize supplies -- sid -- total_qty "sum{ qty }")
+

data/doc/operators/relational/ungroup.md

@@ -0,0 +1,20 @@
+
+Relational un-grouping (inverse of group)
+
+SYNOPSIS
+
+    #(signature)
+
+DESCRIPTION
+
+This operator flattens its operand by ungrouping the relation-valued 
+attribute ATTR. 
+
+EXAMPLE
+
+    # Given `pid` and `qty` groupped as `supplying`
+    !(alf group supplies -- pid qty -- supplying)
+
+    # Let's ungroup them
+    !(alf group supplies -- pid qty -- supplying | alf ungroup -- supplying)
+

data/doc/operators/relational/union.md

@@ -0,0 +1,14 @@
+
+Relational union
+
+SYNOPSIS
+
+    #(signature)
+
+DESCRIPTION
+
+This operator computes the union of its operands, that is the set of 
+tuples that appear in LEFT or in RIGHT. 
+
+The result is a valid relation in that it never contains duplicates.
+

data/doc/operators/relational/unwrap.md

@@ -0,0 +1,20 @@
+
+Relational un-wrapping (inverse of wrap)
+
+SYNOPSIS
+
+    #(signature)
+
+DESCRIPTION
+
+This operator flattens its operand by unwrapping the tuple-valued 
+attribute ATTR.
+
+EXAMPLE
+
+    # Given, `city` and `status` wrapped as `loc_and_status` 
+    !(alf wrap suppliers -- city status -- loc_and_status)
+
+    # Let's unwrap them
+    !(alf wrap suppliers -- city status -- loc_and_status | alf unwrap -- loc_and_status)
+

data/doc/operators/relational/wrap.md

@@ -0,0 +1,24 @@
+
+Relational wrapping (tuple-valued attributes)
+
+SYNOPSIS
+
+    #(signature)
+
+OPTIONS
+
+    #(summarized_options)
+
+DESCRIPTION
+
+This operator wraps attributes in ATTRIBUTES as a new, tuple-valued attribute 
+named AS.
+
+With the allbut option, it wraps all attributes not specified in ATTRIBUTES 
+instead.
+
+EXAMPLE
+
+    # Wrap `city` and `status` and a tuple-value attribute named `loc_and_status` 
+    !(alf wrap suppliers -- city status -- loc_and_status)
+

data/lib/alf/shell/version.rb

@@ -4,7 +4,7 @@ module Alf
 
       MAJOR = 0
       MINOR = 13
-      TINY  = 0
+      TINY  = 1
 
       def self.to_s
         [ MAJOR, MINOR, TINY ].join('.')

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: alf-shell
 version: !ruby/object:Gem::Version
-  version: 0.13.0
+  version: 0.13.1
   prerelease: 
 platform: ruby
 authors:
@@ -103,6 +103,36 @@ files:
 - Gemfile
 - Gemfile.lock
 - bin/alf
+- doc/commands/exec.md
+- doc/commands/help.md
+- doc/commands/main.md
+- doc/commands/show.md
+- doc/operators/non_relational/autonum.md
+- doc/operators/non_relational/clip.md
+- doc/operators/non_relational/coerce.md
+- doc/operators/non_relational/compact.md
+- doc/operators/non_relational/defaults.md
+- doc/operators/non_relational/generator.md
+- doc/operators/non_relational/sort.md
+- doc/operators/non_relational/type-safe.md
+- doc/operators/relational/extend.md
+- doc/operators/relational/group.md
+- doc/operators/relational/infer-heading.md
+- doc/operators/relational/intersect.md
+- doc/operators/relational/join.md
+- doc/operators/relational/matching.md
+- doc/operators/relational/minus.md
+- doc/operators/relational/not-matching.md
+- doc/operators/relational/project.md
+- doc/operators/relational/quota.md
+- doc/operators/relational/rank.md
+- doc/operators/relational/rename.md
+- doc/operators/relational/restrict.md
+- doc/operators/relational/summarize.md
+- doc/operators/relational/ungroup.md
+- doc/operators/relational/union.md
+- doc/operators/relational/unwrap.md
+- doc/operators/relational/wrap.md
 - lib/alf/shell/command/exec.rb
 - lib/alf/shell/command/help.rb
 - lib/alf/shell/command/main.rb
@@ -301,7 +331,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: -1701275740849508639
+      hash: 1359397490184999599
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements: