mongoose 0.1.0

data/README

@@ -0,0 +1,136 @@
+= Mongoose 0.1.0
+
+A database management system written in Ruby.  It has an ActiveRecord-like
+interface, uses Skiplists for its indexing, and Marshal for its data 
+serialization.  I named it Mongoose, because, like Rudyard Kipling's 
+ Rikki-Tikki-Tavi, my aim is for it to be small, quick, and friendly. 
+
+
+== Credits
+
+Thanks to Logan Capaldo for letting me steal a lot of the code from KirbyRecord.
+
+Thanks to Ezra Zygmuntowicz and Fabien Franzen, whose ez_where Rails plugin, 
+provided much of the inspiration for the query language.
+
+Thanks to everyone who gave me feedback on KirbyBase.  I have tried to put all
+the lessons learned from developing that library to good use here.
+
+
+== Installation
+
+Unpack the file you downloaded.  Execute "ruby setup.rb".
+
+
+== Features
+
+* Pure Ruby, with no external dependencies.
+* ActiveRecord-like interface.
+* Fast queries on indexed fields (Up to 10x faster than KirbyBase).  Indexes
+  are Skiplists, which are just plain fun to play around with.
+* Not an in-memory database.  Data is only read in from disk when needed and
+  changes are immediately written out to disk.
+* In-memory indexes are initialized from dedicated index files, rather than
+  rebuilt from scratch upon database initialization (like KirbyBase does).  This
+  can greatly reduce startup times.
+* Supports any datatype that Marshal supports.
+* Table relations supported via has_one, has_many.
+
+
+== Documentation
+
+Right now, documentation is a little light.  It will get better.  See the 
+examples directory for examples of how to use Mongoose.  Here's a quick
+tutorial:
+
+require 'mongoose'
+
+# Create a class for your table.
+class Plane < Mongoose::Table
+  validates_presence_of :name, :speed
+end
+
+# Create a database instance.
+db = Mongoose::Database.new
+
+# Create new table.  Notice how you specify whether a column is indexed or not.
+db.create_table(:plane) do |tbl|
+  tbl.add_indexed_column(:plane_name, :string)
+  tbl.add_column(:country, :string)
+  tbl.add_indexed_column(:speed, :integer)
+  tbl.add_column(:range, :integer)
+end
+
+# Add a record.
+rec = Plane.new
+rec.plane_name = 'P-51'
+rec.country = 'USA'
+rec.speed = 402
+rec.range = 1205
+rec.save 
+
+# Various ways to find a record; should be familiar to ActiveRecord users.
+Plane.find(1)  # Find record with id equal 1.
+
+Plane.find { |plane| plane.speed > 350 }  # Find all planes with speed > 350.
+
+Plane.find  # Find all records.
+
+Plane.find(:first) { |plane| plane.country == 'USA' }
+
+Plane.find do |plane|                 # Find all planes from either USA or
+  plane.any do                        # Great Britain with speed > 400.
+    plane.country == 'USA'
+    plane.country == 'Great Britain'
+  end
+  plane.speed > 400
+end
+
+# Delete a record.
+Plane.find(1).destroy
+
+== Manifest
+
+* README - this file
+* install.rb - install script
+* changes.txt - history of changes.
+* lib directory - dbms module
+* test directory - unit tests
+* examples directory - many example scripts demonstrating features.
+* images directory - images used in manual.
+
+
+== Author
+
+Written in 2006 by Jamey Cribbs <mailto:jcribbs@netpromi.com>
+
+
+== License
+
+Mongoose is distributed under the same license as Ruby.
+
+Copyright (c) 2006 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@netpromi.com
+
+
+== Home Page
+
+http://rubyforge.org/projects/mongoose/

data/changes.txt

@@ -0,0 +1,2 @@
+2006-07-19:: Version 0.1.0
+* Initial release.

data/example/relation_examples.rb

@@ -0,0 +1,117 @@
+begin
+  require 'rubygems'
+  require_gem 'Mongoose'
+rescue LoadError
+  require 'mongoose'
+end
+
+
+Dir.glob('[plane|pilot|flight]*.mg?').each do |filename|
+  File.delete(filename)
+end
+
+class Pilot < Mongoose::Table
+  has_one :plane
+  has_many :flights
+end
+
+class Plane < Mongoose::Table
+  belongs_to :pilot
+end
+
+class Flight < Mongoose::Table
+  belongs_to :pilot
+end
+
+# Create a database instance.
+db = Mongoose::Database.new
+
+# Create tables.
+db.create_table(:pilot) do |tbl|
+  tbl.add_indexed_column(:pilot_name, :string)
+  tbl.add_column(:years_flying, :integer)
+end
+db.create_table(:plane) do |tbl|
+  tbl.add_indexed_column(:plane_name, :string)
+  tbl.add_column(:country, :string)
+  tbl.add_indexed_column(:speed, :integer)
+  tbl.add_column(:range, :integer)
+  tbl.add_column(:pilot_id, :integer)
+end
+db.create_table(:flight) do |tbl|
+  tbl.add_column(:origin, :string)
+  tbl.add_column(:destination, :string)
+  tbl.add_column(:pilot_id, :integer)
+end
+
+# Create Pilot records.
+doolittle = Pilot.new
+doolittle.pilot_name = 'Doolitle, James'
+doolittle.years_flying = 15
+doolittle.save
+
+amelia = Pilot.new
+amelia.pilot_name = 'Earhart, Amelia'
+amelia.years_flying = 10
+amelia.save
+
+# Create Plane records.
+rec = Plane.new
+rec.plane_name = 'P-51'
+rec.country = 'USA'
+rec.speed = 402
+rec.range = 1205
+rec.pilot_id = doolittle.id
+rec.save 
+
+rec = Plane.new
+rec.plane_name = 'Spitfire'
+rec.country = 'Great Britain'
+rec.speed = 333
+rec.range = 454
+rec.pilot_id = amelia.id
+rec.save 
+
+# Create Flight records.
+rec = Flight.new
+rec.pilot_id = doolittle.id
+rec.origin = 'Army'
+rec.destination = 'Nowhere'
+rec.save
+
+rec = Flight.new
+rec.pilot_id = amelia.id
+rec.origin = 'USA'
+rec.destination = 'France'
+
+rec.save
+rec = Flight.new
+rec.pilot_id = amelia.id
+rec.origin = 'USA'
+rec.destination = 'Phillipines'
+rec.save
+
+rec = Flight.new
+rec.pilot_id = amelia.id
+rec.origin = 'China'
+rec.destination = 'Unknown'
+rec.save
+
+puts "\n\nFind Jimmy Doolittle"
+rec = Pilot.find(1)
+p rec
+puts "\nShow his plane"
+p rec.plane
+
+puts "\n\nShow flights that belong to Amelia"
+p amelia.flights
+
+puts "\n\nAdd another flight to Amelia's collection and redisplay"
+rec = Flight.new
+rec.pilot_id = amelia.id
+rec.origin = 'Tuscon'
+rec.destination = 'Phoenix'
+amelia.flights << rec
+p amelia.flights
+
+db.close

data/example/simple_examples.rb

@@ -0,0 +1,117 @@
+begin
+  require 'rubygems'
+  require_gem 'Mongoose'
+rescue LoadError
+  require 'mongoose'
+end
+
+
+Dir.glob('[plane|pilot|flight]*.mg?').each do |filename|
+  File.delete(filename)
+end
+
+class Plane < Mongoose::Table
+  validates_presence_of :name, :speed
+end
+
+# Create a database instance.
+db = Mongoose::Database.new
+
+# Create new table.  Notice how you specify whether a column is indexed or not.
+db.create_table(:plane) do |tbl|
+  tbl.add_indexed_column(:plane_name, :string)
+  tbl.add_column(:country, :string)
+  tbl.add_indexed_column(:speed, :integer)
+  tbl.add_column(:range, :integer)
+end
+
+# Add records.
+rec = Plane.new
+rec.plane_name = 'P-51'
+rec.country = 'USA'
+rec.speed = 402
+rec.range = 1205
+rec.save 
+
+rec2 = Plane.new
+rec2.plane_name = 'Spitfire'
+rec2.country = 'Great Britain'
+rec2.speed = 333
+rec2.range = 454
+rec2.save 
+
+rec3 = Plane.new
+rec3.plane_name = 'ME-109'
+rec3.country = 'Germany'
+rec3.speed = 354
+rec3.range = 501
+rec3.save
+
+rec4 = Plane.new
+rec4.plane_name = 'P-39'
+rec4.country = 'USA'
+rec4.range = 701
+
+# Forgot value for speed, which is a required field.
+begin
+  rec4.save
+rescue RuntimeError => e
+  puts e
+end
+
+rec4.speed = 339
+rec4.save
+
+puts "\n\nFind P-51 record by ID"
+p_51 = Plane.find(1)
+p p_51
+
+if p_51
+  # Change speed on P-51 record and save.
+  p_51.speed = 405
+  p_51.save
+end
+
+puts "\n\nFind all records with speed greater than 350 mph"
+result = Plane.find { |plane| plane.speed > 350 }
+p result
+
+puts "\n\nFind all US planes with speed greater than 300 mph"
+result = Plane.find { |plane| plane.country == 'USA' and plane.speed > 300 }
+p result
+
+puts "\n\nFind all British planes with speed greater than 300 mph"
+result = Plane.find do |plane| 
+  plane.country == 'Great Britain' and plane.speed > 300 
+end
+p result
+
+puts "\n\nFind all Allied planes"
+result = Plane.find do |plane| 
+  plane.any do
+    plane.country == 'USA'
+    plane.country == 'Great Britain'
+  end
+end
+p result
+
+puts "\n\nFind all Allied planes with speed greater than 400 mph"
+result = Plane.find do |plane| 
+  plane.any do
+    plane.country == 'USA'
+    plane.country == 'Great Britain'
+  end
+  plane.speed > 400
+end
+p result
+
+# Delete Spitfire record.
+spitfire = Plane.find(:first) { |plane| plane.plane_name == 'Spitfire' }
+
+spitfire.destroy if spitfire
+
+puts "\n\nFind all records in table."
+result = Plane.find
+p result
+
+db.close

data/lib/mongoose.rb

@@ -0,0 +1,45 @@
+require 'yaml'
+require 'mongoose/database'
+require 'mongoose/table'
+require 'mongoose/column'
+require 'mongoose/skiplist'
+require 'mongoose/linear_search'
+require 'mongoose/util'
+
+#
+# :main:Mongoose
+# :title:Mongoose Module Documentation
+# Mongoose is a library that implements a database management system.  It is
+# written in Ruby so it runs anywhere Ruby runs.  It uses Skiplists for its
+# indexes, so queries are fast.  It uses Marshal to store its data so data
+# retrieval is fast.
+#
+# Author::    Jamey Cribbs (mailto:jcribbs@netpromi.com)
+# Homepage::  http://rubyforge.org/projects/mongoose/
+# Copyright:: Copyright (c) 2006 NetPro Technologies, LLC
+# License::   Distributed under the same terms as Ruby
+# History:
+# 2006-07-19:: Version 0.1.0
+# * Initial release.
+#
+#
+module Mongoose
+
+DATA_TYPES = [:string, :integer, :float, :time, :date, :datetime, :boolean]
+TBL_EXT = '.mgt'
+TBL_HDR_EXT = '.mgh'
+TBL_IDX_EXT = '.mgi'
+
+end
+
+#---------------------------------------------------------------------------
+# Object
+#---------------------------------------------------------------------------
+class Object
+  def full_const_get(name)
+      list = name.split("::")
+      obj = Object
+      list.each {|x| obj = obj.const_get(x) }
+      obj
+  end
+end

data/lib/mongoose/column.rb

@@ -0,0 +1,286 @@
+require 'forwardable'
+
+module Mongoose
+
+#-------------------------------------------------------------------------------
+# BaseColumn class
+#-------------------------------------------------------------------------------
+class BaseColumn
+  attr_reader :name, :data_type, :tbl_class
+  attr_writer :required
+
+  private_class_method :new
+
+  def self.valid_data_type?(data_type)
+    DATA_TYPES.include?(data_type)
+  end
+
+  def self.create(tbl_class, name, col_def)
+    return new(tbl_class, name, col_def)
+  end
+
+  def initialize(tbl_class, name, col_def)
+    @tbl_class = tbl_class
+    @name = name
+    @data_type = col_def
+    @indexed = false
+    @required = false
+  end
+
+  def indexed?
+    @indexed
+  end
+
+  def required?
+    @required
+  end
+
+  def close
+  end
+
+end  
+
+
+#-------------------------------------------------------------------------------
+# Column class
+#-------------------------------------------------------------------------------
+class Column < BaseColumn
+  def initialize(tbl_class, name, col_def)
+    super
+    @idx = LinearSearch.new(self)
+  end
+
+  def store(key, value)
+  end
+
+  def remove(key, value)
+  end
+
+  def >(other)
+    @tbl_class.query << [@idx, :>, other]
+  end
+
+  def >=(other)
+    @tbl_class.query << [@idx, :>=, other]
+  end
+
+  def <(other)
+    @tbl_class.query << [@idx, :<, other]
+  end
+
+  def <=(other)
+    @tbl_class.query << [@idx, :<=, other]
+  end
+
+  def ==(other)
+    @tbl_class.query << [@idx, :==, other]
+  end
+
+  def between(*other)
+    @tbl_class.query << [@idx, :between, other]
+  end
+
+  def one_of(*other)
+    @tbl_class.query << [@idx, :one_of, other]
+  end
+end
+
+
+#-------------------------------------------------------------------------------
+# IndexedColumn class
+#-------------------------------------------------------------------------------
+class IndexedColumn < BaseColumn
+  attr_reader :idx, :index_file_name
+
+  #-----------------------------------------------------------------------------
+  # initialize
+  #-----------------------------------------------------------------------------
+  def initialize(tbl_class, name, col_def)
+    super
+    @indexed = true
+
+    @index_file_name = File.join(@tbl_class.db.path, 
+     @tbl_class.table_name.to_s + '_' + @name.to_s + TBL_IDX_EXT)
+  end
+
+  #-----------------------------------------------------------------------------
+  # close
+  #-----------------------------------------------------------------------------
+  def close
+    rebuild_index_file if index_file_out_of_date?
+  end 
+
+  def init_index
+    if File.exists?(@index_file_name) and not index_file_out_of_date?
+      rebuild_index_from_index_file
+    else
+      rebuild_index_from_table
+    end
+  end
+
+  #-----------------------------------------------------------------------------
+  # with_index_file
+  #-----------------------------------------------------------------------------
+  def with_index_file(access='r')
+    begin
+      yield fptr = open(@index_file_name, access)
+    ensure
+      fptr.close
+    end
+  end
+
+  #-----------------------------------------------------------------------------
+  # index_file_out_of_date?
+  #-----------------------------------------------------------------------------
+  def index_file_out_of_date?
+    if not File.exists?(@index_file_name) or (File.mtime(File.join(
+     @tbl_class.db.path, @tbl_class.table_name.to_s + TBL_EXT)) > 
+     File.mtime(@index_file_name))
+      true
+    else
+      false
+    end
+  end
+end  
+
+
+#-------------------------------------------------------------------------------
+# SkipListIndexColumn class
+#-------------------------------------------------------------------------------
+class SkipListIndexColumn < IndexedColumn
+  def initialize(tbl_class, name, col_def)
+    @idx = SkipList.new
+    super
+  end
+
+  def clear_index
+    @idx = SkipList.new
+  end
+
+  def >(other)
+    @tbl_class.query << [@idx, :>, other]
+  end
+
+  def >=(other)
+    @tbl_class.query << [@idx, :>=, other]
+  end
+
+  def <(other)
+    @tbl_class.query << [@idx, :<, other]
+  end
+
+  def <=(other)
+    @tbl_class.query << [@idx, :<=, other]
+  end
+
+  def ==(other)
+    @tbl_class.query << [@idx, :==, other]
+  end
+
+  def search(other)
+    @tbl_class.query << [@idx, :search, other]
+  end
+
+  def between(*other)
+    @tbl_class.query << [@idx, :between, other]
+  end
+
+  def one_of(*other)
+    @tbl_class.query << [@idx, :one_of, other]
+  end
+
+  def rebuild_index_file
+    with_index_file('w') do |fptr|
+      @idx.each { |k,v| fptr.write(Marshal.dump([k, v])) }
+    end
+  end
+
+  def rebuild_index_from_table
+    clear_index
+    i = @tbl_class.columns.index(self)
+
+    @tbl_class.get_all_recs do |rec, fpos|
+      add_index_rec(rec[i], rec[0]) unless rec[i].nil?
+    end
+  end
+
+  def rebuild_index_from_index_file
+    clear_index
+
+    with_index_file do |fptr|
+      begin
+        while true
+          @idx.load(*Marshal.load(fptr))
+        end
+      rescue EOFError
+      end
+    end
+  end
+
+  def add_index_rec(key, value)
+    @idx.store(key, value)
+  end
+
+  def remove_index_rec(key, value)
+    @idx.remove(key, value)
+  end
+end  
+
+
+#-------------------------------------------------------------------------------
+# IDColumn class
+#-------------------------------------------------------------------------------
+class IDColumn < IndexedColumn
+  extend Forwardable
+
+  def_delegator(:@idx, :[], :[])
+  def_delegator(:@idx, :keys, :keys)
+#  def_delegator(:@idx, :delete, :remove)
+
+  def initialize(tbl_class, name, col_def)
+    @idx = {}
+    super
+  end
+
+  def clear_index
+    @idx = {}
+  end
+
+  def rebuild_index_file
+    with_index_file('w') do |fptr|
+#      @idx.each_pair { |k,v| fptr.write(Marshal.dump([k, v])) }
+      fptr.write(Marshal.dump(@idx))
+    end
+  end
+
+  def rebuild_index_from_table
+    clear_index
+    @tbl_class.get_all_recs do |rec, fpos|
+      add_index_rec(rec[0], fpos)
+    end
+  end
+
+  def rebuild_index_from_index_file
+    clear_index
+
+    with_index_file do |fptr|
+#      begin
+#        while true
+#          add_index_rec(*Marshal.load(fptr))
+#        end
+#      rescue EOFError
+#      end
+    @idx = Marshal.load(fptr)
+    end
+  end
+
+  def add_index_rec(id, fpos)
+    @idx[id] = fpos
+  end
+
+  def remove_index_rec(id)
+    @idx.delete(id)
+  end
+end
+
+end