KirbyBase 2.5

data/README

@@ -0,0 +1,73 @@
+= KirbyBase 2.5
+
+A small, plain-text, dbms written in Ruby.  It can be used either embedded 
+or client/server.  
+
+
+== Installation
+
+Unpack the file you downloaded.  Execute "ruby install.rb" or simply make 
+sure kirbybase.rb is somewhere in your Ruby library path.
+
+
+== Documentation
+
+Documentation is in kirbybaserubymanual.html.  Also, RDoc generated 
+documentation is in the doc directory.
+
+See the examples directory for examples of how to use KirbyBase.
+
+
+== Manifest
+
+* README - this file
+* install.rb - install script
+* changes.txt - history of changes.
+* kirbybaserubymanual.html - documentation
+* kirbybase.rb - dbms library
+* kbserver.rb - multi-threaded database server script.
+* examples directory - many example scripts demonstrating features.
+* doc directory - RDoc generated documentation in html format.
+* images directory - images used in manual.
+
+
+== Warning
+
+KirbyBase defines #method_missing for NilClass.  This might bite you in the
+butt if you override NilClass.method_missing yourself.
+
+
+== Author
+
+Written in 2005 by Jamey Cribbs <mailto:jcribbs@twmi.rr.com>
+
+
+== License
+
+KirbyBase is distributed under the same license as Ruby.
+
+Copyright (c) 2005 Jamey Cribbs
+
+
+
+== Warranty
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING 
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+ IN THE SOFTWARE.
+
+
+== Feedback
+
+Please send any bug reports, suggestions, ideas,
+improvements, to:
+
+jcribbs@twmi.rr.com
+
+== Home Page
+
+http://www.netpromi.com/kirbybase_ruby.html

data/bin/kbserver.rb

@@ -0,0 +1,20 @@
+# Multi-user server script for KirbyBase.
+
+require 'kirbybase'
+require 'drb'
+require 'benchmark'
+include Benchmark
+
+host = ''
+port = 44444
+
+puts 'Initializing database server and indexes...'
+
+# Create an instance of the database.
+db = KirbyBase.new(:server) 
+
+DRb.start_service('druby://:44444', db)
+
+puts 'Server ready to receive connections...'
+
+DRb.thread.join 

data/changes.txt

@@ -0,0 +1,105 @@
+2005-12-01:: Version 2.5
+* Fixed a subtle bug in KBTable#create_indexes.
+* Added the following new methods to KBTable:  add_index, drop_index,
+  rename_column, change_column_type, change_column_default_value, and
+  change_column_required.
+* Added the ability to specify a default column value at table creation
+  time.
+* Added the ability to specify, at table creation time, that a column value 
+  is required when inserting or updating records.
+* Removed #add_table_column and #drop_table_column from KirbyBase class
+  and added #add_column and #drop_column to KBTable class.  I felt like
+  it made more sense to have these methods in the table's class rather
+  than the database's class.
+* Added KirbyBase#rename_table method.
+* Added the ability to, upon database initialization, specify that index
+  creation should not happen until a table is actually opened.  This
+  speeds up database initialization at the cost of slower table
+  initialization later.
+
+2005-11-13:: Version 2.4
+* Added a new column type: :Time.  Thanks to George Moschovitis for coding
+  this enhancement.
+* Added more functionality to Memo and Blob fields.  They are no longer
+  just read-only.  You can now also write to them from KirbyBase.  The
+  interface for Memo and Blob fields has changed because of this.
+* Added the ability to specify, when you initialize a database connection,
+  a base directory where memo/blob fields will be stored.
+* Changed the way indexes are handled by KBTable in client/server mode.
+  Now, when KBTable grabs an index from KBEngine, it will hold onto it and
+  re-use it unless it has been modified since the last time it grabbed it.
+  This speeds up subsequent queries on the same index.
+* Removed the restriction that the child table had to exist before you
+  could define a Link_many field in #create_table.  I did this so that
+  it would possible to now define many-to-many links.  See the example in
+  the distribution.  This also goes for Lookup fields.
+* Added two sample scripts:  kbserverctl.rb and kbserver_daemon.rb, that
+  show how to set up a KirbyBase server process as a Windows Service.
+  Thanks to Daniel Berger for his excellent package, win32-service.
+* Thouroughly revised the manual.  I used the excellent text document
+  formatter, AsciiDoc.  Many thanks to Stuart Rackham for developing this
+  great tool.
+* Fixed a bug in KBTable#clear that was causing the recno counter not to
+  be reset.  Thanks to basi for this.
+
+2005-10-10:: Version 2.3 
+* Added ability to specify lookup fields.
+* Added ability to specify one-to-many links between tables.
+* Added ability to specify calculated fields in tables.
+* Added Memo and Blob field types.
+* Added YAML field type.  Many thanks to Logan Capaldo for this idea!
+* Added indexing to speed up queries.
+* Two new methods:  #add_table_column and #drop_table_column.
+* Added the ability to designate a table field as the "key" field, for
+  Lookup purposes.  This simply makes it easier to define Lookup fields.
+* Added "crosstab" capabilities to KBResultSet.
+
+2005-08-09:: Version 2.2.1
+* Fixed a bug in with_write_lock.  Thanks to Zed A. Shaw for this bugfix.
+* Fixed a bug that occurred if @record_class was a nested class.  Thanks
+  to Hal Fulton for this bugfix.
+
+2005-05-02:: Version 2.2
+* By far the biggest change in this version is that I have completely
+  redesigned the internal structure of the database code.  Because the
+  KirbyBase and KBTable classes were too tightly coupled, I have created
+  a KBEngine class and moved all low-level I/O logic and locking logic
+  to this class.  This allowed me to restructure the KirbyBase class to
+  remove all of the methods that should have been private, but couldn't be
+  because of the coupling to KBTable.  In addition, it has allowed me to
+  take all of the low-level code that should not have been in the KBTable
+  class and put it where it belongs, as part of the underlying engine.  I
+  feel that the design of KirbyBase is much cleaner now.  No changes were
+  made to the class interfaces, so you should not have to change any of 
+  your code.
+* Changed str_to_date and str_to_datetime to use Date#parse method.
+  Thanks to Emiel van de Laar for this enhancement.
+* Changed #pack method so that it no longer reads the whole file into
+  memory while packing it.
+  Thanks to Hugh Sasse for reporting this bug.
+* Changed code so that special character sequences like &linefeed; can be
+  part of input data and KirbyBase will not interpret it as special 
+  characters.
+  Thanks to Hugh Sasse for this bug fix.
+    
+2005-04-11:: Version 2.1
+* Changed the interface to KirbyBase#new and KirbyBase#create_table.  You
+  now specify arguments via a code block or as part of the argument list.
+* Added the ability to specify a class at table creation time.  
+  Thereafter, whenever you do a #select, the result set will be an array
+  of instances of that class, instead of instances of Struct.  You can
+  also use instances of this class as the argument to #insert, #update,
+  #set.
+* Added the ability to encrypt a table so that it is no longer stored as
+  a plain-text file.
+* Added the ability to explicity specify that you want a result set to be
+  sorted in ascending order.
+* Added the ability to import a csv file into an existing table.
+* Added the ability to select a record as if the table were a Hash with 
+  it's key being the recno field.
+* Added the ability to update a record as if the table were a Hash with
+  it's key being the recno field.
+
+2005-03-28:: Version 2.0
+* New version with completely new interface.  A huge thanks to Hal Fulton
+  for all of his help with this new version.

data/examples/aaa_try_this_first/kbtest.rb

@@ -0,0 +1,207 @@
+#Simple test of KirbyBase.
+
+require 'kirbybase'
+require 'date'
+
+def print_divider(text)
+    puts
+    puts text.center(75, '-')
+    puts
+end
+
+#-------------------- Initialize KirbyBase Instance ------------------------
+# To run local, single-user, uncomment next line.
+db = KirbyBase.new
+
+# To run as a client in a multi-user environment, uncomment next line.
+# Also, make sure kbserver.rb is running.
+#db = KirbyBase.new do |d|
+#    d.connect_type = :client
+#    d.host = 'localhost'
+#    d.port = 44444
+#end
+
+#----------------------- Drop Table Example --------------------------------
+# If table exists, delete it.
+db.drop_table(:plane) if db.table_exists?(:plane)
+
+#----------------------- Create Table Example ------------------------------
+# Create a table.
+plane_tbl = db.create_table(:plane, :name, :String, :country, :String,
+ :role, :String, :speed, :Integer, :range, :Integer, :began_service, :Date,
+ :still_flying, :Boolean) { |obj| obj.encrypt = false }
+
+#----------------------- Insert Record Examples ----------------------------
+# Four different ways to insert records in KirbyBase.
+
+# 1) Insert a record using an array for the input values.
+plane_tbl.insert('FW-190', 'Germany', 'Fighter', 399, 499,
+ Date.new(1942,12,1), false)
+
+# 2) Insert a record using a hash for the input values.
+plane_tbl.insert(:name => 'P-51', :country => 'USA',
+ :role => 'Fighter', :speed => 403, :range => 1201,
+ :began_service => Date.new(1943,6,24), :still_flying => true)
+
+# 3) Insert a record using a Struct for the input values.
+InputRec = Struct.new(:name, :country, :role, :speed, :range,
+ :began_service, :still_flying)
+rec = InputRec.new('P-47', 'USA', 'Fighter', 365, 888, Date.new(1943,3,12),
+ false)
+plane_tbl.insert(rec)
+
+# 4) Insert a record using a code block for the input values.
+plane_tbl.insert { |r|
+    r.name = 'B-17'
+    r.country = 'USA'
+    r.role = 'Bomber'
+    r.speed = 315
+    r.range = 1400
+    r.began_service = Date.new(1937, 5, 1)
+    r.still_flying = true
+}
+
+# If a table is already existing and you need to get a reference to it so
+# that you can insert, select, etc., just do a get_table.
+plane_tbl_another_reference = db.get_table(:plane)
+
+# Then, you can use it just like you have been using the reference you got
+# when you created the table.
+plane_tbl_another_reference.insert('Typhoon', 'Great Britain',
+ 'Fighter-Bomber', 389, 690, Date.new(1944,11,20), false)
+
+# Insert a bunch more records so we can have some "select" fun below.
+plane_tbl.insert('Spitfire', 'Great Britain', 'Fighter', 345, 540,
+ Date.new(1939,2,18), true)
+plane_tbl.insert('Oscar', 'Japan', 'Fighter', 361, 777,
+ Date.new(1943,12,31), false)
+plane_tbl.insert('ME-109', 'Germany', 'Fighter', 366, 514,
+ Date.new(1936,7,7),true)
+plane_tbl.insert('JU-88', 'Germany', 'Bomber', 289, 999,
+ Date.new(1937,1,19), false)
+plane_tbl.insert('P-39', 'USA', 'Fighter', nil, nil,
+ nil, false)
+plane_tbl.insert('Zero', 'Japan', 'Fighter', 377, 912,
+ Date.new(1937,5,15), true)
+
+#--------------------- Update Examples -------------------------------------
+# Four different ways to update existing data in KirbyBase.  In all three
+# instances, you still need a code block attached to the update method in
+# order to select records that will be updated.
+
+# 1) Update record using a Hash, Struct, or an Array.
+plane_tbl.update(:speed => 405, :range => 1210) { |r| r.name == 'P-51' }
+
+# 2) Update record using a code block, via the set command.
+plane_tbl.update {|r| r.name == 'P-51'}.set {|r|
+    r.speed = 405
+    r.range = 1210
+}
+
+# 3) Update record using a Hash, Struct, or an Array, via the set
+#    command.
+plane_tbl.update {|r| r.name == 'P-51'}.set(:speed => 405, :range => 1210)
+
+# 4) Update record by treating table as if it were a Hash and the keys were
+#    recno's.
+plane_tbl[2] = {:speed => 405, :range => 1210}
+
+#--------------------- Delete Examples -------------------------------------
+# Delete 'FW-190' record.
+plane_tbl.delete { |r| r.name == 'FW-190' }
+
+# Remove deleted records from the table.
+plane_tbl.pack
+
+#---------------------- Select Example 0 -----------------------------------
+print_divider('Select Example 0')
+# Select all records, including all fields in result set.
+plane_tbl.select.each { |r|
+    puts(('%s ' * r.members.size) % r.to_a)
+}
+
+#-------------------------- Select Example 1 -------------------------------
+print_divider('Select Example 1')
+# Select all Japanese planes. Include just name and speed in the result.
+plane_tbl.select(:name, :speed) { |r| r.country == 'Japan' }.each { |r|
+    puts '%s %s' % [r.name, r.speed]
+}
+
+#-------------------------- Select Example 2 -------------------------------
+print_divider('Select Example 2')
+# Select all US planes with a speed greater than 350mph. Include just name
+# and speed in result set.
+plane_tbl.select(:name, :speed) { |r|
+    r.country == 'USA' and r.speed > 350
+}.each { |r| puts '%s %s' % [r.name, r.speed] }
+
+#-------------------------- Select Example 3 -------------------------------
+print_divider('Select Example 3')
+# Select all Axis fighters.
+plane_tbl.select { |r|
+    (r.country == 'Germany' or r.country == 'Japan') and r.role == 'Fighter'
+}.each { |r| puts r }
+
+#-------------------------- Select Example 4 -------------------------------
+print_divider('Select Example 4')
+# Same query as above, but let's use regular expressions instead of an 'or'.
+plane_tbl.select { |r|
+    r.country =~ /Germany|Japan/ and r.role == 'Fighter'
+}.each { |r| puts r }
+
+#-------------------------- Select Example 5 -------------------------------
+print_divider('Select Example 5')
+# Select all Bombers (but not Fighter-Bombers) and return only their name
+# and country.  This is also an example of how to get a reference to an
+# existing table as opposed to already having a reference to one via the
+# table_create method.
+match_role = /^Bomber/
+plane_tbl2 = db.get_table(:plane)
+plane_tbl2.select(:name, :country) { |r| r.role =~ match_role }.each { |r|
+    puts '%s %s' % r.to_a
+}
+
+#-------------------------- Select Example 6 -------------------------------
+print_divider('Select Example 6')
+# Select all planes.  Include just name, country, and speed in result set.
+# Sort result set by country (ascending) then name (ascending).
+plane_tbl.select(:name, :country, :speed).sort(:country,
+ :name).each { |r| puts "%s %s %d" % r.to_a }
+
+#-------------------------- Select Example 7 -------------------------------
+print_divider('Select Example 7')
+# Select all planes.  Include just name, country, and speed in result set.
+# Return result set as a nicely formatted report, sorted by
+# country (ascending) then speed (descending).
+puts plane_tbl.select(:name, :country, :speed).sort(+:country,
+ -:speed).to_report
+
+#-------------------------- Select Example 8 -------------------------------
+print_divider('Select Example 8')
+# Select planes that are included in nameArray.
+nameArray = ['P-51', 'Spitfire', 'Zero']
+plane_tbl.select { |r| nameArray.include?(r.name) }.each { |r| puts r }
+
+#-------------------------- Select Example 9 -------------------------------
+print_divider('Select Example 9')
+# You can select a record as if the table is a hash and it's keys are the
+# recno's.
+# Select the record that has a recno of 5.
+puts plane_tbl[5].name
+
+#-------------------------- Select Example 10 -------------------------------
+print_divider('Select Example 10')
+# You can even have a select within the code block of another select.  Here
+# we are selecting all records that are from the same country as the Zero.
+puts plane_tbl.select { |r|
+    r.country == plane_tbl.select { |x| x.name == 'Zero' }.first.country
+}
+
+#-------------------------- Misc. Methods Examples -------------------------
+print_divider('Misc. Methods Examples')
+puts 'Total # of records in table: %d' % plane_tbl.total_recs
+puts
+puts 'Fields for plane.tbl:'
+plane_tbl.field_names.zip(plane_tbl.field_types).each { |r|
+    print r[0].to_s.ljust(15), r[1].to_s, "\n"
+}

data/examples/add_column_test/add_column_test.rb

@@ -0,0 +1,27 @@
+#Test of add_column method.
+
+require 'kirbybase'
+
+db = KirbyBase.new
+
+# If table exists, delete it.
+db.drop_table(:plane) if db.table_exists?(:plane)
+
+# Create a table.
+plane_tbl = db.create_table(:plane, :name, :String, :speed, :Integer,
+ :service_date, :Date, :still_flying, :Boolean)
+
+# Insert a bunch more records so we can have some "select" fun below.
+plane_tbl.insert('Spitfire', 345, Date.new(1939,2,18), true)
+plane_tbl.insert('Oscar', 361, Date.new(1943,12,31), false)
+plane_tbl.insert('ME-109', 366, Date.new(1936,7,7),true)
+plane_tbl.insert('JU-88', 289, Date.new(1937,1,19), false)
+plane_tbl.insert('P-39', nil, nil, false)
+plane_tbl.insert('Zero', 377, Date.new(1937,5,15), true)
+
+plane_tbl.add_column(:range, {:DataType=>:Integer, :Index=>1}, :speed)
+
+plane_tbl.update { |r| r.name == 'Spitfire' }.set(:range => 454)
+
+puts plane_tbl.select_by_range_index { |r| r.range > 400 }.sort(:recno
+ ).to_report

data/examples/calculated_field_test/calculated_field_test.rb

@@ -0,0 +1,51 @@
+# This example script shows how to specify calculated fields in a KirbyBase
+# table.  Calculated fields are "virtual" fields.  They do not really exist
+# in the table, but are calculated during a select query.  However, once
+# calculated, they behave just like "real" table fields.
+
+# In this example, we will create an expenses table that holds information
+# on recent purchases.  The total_cost field is a calculated field.  We tell
+# KirbyBase how to calculate it's value, i.e. by multiplying the quantity
+# field by the price field.
+
+require 'kirbybase'
+require 'date'
+
+db = KirbyBase.new
+
+# To run as a client in a multi-user environment, uncomment next line.
+# Also, make sure kbserver.rb is running.
+#db = KirbyBase.new do |d|
+#    d.connect_type = :client
+#    d.host = 'localhost'
+#    d.port = 44444
+#end
+
+# If table exists, delete it.
+db.drop_table(:expenses) if db.table_exists?(:expenses)
+
+# Create a table.
+expenses_tbl = db.create_table(:expenses,
+ :transaction_date, :Date,
+ :description, :String,
+ :quantity, :Integer,
+ :price, :Float,
+ :total_cost, {:DataType=>:Float, :Calculated=>'quantity * price'}
+)
+
+# Insert a couple of expense records.
+expenses_tbl.insert({:transaction_date => Date.new(2005, 9, 7),
+ :description => 'Pencils', :quantity => 100, :price => 0.50})
+expenses_tbl.insert({:transaction_date => Date.new(2005, 9, 8),
+ :description => 'Books', :quantity => 3, :price => 45.0})
+
+# Select all records and send the result to the screen in report format.
+# Notice how the total_cost field for each record has been calculated for
+# you by multiplying price times quantity.
+puts "\nSelect all records:\n\n"
+puts expenses_tbl.select.to_report
+
+# And, you can even use a calculated field in your select condition.  Here
+# we are only selecting records whose total cost is greater than $100.
+puts "\n\nSelect only records with a total cost greater than $100:\n\n"
+puts expenses_tbl.select { |r| r.total_cost > 100.00 }.to_report