KirbyBase 2.5

data/examples/change_column_type_test/change_column_type_test.rb

@@ -0,0 +1,25 @@
+# This script is an example of how to change a column type.
+#
+require 'kirbybase'
+
+db = KirbyBase.new
+
+# If table exists, delete it.
+db.drop_table(:log) if db.table_exists?(:log)
+
+log_tbl = db.create_table(:log, :log_timestamp, :DateTime, :msg, :String)
+
+log_tbl.insert(DateTime.now, 'This is a log message')
+log_tbl.insert(DateTime.now, 'This is a another log message')
+log_tbl.insert(DateTime.now, 'This is the final log message')
+
+p log_tbl.select
+puts;puts
+
+log_tbl.change_column_type(:log_timestamp, :String)
+
+p log_tbl.select
+puts;puts
+
+p log_tbl.field_types
+

data/examples/column_required_test/column_required_test.rb

@@ -0,0 +1,33 @@
+# This script is an example of how to specify that a value is required for a
+# column.
+#
+require 'kirbybase'
+
+db = KirbyBase.new
+
+# If table exists, delete it.
+db.drop_table(:address_book) if db.table_exists?(:address_book)
+
+# Create a table.  Notice how we specify a default value for :category.
+address_book_tbl = db.create_table(:address_book,
+ :firstname, :String, :lastname, :String, :street_address, :String,
+ :city, :String, :phone, :String, 
+ :category, {:DataType=>:String, :Required=>true})
+
+begin
+    # Insert a record.  Notice that I am passing nil for :category.  This
+    # will cause KirbyBase to raise an exception.
+    address_book_tbl.insert('Bruce', 'Wayne', '1234 Bat Cave',
+     'Gotham City', '111-111-1111', nil)
+rescue StandardError => e
+    puts e
+    puts;puts
+end
+
+# Now, let's turn off the required flag for :category.
+address_book_tbl.change_column_required(:category, false)
+
+# And we will attempt to add the record again.
+address_book_tbl.insert('Bruce', 'Wayne', '1234 Bat Cave',
+ 'Gotham City', '111-111-1111', nil)
+

data/examples/crosstab_test/crosstab_test.rb

@@ -0,0 +1,100 @@
+# This script demonstrates how to use crosstab functionality of a
+# KirbyBase result set.  A KirbyBase result set automatically has an
+# equivalent transposed array whereby all of the values of a column are
+# available.  I call this a crosstab, but I am probably using this term
+# incorrectly.  Perhaps the examples below will help explain what I am
+# talking about.
+
+# In this example, we have an order table and an order_item table.  Each
+# record in the order table represents a customer order.  The order_item
+# table holds the detail items for each order. We create a one-to-many link
+# between the order table and the order_item table by providing extra
+# information about the order.items field when we create the order table.
+
+require 'kirbybase'
+
+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 tables exists, delete it.
+db.drop_table(:order) if db.table_exists?(:order)
+db.drop_table(:order_item) if db.table_exists?(:order_item)
+
+# Create an order item table.  This is the child table to the order table.
+# Make sure you create the child table BEFORE you create the parent table
+# so that KirbyBase can take advantage of any indexes that you have defined.
+order_item_tbl = db.create_table(:order_item,
+ :item_id, :Integer,
+ :order_id, :Integer,
+ :descr, :String,
+ :qty, :Integer,
+ :price, :Float,
+ :total, {:DataType=>:Float, :Calculated=>'qty*price'}
+)
+
+# Create an order table.  We are telling KirbyBase that the items field is
+# to be linked to the order_item table by comparing the order.order_id
+# field to the order_item.order_id field.  By specifying :Link_many, we are
+# telling KirbyBase to make this a one-to-many link.  The result of this is
+# that when you do a select, the items field of the order table is going to
+# hold a reference to a ResultSet (i.e. Array) holding all order_item
+# records whose order_id field match the order_id field in the order record.
+order_tbl = db.create_table(:order,
+ :order_id, :Integer,
+ :customer, :String,
+ :items, {:DataType=> :ResultSet, :Link_many=> [:order_id, :order_item,
+ :order_id]}
+)
+
+# Insert some order records.
+order_tbl.insert({:order_id=>345, :customer=>'Ford'})
+order_tbl.insert({:order_id=>454, :customer=>'Microsoft'})
+order_tbl.insert({:order_id=>17, :customer=>'Boeing'})
+
+# Insert some order item records.
+order_item_tbl.insert(1,345,'Steel',30,19.99,nil)
+order_item_tbl.insert(2,345,'Glass',5,4.15,nil)
+order_item_tbl.insert(5,454,'Floppies',750000,0.5,nil)
+order_item_tbl.insert(3,17,'Wheels',200,2500.0,nil)
+order_item_tbl.insert(4,17,'Wings',25,1000000.0,nil)
+
+
+# Print all orders.  Under each order print all items in that order.  Notice
+# that we are able to print the total for each order because we have access
+# to the entire order_items.total column of the result set.  We don't have
+# to loop through all of the order item result set records to add up the
+# total for each order.
+puts "\nPrint all orders:\n"
+order_tbl.select.each do |r|
+    puts "\nid: %3d  customer: %-10s  total charge: %11.2f" % [r.order_id,
+     r.customer, r.items.total.inject { |sum, n| sum + n }]
+
+    r.items.each do |i|
+        puts "\titem:  %-10s %6d * %10.2f = %11.2f" % [i.descr,
+         i.qty, i.price, i.total]
+    end
+end
+puts '-' * 70;puts
+
+# You can even use the ability to access an entire column of values in your
+# select statements.  In this example, we only want to select those orders
+# whose total charges exceeds $100,000.  We can do this because we have
+# access to the entire total column of the child table, order items.
+puts "Print only orders whose total charge exceeds $100,000:\n"
+order_tbl.select { |r| r.items.total.inject { |sum, n| sum+n } > 100000
+ }.each do |r|
+    puts "\nid: %3d  customer: %-10s  total charge: %11.2f" % [r.order_id,
+     r.customer, r.items.total.inject { |sum, n| sum + n }]
+
+    r.items.each do |i|
+        puts "\titem:  %-10s %6d * %10.2f = %11.2f" % [i.descr,
+         i.qty, i.price, i.total]
+    end
+end

data/examples/csv_import_test/csv_import_test.rb

@@ -0,0 +1,31 @@
+#Test of CSV file import.
+
+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(:plane) if db.table_exists?(:plane)
+
+# 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)
+
+# Import csv file.
+puts 'Records imported: %d' % plane_tbl.import_csv('plane.csv')
+
+puts
+
+# Now, lets show that the csv file did, in fact, get imported.
+puts plane_tbl.select(:name, :country, :role, :speed, :range).sort(:name
+ ).to_report

data/examples/csv_import_test/plane.csv

@@ -0,0 +1,11 @@
+FW-190,Germany,Fighter,399,499,1942-12-01,false
+P-51,USA,Fighter,405,1210,1943-06-24,true
+P-47,USA,Fighter,365,888,1943-03-12,false
+B-17,USA,Bomber,315,1400,1937-05-01,true
+Typhoon,Great Britain,Fighter-Bomber,389,690,1944-11-20,false
+Spitfire,Great Britain,Fighter,345,540,1939-02-18,true
+Oscar,Japan,Fighter,361,777,1943-12-31,false
+ME-109,Germany,Fighter,366,514,1936-07-07,true
+JU-88,Germany,Bomber,289,999,1937-01-19,false
+P-39,USA,Fighter,,,,false
+Zero,Japan,Fighter,377,912,1937-05-15,true

data/examples/default_value_test/default_value_test.rb

@@ -0,0 +1,43 @@
+# This script is an example of how to specify a default value for a column.
+#
+require 'kirbybase'
+
+db = KirbyBase.new
+
+# If table exists, delete it.
+db.drop_table(:address_book) if db.table_exists?(:address_book)
+
+# Create a table.  Notice how we specify a default value for :category.
+address_book_tbl = db.create_table(:address_book,
+ :firstname, :String, :lastname, :String, :street_address, :String,
+ :city, :String, :phone, :String, 
+ :category, {:DataType=>:String, :Default=>'Super Hero'})
+
+# Insert a record.  Notice that I am passing nil for :category.  KirbyBase
+# will insert the default value, 'Super Hero', in that field.
+address_book_tbl.insert('Bruce', 'Wayne', '1234 Bat Cave', 'Gotham City',
+ '111-111-1111', nil)
+
+# Insert another record.  Here we supply the value for :category, so
+# KirbyBase will use it instead of the default.
+address_book_tbl.insert('Bugs', 'Bunny', '1234 Rabbit Hole', 'The Forest',
+ '222-222-2222', 'Cartoon Character')
+
+# Now lets change the default value for :category to 'President'.
+address_book_tbl.change_column_default_value(:category, 'President')
+
+# And let's add another record without supplying a value for :category.
+address_book_tbl.insert(firstname='George', lastname='Bush',
+ street_address='1600 Pennsylvania Ave', 'Washington', '333-333-3333', nil)
+
+# Now, let's remove the default value for :category
+address_book_tbl.change_column_default_value(:category, nil)
+
+# And add another record.  We won't specify a value for :category and,
+# KirbyBase will not use a default value, because we removed it.
+address_book_tbl.insert('Silver', 'Surfer', '1234 Galaxy Way',
+ 'Any City', '444-444-4444', nil)
+
+# Now lets print the table out and you will see how all of the defaults
+# worked.
+puts address_book_tbl.select.to_report

data/examples/drop_column_test/drop_column_test.rb

@@ -0,0 +1,24 @@
+#Test of drop_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.drop_column(:speed)
+
+puts plane_tbl.select.to_report

data/examples/indexes_test/add_index_test.rb

@@ -0,0 +1,46 @@
+# This script is an example of how to add an index to an existing table.
+#
+require 'kirbybase'
+
+db = KirbyBase.new
+
+# If table exists, delete it.
+db.drop_table(:address_book) if db.table_exists?(:address_book)
+
+address_book_tbl = db.create_table(:address_book,
+ :firstname, :String, :lastname, :String, :street_address, :String,
+ :city, :String, :phone, :String, :category, :String)
+
+# Insert some contact info records.
+address_book_tbl.insert('Bruce', 'Wayne', '1234 Bat Cave', 'Gotham City',
+ '111-111-1111', 'Super Hero')
+address_book_tbl.insert('Bugs', 'Bunny', '1234 Rabbit Hole', 'The Forest',
+ '222-222-2222', 'Cartoon Character')
+address_book_tbl.insert('George', 'Bush', '1600 Pennsylvania Ave',
+ 'Washington', '333-333-3333', 'President')
+address_book_tbl.insert('Silver', 'Surfer', '1234 Galaxy Way',
+ 'Any City', '444-444-4444', 'Super Hero')
+
+# Select all super heros without using the index.
+address_book_tbl.select { |r| r.category == 'Super Hero' }.each { |r|
+    puts '%s %s %s' % [r.firstname, r.lastname, r.phone]
+}
+puts;puts
+
+address_book_tbl.add_index(:category)
+
+# Now, do the same query, but use the category index.  These
+# select_by_index methods are automatically created by KirbyBase when you
+# specify that a column be indexed.
+address_book_tbl.select_by_category_index { |r|
+ r.category == 'Super Hero' }.each { |r|
+    puts '%s %s %s' % [r.firstname, r.lastname, r.phone]
+}
+puts;puts
+
+address_book_tbl.add_index(:firstname, :lastname)
+
+# Select Bugs Bunny using the firstname+lastname index.
+address_book_tbl.select_by_firstname_lastname_index { |r|
+    r.firstname == 'Bugs' and r.lastname == 'Bunny'
+}.each { |r| puts '%s %s %s' % [r.firstname, r.lastname, r.phone] }

data/examples/indexes_test/drop_index_test.rb

@@ -0,0 +1,66 @@
+# This script is an example of how to drop an index from an existing table.
+#
+require 'kirbybase'
+
+db = KirbyBase.new
+
+# If table exists, delete it.
+db.drop_table(:address_book) if db.table_exists?(:address_book)
+
+address_book_tbl = db.create_table(:address_book,
+ :firstname, {:DataType=>:String, :Index=>1},
+ :lastname, {:DataType=>:String, :Index=>1},
+ :street_address, :String,
+ :city, :String,
+ :phone, :String,
+ :category, {:DataType=>:String, :Index=>2}
+)
+
+# Insert some contact info records.
+address_book_tbl.insert('Bruce', 'Wayne', '1234 Bat Cave', 'Gotham City',
+ '111-111-1111', 'Super Hero')
+address_book_tbl.insert('Bugs', 'Bunny', '1234 Rabbit Hole', 'The Forest',
+ '222-222-2222', 'Cartoon Character')
+address_book_tbl.insert('George', 'Bush', '1600 Pennsylvania Ave',
+ 'Washington', '333-333-3333', 'President')
+address_book_tbl.insert('Silver', 'Surfer', '1234 Galaxy Way',
+ 'Any City', '444-444-4444', 'Super Hero')
+
+p address_book_tbl.field_indexes
+puts;puts
+
+address_book_tbl.select_by_category_index { |r|
+ r.category == 'Super Hero' }.each { |r|
+    puts '%s %s %s' % [r.firstname, r.lastname, r.phone]
+}
+puts;puts
+
+address_book_tbl.drop_index(:category)
+
+begin
+    address_book_tbl.select_by_category_index { |r|
+     r.category == 'Super Hero' }.each { |r|
+        puts '%s %s %s' % [r.firstname, r.lastname, r.phone]
+    }
+rescue StandardError => e
+    puts e
+    puts;puts
+end
+
+# Select Bugs Bunny using the firstname+lastname index.
+address_book_tbl.select_by_firstname_lastname_index { |r|
+    r.firstname == 'Bugs' and r.lastname == 'Bunny'
+}.each { |r| puts '%s %s %s' % [r.firstname, r.lastname, r.phone] }
+
+address_book_tbl.drop_index(:firstname, :lastname)
+
+begin
+    address_book_tbl.select_by_firstname_lastname_index { |r|
+        r.firstname == 'Bugs' and r.lastname == 'Bunny'
+    }.each { |r| puts '%s %s %s' % [r.firstname, r.lastname, r.phone] }
+rescue StandardError => e
+    puts e
+    puts;puts
+end
+
+p address_book_tbl.field_indexes

data/examples/indexes_test/index_test.rb

@@ -0,0 +1,71 @@
+# This script is an example of how to use indexes in KirbyBase.  Indexes
+# allow for faster queries on large datasets.
+#
+# To use indexes, you must first specify which fields are to be indexed.
+# You do this at table creation time.  Both single and compound indexes can
+# be created.  Then, when performing a select query, you simply use the
+# automatically created select_by_?????_index method, where ????? is
+# replaced by the name(s) of the indexed field(s).  That's it.  Everything
+# else concerning building and maintaing indexes is done by KirbyBase.
+require 'kirbybase'
+
+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(:address_book) if db.table_exists?(:address_book)
+
+# Here we are creating a table to hold contact info.  We are going to create
+# two indexes.  One index is going to be a compound index containing the
+# firstname and lastname fields.  Notice how we group the firstname and
+# lastname fields into one index by specifying :Index=>1 for both of them.
+# This just tells KirbyBase that the two fields should be combined into one
+# compound index because they both are using the same index number.  The
+# second index is going to be a single index containing the category field.
+# Since we want it to be a separate index, we simply use the next available
+# number, 2, as the value of it's :Index key.
+address_book_tbl = db.create_table(:address_book,
+ :firstname, {:DataType=>:String, :Index=>1},
+ :lastname, {:DataType=>:String, :Index=>1},
+ :street_address, :String,
+ :city, :String,
+ :phone, :String,
+ :category, {:DataType=>:String, :Index=>2}
+)
+
+# Insert some contact info records.
+address_book_tbl.insert('Bruce', 'Wayne', '1234 Bat Cave', 'Gotham City',
+ '111-111-1111', 'Super Hero')
+address_book_tbl.insert('Bugs', 'Bunny', '1234 Rabbit Hole', 'The Forest',
+ '222-222-2222', 'Cartoon Character')
+address_book_tbl.insert('George', 'Bush', '1600 Pennsylvania Ave',
+ 'Washington', '333-333-3333', 'President')
+address_book_tbl.insert('Silver', 'Surfer', '1234 Galaxy Way',
+ 'Any City', '444-444-4444', 'Super Hero')
+
+# Select all super heros without using the index.
+address_book_tbl.select { |r| r.category == 'Super Hero' }.each { |r|
+    puts '%s %s %s' % [r.firstname, r.lastname, r.phone]
+}
+puts;puts
+# Now, do the same query, but use the category index.  These
+# select_by_index methods are automatically created by KirbyBase, based on
+# the indexes you specified at table creation.
+address_book_tbl.select_by_category_index { |r|
+ r.category == 'Super Hero' }.each { |r|
+    puts '%s %s %s' % [r.firstname, r.lastname, r.phone]
+}
+puts;puts
+# Select Bugs Bunny using the firstname+lastname index.
+address_book_tbl.select_by_firstname_lastname_index { |r|
+    r.firstname == 'Bugs' and r.lastname == 'Bunny'
+}.each { |r| puts '%s %s %s' % [r.firstname, r.lastname, r.phone] }
+
+p address_book_tbl.field_indexes