SQLite/Ruby Interface
---------------------

This module allows Ruby programs to interface with the SQLite
database engine (http://www.sqlite.org).  You must have the
SQLite engine installed in order to build this module.


Compilation and Installation
----------------------------

Simply do the following, after installing SQLite:

  ruby extconf.rb
  make
  make install

To run the sample programs, run them from the parent
directory of the 'samples' dir:

  ruby samples/define_db.rb
  ruby samples/queries.rb
  ruby samples/advanced.rb


API Reference
-------------

The complete API reference is at www.sqlite.org, under the C interface
document.  The following defines the classes and methods available
with this interface.

  module SQLite
    this is the module that contains all of the SQLite classes.

  class SQLite::Database
    This represents a connection to a single SQLite database.

    .new( file, mode )
    .open( file, mode )
      Each of these methods opens the given file as a database, creating
      it if necessary.  The mode parameter is ignored, and should be set
      to 0.

    .close()
      Closes the reciever.

    .exec( sql, callback, parm )
      Executes the given SQL, calling the 'callback' Method object for each
      row,  The 'parm' parameter is also passed to the callback each time.

    .execute( sql, parm = nil ) { |row| ... }
      Executes the given SQL, calling the associated block for each row.
      The 'row' object is simply a Hash object, with the additional property
      of 'argument', which is the value of the 'parm' parameter that was passed
      to execute.

    .last_insert_rowid()
      Returns the row-id of the row that was most recently inserted.

    .changes()
      Returns the number of rows modified.

    .interrupt()
      Interrupts the currently running query.

    .complete?( sql )
      Returns true if the given sql statement is 'complete' (which is not to say,
      correct---the query may have syntax errors, but it is completely formed).

    .create_function( name, arg_count, callback, parm )
      Creates a new SQL function with the given name that takes the given number
      of arguments.  When the SQL function is invoked, the associated callback
      is invoked, and the SQL context and arguments are passed to it, in that
      order.  The 'parm' is not currently accessible from the callback... yet.
      
    .create_aggregate( name, arg_count, step, finalize, parm )
      Creates a new SQL aggregate function with the given name and argument
      count.  For each row in the query, 'step' is called, and then 'finalize'
      is called to return the value for the function.  The finalize method
      only takes one parameter, the context.

    ::VERSION
      The current version of the SQLite engine.

    ::ENCODING
      The current character encoding used by the SQLite engine.

    In addition, all of the pragmas that SQLite supports have been implemented as
    accessor methods of SQLite::Database; see the sqlite.rb file for the complete
    list.


  class SQLite::DatabaseException
    Thrown by the methods of SQLite::Database if there is an error.


  class SQLite::QueryContext
    An instance of this is passed to any custom SQL functions you create.

    .aggregate_count()
      Only valid when used in an aggregate context, this returns the total
      number of rows in the query.

    .properties()
      Only valid when used in an aggregate context, this returns a hash
      object that you can use to store values between rows in the step
      function.

