activemdb 0.2.0 → 0.2.1

data/History.txt

@@ -1,4 +1,8 @@
-== 0.1.0 / 2007-02-22
+== 0.2.1 / 2007-04-10
+
+Added typecasting so that the strings returned from mdb-sql become happy appropriate Ruby things.
 
+== 0.2.0 / 2007-04-05
+== 0.1.0 / 2007-02-22
 
 

data/Manifest.txt

@@ -17,6 +17,7 @@ lib/active_mdb/table.rb
 support/a.insert
 test/test_activemdb.rb
 test/test_base.rb
+test/test_column.rb
 test/test_helper.rb
 test/test_mdb.rb
 test/test_mdb_tools.rb

data/Rakefile

@@ -8,10 +8,10 @@ Hoe.new('activemdb', ActiveMDB::VERSION) do |p|
   p.rubyforge_name = 'activemdb'
   p.author = 'Matthew King'
   p.email = 'automatthew@gmail.com'
-  p.summary = 'ActiveRecordy wrapper around MDB Tools, which lets POSIX platforms read MS Access (.mdb) files'
+  p.summary = 'ActiveRecordy wrapper around MDB Tools, allowing POSIX platforms to read MS Access (.mdb) files'
   p.description = p.paragraphs_of('README.txt', 2).join("\n\n")
-  p.url = p.paragraphs_of('README.txt',0).first.split(/\n/)[2..-1]
-  # p.changes = p.paragraphs_of('History.txt', 0..1).join("\n\n")
+  p.url = 'http://activemdb.rubyforge.org/'
+  p.changes = p.paragraphs_of('History.txt', 0..1).join("\n\n")
 end
 
 # vim: syntax=Ruby

data/lib/active_mdb.rb

@@ -1,6 +1,6 @@
 $:.unshift(File.dirname(__FILE__))
 module ActiveMDB
-  VERSION = '0.2.0'
+  VERSION = '0.2.1'
 end
 
 

data/lib/active_mdb/base.rb

@@ -1,11 +1,10 @@
 module ActiveMDB
+  # Hi, I am an imitation of ActiveRecord.
   class Base
     
     def initialize(attributes=nil)
       @attributes = attributes unless attributes.nil?
     end
-
-    
     
     cattr_accessor :pluralize_table_names, :instance_writer => false
     @@pluralize_table_names = true
@@ -14,11 +13,13 @@ module ActiveMDB
       attr_accessor :mdb_file
       attr_reader :mdb
       
+      # set the path to the MDB file
       def set_mdb_file(file)
         @mdb_file = file
         @mdb = MDB.new(file)
       end
-    
+      
+      # set the name of the table in the MDB file
       def table_name
         table_name = Inflector.underscore(Inflector.demodulize(self.to_s))
         table_name = Inflector.pluralize(table_name) if pluralize_table_names
@@ -44,10 +45,14 @@ module ActiveMDB
         @mdb.column_names(table_name)
       end
       
+      # returns 'id' unless you overwrite this method using set_primary_key
       def primary_key
         'id'
       end
 
+      # specify the field to be used as a primary key for those
+      # operations that require one.  At this time, that isn't really
+      # anything except count.
       def set_primary_key(value = nil, &block)
         define_attr_method :primary_key, value, &block
       end
@@ -57,20 +62,31 @@ module ActiveMDB
         @mdb.tables.include? table_name
       end
       
+      # How many?  Requires that the primary_key return a valid field.
       def count
         @mdb.count(table_name, primary_key)
       end
       
+      # the conditions hash keys are column names, the values are search values
+      # find_first :superhero_name => 'The Ironist', :powers => 'Wit'
+      #
+      # mdb-sql doesn't implement LIMIT yet, so this method pulls all results and
+      # calls Array#first on them.  Ooky.
       def find_first(conditions_hash)
         # rekey_hash(conditions_hash)
-        sql_search(conditions_hash).first 
+        find_from_hash(conditions_hash).first 
       end
       
+      # the conditions hash keys are column names, the values are search values
+      # find_all :superhero_name => 'The Ironist', :powers => 'Wit'
+      #
+      # mdb-sql doesn't implement LIMIT yet, so this method pulls all results and
+      # calls Array#first on them.  Ooky.
       def find_all(conditions_hash)
-        sql_search(conditions_hash)
+        find_from_hash(conditions_hash)
       end
           
-      # borrowed from ActiveRecord
+      # borrowed from ActiveRecord.
       def define_attr_method(name, value=nil, &block)
         sing = class << self; self; end
         sing.send :alias_method, "original_#{name}", name
@@ -94,18 +110,54 @@ module ActiveMDB
           end
         end
       end
+          
+      # supply a conditions string that would nestle gently in a 
+      # WHERE clause, after the WHERE but before the.
+      def find_where(conditions)
+        MDBTools.sql_select_where(mdb_file, table_name, nil, conditions).collect! { |record| instantiate(record) }
+      end
+      
+      # takes a hash where the keys are column names (string or symbol)
+      # and the values are the associated values.
+      def find_from_hash(hash)
+        conditions = conditions_from_hash(hash)
+        find_where(conditions)
+      end
       
       # the conditions hash keys are column names, the values are search values
-      # e.g. sql_search(:first_name => 'Matthew', :last_name => 'King')
-      def sql_search(conditions_hash)
-        conditions = MDBTools.compile_conditions(conditions_hash)
-        MDBTools.sql_select(mdb_file, table_name, nil, conditions).collect! { |record| instantiate(record) }
+      # e.g. search_with_hash(:first_name => 'Matthew', :last_name => 'King')
+      def conditions_from_hash(hash)
+        MDBTools.compile_conditions(hash) do |column_name, value|
+          column = column_for(column_name)
+          case column.klass.to_s
+          when 'Fixnum', 'Float'
+            "#{column_name} = #{value}"
+          when 'String'
+            "#{column_name} LIKE '%#{value}%'"
+          when 'Object'
+            value = value ? 1 : 0
+            "#{column_name} IS #{value}"
+          end
+        end
+      end
+      
+      # given the name of a column, return the Column object
+      def column_for(column_name)
+        columns.detect {|c| c.name == column_name.to_s}
       end
       
       private
       
       def instantiate(record)
-        new(record)
+        new_hash = {}
+        record.each do |name,value|
+          begin
+            new_hash[name] = column_for(name).type_cast(value)
+          rescue
+            raise "No column for #{name}"
+          end
+        end
+        self.new new_hash
       end
       
       

data/lib/active_mdb/column.rb

@@ -8,6 +8,8 @@ class Column
     @method_name, @size = methodize(name), size.to_i
   end
   
+  # returns a new Column from a hash with the keys: 
+  # 'Column Name', 'Type', and 'Size'
   def self.new_from_describe(describe_hash)
     self.new(describe_hash["Column Name"], describe_hash["Type"], describe_hash["Size"])
   end
@@ -18,6 +20,7 @@ class Column
     case type
       when 'Text', 'Character'  then String
       when 'Long Integer'       then Fixnum
+      when 'Double'             then Float
       when 'Currency', 'Float'  then Float
       when 'DateTime (Short)'   then Time
       when 'Boolean'            then Object
@@ -34,6 +37,7 @@ class Column
       when 'Text', 'Character'  then value
       when 'Long Integer'       then value.to_i rescue value ? 1 : 0
       when 'Currency', 'Float'  then value.to_f
+      when 'Double'             then value.to_f
       when 'DateTime (Short)'   then self.class.string_to_time(value)
       when 'Boolean'            then self.class.value_to_boolean(value)
       when 'Decimal'            then self.class.value_to_decimal(value)
@@ -42,6 +46,8 @@ class Column
     end
   end
   
+  # provided any argument, returns the mdb-tools version 
+  # of truth (which is to say, 1 or 0)
   def self.value_to_boolean(value)
     if value == true || value == false
       value
@@ -50,8 +56,9 @@ class Column
     end
   end
   
+  # Are you a Boolean?
   def boolean?
-    self.type == 'boolean'
+    self.type == 'Boolean'
   end
   
   

data/lib/active_mdb/mdb.rb

@@ -14,6 +14,7 @@ class MDB
     # @tables = create_table_objects
   end
   
+  # consumer of poor, weak MDBTools.faked_count
   def count(table_name, attribute)
     MDBTools.faked_count(@mdb_file, table_name, attribute)
   end

data/lib/active_mdb/mdb_tools.rb

@@ -7,6 +7,7 @@ module MDBTools
   SANITIZER = /^\w\.\_/ # dumb filter for SQL arguments
   BACKENDS = %w{ access mysql oracle postgres sybase }
   
+  # test for existence and usability of file
   def check_file(mdb_file)
     raise ArgumentError, "File not found: #{mdb_file}" unless File.exist?(mdb_file)
     @mdb_version = `mdb-ver #{mdb_file} 2>&1`.chomp
@@ -16,6 +17,7 @@ module MDBTools
     mdb_file
   end
   
+  # runs mdb_version.  A blank version indicates an unusable file
   def valid_file?(file)
     !mdb_version(file).blank?
   end
@@ -24,6 +26,8 @@ module MDBTools
     `mdb-ver #{file} 2> /dev/null`.chomp
   end
   
+  # raises an ArgumentError unless the mdb file contains a table with the specified name.
+  # returns the table name, otherwise.
   def check_table(mdb_file, table_name)
     unless mdb_tables(mdb_file).include?(table_name)
       raise ArgumentError, "mdbtools does not think a table named \"#{table_name}\" exists"
@@ -31,7 +35,15 @@ module MDBTools
     table_name
   end
   
-  
+  # uses mdb-tables tool to return an array of table names.
+  # You can filter the tables by passing an array of strings as
+  # either the :exclude or :include key to the options hash.
+  # The strings will be ORed into a regex.  Only one or the other of
+  # :exclude or :include, please.
+  #
+  # ex. mdb_tables('thing.mdb', :exclude => ['_Lookup'])
+  #
+  # ex. mdb_tables('thing.mdb', :include => ['tbl'])
   def mdb_tables(mdb_file, options = {})
     included, excluded = options[:include], options[:exclude]
     return `mdb-tables -1 #{mdb_file}`.split(LINEBREAK) if not (included || excluded)
@@ -46,8 +58,10 @@ module MDBTools
     end
     tables
   end
-    
-  def sql_select(mdb_file, table_name, attributes = nil, conditions=nil)
+  
+  # takes an array of field names
+  # and some conditions to append in a WHERE clause
+  def sql_select_where(mdb_file, table_name, attributes = nil, conditions=nil)
     if attributes.respond_to?(:join)
       fields = attributes.join(' ') 
     else
@@ -58,8 +72,12 @@ module MDBTools
     mdb_sql(mdb_file, sql)
   end
   
+  # forks an IO.popen running mdb-sql and discarding STDERR to /dev/null.
+  # The sql argument should be a single statement, 'cause I don't know
+  # what will happen otherwise.  mdb-sql uses "\ngo" as the command terminator.
   def mdb_sql(mdb_file,sql)
-    command = "mdb-sql -Fp -d '#{DELIMITER}' #{mdb_file}\n"
+    # libMDB barks on stderr quite frequently, so discard stderr entirely
+    command = "mdb-sql -Fp -d '#{DELIMITER}' #{mdb_file} 2> /dev/null \n"
     array = []
     IO.popen(command, 'r+') do |pipe|
       pipe << "#{sql}\ngo\n"
@@ -77,20 +95,27 @@ module MDBTools
     end
     array
   end
-  
-  def old_mdb_sql(mdb_file, sql)
-    result = `echo -n #{sql} | mdb-sql -Fp -H -d '#{DELIMITER}' #{mdb_file}`.strip
-    delimited_to_arrays(result)
-  end
-  
+
+  # uses mdb-sql to retrieve an array of the table's field names
   def field_names_for(mdb_file, table)
     fields = `echo -n 'select * from #{table} where 1 = 2' | mdb-sql -Fp -d '#{DELIMITER}' #{mdb_file}`.chomp.sub(/^\n+/, '')
     fields.split(DELIMITER)
   end
   
 
-  
-  def compile_conditions(conditions_hash, *args)
+  # takes a hash where keys are column names, values are search values
+  # and returns a string that you can use in a WHERE clause
+  #
+  # ex. compile_conditions(:first_name => 'Summer', :last_name => 'Roberts') 
+  # gives "first_name like '%Summer%' AND last_name like '%Roberts%'
+  #
+  # if you want to use an operator other than LIKE, give compile_conditions
+  # a block that accepts column_name and value and does something interesting
+  #
+  # compile_conditions(:age => 18) {|name, value| "#{name} = #{value}"}
+  #
+  # the condition phrases are all ANDed together before insertion into a WHERE clause
+  def compile_conditions(conditions_hash)
     conditions = conditions_hash.sort_by{|k,v| k.to_s}.map do |column_name, value|
       if block_given?
         yield column_name, value
@@ -100,10 +125,15 @@ module MDBTools
     end.join(' AND ')
   end
   
+  # really dumb way to get a count.  Does a SELECT and call size on the results
   def faked_count(*args)
-    sql_select(*args).size
+    sql_select_where(*args).size
   end
   
+  # convenience method, not really used with ActiveMDB.  
+  # Valid options are :format, :headers, and :sanitize, 
+  # which correspond rather directly to the underlying mdb-export arguments.
+  # Defaults to :format => 'sql', :headers => false, :sanitize => true
   def mdb_export(mdb_file, table_name, options = {})
     defaults = {  :format => 'sql',
                   :headers => false,
@@ -126,16 +156,18 @@ module MDBTools
     `mdb-export #{args} #{mdb_file} #{table_name.to_s.dump}`
   end
   
+  # wrapper for DESCRIBE TABLE using mdb-sql
   def describe_table(mdb_file, table_name)
     command = "describe table \"#{table_name}\""
     mdb_sql(mdb_file,command)
   end
   
+  # wrapper for mdb-schema, returns SQL statements
   def mdb_schema(mdb_file, table_name)
     schema = `mdb-schema -T #{table_name.dump} #{mdb_file}`
   end
 
-  
+  # convenience method for mdb_export to output CSV with headers.
   def table_to_csv(mdb_file, table_name)
     mdb_export(mdb_file, table_name, :format => 'csv', :headers => true)
   end
@@ -158,7 +190,8 @@ module MDBTools
   end
   
 
-  
+  # helper to turn table names into standard format method names.
+  # Inside, it's just ActionView::Inflector.underscore
   def methodize(table_name)
     Inflector.underscore table_name
   end
@@ -167,10 +200,13 @@ module MDBTools
     BACKENDS
   end
   
+  # poor, weakly sanitizing gsub!.
   def sanitize!(string)
     string.gsub!(SANITIZER, '')
   end
   
+  # mdb-tools recognizes 1 and 0 as the boolean values.
+  # Make it so.
   def mdb_truth(value)
     case value
     when false

data/lib/active_mdb/record.rb

@@ -1,5 +1,6 @@
 # require 'mdb_tools'
 
+# Deprecated way more than Table
 class Record
   include MDBTools
   include Enumerable

data/lib/active_mdb/table.rb

@@ -1,5 +1,6 @@
 # require 'mdb_tools'  
 
+# Deprecated.  So very deprecated.
 class Table
   include MDBTools
   
@@ -22,6 +23,7 @@ class Table
     self.columns.detect {|c| c.method_name == method_name }
   end
   
+  # returns an array of column names
   def column_names
     columns.collect {|x| methodize(x.method_name).to_sym}
   end
@@ -34,20 +36,24 @@ class Table
   def to_csv
     table_to_csv(mdb_file, table_name)
   end
-  
-  def to_sql
-    raise 'not implemented'
-  end
-  
+
+  # returns the first record that meets the equality (sometimes LIKE) conditions
+  # of the supplied hash.  No comparison operators available at the moment.
+  #
+  # find_first :superhero_name => 'The Ironist', :powers => 'Wit'
+  #
+  # mdb-sql doesn't implement LIMIT yet, so this method pulls all results and
+  # calls Array#first on them.  Ooky.
   def find_first(conditions_hash)
     rekey_hash(conditions_hash)
     result = sql_search(conditions_hash).first
     create_record(result) 
   end
   
+  
   def find_all(conditions_hash={})
     if conditions_hash.empty?
-      return sql_select(mdb_file, table_name, nil, '1 = 1').collect {|r| create_record(r)}
+      return sql_select_where(mdb_file, table_name, nil, '1 = 1').collect {|r| create_record(r)}
     end
     rekey_hash(conditions_hash)
     sql_search(conditions_hash).collect {|r| create_record(r) }
@@ -81,7 +87,7 @@ class Table
         "#{column.name} like '%#{value}%'"
       end
     end
-    sql_select(mdb_file, table_name, nil, conditions)
+    sql_select_where(mdb_file, table_name, nil, conditions)
   end
   
   

data/test/test_base.rb

@@ -18,8 +18,6 @@ class BaseTest < Test::Unit::TestCase
     set_primary_key 'Room'
   end
   
-
-  
   def test_setting_mdb_file
     assert_equal TEST_DB, Employee.mdb_file
   end
@@ -60,18 +58,37 @@ class BaseTest < Test::Unit::TestCase
   end
   
   def test_instantiate
-    hash = [{"Department"=>"Engineering", "Gender"=>"M", "Room"=>"6072", "Title"=>"Programmer", "Emp_Id"=>"1045", "First_Name"=>"Robert", "Last_Name"=>"Weinfeld"}]
+    hash = {"Department"=>"Engineering", "Gender"=>"M", "Room"=>"6072", "Title"=>"Programmer", "Emp_Id"=>"1045", "First_Name"=>"Robert", "Last_Name"=>"Weinfeld"}
     record = Employee.send(:instantiate, hash)
     assert_equal hash, record.instance_variable_get('@attributes')
+    hash = {"Area"=>"135.38","Entity_Handle"=>"9D7A","Room"=>"6004","Room_Type"=>"STOR-GEN"}
+    record = Room.send(:instantiate, hash)
+    assert_kind_of Float, record.instance_variable_get('@attributes')['Area']
   end
   
-  def test_sql_search
-    record = Employee.sql_search(:Room => '6072').first
+  def test_find_from_hash
+    record = Employee.find_from_hash(:Room => '6072').first
     assert_kind_of Employee, record
+    record = Room.find_first(:Area => 135.38)
+    assert_kind_of Room, record
+  end
+  
+  def test_find_where
+    weinstein = Employee.find_where( "Last_Name = 'Weinfeld'").first
+    assert_equal 'Robert', weinstein.First_Name
+  end
+  
+  def test_conditions_from_hash
+    hash = {:Room => '6072'}
+    conditions = "Room LIKE '%6072%'"
+    assert_equal conditions, Employee.conditions_from_hash(hash)
+    hash = {:Area => 45}
+    conditions = "Area = 45"
+    assert_equal conditions, Room.conditions_from_hash(hash)
   end
   
   def test_attribute_magic
-    record = Employee.sql_search(:Room => '6072').first
+    record = Employee.find_from_hash(:Room => '6072').first
     assert_equal '6072', record.Room
   end
   
@@ -80,7 +97,10 @@ class BaseTest < Test::Unit::TestCase
     assert_equal 2, Employee.find_all(:First_Name => 'G').size
   end
   
-
+  def test_column_for
+    assert_kind_of Column, Employee.column_for(:Room)
+    assert_nil Employee.column_for('foo')
+  end
   
 
 end

data/test/test_column.rb

@@ -0,0 +1,19 @@
+require File.join(File.dirname(__FILE__), "..", 'lib', 'active_mdb')
+require 'test/unit'
+require File.join(File.dirname(__FILE__), 'test_helper')
+
+class ColumnTest < Test::Unit::TestCase
+  
+
+  
+  def setup
+    @c1 = Column.new('is_available', 'Boolean', 0)
+  end
+  
+  def test_boolean_column
+    assert_equal false, @c1.type_cast(0)
+  end
+  
+
+  
+end

data/test/test_mdb_tools.rb

@@ -97,9 +97,9 @@ class MDBToolsTest < Test::Unit::TestCase
   #   assert_equal TORBATI_Y, employee_hash.first
   # end
   
-  def test_sql_select
+  def test_sql_select_where
     yo = {"Department"=>"Engineering", "Gender"=>"F", "Room"=>"6044", "Title"=>"Programmer", "Emp_Id"=>"1000", "First_Name"=>"Yolanda", "Last_Name"=>"Torbati"}
-    assert_equal yo, sql_select(TEST_DB, 'Employee', ['*'], "First_Name LIKE 'Yolanda'" ).first
+    assert_equal yo, sql_select_where(TEST_DB, 'Employee', ['*'], "First_Name LIKE 'Yolanda'" ).first
   end
   
   def test_compile_conditions
@@ -107,8 +107,8 @@ class MDBToolsTest < Test::Unit::TestCase
     assert_equal "baz like '%1%' AND foo like '%bar%' AND nark like '%noo%'", compile_conditions(conditions)
   end
   
-  def test_compiled_sql_select
-    sql_select(TEST_DB, 'Employee', nil, compile_conditions(:first_name => 'Yolanda'))
+  def test_compiled_sql_select_where
+    sql_select_where(TEST_DB, 'Employee', nil, compile_conditions(:first_name => 'Yolanda'))
   end
   
   def test_count

metadata

@@ -3,13 +3,13 @@ rubygems_version: 0.9.2
 specification_version: 1
 name: activemdb
 version: !ruby/object:Gem::Version 
-  version: 0.2.0
-date: 2007-04-05 00:00:00 -05:00
-summary: ActiveRecordy wrapper around MDB Tools, which lets POSIX platforms read MS Access (.mdb) files
+  version: 0.2.1
+date: 2007-04-10 00:00:00 -05:00
+summary: ActiveRecordy wrapper around MDB Tools, allowing POSIX platforms to read MS Access (.mdb) files
 require_paths: 
 - lib
 email: automatthew@gmail.com
-homepage: http://rubyforge.org/projects/activemdb/
+homepage: http://activemdb.rubyforge.org/
 rubyforge_project: activemdb
 description: Intended for exploration and migration, not production. And it's *READ ONLY*, so don't try to get fresh. ActiveMDB provides a wrapper of varying thickness around the utilities from Brian Bruns's MDB Tools project (http://mdbtools.sourceforge.net/).  Kudos to Mr. Bruns.
 autorequire: 
@@ -48,6 +48,7 @@ files:
 - support/a.insert
 - test/test_activemdb.rb
 - test/test_base.rb
+- test/test_column.rb
 - test/test_helper.rb
 - test/test_mdb.rb
 - test/test_mdb_tools.rb
@@ -56,6 +57,7 @@ files:
 test_files: 
 - test/test_activemdb.rb
 - test/test_base.rb
+- test/test_column.rb
 - test/test_helper.rb
 - test/test_mdb.rb
 - test/test_mdb_tools.rb