From 05c56d82630bc837bc3d68b8f47cb0852fb5b4a0 Mon Sep 17 00:00:00 2001
From: Orlando Vazquez <ovazquez@gmail.com>
Date: Wed, 17 Mar 2010 01:29:31 -0700
Subject: [PATCH] update README

---
 README | 90 ++++++++++++++++++++++++++++++++++++++++++++++++++++------
 1 file changed, 81 insertions(+), 9 deletions(-)

diff --git a/README b/README
index a6c800e..e1b1b3a 100644
--- a/README
+++ b/README
@@ -1,13 +1,85 @@
-SQLite3 bindings for Node.js
-=============================
+NAME
+----
 
-Documentation lives at http://grumdrig.com/node-sqlite/
-The code lives at http://github.com/grumdrig/node-sqlite/
+node-sqlite - Asynchronous SQLite3 driver for Node.js
 
-The two files required to use these bindings are sqlite.js and
-build/default/sqlite3_bindings.node. Put this directory in your
-NODE_PATH or copy those two files where you need them.
+SYNOPSIS
+--------
 
-Tested with Node version v0.1.25-15-g4e16e38
+    var sys    = require('sys'),
+        sqlite = require('./sqlite');
 
-(c) 2010 Eric Fredricksen - See permissive license terms at top of sqlite.js
+    var db = new sqlite.Database();
+
+    // open the database for reading if file exists
+    // create new database file if not
+
+    db.open("lilponies.db", function () {
+      var colour = 'pink';
+      var sql = 'SELECT name FROM ponies WHERE tail_colour = ?';
+
+      // bindings list is optional
+
+      var ponies = [];
+      
+      db.query(sql, [colour], function (pony) {
+        if (!pony) {
+          // no more ponies
+          if (!ponies.length)
+            sys.puts('There are no ponies with ' + colour + ' tails. :(');
+          else 
+            sys.puts('The following ponies have ' + colour + ' tails: ' + ponies.join(', '));
+        }
+        sys.puts(sys.inspect(pony));
+        ponies.push(pony);
+      });
+    });
+
+
+DESCRIPTION
+-----------
+
+This distribution includes two SQLite version 3 drivers: a low level driver
+written in C++ and a high level driver. The latter wraps the former to add
+nicer API and per-database query queuing to ensure queries do not clobber each
+other.
+
+It's HTML5 WebDatabase'ish but much, much simpler.
+
+At the moment, this library is the bare minimum necessary to get results out
+of SQLite, but extending either driver should be quite straight forward.
+
+This SQLite interface is incompatible with verison 2.
+
+SQLite's synchronous nature is fundamentally incompatible with a non-blocking
+system such as Node. To get around this synchronous calls happen within Node's
+libeio thread-pool, in a similar manner to how POSIX calls are currently made.
+This is exposed to JavaScript in the form of Database and Statement objects.
+
+The author is aware that SQLite ships with an asynchronous interface. This
+interface however lacks the necessariy notification mechanism to alert the
+caller when the SQLite call has completed. In other words, to be able to
+support callbacks, we use the synchronous driver within a seperate thread.
+
+SEE ALSO
+--------
+
+* http://sqlite.org/docs.html
+* http://github.com/grumdrig/node-sqlite/
+
+AUTHOR
+------
+
+Orlando Vazquez [ovazquez@gmail.com]
+
+THANKS
+------
+
+Many thanks to Eric Fredricksen for his synchronous driver on which this was
+based.
+
+http://github.com/grumdrig/node-sqlite/
+http://grumdrig.com/node-sqlite/
+
+(c) 2010 Eric Fredricksen
+(c) 2010 Orlando Vazquez