Permalink
Browse files

documentation upates

20080614224210-2f820-e5ca29b4628aa951a9251432bc101e765bdfe4e5.gz
  • Loading branch information...
copiousfreetime authored and git-darcs-import committed Jun 14, 2008
1 parent 8a99cab commit b2b2f93b95fccd3cd3da92d1cbcb7b9caaf373a0
Showing with 101 additions and 65 deletions.
  1. +7 −5 README
  2. +2 −3 TODO
  3. +5 −0 lib/amalgalite/column.rb
  4. +69 −41 lib/amalgalite/database.rb
  5. +5 −0 lib/amalgalite/index.rb
  6. +12 −15 lib/amalgalite/statement.rb
  7. +1 −1 tasks/config.rb
View
12 README
@@ -1,8 +1,8 @@
== amalgalite
== Amalgalite
* Homepage
* rubyforge project
* email
* Homepage[http://www.copiousfreetime.org/projects/amalgalite]
* {Rubyforge Project}[http://rubyforge.org/projects/copiousfreetime/]
* email jeremy at copiousfreetime dot org
== DESCRIPTION
@@ -12,9 +12,11 @@
== CREDITS
* Jamis Buck for the first ruby sqlite implementation
== LICENSE
Copyright (c) Jeremy Hinegardner
Copyright (c) 2008 Jeremy Hinegardner
All rights reserved.
View
5 TODO
@@ -1,9 +1,7 @@
For first release
=================
* convert type dependency to just use 'call'
* amalgalite command line tool
* documentation
? if in a transaction, and you call transaction, then yield the block
For future releases
===================
@@ -20,4 +18,5 @@ For future releases
* full text search
* virtual file system
* encryption key support
* call instead of
* convert type dependency to just use 'call'
? if in a transaction, and you call transaction, then yield the block
View
@@ -55,22 +55,27 @@ def initialize( db, name, table )
@default_value = nil
end
# true if the column has a default value
def has_default_value?
not default_value.nil?
end
# true if the column may have a NULL value
def nullable?
not_null_constraint == false
end
# true if the column as a NOT NULL constraint
def not_null_constraint?
not_null_constraint
end
# true if the column is a primary key column
def primary_key?
primary_key
end
# true if the column is auto increment
def auto_increment?
auto_increment
end
View
@@ -9,6 +9,23 @@
require 'amalgalite/type_maps/default_map'
module Amalgalite
#
# The encapsulation of a connection to an SQLite3 database.
#
# Example opening and possibly creating a new daabase
#
# db = Amalgalite::Database.new( "mydb.db" )
# db.execute( "SELECT * FROM table" ) do |row|
# puts row
# end
#
# db.close
#
# Open a database read only:
#
# db = Amalgalite::Database.new( "mydb.db", "r" )
#
#
class Database
class InvalidModeError < ::Amalgalite::Error; end
@@ -27,46 +44,18 @@ def self.valid?( mode )
end
end
##
# Create a new Amalgalite database
#
# :call-seq:
# Amalgalite::Database.new( filename, "r", opts = {}) -> Database
#
# The first parameter is the filename of the sqlite database.
# The second parameter is the standard file modes of how to open a file.
#
# The modes are:
# * r - Read-only
# * r+ - Read/write, an error is thrown if the database does not already
# exist.
# * w+ - Read/write, create a new database if it doesn't exist
# This is the default as this is how most databases will want
# to be utilized.
#
# opts is a hash of available options for the database:
#
# :utf16 : option to set the database to a utf16 encoding if creating
# a database. By default, databases are created with an
# encoding of utf8. Setting this to true and opening an already
# existing database has no effect.
#
# Currently :utf16 is not supported by Amalgalite, it is planned
# for a later release
#
#
include Amalgalite::SQLite3::Constants
include Amalgalite::SQLite3::Constants
VALID_MODES = {
"r" => Open::READONLY,
"r+" => Open::READWRITE,
"w+" => Open::READWRITE | Open::CREATE,
}
# the lower level SQLite3::Database
# the low level Amalgalite::SQLite3::Database
attr_reader :api
# An instance of something that follows the TraceTap protocol.
# Be default this is nil
# By default this is nil
attr_reader :trace_tap
# An instances of something that follows the ProfileTap protocol.
@@ -78,7 +67,32 @@ def self.valid?( mode )
attr_reader :type_map
##
# Create a new database
# Create a new Amalgalite database
#
# :call-seq:
# Amalgalite::Database.new( filename, "w+", opts = {}) -> Database
#
# The first parameter is the filename of the sqlite database.
# The second parameter is the standard file modes of how to open a file.
#
# The modes are:
#
# * r - Read-only
# * r+ - Read/write, an error is thrown if the database does not already exist
# * w+ - Read/write, create a new database if it doesn't exist
#
# <tt>w+</tt> is the default as this is how most databases will want to be utilized.
#
# opts is a hash of available options for the database:
#
# * :utf16 option to set the database to a utf16 encoding if creating a database.
#
# By default, databases are created with an encoding of utf8. Setting this to
# true and opening an already existing database has no effect.
#
# *NOTE* Currently :utf16 is not supported by Amalgalite, it is planned
# for a later release
#
#
def initialize( filename, mode = "w+", opts = {})
@open = false
@@ -158,14 +172,16 @@ def in_transaction?
##
# return how many rows have changed in the last insert, update or delete
# statement
# statement.
#
def row_changes
@api.row_changes
end
##
# return how many rows have changed since the connection to the database has
# been opend.
# return how many rows have changed since the connection to the database was
# opened.
#
def total_changes
@api.total_changes
end
@@ -176,6 +192,18 @@ def total_changes
# If called with a block, the statement is yielded to the block and the
# statement is closed when the block is done.
#
# db.prepare( "SELECT * FROM table WHERE c = ?" ) do |stmt|
# list_of_c_values.each do |c|
# stmt.execute( c ) do |row|
# puts "when c = #{c} : #{row.inspect}"
# end
# end
# end
#
# Or without a block:
#
# stmt = db.prepare( "INSERT INTO t1(x, y, z) VALUES ( :
#
def prepare( sql )
stmt = Amalgalite::Statement.new( self, sql )
if block_given? then
@@ -402,12 +430,12 @@ def pragma( cmd )
##
# Begin a transaction. The valid transaction types are:
#
# DEFERRED : no read or write locks are created until the first
# statement is executed that requries a read or a write
# IMMEDIATE : a readlock is obtained immediately so that no other process
# can write to the database
# EXCLUSIVE : a read+write lock is obtained, no other proces can read or
# write to the database
# DEFERRED:: no read or write locks are created until the first
# statement is executed that requries a read or a write
# IMMEDIATE:: a readlock is obtained immediately so that no other process
# can write to the database
# EXCLUSIVE:: a read+write lock is obtained, no other proces can read or
# write to the database
#
# As a convenience, these are constants available in the
# Database::TransactionBehavior class.
View
@@ -8,8 +8,13 @@ module Amalgalite
# a class representing the meta information about an SQLite index
#
class Index
# the name of the index
attr_reader :name
# the sql statement that created the index
attr_reader :sql
# the table the index is for
attr_accessor :table
def initialize( name, sql, table )
@@ -162,7 +162,7 @@ def param_position_of( name )
return pos
end
#
##
# Check and make sure that the number of parameters aligns with the number
# that sqlite expects
#
@@ -175,7 +175,7 @@ def check_parameter_count!( num )
end
#
##
# Iterate over the results of the statement returning each row of results
# as a hash by +column_name+. The column names are the value after an
# 'AS' in the query or default chosen by sqlite.
@@ -187,12 +187,9 @@ def each
return self
end
#
# Return the next row of data, with type conversion as best as possible into
# ruby types.
#
# TOOD: should the result set be a has or an array by default, and if it is
# a hash, should non-unique keys mean that there is an error?
##
# Return the next row of data, with type conversion as indicated by the
# Database#type_map
#
def next_row
row = []
@@ -228,7 +225,7 @@ def next_row
return row
end
#
##
# Return all rows from the statement as one array
#
def all_rows
@@ -239,7 +236,7 @@ def all_rows
return rows
end
#
##
# Inspect the statement and gather all the meta information about the
# results, include the name of the column result column and the origin
# column. The origin column is the original database.table.column the value
@@ -269,37 +266,37 @@ def result_meta
return @result_meta
end
#
##
# Return the array of field names for the result set, the field names are
# all strings
#
def result_fields
@fields ||= result_meta.collect { |m| m.name }
end
#
##
# Return any unsued SQL from the statement
#
def remaining_sql
@stmt_api.remaining_sql
end
#
##
# return the number of columns in the result of this query
#
def column_count
@stmt_api.column_count
end
#
##
# return the raw sql that was originally used to prepare the statement
#
def sql
@stmt_api.sql
end
#
##
# Close the statement. The statement is no longer valid for use after it
# has been closed.
#
View
@@ -15,7 +15,7 @@
description Utils.section_of("README", "description")
summary description.split(".").first
history "HISTORY"
license FileList["LICENSE", "COPYING"]
license FileList["LICENSE"]
readme "README"
}

0 comments on commit b2b2f93

Please sign in to comment.