rhubarb 0.2.0 → 0.2.1

data/CHANGES

@@ -1,4 +1,15 @@
-version 0.2.0
+version 0.2.1
+
+*  Code cleanups
+
+*  Performance improvements
+
+*  Rhubarb now no longer uses explicit transactions internally.  I have
+   become convinced that Rhubarb's use of transactions was overly
+   cautious; removing these enables Rhubarb users to use transactions
+   in their own code.
+
+version 0.2.0 (eecc7cceda993ea9c20cd952aa709ebe470a9f3d)
 
 *  First standalone release of Rhubarb.  Previous releases are included
    with SPQR.

data/Rakefile

@@ -1,6 +1,23 @@
 require 'rubygems'
 require 'rake'
 
+begin 
+  require 'metric_fu'
+  MetricFu::Configuration.run do |config|
+    #define which metrics you want to use
+    config.metrics  = [:flog, :flay, :reek, :roodi]
+    config.graphs   = [:flog, :flay, :reek, :roodi]
+    config.flay     = { :dirs_to_flay => ['lib'],
+                          :minimum_score => 10  } 
+    config.flog     = { :dirs_to_flog => ['lib']  }
+    config.reek     = { :dirs_to_reek => ['lib']  }
+    config.roodi    = { :dirs_to_roodi => ['lib'] }
+    config.graph_engine = :bluff
+  end
+rescue LoadError
+  nil
+end
+
 begin
   require 'jeweler'
   Jeweler::Tasks.new do |gem|
@@ -24,6 +41,65 @@ def pkg_version
   return version.chomp
 end
 
+def pkg_version
+  version = File.exist?('VERSION') ? File.read('VERSION') : ""
+  return version.chomp
+end
+
+def pkg_name
+  return 'ruby-rhubarb'
+end
+
+def pkg_spec
+  return pkg_name() + ".spec"
+end
+
+def pkg_rel
+  return `grep -i 'define rel' #{pkg_spec} | awk '{print $3}'`.chomp()
+end
+
+def pkg_source
+  return pkg_name() + "-" + pkg_version() + "-" + pkg_rel() + ".tar.gz"
+end
+
+def pkg_dir
+  return pkg_name() + "-" + pkg_version()
+end
+
+def rpm_dirs
+  return %w{BUILD BUILDROOT RPMS SOURCES SPECS SRPMS}
+end
+
+desc "create RPMs"
+task :rpms => [:build, :tarball] do
+  require 'fileutils'
+  FileUtils.cp pkg_spec(), 'SPECS'
+  sh "rpmbuild --define=\"_topdir \${PWD}\" -ba SPECS/#{pkg_spec}"
+end
+
+desc "Create a tarball"
+task :tarball => :make_rpmdirs do
+  require 'fileutils'
+  FileUtils.cp_r 'lib', pkg_dir()
+  FileUtils.cp ['LICENSE', 'README.rdoc', 'CHANGES', 'TODO', 'VERSION'], pkg_dir()
+  sh "tar -cf #{pkg_source} #{pkg_dir}"
+  FileUtils.mv pkg_source(), 'SOURCES'
+end
+
+desc "Make dirs for building RPM"
+task :make_rpmdirs => :rpm_clean do
+  require 'fileutils'
+  FileUtils.mkdir pkg_dir()
+  FileUtils.mkdir rpm_dirs()
+end
+
+desc "Cleanup after an RPM build"
+task :rpm_clean do
+  require 'fileutils'
+  FileUtils.rm_r pkg_dir(), :force => true
+  FileUtils.rm_r rpm_dirs(), :force => true
+end
+
 require 'spec/rake/spectask'
 Spec::Rake::SpecTask.new(:spec) do |spec|
   spec.libs << 'lib' << 'spec'

data/TODO

@@ -4,6 +4,7 @@
 * Bring code coverage up to 100%
 * Documentation
 * Standalone examples (i.e. not just "please see the test suite")
+* Resolve issues related to using prepared statements
 
 Legend:
 

data/VERSION

@@ -1 +1 @@
-0.2.0
+0.2.1

data/lib/rhubarb/classmixins.rb

@@ -0,0 +1,274 @@
+# Class mixins for persisting classes.  Part of Rhubarb.
+#
+# Copyright (c) 2009--2010 Red Hat, Inc.
+#
+# Author:  William Benton (willb@redhat.com)
+# 
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+# 
+#     http://www.apache.org/licenses/LICENSE-2.0
+
+require 'rhubarb/mixins/freshness'
+
+module Rhubarb
+  # Methods mixed in to the class object of a persisting class
+  module PersistingClassMixins 
+    # Returns the name of the database table modeled by this class.
+    # Defaults to the name of the class (sans module names)
+    def table_name
+      @table_name ||= self.name.split("::").pop.downcase  
+    end
+
+    # Enables setting the table name to a custom name
+    def declare_table_name(nm)
+      @table_name = nm
+    end
+    
+    alias table_name= declare_table_name
+
+    # Models a foreign-key relationship. +options+ is a hash of options, which include
+    # +:column => + _name_::  specifies the name of the column to reference in +klass+ (defaults to row id)
+    # +:on_delete => :cascade+:: specifies that deleting the referenced row in +klass+ will delete all rows referencing that row through this reference
+    def references(table, options={})
+      Reference.new(table, options)
+    end
+
+    # Models a CHECK constraint.
+    def check(condition)
+      "check (#{condition})"
+    end
+
+    # Returns an object corresponding to the row with the given ID, or +nil+ if no such row exists.
+    def find(id)
+      tup = self.find_tuple(id)
+      tup ? self.new(tup) : nil
+    end
+    
+    alias find_by_id find
+
+    def find_by(arg_hash)
+      arg_hash = arg_hash.dup
+      valid_cols = self.colnames.intersection arg_hash.keys
+      select_criteria = valid_cols.map {|col| "#{col.to_s} = #{col.inspect}"}.join(" AND ")
+      arg_hash.each {|k,v| arg_hash[k] = v.row_id if v.respond_to? :row_id}
+
+      self.db.execute("select * from #{table_name} where #{select_criteria} order by row_id", arg_hash).map {|tup| self.new(tup) }
+    end
+
+    # Does what it says on the tin.  Since this will allocate an object for each row, it isn't recomended for huge tables.
+    def find_all
+      self.db.execute("SELECT * from #{table_name}").map {|tup| self.new(tup)}
+    end
+
+    def delete_all
+      self.db.execute("DELETE from #{table_name}")
+    end
+
+    # Declares a query method named +name+ and adds it to this class.  The query method returns a list of objects corresponding to the rows returned by executing "+SELECT * FROM+ _table_ +WHERE+ _query_" on the database.
+    def declare_query(name, query)
+      declare_custom_query(name, "select * from __TABLE__ where #{query}")
+    end
+
+    # Declares a custom query method named +name+, and adds it to this class.  The custom query method returns a list of objects corresponding to the rows returned by executing +query+ on the database.  +query+ should select all fields (with +SELECT *+).  If +query+ includes the string +\_\_TABLE\_\_+, it will be expanded to the table name.  Typically, you will want to use +declare\_query+ instead; this method is most useful for self-joins.
+    def declare_custom_query(name, query)
+      klass = (class << self; self end)
+      klass.class_eval do
+        define_method name.to_s do |*args|
+          # handle reference parameters
+          args = args.map {|arg| Util::rhubarb_fk_identity(arg)}
+
+          res = self.db.execute(query.gsub("__TABLE__", "#{self.table_name}"), args)
+          res.map {|row| self.new(row) }        
+        end
+      end
+    end
+
+    def declare_index_on(*fields)
+      @creation_callbacks << Proc.new do
+        idx_name = "idx_#{self.table_name}__#{fields.join('__')}__#{@creation_callbacks.size}"
+        creation_cmd = "create index #{idx_name} on #{self.table_name} (#{fields.join(', ')})"
+        self.db.execute(creation_cmd)
+      end if fields.size > 0
+    end
+
+    # Adds a column named +cname+ to this table declaration, and adds the following methods to the class:
+    # * accessors for +cname+, called +cname+ and +cname=+
+    # * +find\_by\_cname+ and +find\_first\_by\_cname+ methods, which return a list of rows and the first row that have the given value for +cname+, respectively
+    # If the column references a column in another table (given via a +references(...)+ argument to +quals+), then add triggers to the database to ensure referential integrity and cascade-on-delete (if specified)
+    def declare_column(cname, kind, *quals)
+      ensure_accessors
+
+      find_method_name = "find_by_#{cname}".to_sym
+      find_first_method_name = "find_first_by_#{cname}".to_sym
+      find_query = "select * from #{table_name} where #{cname} = ?"
+
+      get_method_name = "#{cname}".to_sym
+      set_method_name = "#{cname}=".to_sym
+
+      # does this column reference another table?
+      rf = quals.find {|q| q.class == Reference}
+      if rf
+        self.refs[cname] = rf
+      end
+
+      # add a find for this column (a class method)
+      klass = (class << self; self end)
+      klass.class_eval do 
+        define_method find_method_name do |arg|
+          res = self.db.execute(find_query, arg)
+          res.map {|row| self.new(row)}
+        end
+
+        define_method find_first_method_name do |arg|
+          res = self.db.get_first_row(find_query, arg)
+          res ? self.new(res) : nil
+        end
+      end
+
+      self.colnames.merge([cname])
+      self.columns << Column.new(cname, kind, quals)
+
+      # add accessors
+      define_method get_method_name do
+        freshen
+        return @tuple["#{cname}"] if @tuple
+        nil
+      end
+
+      if not rf
+        define_method set_method_name do |arg|
+          @tuple["#{cname}"] = arg
+          update cname, arg
+        end      
+      else
+        # this column references another table; create a set 
+        # method that can handle either row objects or row IDs
+        define_method set_method_name do |arg|
+          freshen
+
+          arg_id = nil
+
+          if arg.class == Fixnum
+            arg_id = arg
+            arg = rf.referent.find arg_id
+          else
+            arg_id = arg.row_id
+          end
+          @tuple["#{cname}"] = arg
+
+          update cname, arg_id
+        end
+
+        # Finally, add appropriate triggers to ensure referential integrity.
+        # If rf has an on_delete trigger, also add the necessary
+        # triggers to cascade deletes. 
+        # Note that we do not support update triggers, since the API does 
+        # not expose the capacity to change row IDs.
+        
+        rtable = rf.referent.table_name
+
+        self.creation_callbacks << Proc.new do   
+          @ccount ||= 0
+
+          insert_trigger_name, delete_trigger_name = %w{insert delete}.map {|op| "ri_#{op}_#{self.table_name}_#{@ccount}_#{rtable}" } 
+
+          self.db.execute_batch("CREATE TRIGGER #{insert_trigger_name} BEFORE INSERT ON \"#{self.table_name}\" WHEN new.\"#{cname}\" IS NOT NULL AND NOT EXISTS (SELECT 1 FROM \"#{rtable}\" WHERE new.\"#{cname}\" == \"#{rf.column}\") BEGIN SELECT RAISE(ABORT, 'constraint #{insert_trigger_name} (#{rtable} missing foreign key row) failed'); END;")
+
+          self.db.execute_batch("CREATE TRIGGER #{delete_trigger_name} BEFORE DELETE ON \"#{rtable}\" WHEN EXISTS (SELECT 1 FROM \"#{self.table_name}\" WHERE old.\"#{rf.column}\" == \"#{cname}\") BEGIN DELETE FROM \"#{self.table_name}\" WHERE \"#{cname}\" = old.\"#{rf.column}\"; END;") if rf.options[:on_delete] == :cascade
+
+          @ccount = @ccount + 1
+        end
+      end
+    end
+
+    # Declares a constraint.  Only check constraints are supported; see
+    # the check method.
+    def declare_constraint(cname, kind, *details)
+      ensure_accessors
+      @constraints << "constraint #{cname} #{kind} #{details.join(" ")}"
+    end
+
+    # Creates a new row in the table with the supplied column values.
+    # May throw a SQLite3::SQLException.
+    def create(*args)
+      new_row = args[0]
+      new_row[:created] = new_row[:updated] = Util::timestamp
+
+      cols = colnames.intersection new_row.keys
+      colspec, valspec = [:to_s, :inspect].map {|msg| (cols.map {|col| col.send(msg)}).join(", ")}
+      res = nil
+
+      # resolve any references in the args
+      new_row.each do |column,value|
+        new_row[column] = Util::rhubarb_fk_identity(value)
+      end
+
+      stmt = "insert into #{table_name} (#{colspec}) values (#{valspec})"
+      db.execute(stmt, new_row)
+      res = find(db.last_insert_row_id)
+      
+      res
+    end
+
+    # Returns a string consisting of the DDL statement to create a table
+    # corresponding to this class. 
+    def table_decl
+      ddlspecs = [columns.join(", "), constraints.join(", ")].reject {|str| str.size==0}.join(", ")
+      "create table #{table_name} (#{ddlspecs});"
+    end
+
+    # Creates a table in the database corresponding to this class.
+    def create_table(dbkey=:default)
+      self.db ||= Persistence::dbs[dbkey] unless @explicitdb
+      self.db.execute(table_decl)
+      @creation_callbacks.each {|func| func.call}
+    end
+
+    def db
+      @db || Persistence::db
+    end
+
+    def db=(dbo)
+      @explicitdb = true
+      @db = dbo
+    end
+
+    # Ensure that all the necessary accessors on our class instance are defined 
+    # and that all metaclass fields have the appropriate values
+    def ensure_accessors
+      # Define singleton accessors
+      if not self.respond_to? :columns
+        class << self
+          # Arrays of columns, column names, and column constraints.
+          # Note that colnames does not contain id, created, or updated.
+          # The API purposefully does not expose the ability to create a
+          # row with a given id, and created and updated values are
+          # maintained automatically by the API.
+          attr_accessor :columns, :colnames, :constraints, :dirtied, :refs, :creation_callbacks
+        end
+      end
+
+      # Ensure singleton fields are initialized
+      self.columns ||= [Column.new(:row_id, :integer, [:primary_key]), Column.new(:created, :integer, []), Column.new(:updated, :integer, [])]
+      self.colnames ||= Set.new [:created, :updated]
+      self.constraints ||= []
+      self.dirtied ||= {}
+      self.refs ||= {}
+      self.creation_callbacks ||= []
+    end
+
+    # Returns the number of rows in the table backing this class
+    def count
+      self.db.get_first_value("select count(row_id) from #{table_name}").to_i
+    end
+
+    def find_tuple(id)
+      self.db.get_first_row("select * from #{table_name} where row_id = ?", id)
+    end
+    
+    include FindFreshest
+    
+  end
+end

data/lib/rhubarb/column.rb

@@ -0,0 +1,32 @@
+# Column abstraction for Rhubarb.
+#
+# Copyright (c) 2009--2010 Red Hat, Inc.
+#
+# Author:  William Benton (willb@redhat.com)
+# 
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+# 
+#     http://www.apache.org/licenses/LICENSE-2.0
+
+module Rhubarb
+  class Column
+    attr_reader :name
+
+    def initialize(name, kind, quals)
+      @name, @kind = name, kind
+      @quals = quals.map {|x| x.to_s.gsub("_", " ") if x.class == Symbol}
+      @quals.map 
+    end
+
+    def to_s
+      qualifiers = @quals.join(" ")
+      if qualifiers == ""
+        "#@name #@kind"
+      else
+        "#@name #@kind #{qualifiers}"
+      end
+    end
+  end
+end

data/lib/rhubarb/mixins/freshness.rb

@@ -0,0 +1,62 @@
+# Freshness-based queries ("find_freshest") for Rhubarb classes.
+#
+# Copyright (c) 2009--2010 Red Hat, Inc.
+#
+# Author:  William Benton (willb@redhat.com)
+# 
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+# 
+#     http://www.apache.org/licenses/LICENSE-2.0
+
+module Rhubarb
+  module FindFreshest
+    # args contains the following keys
+    #  * :group_by maps to a list of columns to group by (mandatory)
+    #  * :select_by maps to a hash mapping from column symbols to values (optional)
+    #  * :version maps to some version to be considered "current" for the purposes of this query; that is, all rows later than the "current" version will be disregarded (optional, defaults to latest version)
+    def find_freshest(args)
+      args = args.dup
+
+      args[:version] ||= Util::timestamp
+      args[:select_by] ||= {}
+
+      query_params = {}
+      query_params[:version] = args[:version]
+
+      select_clauses = ["created <= :version"]
+
+      valid_cols = self.colnames.intersection args[:select_by].keys
+
+      valid_cols.map do |col|
+        select_clauses << "#{col.to_s} = #{col.inspect}"
+        val = args[:select_by][col]
+        val = val.row_id if val.respond_to? :row_id
+        query_params[col] = val
+      end
+
+      group_by_clause = "GROUP BY " + args[:group_by].join(", ")
+      where_clause = "WHERE " + select_clauses.join(" AND ")
+      projection = self.colnames - [:created]
+      join_clause = projection.map do |column|
+        "__fresh.#{column} = __freshest.#{column}"
+      end
+
+      projection << "MAX(created) AS __current_version"
+      join_clause << "__fresh.__current_version = __freshest.created"
+
+      query = "
+  SELECT __freshest.* FROM (
+    SELECT #{projection.to_a.join(', ')} FROM (
+      SELECT * from #{table_name} #{where_clause}
+    ) #{group_by_clause}
+  ) as __fresh INNER JOIN #{table_name} as __freshest ON
+    #{join_clause.join(' AND ')}
+    ORDER BY row_id
+  "
+
+      self.db.execute(query, query_params).map {|tup| self.new(tup) }
+    end
+  end
+end

data/lib/rhubarb/persistence.rb

@@ -0,0 +1,55 @@
+# Database interface for Rhubarb
+#
+# Copyright (c) 2009--2010 Red Hat, Inc.
+#
+# Author:  William Benton (willb@redhat.com)
+# 
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+# 
+#     http://www.apache.org/licenses/LICENSE-2.0
+
+module Rhubarb
+  module Persistence
+    class DbCollection < Hash
+      alias orig_set []=
+      
+      def []=(key,db)
+        setup_db(db) if db
+        orig_set(key,db)
+      end
+      
+      private
+      def setup_db(db)
+        db.results_as_hash = true
+        db.type_translation = true
+      end
+    end
+    
+    @dbs = DbCollection.new
+    
+    def self.open(filename, which=:default)
+      dbs[which] = SQLite3::Database.new(filename)
+    end
+  
+    def self.close(which=:default)
+      if dbs[which]
+        dbs[which].close
+        dbs.delete(which)
+      end
+    end
+  
+    def self.db
+      dbs[:default]
+    end
+    
+    def self.db=(d)
+      dbs[:default] = d
+    end
+  
+    def self.dbs
+      @dbs
+    end
+  end
+end

data/lib/rhubarb/persisting.rb

@@ -0,0 +1,122 @@
+# Instance mixins for persisting classes.  Part of Rhubarb.
+#
+# Copyright (c) 2009--2010 Red Hat, Inc.
+#
+# Author:  William Benton (willb@redhat.com)
+# 
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+# 
+#     http://www.apache.org/licenses/LICENSE-2.0
+
+module Rhubarb
+  
+  module Persisting
+    def self.included(other)
+      class << other
+        include PersistingClassMixins
+      end
+
+      other.class_eval do
+        attr_reader :row_id
+        attr_reader :created
+        attr_reader :updated
+      end
+    end
+
+    def db
+      self.class.db
+    end
+
+    # Returns true if the row backing this object has been deleted from the database
+    def deleted?
+      freshen
+      not @tuple
+    end
+
+    # Initializes a new instance backed by a tuple of values.  Do not call this directly. 
+    # Create new instances with the create or find methods.
+    def initialize(tup)
+      @backed = true
+      @tuple = tup
+      mark_fresh
+      @row_id = @tuple["row_id"]
+      @created = @tuple["created"]
+      @updated = @tuple["updated"]
+      resolve_referents
+      self.class.dirtied[@row_id] ||= @expired_after
+      self
+    end
+
+    # Deletes the row corresponding to this object from the database; 
+    # invalidates =self= and any other objects backed by this row
+    def delete
+      self.db.execute("delete from #{self.class.table_name} where row_id = ?", @row_id)
+      mark_dirty
+      @tuple = nil
+      @row_id = nil
+    end
+
+    ## Begin private methods
+
+    private
+
+    # Fetches updated attribute values from the database if necessary
+    def freshen
+      if needs_refresh?
+        @tuple = self.class.find_tuple(@row_id)
+        if @tuple
+          @updated = @tuple["updated"]
+        else
+          @row_id = @updated = @created = nil
+        end
+        mark_fresh
+        resolve_referents
+      end
+    end
+
+    # True if the underlying row in the database is inconsistent with the state 
+    # of this object, whether because the row has changed, or because this object has no row id
+    def needs_refresh?
+      if not @row_id 
+        @tuple != nil
+      else
+        @expired_after < self.class.dirtied[@row_id]
+      end
+    end
+
+    # Mark this row as dirty so that any other objects backed by this row will 
+    # update from the database before their attributes are inspected
+    def mark_dirty
+      self.class.dirtied[@row_id] = Util::timestamp
+    end
+
+    # Mark this row as consistent with the underlying database as of now
+    def mark_fresh
+      @expired_after = Util::timestamp
+    end
+
+    # Helper method to update the row in the database when one of our fields changes
+    def update(attr_name, value)
+      mark_dirty
+      self.db.execute("update #{self.class.table_name} set #{attr_name} = ?, updated = ? where row_id = ?", value, Util::timestamp, @row_id)
+    end
+
+    # Resolve any fields that reference other tables, replacing row ids with referred objects
+    def resolve_referents
+      refs = self.class.refs
+
+      refs.each do |c,r|
+        c = c.to_s
+        if r.referent == self.class and @tuple[c] == row_id
+          @tuple[c] = self
+        else
+          row = r.referent.find @tuple[c]
+          @tuple[c] = row if row
+        end
+      end
+    end
+
+  end
+end

data/lib/rhubarb/reference.rb

@@ -0,0 +1,39 @@
+# Foreign-key abstraction for Rhubarb.
+#
+# Copyright (c) 2009--2010 Red Hat, Inc.
+#
+# Author:  William Benton (willb@redhat.com)
+# 
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+# 
+#     http://www.apache.org/licenses/LICENSE-2.0
+
+module Rhubarb
+  class Reference
+    attr_reader :referent, :column, :options
+
+    # Creates a new Reference object, modeling a foreign-key relationship to another table.  +klass+ is a class that includes Persisting; +options+ is a hash of options, which include
+    # +:column => + _name_::  specifies the name of the column to reference in +klass+ (defaults to row id)
+    # +:on_delete => :cascade+:: specifies that deleting the referenced row in +klass+ will delete all rows referencing that row through this reference
+    def initialize(klass, options={})
+      @referent = klass
+      @options = options
+      @options[:column] ||= "row_id"
+      @column = options[:column]
+    end
+
+    def to_s
+      trigger = ""
+      trigger = " on delete cascade" if options[:on_delete] == :cascade
+      "references #{@referent}(#{@column})#{trigger}"
+    end
+
+    def managed_ref?
+      # XXX?
+      return false if referent.class == String
+      referent.ancestors.include? Persisting
+    end
+  end
+end

data/lib/rhubarb/rhubarb.rb

@@ -13,533 +13,10 @@
 
 require 'rubygems'
 require 'set'
-require 'time'
 require 'sqlite3'
-
-module Rhubarb
-
-module SQLBUtil
-  def self.timestamp(tm=nil)
-    tm ||= Time.now.utc
-    (tm.tv_sec * 1000000) + tm.tv_usec
-  end
-end
-    
-
-module Persistence
-  class DbCollection < Hash
-    alias orig_set []=
-    
-    def []=(k,v)
-      v.results_as_hash = true if v
-      v.type_translation = true if v
-      orig_set(k,v)
-    end
-  end
-  
-  @@dbs = DbCollection.new
-  
-  def self.open(filename, which=:default)
-    dbs[which] = SQLite3::Database.new(filename)
-  end
-
-  def self.close(which=:default)
-    if dbs[which]
-      dbs[which].close
-      dbs.delete(which)
-    end
-  end
-
-  def self.db
-    dbs[:default]
-  end
-  
-  def self.db=(d)
-    dbs[:default] = d
-  end
-
-  def self.dbs
-    @@dbs
-  end
-end
-
-class Column
-  attr_reader :name
-
-  def initialize(name, kind, quals)
-    @name, @kind = name, kind
-    @quals = quals.map {|x| x.to_s.gsub("_", " ") if x.class == Symbol}
-    @quals.map 
-  end
-  
-  def to_s
-    qualifiers = @quals.join(" ")
-    if qualifiers == ""
-      "#@name #@kind"
-    else
-      "#@name #@kind #{qualifiers}"
-    end
-  end
-end
-
-class Reference
-  attr_reader :referent, :column, :options
-
-  # Creates a new Reference object, modeling a foreign-key relationship to another table.  +klass+ is a class that includes Persisting; +options+ is a hash of options, which include
-  # +:column => + _name_::  specifies the name of the column to reference in +klass+ (defaults to row id)
-  # +:on_delete => :cascade+:: specifies that deleting the referenced row in +klass+ will delete all rows referencing that row through this reference
-  def initialize(klass, options={})
-    @referent = klass
-    @options = options
-    @options[:column] ||= "row_id"
-    @column = options[:column]
-  end
-
-  def to_s
-    trigger = ""
-    trigger = " on delete cascade" if options[:on_delete] == :cascade
-    "references #{@referent}(#{@column})#{trigger}"
-  end
-
-  def managed_ref?
-    # XXX?
-    return false if referent.class == String
-    referent.ancestors.include? Persisting
-  end
-end
-
-
-# Methods mixed in to the class object of a persisting class
-module PersistingClassMixins 
-  # Returns the name of the database table modeled by this class.
-  # Defaults to the name of the class (sans module names)
-  def table_name
-    @table_name ||= self.name.split("::").pop.downcase  
-  end
-  
-  # Enables setting the table name to a custom name
-  def declare_table_name(nm)
-    @table_name = nm
-  end
-
-  # Models a foreign-key relationship. +options+ is a hash of options, which include
-  # +:column => + _name_::  specifies the name of the column to reference in +klass+ (defaults to row id)
-  # +:on_delete => :cascade+:: specifies that deleting the referenced row in +klass+ will delete all rows referencing that row through this reference
-  def references(table, options={})
-    Reference.new(table, options)
-  end
-
-  # Models a CHECK constraint.
-  def check(condition)
-    "check (#{condition})"
-  end
-  
-  # Returns an object corresponding to the row with the given ID, or +nil+ if no such row exists.
-  def find(id)
-    tup = self.find_tuple(id)
-    return self.new(tup) if tup
-    nil
-  end
-  
-  alias find_by_id find
-
-  def find_by(arg_hash)
-    arg_hash = arg_hash.dup
-    valid_cols = self.colnames.intersection arg_hash.keys
-    select_criteria = valid_cols.map {|col| "#{col.to_s} = #{col.inspect}"}.join(" AND ")
-    arg_hash.each {|k,v| arg_hash[k] = v.row_id if v.respond_to? :row_id}
-
-    self.db.execute("select * from #{table_name} where #{select_criteria} order by row_id", arg_hash).map {|tup| self.new(tup) }
-  end
-
-  # args contains the following keys
-  #  * :group_by maps to a list of columns to group by (mandatory)
-  #  * :select_by maps to a hash mapping from column symbols to values (optional)
-  #  * :version maps to some version to be considered "current" for the purposes of this query; that is, all rows later than the "current" version will be disregarded (optional, defaults to latest version)
-  def find_freshest(args)
-    args = args.dup
-    
-    args[:version] ||= SQLBUtil::timestamp
-    args[:select_by] ||= {}
-    
-    query_params = {}
-    query_params[:version] = args[:version]
-    
-    select_clauses = ["created <= :version"]
-
-    valid_cols = self.colnames.intersection args[:select_by].keys
-
-    valid_cols.map do |col|
-      select_clauses << "#{col.to_s} = #{col.inspect}"
-      val = args[:select_by][col]
-      val = val.row_id if val.respond_to? :row_id
-      query_params[col] = val
-    end
-
-    group_by_clause = "GROUP BY " + args[:group_by].join(", ")
-    where_clause = "WHERE " + select_clauses.join(" AND ")
-    projection = self.colnames - [:created]
-    join_clause = projection.map do |column|
-      "__fresh.#{column} = __freshest.#{column}"
-    end
-
-    projection << "MAX(created) AS __current_version"
-    join_clause << "__fresh.__current_version = __freshest.created"
-
-    query = "
-SELECT __freshest.* FROM (
-  SELECT #{projection.to_a.join(', ')} FROM (
-    SELECT * from #{table_name} #{where_clause}
-  ) #{group_by_clause}
-) as __fresh INNER JOIN #{table_name} as __freshest ON
-  #{join_clause.join(' AND ')}
-  ORDER BY row_id
-"
-
-    self.db.execute(query, query_params).map {|tup| self.new(tup) }
-  end
-
-  # Does what it says on the tin.  Since this will allocate an object for each row, it isn't recomended for huge tables.
-  def find_all
-    self.db.execute("SELECT * from #{table_name}").map {|tup| self.new(tup)}
-  end
-
-  def delete_all
-    self.db.execute("DELETE from #{table_name}")
-  end
-
-  # Declares a query method named +name+ and adds it to this class.  The query method returns a list of objects corresponding to the rows returned by executing "+SELECT * FROM+ _table_ +WHERE+ _query_" on the database.
-  def declare_query(name, query)
-    klass = (class << self; self end)
-    klass.class_eval do
-      define_method name.to_s do |*args|
-        # handle reference parameters
-        args = args.map {|x| (x.row_id if x.class.ancestors.include? Persisting) or x}
-        
-        res = self.db.execute("select * from #{table_name} where #{query}", args)
-        res.map {|row| self.new(row)}        
-      end
-    end
-  end
-
-  # Declares a custom query method named +name+, and adds it to this class.  The custom query method returns a list of objects corresponding to the rows returned by executing +query+ on the database.  +query+ should select all fields (with +SELECT *+).  If +query+ includes the string +\_\_TABLE\_\_+, it will be expanded to the table name.  Typically, you will want to use +declare\_query+ instead; this method is most useful for self-joins.
-  def declare_custom_query(name, query)
-    klass = (class << self; self end)
-    klass.class_eval do
-      define_method name.to_s do |*args|
-        # handle reference parameters
-        args = args.map {|x| (x.row_id if x.class.ancestors.include? Persisting) or x}
-        
-        res = self.db.execute(query.gsub("__TABLE__", "#{self.table_name}"), args)
-        # XXX:  should freshen each row?
-        res.map {|row| self.new(row) }        
-      end
-    end
-  end
-  
-  def declare_index_on(*fields)
-    @creation_callbacks << Proc.new do
-      idx_name = "idx_#{self.table_name}__#{fields.join('__')}__#{@creation_callbacks.size}"
-      creation_cmd = "create index #{idx_name} on #{self.table_name} (#{fields.join(', ')})"
-      self.db.execute(creation_cmd)
-    end if fields.size > 0
-  end
-
-  # Adds a column named +cname+ to this table declaration, and adds the following methods to the class:
-  # * accessors for +cname+, called +cname+ and +cname=+
-  # * +find\_by\_cname+ and +find\_first\_by\_cname+ methods, which return a list of rows and the first row that have the given value for +cname+, respectively
-  # If the column references a column in another table (given via a +references(...)+ argument to +quals+), then add triggers to the database to ensure referential integrity and cascade-on-delete (if specified)
-  def declare_column(cname, kind, *quals)
-    ensure_accessors
-    
-    find_method_name = "find_by_#{cname}".to_sym
-    find_first_method_name = "find_first_by_#{cname}".to_sym
-    
-    get_method_name = "#{cname}".to_sym
-    set_method_name = "#{cname}=".to_sym
-    
-    # does this column reference another table?
-    rf = quals.find {|q| q.class == Reference}
-    if rf
-      self.refs[cname] = rf
-    end
-
-    # add a find for this column (a class method)
-    klass = (class << self; self end)
-    klass.class_eval do 
-      define_method find_method_name do |arg|
-        res = self.db.execute("select * from #{table_name} where #{cname} = ?", arg)
-        res.map {|row| self.new(row)}
-      end
-
-      define_method find_first_method_name do |arg|
-        res = self.db.execute("select * from #{table_name} where #{cname} = ?", arg)
-        return self.new(res[0]) if res.size > 0
-        nil
-      end
-    end
-
-    self.colnames.merge([cname])
-    self.columns << Column.new(cname, kind, quals)
-    
-    # add accessors
-    define_method get_method_name do
-      freshen
-      return @tuple["#{cname}"] if @tuple
-      nil
-    end
-    
-    if not rf
-      define_method set_method_name do |arg|
-        @tuple["#{cname}"] = arg
-        update cname, arg
-      end      
-    else
-      # this column references another table; create a set 
-      # method that can handle either row objects or row IDs
-      define_method set_method_name do |arg|
-        freshen
-        
-        arg_id = nil
-
-        if arg.class == Fixnum
-          arg_id = arg
-          arg = rf.referent.find arg_id
-        else
-          arg_id = arg.row_id
-        end
-        @tuple["#{cname}"] = arg
-        
-        update cname, arg_id
-      end
-      
-      # Finally, add appropriate triggers to ensure referential integrity.
-      # If rf has an on_delete trigger, also add the necessary
-      # triggers to cascade deletes. 
-      # Note that we do not support update triggers, since the API does 
-      # not expose the capacity to change row IDs.
-      
-      self.creation_callbacks << Proc.new do   
-        @ccount ||= 0
-
-        insert_trigger_name = "ri_insert_#{self.table_name}_#{@ccount}_#{rf.referent.table_name}"
-        delete_trigger_name = "ri_delete_#{self.table_name}_#{@ccount}_#{rf.referent.table_name}"
-        
-        self.db.execute_batch("CREATE TRIGGER #{insert_trigger_name} BEFORE INSERT ON \"#{self.table_name}\" WHEN new.\"#{cname}\" IS NOT NULL AND NOT EXISTS (SELECT 1 FROM \"#{rf.referent.table_name}\" WHERE new.\"#{cname}\" == \"#{rf.column}\") BEGIN SELECT RAISE(ABORT, 'constraint #{insert_trigger_name} (#{rf.referent.table_name} missing foreign key row) failed'); END;")
-
-        self.db.execute_batch("CREATE TRIGGER #{delete_trigger_name} BEFORE DELETE ON \"#{rf.referent.table_name}\" WHEN EXISTS (SELECT 1 FROM \"#{self.table_name}\" WHERE old.\"#{rf.column}\" == \"#{cname}\") BEGIN DELETE FROM \"#{self.table_name}\" WHERE \"#{cname}\" = old.\"#{rf.column}\"; END;") if rf.options[:on_delete] == :cascade
-
-        @ccount = @ccount + 1
-      end
-    end
-  end
-  
-  # Declares a constraint.  Only check constraints are supported; see
-  # the check method.
-  def declare_constraint(cname, kind, *details)
-    ensure_accessors
-    info = details.join(" ")
-    @constraints << "constraint #{cname} #{kind} #{info}"
-  end
-  
-  # Creates a new row in the table with the supplied column values.
-  # May throw a SQLite3::SQLException.
-  def create(*args)
-    new_row = args[0]
-    new_row[:created] = new_row[:updated] = SQLBUtil::timestamp
-    
-    cols = colnames.intersection new_row.keys
-    colspec = (cols.map {|col| col.to_s}).join(", ")
-    valspec = (cols.map {|col| col.inspect}).join(", ")
-    res = nil
-
-    # resolve any references in the args
-    new_row.each do |k,v|
-      new_row[k] = v.row_id if v.class.ancestors.include? Persisting
-    end
-
-    self.db.transaction do |db|
-      stmt = "insert into #{table_name} (#{colspec}) values (#{valspec})"
-#      p stmt
-      db.execute(stmt, new_row)
-      res = find(db.last_insert_row_id)
-    end
-    res
-  end
-  
-  # Returns a string consisting of the DDL statement to create a table
-  # corresponding to this class. 
-  def table_decl
-    cols = columns.join(", ")
-    consts = constraints.join(", ")
-    if consts.size > 0
-      "create table #{table_name} (#{cols}, #{consts});"
-    else
-      "create table #{table_name} (#{cols});"
-    end
-  end
-  
-  # Creates a table in the database corresponding to this class.
-  def create_table(dbkey=:default)
-    self.db ||= Persistence::dbs[dbkey]
-    self.db.execute(table_decl)
-    @creation_callbacks.each {|func| func.call}
-  end
-
-  def db
-    @db || Persistence::db
-  end
-
-  def db=(d)
-    @db = d
-  end
-
-  # Ensure that all the necessary accessors on our class instance are defined 
-  # and that all metaclass fields have the appropriate values
-  def ensure_accessors
-    # Define singleton accessors
-    if not self.respond_to? :columns
-      class << self
-        # Arrays of columns, column names, and column constraints.
-        # Note that colnames does not contain id, created, or updated.
-        # The API purposefully does not expose the ability to create a
-        # row with a given id, and created and updated values are
-        # maintained automatically by the API.
-        attr_accessor :columns, :colnames, :constraints, :dirtied, :refs, :creation_callbacks
-      end
-    end
-
-    # Ensure singleton fields are initialized
-    self.columns ||= [Column.new(:row_id, :integer, [:primary_key]), Column.new(:created, :integer, []), Column.new(:updated, :integer, [])]
-    self.colnames ||= Set.new [:created, :updated]
-    self.constraints ||= []
-    self.dirtied ||= {}
-    self.refs ||= {}
-    self.creation_callbacks ||= []
-  end
-
-  # Returns the number of rows in the table backing this class
-  def count
-    result = self.db.execute("select count(row_id) from #{table_name}")[0]
-    result[0].to_i
-  end
-
-  def find_tuple(id)
-    res = self.db.execute("select * from #{table_name} where row_id = ?", id)
-    if res.size == 0
-      nil
-    else
-      res[0]
-    end
-  end
-end
-
-module Persisting
-  def self.included(other)
-    class << other
-      include PersistingClassMixins
-    end
-
-    other.class_eval do
-      attr_reader :row_id
-      attr_reader :created
-      attr_reader :updated
-    end
-  end
-  
-  def db
-    self.class.db
-  end
-  
-  # Returns true if the row backing this object has been deleted from the database
-  def deleted?
-    freshen
-    not @tuple
-  end
-  
-  # Initializes a new instance backed by a tuple of values.  Do not call this directly. 
-  # Create new instances with the create or find methods.
-  def initialize(tup)
-    @backed = true
-    @tuple = tup
-    mark_fresh
-    @row_id = @tuple["row_id"]
-    @created = @tuple["created"]
-    @updated = @tuple["updated"]
-    resolve_referents
-    self.class.dirtied[@row_id] ||= @expired_after
-    self
-  end
-  
-  # Deletes the row corresponding to this object from the database; 
-  # invalidates =self= and any other objects backed by this row
-  def delete
-    self.db.execute("delete from #{self.class.table_name} where row_id = ?", @row_id)
-    mark_dirty
-    @tuple = nil
-    @row_id = nil
-  end
-
-  ## Begin private methods
-
-  private
-  
-  # Fetches updated attribute values from the database if necessary
-  def freshen
-    if needs_refresh?
-      @tuple = self.class.find_tuple(@row_id)
-      if @tuple
-        @updated = @tuple["updated"]
-      else
-        @row_id = @updated = @created = nil
-      end
-      mark_fresh
-      resolve_referents
-    end
-  end
-  
-  # True if the underlying row in the database is inconsistent with the state 
-  # of this object, whether because the row has changed, or because this object has no row id
-  def needs_refresh?
-    if not @row_id 
-      @tuple != nil
-    else
-      @expired_after < self.class.dirtied[@row_id]
-    end
-  end
-  
-  # Mark this row as dirty so that any other objects backed by this row will 
-  # update from the database before their attributes are inspected
-  def mark_dirty
-    self.class.dirtied[@row_id] = SQLBUtil::timestamp
-  end
-  
-  # Mark this row as consistent with the underlying database as of now
-  def mark_fresh
-    @expired_after = SQLBUtil::timestamp
-  end
-  
-  # Helper method to update the row in the database when one of our fields changes
-  def update(attr_name, value)
-    mark_dirty
-    self.db.execute("update #{self.class.table_name} set #{attr_name} = ?, updated = ? where row_id = ?", value, SQLBUtil::timestamp, @row_id)
-  end
-  
-  # Resolve any fields that reference other tables, replacing row ids with referred objects
-  def resolve_referents
-    refs = self.class.refs
-
-    refs.each do |c,r|
-      c = c.to_s
-      if r.referent == self.class and @tuple[c] == row_id
-        @tuple[c] = self
-      else
-        row = r.referent.find @tuple[c]
-        @tuple[c] = row if row
-      end
-    end
-  end
-
-end
-
-end
+require 'rhubarb/util'
+require 'rhubarb/persistence'
+require 'rhubarb/column'
+require 'rhubarb/reference'
+require 'rhubarb/classmixins'
+require 'rhubarb/persisting'

data/lib/rhubarb/util.rb

@@ -0,0 +1,28 @@
+# Timestamp function for Rhubarb.
+#
+# Copyright (c) 2009--2010 Red Hat, Inc.
+#
+# Author:  William Benton (willb@redhat.com)
+# 
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+# 
+#     http://www.apache.org/licenses/LICENSE-2.0
+
+require 'time'
+
+module Rhubarb
+  module Util
+    # A higher-resolution timestamp
+    def self.timestamp(tm=nil)
+      tm ||= Time.now.utc
+      (tm.tv_sec * 1000000) + tm.tv_usec
+    end
+
+    # Identity for objects that may be used as foreign keys
+    def self.rhubarb_fk_identity(object)
+      (object.row_id if object.class.ancestors.include? Persisting) || object
+    end
+  end
+end

data/ruby-rhubarb.spec

@@ -0,0 +1,60 @@
+%{!?ruby_sitelib: %global ruby_sitelib %(ruby -rrbconfig -e 'puts Config::CONFIG["sitelibdir"] ')}
+%define rel 0.3
+
+Summary: Simple versioned object-graph persistence layer
+Name: ruby-rhubarb
+Version: 0.2.0
+Release: %{rel}%{?dist}
+Group: Applications/System
+License: ASL 2.0
+URL: http://git.fedorahosted.org/git/grid/rhubarb.git
+Source0: %{name}-%{version}-%{rel}.tar.gz
+BuildRoot: %(mktemp -ud %{_tmppath}/%{name}-%{version}-%{release}-XXXXXX)
+Requires: ruby-sqlite3
+Requires: ruby
+Requires: ruby(abi) = 1.8
+BuildRequires: ruby
+BuildArch: noarch
+
+%description
+A simple versioned object-graph persistence layer that stores
+instances of specially-declared Ruby classes in a SQLite3 database
+
+%prep
+%setup -q
+
+%build
+
+%install
+rm -rf %{buildroot}
+mkdir -p %{buildroot}/%{ruby_sitelib}/rhubarb
+mkdir -p %{buildroot}/%{ruby_sitelib}/rhubarb/mixins
+cp -f lib/rhubarb/mixins/*.rb %{buildroot}/%{ruby_sitelib}/rhubarb/mixins
+cp -f lib/rhubarb/*.rb %{buildroot}/%{ruby_sitelib}/rhubarb
+
+%clean
+rm -rf %{buildroot}
+
+%files
+%defattr(-, root, root, -)
+%doc LICENSE README.rdoc CHANGES TODO VERSION
+%{ruby_sitelib}/rhubarb/rhubarb.rb
+%{ruby_sitelib}/rhubarb/classmixins.rb
+%{ruby_sitelib}/rhubarb/mixins/freshness.rb
+%{ruby_sitelib}/rhubarb/column.rb
+%{ruby_sitelib}/rhubarb/reference.rb
+%{ruby_sitelib}/rhubarb/util.rb
+%{ruby_sitelib}/rhubarb/persisting.rb
+%{ruby_sitelib}/rhubarb/persistence.rb
+
+%changelog
+* Fri Feb  5 2010  <rrat@redhat> - 0.2.0-0.3
+- Explicitly list files
+- Added ruby(abi) and dependency
+- Added ruby build dependency
+
+* Thu Feb  4 2010  <willb@redhat.com> - 0.2.0-0.2
+- Post-0.2 cleanups
+
+* Tue Feb  2 2010  <rrati@redhat> - 0.2.0-0.1
+- Initial package

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: rhubarb
 version: !ruby/object:Gem::Version 
-  version: 0.2.0
+  version: 0.2.1
 platform: ruby
 authors: 
 - William Benton
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-02-02 00:00:00 -06:00
+date: 2010-02-15 00:00:00 -06:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -51,7 +51,15 @@ files:
 - Rakefile
 - TODO
 - VERSION
+- lib/rhubarb/classmixins.rb
+- lib/rhubarb/column.rb
+- lib/rhubarb/mixins/freshness.rb
+- lib/rhubarb/persistence.rb
+- lib/rhubarb/persisting.rb
+- lib/rhubarb/reference.rb
 - lib/rhubarb/rhubarb.rb
+- lib/rhubarb/util.rb
+- ruby-rhubarb.spec
 - test/helper.rb
 - test/test_rhubarb.rb
 has_rdoc: true