qoobaa-sqlite3-ruby 1.2.5

data/.document

@@ -0,0 +1,7 @@
+README.rdoc
+faq/faq/*
+lib/**/*.rb
+ext/sqlite3_api/*
+test/**/*.rb
+CHANGELOG.rdoc
+LICENSE

data/.gitignore

@@ -0,0 +1,5 @@
+*.sw?
+.DS_Store
+coverage
+rdoc
+pkg

data/CHANGELOG.rdoc

@@ -0,0 +1,55 @@
+=== 1.2.5 / 13 May 2009
+
+* Ruby 1.9.1 UTF-8 support [Jakub Kuźma]
+
+* Check for illegal nil before executing SQL [Erik Veenstra]
+
+=== 1.2.4 / 27 Aug 2008
+
+* Package the updated C file for source builds. [Jamis Buck]
+
+
+=== 1.2.3 / 26 Aug 2008
+
+* Fix incorrect permissions on database.rb and translator.rb [Various]
+
+* Avoid using Object#extend for greater speedups [Erik Veenstra]
+
+* Ruby 1.9 compatibility tweaks for Array#zip [jimmy88@gmail.com]
+
+* Fix linking against Ruby 1.8.5 [Rob Holland <rob@inversepath.com>]
+
+
+=== 1.2.2 / 31 May 2008
+
+* Make the table_info method adjust the returned default value for the rows
+  so that the sqlite3 change in 3.3.8 and greater can be handled
+  transparently [Jamis Buck <jamis@37signals.com>]
+
+* Ruby 1.9 compatibility tweaks [Roman Le Negrate <roman2k@free.fr>]
+
+* Various performance enhancements [thanks Erik Veenstra]
+
+* Correct busy_handler documentation [Rob Holland <rob@inversepath.com>]
+
+* Use int_bind64 on Fixnum values larger than a 32bit C int can take. [Rob Holland <rob@inversepath.com>]
+
+* Work around a quirk in SQLite's error reporting by calling sqlite3_reset
+  to produce a more informative error code upon a failure from
+  sqlite3_step. [Rob Holland <rob@inversepath.com>]
+
+* Various documentation, test, and style tweaks [Rob Holland <rob@inversepath.com>]
+
+* Be more granular with time/data translation [Rob Holland <rob@inversepath.com>]
+
+* Use Date directly for parsing rather than going via Time [Rob Holland <rob@inversepath.com>]
+
+* Check for the rt library and fdatasync so we link against that when
+  needed [Rob Holland <rob@inversepath.com>]
+
+* Rename data structures to avoid collision on win32. based on patch
+  by: Luis Lavena [Rob Holland <rob@inversepath.com>]
+
+* Add test for defaults [Daniel Rodríguez Troitiño]
+
+* Correctly unquote double-quoted pragma defaults [Łukasz Dargiewicz <lukasz.dargiewicz@gmail.com>]

data/LICENSE

@@ -0,0 +1,27 @@
+Copyright (c) 2004, Jamis Buck (jamis@jamisbuck.org)
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+    * Redistributions of source code must retain the above copyright notice,
+      this list of conditions and the following disclaimer.
+
+    * Redistributions in binary form must reproduce the above copyright
+      notice, this list of conditions and the following disclaimer in the
+      documentation and/or other materials provided with the distribution.
+
+    * The names of its contributors may not be used to endorse or promote
+      products derived from this software without specific prior written
+      permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

data/README.rdoc

@@ -0,0 +1,52 @@
+= SQLite3/Ruby Interface
+
+This module allows Ruby programs to interface with the SQLite3
+database engine (http://www.sqlite.org).  You must have the
+SQLite engine installed in order to build this module.
+
+Note that this module is NOT compatible with SQLite 2.x.
+
+This version includes full UTF-8 support in Ruby 1.9.1.
+
+== Compilation and Installation
+
+Simply do the following, after installing SQLite3:
+
+  ruby setup.rb config
+  ruby setup.rb setup
+  ruby setup.rb install
+
+Alternatively, you can download and install the RubyGem package for
+SQLite3/Ruby (you must have RubyGems and SQLite3 installed, first):
+
+  gem install sqlite3-ruby
+
+If you have sqlite3 installed in a non-standard location, you can specify the location of the include and lib files by doing:
+
+  gem install sqlite3-ruby -- --with-sqlite3-include=/opt/local/include \
+     --with-sqlite3-lib=/opt/local/lib
+
+Also, the gem ships with the C source-code pre-built, so (as of version 1.1.1)
+you no longer need to have SWIG installed. However, if you have SWIG installed
+and you want to generate the C file yourself, you can specify the
+<code>--with-swig</code> option.
+
+== Usage
+
+For help figuring out the SQLite3/Ruby interface, check out the
+FAQ[http://sqlite-ruby.rubyforge.org/sqlite3/faq.html]. It includes examples of
+usage. If you have any questions that you feel should be address in the
+FAQ, please send them to jamis@37signals.com
+
+== Source Code
+
+The source repository is accessible via git:
+
+  git clone git://github.com/qoobaa/sqlite3-ruby.git
+
+== Contact Information
+
+The project page is http://rubyforge.org/projects/sqlite-ruby. There, you can
+find links to mailing lists and forums that you can use to discuss this
+library. Additionally, there are trackers for submitting bugs and feature
+requests. Feel free to use them!

data/Rakefile

@@ -0,0 +1,59 @@
+#encoding: utf-8
+
+require 'rubygems'
+require 'rake'
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gem|
+    gem.name = "sqlite3-ruby"
+    gem.summary = %Q{A Ruby interface for the SQLite database engine.}
+    gem.email = "qoobaa@gmail.com"
+    gem.homepage = "http://github.com/qoobaa/sqlite3-ruby"
+    gem.authors = ["Jakub Kuźma"]
+    # gem is a Gem::Specification... see http://www.rubygems.org/read/chapter/20 for additional settings
+    gem.extensions << 'ext/sqlite3_api/extconf.rb'
+  end
+
+rescue LoadError
+  puts "Jeweler (or a dependency) not available. Install it with: sudo gem install jeweler"
+end
+
+require 'rake/testtask'
+Rake::TestTask.new(:test) do |test|
+  test.libs << 'lib' << 'test'
+  test.pattern = 'test/**/*_test.rb'
+  test.verbose = true
+end
+
+begin
+  require 'rcov/rcovtask'
+  Rcov::RcovTask.new do |test|
+    test.libs << 'test'
+    test.pattern = 'test/**/*_test.rb'
+    test.verbose = true
+  end
+rescue LoadError
+  task :rcov do
+    abort "RCov is not available. In order to run rcov, you must: sudo gem install spicycode-rcov"
+  end
+end
+
+
+task :default => :test
+
+require 'rake/rdoctask'
+Rake::RDocTask.new do |rdoc|
+  if File.exist?('VERSION.yml')
+    config = YAML.load(File.read('VERSION.yml'))
+    version = "#{config[:major]}.#{config[:minor]}.#{config[:patch]}"
+  else
+    version = ""
+  end
+
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "sqlite3-ruby #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+

data/VERSION

@@ -0,0 +1 @@
+1.2.5

data/doc/faq/faq.rb

@@ -0,0 +1,145 @@
+require 'yaml'
+require 'redcloth'
+
+def process_faq_list( faqs )
+  puts "<ul>"
+  faqs.each do |faq|
+    process_faq_list_item faq
+  end
+  puts "</ul>"
+end
+
+def process_faq_list_item( faq )
+  question = faq.keys.first
+  answer = faq.values.first
+
+  print "<li>"
+
+  question_text = RedCloth.new(question).to_html.gsub( %r{</?p>},"" )
+  if answer.is_a?( Array )
+    puts question_text
+    process_faq_list answer
+  else
+    print "<a href='##{question.object_id}'>#{question_text}</a>"
+  end
+
+  puts "</li>"
+end
+
+def process_faq_descriptions( faqs, path=nil )
+  faqs.each do |faq|
+    process_faq_description faq, path
+  end
+end
+
+def process_faq_description( faq, path )
+  question = faq.keys.first
+  path = ( path ? path + " " : "" ) + question
+  answer = faq.values.first
+
+  if answer.is_a?( Array )
+    process_faq_descriptions( answer, path )
+  else
+    title = RedCloth.new( path ).to_html.gsub( %r{</?p>}, "" )
+    answer = RedCloth.new( answer || "" )
+
+    puts "<a name='#{question.object_id}'></a>"
+    puts "<div class='faq-title'>#{title}</div>"
+    puts "<div class='faq-answer'>#{add_api_links(answer.to_html)}</div>"
+  end
+end
+
+API_OBJECTS = [ "Database", "Statement", "ResultSet",
+  "ParsedStatement", "Pragmas", "Translator" ].inject( "(" ) { |acc,name|
+    acc << "|" if acc.length > 1
+    acc << name
+    acc
+  } + ")"
+
+def add_api_links( text )
+  text.gsub( /#{API_OBJECTS}(#(\w+))?/ ) do
+    disp_obj = obj = $1
+
+    case obj
+      when "Pragmas"; disp_obj = "Database"
+    end
+
+    method = $3
+    s = "<a href='http://sqlite-ruby.rubyforge.org/classes/SQLite/#{obj}.html'>#{disp_obj}"
+    s << "##{method}" if method
+    s << "</a>"
+    s
+  end
+end
+
+faqs = YAML.load( File.read( "faq.yml" ) )
+
+puts <<-EOF
+<html>
+  <head>
+    <title>SQLite3/Ruby FAQ</title>
+    <style type="text/css">
+      a, a:visited, a:active {
+        color: #00F;
+        text-decoration: none;
+      }
+
+      a:hover {
+        text-decoration: underline;
+      }
+
+      .faq-list {
+        color: #000;
+        font-family: vera-sans, verdana, arial, sans-serif;
+      }
+
+      .faq-title {
+        background: #007;
+        color: #FFF;
+        font-family: vera-sans, verdana, arial, sans-serif;
+        padding-left: 1em;
+        padding-top: 0.5em;
+        padding-bottom: 0.5em;
+        font-weight: bold;
+        font-size: large;
+        border: 1px solid #000;
+      }
+
+      .faq-answer {
+        margin-left: 1em;
+        color: #000;
+        font-family: vera-sans, verdana, arial, sans-serif;
+      }
+
+      .faq-answer pre {
+        margin-left: 1em;
+        color: #000;
+        background: #FFE;
+        font-size: normal;
+        border: 1px dotted #CCC;
+        padding: 1em;
+      }
+
+      h1 {
+        background: #005;
+        color: #FFF;
+        font-family: vera-sans, verdana, arial, sans-serif;
+        padding-left: 1em;
+        padding-top: 1em;
+        padding-bottom: 1em;
+        font-weight: bold;
+        font-size: x-large;
+        border: 1px solid #00F;
+      }
+    </style>
+  </head>
+  <body>
+  <h1>SQLite/Ruby FAQ</h1>
+  <div class="faq-list">
+EOF
+
+process_faq_list( faqs )
+puts "</div>"
+process_faq_descriptions( faqs )
+
+puts "</body></html>"

data/doc/faq/faq.yml

@@ -0,0 +1,426 @@
+---
+- "How do I do a database query?":
+  - "I just want an array of the rows...": >-
+
+      Use the Database#execute method. If you don't give it a block, it will
+      return an array of all the rows:
+
+
+      <pre>
+        require 'sqlite3'
+
+        db = SQLite3::Database.new( "test.db" )
+        rows = db.execute( "select * from test" )
+      </pre>
+
+  - "I'd like to use a block to iterate through the rows...": >-
+
+      Use the Database#execute method. If you give it a block, each row of the
+      result will be yielded to the block:
+
+
+      <pre>
+        require 'sqlite3'
+
+        db = SQLite3::Database.new( "test.db" )
+        db.execute( "select * from test" ) do |row|
+          ...
+        end
+      </pre>
+
+  - "I need to get the column names as well as the rows...": >-
+
+      Use the Database#execute2 method. This works just like Database#execute;
+      if you don't give it a block, it returns an array of rows; otherwise, it
+      will yield each row to the block. _However_, the first row returned is
+      always an array of the column names from the query:
+
+
+      <pre>
+        require 'sqlite3'
+
+        db = SQLite3::Database.new( "test.db" )
+        columns, *rows = db.execute2( "select * from test" )
+
+        # or use a block:
+
+        columns = nil
+        db.execute2( "select * from test" ) do |row|
+          if columns.nil?
+            columns = row
+          else
+            # process row
+          end
+        end
+      </pre>
+
+  - "I just want the first row of the result set...": >-
+
+      Easy. Just call Database#get_first_row:
+
+
+      <pre>
+        row = db.get_first_row( "select * from table" )
+      </pre>
+
+
+      This also supports bind variables, just like Database#execute
+      and friends.
+
+  - "I just want the first value of the first row of the result set...": >-
+
+      Also easy. Just call Database#get_first_value:
+
+
+      <pre>
+        count = db.get_first_value( "select count(*) from table" )
+      </pre>
+
+
+      This also supports bind variables, just like Database#execute
+      and friends.
+
+- "How do I prepare a statement for repeated execution?": >-
+    If the same statement is going to be executed repeatedly, you can speed
+    things up a bit by _preparing_ the statement. You do this via the
+    Database#prepare method. It returns a Statement object, and you can
+    then invoke #execute on that to get the ResultSet:
+
+    
+    <pre>
+      stmt = db.prepare( "select * from person" )
+
+      1000.times do
+        stmt.execute do |result|
+          ...
+        end
+      end
+
+      stmt.close
+
+      # or, use a block
+
+      db.prepare( "select * from person" ) do |stmt|
+        1000.times do
+          stmt.execute do |result|
+            ...
+          end
+        end
+      end
+    </pre>
+
+
+    This is made more useful by the ability to bind variables to placeholders
+    via the Statement#bind_param and Statement#bind_params methods. (See the
+    next FAQ for details.)
+
+- "How do I use placeholders in an SQL statement?": >-
+    Placeholders in an SQL statement take any of the following formats:
+
+
+    * @?@
+
+    * @?_nnn_@
+
+    * @:_word_@
+
+
+    Where _n_ is an integer, and _word_ is an alpha-numeric identifier (or
+    number). When the placeholder is associated with a number, that number
+    identifies the index of the bind variable to replace it with. When it
+    is an identifier, it identifies the name of the correponding bind
+    variable. (In the instance of the first format--a single question
+    mark--the placeholder is assigned a number one greater than the last
+    index used, or 1 if it is the first.)
+
+
+    For example, here is a query using these placeholder formats:
+
+
+    <pre>
+      select *
+        from table
+       where ( c = ?2 or c = ? )
+         and d = :name
+         and e = :1
+    </pre>
+
+
+    This defines 5 different placeholders: 1, 2, 3, and "name".
+
+
+    You replace these placeholders by _binding_ them to values. This can be
+    accomplished in a variety of ways.
+
+
+    The Database#execute, and Database#execute2 methods all accept additional
+    arguments following the SQL statement. These arguments are assumed to be
+    bind parameters, and they are bound (positionally) to their corresponding
+    placeholders:
+
+
+    <pre>
+      db.execute( "select * from table where a = ? and b = ?",
+                  "hello",
+                  "world" )
+    </pre>
+
+
+    The above would replace the first question mark with 'hello' and the
+    second with 'world'. If the placeholders have an explicit index given, they
+    will be replaced with the bind parameter at that index (1-based).
+
+
+    If a Hash is given as a bind parameter, then its key/value pairs are bound
+    to the placeholders. This is how you bind by name:
+
+
+    <pre>
+      db.execute( "select * from table where a = :name and b = :value",
+                  "name" => "bob",
+                  "value" => "priceless" )
+    </pre>
+
+
+    You can also bind explicitly using the Statement object itself. Just pass
+    additional parameters to the Statement#execute statement:
+    
+
+    <pre>
+      db.prepare( "select * from table where a = :name and b = ?" ) do |stmt|
+        stmt.execute "value", "name" => "bob"
+      end
+    </pre>
+
+
+    Or do a Database#prepare to get the Statement, and then use either
+    Statement#bind_param or Statement#bind_params:
+
+
+    <pre>
+      stmt = db.prepare( "select * from table where a = :name and b = ?" )
+
+      stmt.bind_param( "name", "bob" )
+      stmt.bind_param( 1, "value" )
+
+      # or
+
+      stmt.bind_params( "value", "name" => "bob" )
+    </pre>
+
+- "How do I discover metadata about a query?": >-
+  
+    If you ever want to know the names or types of the columns in a result
+    set, you can do it in several ways.
+
+
+    The first way is to ask the row object itself. Each row will have a
+    property "fields" that returns an array of the column names. The row
+    will also have a property "types" that returns an array of the column
+    types:
+
+
+    <pre>
+      rows = db.execute( "select * from table" )
+      p rows[0].fields
+      p rows[0].types
+    </pre>
+
+
+    Obviously, this approach requires you to execute a statement that actually
+    returns data. If you don't know if the statement will return any rows, but
+    you still need the metadata, you can use Database#query and ask the
+    ResultSet object itself:
+
+
+    <pre>
+      db.query( "select * from table" ) do |result|
+        p result.columns
+        p result.types
+        ...
+      end
+    </pre>
+
+
+    Lastly, you can use Database#prepare and ask the Statement object what
+    the metadata are:
+
+
+    <pre>
+      stmt = db.prepare( "select * from table" )
+      p stmt.columns
+      p stmt.types
+    </pre>
+
+- "I'd like the rows to be indexible by column name.": >-
+    By default, each row from a query is returned as an Array of values. This
+    means that you can only obtain values by their index. Sometimes, however,
+    you would like to obtain values by their column name.
+
+
+    The first way to do this is to set the Database property "results_as_hash"
+    to true. If you do this, then all rows will be returned as Hash objects,
+    with the column names as the keys. (In this case, the "fields" property
+    is unavailable on the row, although the "types" property remains.)
+
+
+    <pre>
+      db.results_as_hash = true
+      db.execute( "select * from table" ) do |row|
+        p row['column1']
+        p row['column2']
+      end
+    </pre>
+
+
+    The other way is to use Ara Howard's
+    "ArrayFields":http://rubyforge.org/projects/arrayfields
+    module. Just require "arrayfields", and all of your rows will be indexable
+    by column name, even though they are still arrays!
+
+
+    <pre>
+      require 'arrayfields'
+
+      ...
+      db.execute( "select * from table" ) do |row|
+        p row[0] == row['column1']
+        p row[1] == row['column2']
+      end
+    </pre>
+
+- "I'd like the values from a query to be the correct types, instead of String.": >-
+    You can turn on "type translation" by setting Database#type_translation to
+    true:
+
+
+    <pre>
+      db.type_translation = true
+      db.execute( "select * from table" ) do |row|
+        p row
+      end
+    </pre>
+
+
+    By doing this, each return value for each row will be translated to its
+    correct type, based on its declared column type.
+
+
+    You can even declare your own translation routines, if (for example) you are
+    using an SQL type that is not handled by default:
+
+
+    <pre>
+      # assume "objects" table has the following schema:
+      #   create table objects (
+      #     name varchar2(20),
+      #     thing object
+      #   )
+
+      db.type_translation = true
+      db.translator.add_translator( "object" ) do |type, value|
+        db.decode( value )
+      end
+
+      h = { :one=>:two, "three"=>"four", 5=>6 }
+      dump = db.encode( h )
+
+      db.execute( "insert into objects values ( ?, ? )", "bob", dump )
+
+      obj = db.get_first_value( "select thing from objects where name='bob'" )
+      p obj == h
+    </pre>
+
+- "How do insert binary data into the database?": >-
+    Use blobs. Blobs are new features of SQLite3. You have to use bind
+    variables to make it work:
+
+
+    <pre>
+      db.execute( "insert into foo ( ?, ? )",
+        SQLite3::Blob.new( "\0\1\2\3\4\5" ),
+        SQLite3::Blob.new( "a\0b\0c\0d ) )
+    </pre>
+
+
+    The blob values must be indicated explicitly by binding each parameter to
+    a value of type SQLite3::Blob.
+
+- "How do I do a DDL (insert, update, delete) statement?": >-
+    You can actually do inserts, updates, and deletes in exactly the same way
+    as selects, but in general the Database#execute method will be most
+    convenient:
+
+    
+    <pre>
+      db.execute( "insert into table values ( ?, ? )", *bind_vars )
+    </pre>
+
+- "How do I execute multiple statements in a single string?": >-
+    The standard query methods (Database#execute, Database#execute2,
+    Database#query, and Statement#execute) will only execute the first
+    statement in the string that is given to them. Thus, if you have a
+    string with multiple SQL statements, each separated by a string,
+    you can't use those methods to execute them all at once.
+
+
+    Instead, use Database#execute_batch:
+
+
+    <pre>
+      sql = <<SQL
+        create table the_table (
+          a varchar2(30),
+          b varchar2(30)
+        );
+
+        insert into the_table values ( 'one', 'two' );
+        insert into the_table values ( 'three', 'four' );
+        insert into the_table values ( 'five', 'six' );
+      SQL
+
+      db.execute_batch( sql )
+    </pre>
+
+
+    Unlike the other query methods, Database#execute_batch accepts no
+    block. It will also only ever return +nil+. Thus, it is really only
+    suitable for batch processing of DDL statements.
+
+- "How do I begin/end a transaction?":
+    Use Database#transaction to start a transaction. If you give it a block,
+    the block will be automatically committed at the end of the block,
+    unless an exception was raised, in which case the transaction will be
+    rolled back. (Never explicitly call Database#commit or Database#rollback
+    inside of a transaction block--you'll get errors when the block
+    terminates!)
+
+
+    <pre>
+      database.transaction do |db|
+        db.execute( "insert into table values ( 'a', 'b', 'c' )" )
+        ...
+      end
+    </pre>
+
+
+    Alternatively, if you don't give a block to Database#transaction, the
+    transaction remains open until you explicitly call Database#commit or
+    Database#rollback.
+
+
+    <pre>
+      db.transaction
+      db.execute( "insert into table values ( 'a', 'b', 'c' )" )
+      db.commit
+    </pre>
+
+
+    Note that SQLite does not allow nested transactions, so you'll get errors
+    if you try to open a new transaction while one is already active. Use
+    Database#transaction_active? to determine whether a transaction is
+    active or not.
+
+#- "How do I discover metadata about a table/index?":
+#
+#- "How do I do tweak database settings?":