alf 0.9.0 → 0.9.1

data/README.md

@@ -1,38 +1,64 @@
-# Alf - Classy data-manipulation dressed in a DSL (+ commandline)
+# Alf - Relational Algebra at your fingertips (version 0.9.1)
+
+## Description
+
+### What & Why
+
+Alf brings the relational algebra both in Shell and in Ruby. In Shell, because 
+manipulating any relation-like data source should be as straightforward as a 
+one-liner. In Ruby, because I've never understood why programming languages 
+provide data structures like arrays, hashes, sets, trees and graphs but not 
+_relations_... Let's stop the segregation ;-)
+
+### Install
 
     % [sudo] gem install alf
     % alf --help
 
-## Links
+### Links
     
 * {http://rubydoc.info/github/blambeau/alf/master/frames} (read this file there!)
 * {http://github.com/blambeau/alf} (source code)
 * {http://revision-zero.org} (author's blog)
 
-## Description
+### Quick overview
 
 Alf is a commandline tool and Ruby library to manipulate data with all the power 
 of a truly relational algebra approach. Objectives behind Alf are manifold:
 
-* Pragmatically, Alf aims at being a useful commandline executable for 
-  manipulating csv files, database records, or whatever looks like a (physical
-  representation of a) relation. See 'alf --help' for the list of available 
-  commands and implemented relational operators.
+* Pragmatically, Alf aims at being a useful commandline executable for manipulating 
+  relational-like data: database records, csv files, or **whatever can be interpreted 
+  as (the physical encoding of) a relation**. See 'alf --help' for the list of 
+  available commands and implemented relational operators.
   
       % alf restrict suppliers -- "city == 'London'" | alf join cities 
   
 * Alf is also a 100% Ruby relational algebra implementation shipped with a simple 
   to use, powerful, functional DSL for compiling and evaluating relational queries. 
-  Alf is not limited to simple scalar values, but admit values of arbitrary 
+  Alf is not limited to simple scalar values, but admits values of arbitrary 
   complexity (under a few requirements about their implementation, see next 
   section). See 'alf --help' as well as .alf files in the examples directory 
   for syntactic examples.
   
-      Alf.lispy.compile{ 
+      Alf.lispy.evaluate { 
         (join (restrict :suppliers, lambda{ city == 'London' }), :cities)
       }
-
-* Alf is also an educational tool, that I've written to draw people's attention
+      
+  In addition to this functional syntax, Alf comes bundled with an in-memory 
+  Relation data structure that provides an object-oriented way of manipulating
+  relations in simplest cases:
+  
+      suppliers = Alf::Relation[
+        {: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'},     
+      ]
+      cities = ...
+      puts suppliers.restrict(lambda{ city == 'London' }).join(cities)    
+
+* Alf is also an educational tool, that I've written to draw people attention
   about the ill-known relational theory (and ill-represented by SQL). The tool
   is largely inspired from TUTORIAL D, the tutorial language of Chris Date and 
   Hugh Darwen in their books, more specifically in 
@@ -41,9 +67,9 @@ of a truly relational algebra approach. Objectives behind Alf are manifold:
   there (Alf is neither a relational _database_, nor a relational _language_). 
   I hope that people (especially talented developers) will be sufficiently 
   enticed by features shown here to open that book, read it more deeply, and 
-  implement new stuff around Date & Darwen vision. Have a look at the result of 
-  the following query for things that you'll never ever have in SQL (see also 
-  'alf help quota', 'alf help nest', 'alf help group', ...):
+  implement new stuff around Date & Darwen's vision. Have a look at the result of 
+  the following query for the kind of things that you'll never ever have in SQL 
+  (see also 'alf help quota', 'alf help wrap', 'alf help group', ...):
   
       % alf --text summarize supplies --by=sid -- total "sum(:qty)" -- which "group(:pid)"
   
@@ -74,7 +100,7 @@ Familiar? Skip. Otherwise, read on.
 ### The example database
 
 This README file shows a lot of examples built on top of the following suppliers 
-& parts database (almost identical to the original version in C.J. Date database 
+& parts database (almost identical to the original version in C. J. Date's database 
 books). By default, the alf command line is wired to this embedded example. All
 examples shown here should therefore work immediately, if you want to reproduce
 them!
@@ -103,7 +129,7 @@ them!
     +-------------------------------------+-------------------------------------------------+-------------------------+------------------------+
 
 Many people think that relational databases are necessary 'flat', that they are 
-necessarily limited to simply scalar values in two dimension tables. This is 
+necessarily limited to simple scalar values put in two dimension tables. This is 
 wrong; most SQL databases are indeed 'flat', but _relations_ (in the mathematical 
 sense of the relational theory) are not! Look, **the example above is a relation!**; 
 that 'contains' other relations as particular values, which, in turn, could 
@@ -115,15 +141,16 @@ that 'contains' other relations as particular values, which, in turn, could
 To understand what is a relation exactly, one needs to remember elementary 
 notions of set theory and the concepts of _type_ and _value_. 
 
-* A _type_ is a finite set of values; it is non particularly ordered and, being 
-a set, it does never contains two values which are considered equal.  
+* A _type_ is a finite set of values; it is not particularly ordered and, being 
+a set, it does never contain two values which are equal (any type is necessarily 
+accompanied with an equality operator, denoted here by '==').  
 
 * A _value_ is **immutable** (you cannot 'change' a value, in any way), has no 
 localization in time and space, and is always typed (that is, it is always 
 accompanied by some identification of the type it belongs to). 
  
 As you can see, _type_ and _value_ are not the same concepts as _class_ and 
-_object_, with which you are probably familiar with. Alf considers that the 
+_object_, which you are probably more familiar with. Alf considers that the 
 latter are _implementations_ of the former. Alf assumes _valid_ implementations
 (equality and hash methods must be correct) and _valid_ usage (objects used for
 representing values are kept immutable in practice). Alf _assumes_ this, but 
@@ -157,11 +184,11 @@ can have them inside relations!
   pairs. Moreover, it does not contain two attributes with the same name and is 
   **not particularly ordered**. Also, **a tuple is a _value_, and is therefore 
   immutable**. Last, but not least, a tuple **does not admit nulls/nils**. Tuples 
-  in Alf are simply implemented with ruby hashes, taken as tuples implementations. 
+  in Alf are simply implemented with ruby hashes, taken as tuple implementations. 
   Not all hashes are valid tuple implementations, of course (those containing nil
   are not, for example). Alf _assumes_ valid tuples, but does not _enforce_ this
   precondition. It's up to you to use Alf the right way! No support is or will 
-  ever be provided for ordering tuple attributes. Howeber, as hashes are ordered 
+  ever be provided for ordering tuple attributes. However, as hashes are ordered 
   in Ruby 1.9, Alf implements a best effort strategy to keep a friendly ordering 
   when rendering tuples and relations. This is a very good practical reason for 
   migrating to ruby 1.9 if not already done!
@@ -173,15 +200,18 @@ can have them inside relations!
   particularly ordered**. Moreover, all tuples of a relation must have the same
   _heading_, that is, the same set of attribute (name, type) pairs. Also, **a 
   relation is a _value_, is therefore immutable** and **does not admit null/nil**.
-  Alf being mainly an implementation of relational algebra (see section below) 
-  it loosely considers any Iterator of tuples as a potentially valid relation
-  implementation (see later). 
+  
+Alf is mainly an implementation of relational algebra (see section below). The
+implemented operators consider any Iterator of tuples as potentially valid 
+operand. In addition Alf provides a Relation ruby class, that acts as an 
+in-memory data structure that provides an Object-Oriented API to call operators
+(see "Interfacing Alf in Ruby" below).
 
 ### Relational Algebra
 
-In classical algebra, you can do computations like <code>(5 + 2) - 3</code>. In 
-relational algebra, you can do similar things on relations. Alf uses an infix, 
-functional programming-oriented syntax for algebra expressions: 
+In classical algebra, you can make computations like <code>(5 + 2) - 3</code>. 
+In relational algebra, you can make similar things on relations. Alf uses an 
+infix, functional programming-oriented syntax for algebra expressions: 
   
     (minus (union :suppliers, xxx), yyy)
     
@@ -201,28 +231,66 @@ you want! The same query, in shell:
 The Third Manifesto defines a series of prescriptions, proscriptions and very 
 strong suggestions for designing a truly relational _language_, called a _D_, 
 as an alternative to SQL for managing relational databases. This is far behind
-our objective with Alf, as we don't look at database aspects at all (persistence,
-transactions, and so on.) and don't actually define a programming language either 
-(only a small functional ruby DSL). 
+my objective with Alf, as it does not touch at database issues at all (persistence,
+transactions, and so on.) and don't actually define a programming language (only 
+a small functional ruby DSL). 
 
 Alf must simply be interpreted as a ruby library implementing (a variant of) 
-Date's and Darwen relational algebra. This library is designed as a set of operator 
+Date and Darwen's relational algebra. This library is designed as a set of operator 
 implementations, that work as tuple iterators taking other tuple iterators as 
 input. Under the pre-condition that you provide them _valid_ tuple iterators as 
 input (no duplicates, no nil, + other preconditions on an operator basis), the 
 result is a valid iterator as well. Unless explicitely stated otherwise, any
 behavior observed when not respecting these preconditions, even an interesting 
-behavior, is not guaranteed and can change with tiny version changes (see section
-about versioning policy at the end of this file).
+behavior, is not guaranteed and might change with tiny version changes (see 
+section about versioning policy at the end of this file).
+
+### The command line utility
+
+    #
+    # Provided that suppliers and cities are valid relation representations
+    # [something similar] 
+    #
+    % alf restrict suppliers -- "city == 'London'" | alf join cities
+
+    # the resulting stream is a valid relation representation in the output
+    # stream format that you have selected (.rash by default). It can therefore 
+    # be piped to another alf shell invocation, or saved to a file and re-read
+    # later (under the assumption that input and output data formats match, or 
+    # course). [Something similar about responsibility and bug].
 
-### In ruby
+If you take a look at .alf example files, you'll find functional ruby expressions 
+like the following (called Lispy expressions):
+
+    % cat examples/minus.alf
+
+    # Give all suppliers, except those living in Paris
+    (minus :suppliers, 
+           (restrict :suppliers, lambda{ city == 'Paris' }))
+    
+    # This is a contrived example for illustrating minus, as the
+    # following is equivalent
+    (restrict :suppliers, lambda{ city != 'Paris' })
+    
+You can simply execute such expressions with the alf command line itself (the 
+three following invocations return the same result):
+ 
+    % alf examples/minus.alf | alf show
+    % alf show minus
+    % alf -e "(restrict :suppliers, lambda{ city != 'Paris' })" | alf show
+
+Symbols are magically resolved from the environment, which is wired to the 
+examples by default. See the dedicated sections below to update this behavior
+to your needs.
+
+### The algebra compiler
 
     # 
     # Provided that :suppliers and :cities are valid relation representations
     # (under the responsibility shared by you and the Reader and Environment 
     # subclasses you use -- see later),  then, 
     # 
-    op = Alf.lispy.compile{ 
+    op = Alf.lispy.compile { 
       (join (restrict :suppliers, lambda{ city == 'London' }), :cities)
     }
     
@@ -231,19 +299,128 @@ about versioning policy at the end of this file).
     # of any other expression. This is under Alf's responsibility, and any 
     # failure must be considered a bug!
 
-### In shell
+### The Relation data structure
 
-    #
-    # Provided that suppliers and cities are valid relation representations
-    # [something similar] 
-    #
-    % alf restrict suppliers -- "city == 'London'" | alf join cities
+In addition, Alf is bundled with an in-memory Relation data structure that 
+provided a more abstract API for manipulating relations in simple cases (the 
+rules are the same about pre and post-conditions):
 
-    # the resulting stream is a valid relation representation in the output
-    # stream format that you have selected (.rash by default). It can therefore 
-    # be piped to another alf shell invocation, or saved to a file and re-read
-    # later (under the assumption that input and output data formats match, or 
-    # course). [Something similar about responsibility and bug].
+    # The query above can be done as follows. Note that relations are always
+    # loaded in memory here!
+    suppliers = Alf::Relation[ ... ]
+    cities    = Alf::Relation[ ... ]
+    suppliers.restrict(lambda{ city == 'London' }).
+              join(cities)
+    # => Alf::Relation[ ... ]
+
+All relational operators have an instance method equivalent on the Alf::Relation 
+class. Semantically, the receiver object is simply the first operand of the 
+functional call, as illustrated above.
+
+### Where do relations come from?
+
+Relation literals can simply be written as follows:
+
+    suppliers = Alf::Relation[
+      {: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'},     
+    ]
+    
+Environment classes serve datasets (see later) that always have a to_rel method
+for obtaining in-memory relations:
+
+    env = Alf::Environment.examples
+    env.dataset(:suppliers).to_rel
+    # => Alf::Relation[ ... ]
+
+Compiled expressions always have a to_rel method that allows obtaining an 
+in-memory relation:
+
+    op = Alf.lispy.compile { 
+      (join (restrict :suppliers, lambda{ city == 'London' }), :cities)
+    }
+    op.to_rel 
+    # => Alf::Relation[...]
+    
+Lispy provides an 'evaluate' method which is precisely equivalent to the chain
+above. Therefore:
+
+    rel = Alf.lispy.evaluate { 
+      (join (restrict :suppliers, lambda{ city == 'London' }), :cities)
+    }
+    # => Alf::Relation[...]
+
+### Algebra is closed under its operators!
+
+Of course, from the closure property of a relational algebra (that states that 
+operators works on relations and return relations), you can use a sub expression 
+*everytime* a relational operand is expected, everytime:
+
+    # Compute the total qty supplied in each country together with the subset 
+    # of products shipped there. Only consider suppliers that have a status
+    # greater than 10, however.
+    (summarize \
+      (join \
+        (join (restrict :suppliers, lambda{ status > 10 }), 
+              :supplies), 
+        :cities),
+      [:country],
+      :which => Agg::group(:pid),
+      :total => Agg::sum{ qty })
+
+Of course, complex queries quickly become unreadable that way. But you can always
+split complex tasks in more simple ones:
+
+    kept_suppliers = (restrict :suppliers, lambda{ status > 10 })
+    with_countries = (join kept_suppliers, :cities),
+    supplying      = (join with_countries, :supplies)
+    (summarize supplying,
+               [:country],
+               :which => Agg::group(:pid),
+               :total => Agg::sum{ qty })
+
+And here is the result !
+
+    +----------+----------+--------+
+    | :country | :which   | :total |
+    +----------+----------+--------+
+    | England  | +------+ |   2200 |
+    |          | | :pid | |        |
+    |          | +------+ |        |
+    |          | | P1   | |        |
+    |          | | P2   | |        |
+    |          | | P3   | |        |
+    |          | | P4   | |        |
+    |          | | P5   | |        |
+    |          | | P6   | |        |
+    |          | +------+ |        |
+    | France   | +------+ |    200 |
+    |          | | :pid | |        |
+    |          | +------+ |        |
+    |          | | P2   | |        |
+    |          | +------+ |        |
+    +----------+----------+--------+
+
+### Reference API
+
+For now, the Ruby API is documented in the commandline help itself (a cheatsheet
+or something will be provided as soon as possible). For example, you'll find the 
+allowed syntaxes for RESTRICT as follows:
+
+    % alf help restrict
+    
+    ...
+    API & EXAMPLE
+    
+      # Restrict to suppliers with status greater than 20
+      (restrict :suppliers, lambda{ status > 20 })
+    
+      # Restrict to suppliers that live in London
+      (restrict :suppliers, lambda{ city == 'London' })
+    ...
 
 ### Coping with non-relational data sources (nil, duplicates, etc.)
 
@@ -271,7 +448,7 @@ is null/nil, but it won't probably fail if any other attribute is nil.
 
 This best-effort strategy is not enough, and striclty speaking, must be considered 
 unsound (for example, it strongly hurts optimization possibilities). Therefore,
-we strongly encourage you to go a step further: **if relational operators want
+I strongly encourage you to go a step further: **if relational operators want
 true relations as input, please, give them!**. For this, Alf also provides a few
 non-relational operators in addition to relational ones. Those operators must be 
 interpreted as "pre-relational" operators, in the sense that they help obtaining 
@@ -281,13 +458,12 @@ You'll find,
 
 * <code>alf autonum</code>  -- ensure no duplicates by generating a unique attribute
 * <code>alf compact</code>  -- brute-force duplicates removal
-* <code>alf defaults</code> -- replace nulls/nil by valid values, on an attribute 
-                               basis
+* <code>alf defaults</code> -- replace nulls/nil by valid values, on an attribute basis
 
 Play the game, it's easy! 
 
 - _Give id, name and status of suppliers whose status is greater that 10_
-- Hey man, we don't know supplier's status for all of them! What about the others?
+- Hey man, we don't know the status for all suppliers! What about these cases?
 - _Ignore them_
 - No problem dude!
 
@@ -311,16 +487,16 @@ analyzing the whole query expression in the light of a catalog of typed
 operators. This way, a tool can check that a query is statically valid, i.e. 
 that it respects operator preconditions. While this approach has the major 
 advantage of allowing strong optimizations, it also has a few drawbacks (as 
-knowing the heading of used datasources in advance) and is difficult to mary 
-with dynamically-typed languages like Ruby. Therefore, Alf takes another approach, 
-which is similar to duck-typing. In essence, this approach can be summarized as 
-follows:
+the need to know the heading of used datasources in advance) and is difficult to 
+mary with dynamically-typed languages like Ruby. Therefore, Alf takes another 
+approach, which is similar to duck-typing. In essence, this approach can be 
+summarized as follows:
 
-- _You have the responsibility of ensuring that the evaluation of your query 
-  will succeed and will return valid results_
+- _You have the responsibility of not violating operators' preconditions. If you
+  do, Alf has the responsibility of returning correct results._.
 - No problem dude!
 
-## Getting started in shell
+## More about the shell command line
 
     % alf --help
 
@@ -440,104 +616,7 @@ Also, mimicing the ruby executable, the following invocation is also possible:
 where the argument is a relational expression in Alf's Lispy dialect, which
 is detailed in the next section.
 
-## Lispy expressions
-
-If you take a look at .alf example files, you'll find functional ruby expressions
-like the following:
-
-    % cat examples/minus.alf
-
-    # Give all suppliers, except those living in Paris
-    (minus :suppliers, 
-           (restrict :suppliers, lambda{ city == 'Paris' }))
-    
-    # This is a contrived example for illustrating minus, as the
-    # following is equivalent
-    (restrict :suppliers, lambda{ city != 'Paris' })
-    
-You can simply execute such expressions with the alf command line itself (the 
-three following invocations return the same result):
- 
-    % alf examples/minus.alf | alf show
-    % alf show minus
-    % alf -e "(restrict :suppliers, lambda{ city != 'Paris' })" | alf show
-
-Symbols are magically resolved from the environment, which is wired to the 
-examples by default. See the dedicated sections below to update this behavior
-to your needs.
-
-### Algebra is closed under its operators!
-
-Of course, from the closure property of a relational algebra (that states that 
-operators works on relations and return relations), you can use a sub expression 
-*everytime* a relational operand is expected, everytime:
-
-    # Compute the total qty supplied in each country together with the subset 
-    # of products shipped there. Only consider suppliers that have a status
-    # greater than 10, however.
-    (summarize \
-      (join \
-        (join (restrict :suppliers, lambda{ status > 10 }), 
-              :supplies), 
-        :cities),
-      [:country],
-      :which => Agg::group(:pid),
-      :total => Agg::sum{ qty })
-
-Of course, complex queries quickly become unreadable that way. But you can always
-split complex tasks in more simple ones using _with_:
-
-    with( :kept_suppliers => (restrict :suppliers, lambda{ status > 10 }),
-          :with_countries => (join :kept_suppliers, :cities),
-          :supplying      => (join :with_countries, :supplies) ) do
-      (summarize :supplying,
-                 [:country],
-                 :which => Agg::group(:pid),
-                 :total => Agg::sum{ qty })
-    end
-
-And here is the result !
-
-    +----------+----------+--------+
-    | :country | :which   | :total |
-    +----------+----------+--------+
-    | England  | +------+ |   2200 |
-    |          | | :pid | |        |
-    |          | +------+ |        |
-    |          | | P1   | |        |
-    |          | | P2   | |        |
-    |          | | P3   | |        |
-    |          | | P4   | |        |
-    |          | | P5   | |        |
-    |          | | P6   | |        |
-    |          | +------+ |        |
-    | France   | +------+ |    200 |
-    |          | | :pid | |        |
-    |          | +------+ |        |
-    |          | | P2   | |        |
-    |          | +------+ |        |
-    +----------+----------+--------+
-
-
-### Going further
-
-For now, the Ruby API is documented in the commandline help itself (a cheatsheet
-or something will be provided as soon as possible). For example, you'll find the 
-allowed syntaxes for RESTRICT as follows:
-
-    % alf help restrict
-    
-    ...
-    API & EXAMPLE
-    
-      # Restrict to suppliers with status greater than 20
-      (restrict :suppliers, lambda{ status > 20 })
-    
-      # Restrict to suppliers that live in London
-      (restrict :suppliers, lambda{ city == 'London' })
-    ...
-
-## Interfacing Alf in Ruby
+## More about Alf in Ruby
 
 ### Calling commands 'ala' shell
 
@@ -560,11 +639,10 @@ If this kind of API is not sufficiently expressive for you, you'll have to learn
 the APIs deeper, and use the Lispy functional style that Alf provides, which can
 be compiled and used as explained in the next section.
 
-### Compiling lispy expressions
+### Compiler vs. Relation data structure
 
-If you want to use Alf in ruby directly (that is, not in shell or by executing
-.alf files), you can simply compile expressions and use resulting operators as 
-follows:
+The compilers allow you to manipulate algebra expressions. Just obtain a Lispy
+instance on an environment and you're ready:
 
     # 
     # Expressions can simply be compiled as illustrated below. We use the 
@@ -572,29 +650,37 @@ follows:
     # available environments. 
     #
     lispy = Alf.lispy(Alf::Environment.examples)
-    op = lispy.compile do
+    london_suppliers = lispy.compile do
       (restrict :suppliers, lambda{ city == 'London' })
     end
 
     #
-    # Returned _op_ is an enumerable of ruby hashes. Provided that datasets
+    # Returned operator is an enumerable of ruby hashes. Provided that datasets
     # offered by the environment (:suppliers here) can be enumerated more than 
     # once, the operator may be used multiple times and is even thread safe!
     #  
-    op.each do |tuple|
+    london_suppliers.each do |tuple|
       # tuple is a ruby Hash
     end
 
     #
     # Now, maybe you want to reuse op in a larger query, for example 
-    # by projecting on the city attribute... Here is how with expressions
-    # can be handled in that case
+    # by projecting on the city attribute... Here is how this can be
+    # done:
     #
-    projection = lispy.with(:kept_suppliers => op) do
-      (project :kept_suppliers, [:city])
-    end
+    projection = (project london_suppliers, [:city])
+
+Note that the examples above manipulate algebra operators, not relations per se.
+This means that equality and other such operators, that operate on relation 
+_values_, do not operate correctly here:
+
+    projection == Alf::Relation[{:city => 'London'}] 
+    # => nil
+    
+In contrast, you can use such operators when operating on true relation values:
 
-## Going further
+    projection.to_rel == Alf::Relation[{:city => 'London'}] 
+    # => true
 
 ### Using/Implementing other Environments
 
@@ -681,7 +767,7 @@ following template for contributions in lib/alf/renderer
 
 ## Related Work & Tools
 
-- You should certainly have a look at the Third Manifesto website: http://www.thethirdmanifesto.com/
+- You should certainly have a look at the Third Manifesto website: {http://www.thethirdmanifesto.com/}
 - Why not reading the {http://www.dcs.warwick.ac.uk/~hugh/TTM/DBE-Chapter01.pdf 
   third manifesto paper} itself? 
 - Also have a look at {http://www.dcs.warwick.ac.uk/~hugh/TTM/Projects.html other 
@@ -713,8 +799,8 @@ your needs and I'll see what I can do!
 ### Internals -- Tribute to Sinatra
 
 Alf's code style is very inspired from what I've found in Sinatra when looking 
-at its internals a few month ago. Alf, as Sinatra, is mostly implemented in a 
-single file, lib/alf.rb. Everything is there except additional contributions 
+at its internals a few months ago. Alf, as Sinatra, is mostly implemented in a 
+single file, lib/alf.rb. Everything is there except specific third-party contributions 
 (in lib/alf/...). You'll need an editor or IDE that supports code folding/unfolding. 
 Then, follow the guide:
 

data/TODO.md

@@ -4,17 +4,17 @@
         (rename :suppliers, [:name, :city], :suffix => "_sup")
         (rename :suppliers, [:name, :city], lambda{|name| name.upcase}) 
 
-* NEST: provide a multi-nesting ability?
+* WRAP: provide a multi-wraping ability?
 
-        (nest (nest :supplies, [:a, :b], :x), [:x, :c], :y)
-         => (nest :supplies, :x => [:a, :b], :y => [:x, :c])
+        (wrap (wrap :supplies, [:a, :b], :x), [:x, :c], :y)
+         => (wrap :supplies, :x => [:a, :b], :y => [:x, :c])
 
     But this would only work with Ruby 1.9 as the hash order would be important
     as such
 
 * GROUP: provide a multi-grouping ability?
 
-    Similar to nest, with same limitation.
+    Similar to wrap, with same limitation.
   
 * Add PIVOT and UNPIVOT operators
 

data/alf.gemspec

@@ -21,13 +21,13 @@ Gem::Specification.new do |s|
   # A short summary of this gem
   #
   # This is displayed in `gem list -d`.
-  s.summary = "Classy data-manipulation dressed in a DSL (+ commandline)"
+  s.summary = "Relational Algebra at your fingertips"
 
   # A long description of this gem (required)
   #
   # The description should be more detailed than the summary.  For example,
   # you might wish to copy the entire README into the description.
-  s.description = "Alf is a commandline tool and Ruby library to manipulate data with all the \npower of a truly relational algebra approach. "
+  s.description = "Alf brings the relational algebra both in Shell and in Ruby. In Shell, because \nmanipulating any relation-like data source should be as straightforward as a \none-liner. In Ruby, because I've never understood why programming languages \nprovide data structures like arrays, hashes, sets, trees and graphs but not \n_relations_... Let's stop the segregation ;-)"
   
   # The URL of this gem home page (optional)
   s.homepage = "http://rubydoc.info/github/blambeau/alf/master/frames"
@@ -123,7 +123,7 @@ Gem::Specification.new do |s|
   # One call to add_development_dependency('gem_name', 'gem version requirement')
   # for each development dependency. These gems are required for developers
   #
-  s.add_development_dependency("rake", "~> 0.8.7")
+  s.add_development_dependency("rake", "~> 0.9.2")
   s.add_development_dependency("bundler", "~> 1.0")
   s.add_development_dependency("rspec", "~> 2.6.0")
   s.add_development_dependency("yard", "~> 0.7.2")