added primitive update functionality

1 files changed, 60 insertions, 1 deletions

diff --git a/README b/README
index 9e1efa331f..2b661bfebb 100644
--- a/README
+++ b/README
@@ -1 +1,60 @@
-ActiveRelation is a Relational Algebra for Ruby. It simplifies both the simplest and the most complex of SQL queries and it transparently adapts to various RDBMS systems. It is intended to be a framework framework; that is, you can build your own ORM with it, focusing on what makes your ORM different. It can also be used for in-memory relational modeling and querying, independent of a database.
\ No newline at end of file
+== Abstract ==
+
+ActiveRelation is a Relational Algebra for Ruby. It simplifies the generation of both the simplest and the most complex of SQL queries and it transparently adapts to various RDBMS systems. It is intended to be a framework framework; that is, you can build your own ORM with it, focusing on innovative object and collection modeling as opposed to database compatibility and query generation.
+
+== A Gentle Introduction ==
+
+Generating a query with ARel is simple. For example, in order to produce
+
+    SELECT * FROM users
+   
+you construct a table relation and convert it to sql:
+
+    ActiveRelation::Table.new(:users).to_sql
+   
+In fact, you will probably never call `#to_sql` directly. Let `users = ActiveRelation::Table.new(:users)`. You can iterate through all rows in the `users` table like this:
+
+    users.each { |user| ... }
+    
+In other words, Arel relations behave similar regular Ruby collections. Let's have a look at a concrete example:
+
+    users.first # => {'id' => 10, 'name' => 'bob'}
+    
+As you can see, Arel converts the rows into a hash, the values of which are the appropriate Ruby primitive (integers, strings, and so forth).
+
+== Relational Algebra ==
+
+Arel is based on the Relational Algebra, a mathematical model that is also the inspiration for relational databases. ActiveRelation::Relation objects do not represent queries per se (i.e., they are not object-representations of `SELECT`, `INSERT`, `UPDATE`, or `DELETE`), rather they represent a collection of data that you can select from, insert into, update, and delete.For example, to insert a row into the users table, do the following:
+
+    users.insert({'id' => 11, 'name' => 'amy'})
+    
+To delete all users:
+
+    users.delete
+    
+To update:
+
+    users.update({'name' => 'carl'})
+    
+As you can see, the `relation` users does not represent an individual query; rather it is an abstraction on a collection of data and it can produce appropriate queries to do the various CRUD operations.
+
+=== More Sophisticated Queries ===
+
+Following the Relational Algebra, Arel's interface uses some jargon that differs from standard SQL. For example, in order to add a `WHERE` clause to your relations, you use the `select` operation:
+
+    users.select(users[:name].equals('amy')) # => SELECT * FROM users WHERE users.name = 'amy'
+
+What would, in SQL, be part of the `SELECT` clause is called here a `projection`:
+
+    users.project(users[:id]) # => SELECT users.id FROM users
+
+The best property of the Relational is compositionality, or closure under all operations. For example, to combine the two previous queries:
+
+    users                                 \
+      .select(users[:name].equals('amy')) \
+      .project(users[:id])
+    # => SELECT users.id FROM users WHERE users.name = 'amy'
+
+== Contributions ==
+
+I appreciate all contributions to ActiveRelation. There is only one "unusual" requirement I have concerning code style: all specs should be written without mocks, using concrete examples to elicit testable behavior. This has two benefits: it 1) ensures the tests serve as concrete documentation and 2) suits the functional nature of this library, which emphasizes algebraic transformation rather than decoupled components.
\ No newline at end of file