infused-dbf 1.0.7

data/lib/dbf/table.rb

@@ -0,0 +1,243 @@
+module DBF
+
+  class Table
+    include Enumerable
+    
+    attr_reader :column_count           # The total number of columns (columns)
+    attr_reader :columns                # An array of DBF::Column
+    attr_reader :version                # Internal dBase version number
+    attr_reader :last_updated           # Last updated datetime
+    attr_reader :memo_file_format       # :fpt or :dpt
+    attr_reader :memo_block_size        # The block size for memo records
+    attr_reader :options                # The options hash that was used to initialize the table
+    attr_reader :data                   # DBF file handle
+    attr_reader :memo                   # Memo file handle
+    
+    # Initializes a new DBF::Table
+    # Example:
+    #   table = DBF::Table.new 'data.dbf'
+    def initialize(filename, options = {})
+      @data = File.open(filename, 'rb')
+      @memo = open_memo(filename)
+      @options = options
+      reload!
+    end
+    
+    # Reloads the database and memo files
+    def reload!
+      @records = nil
+      get_header_info
+      get_memo_header_info if @memo
+      get_column_descriptors
+      build_db_index
+    end
+    
+    # Returns true if there is a corresponding memo file
+    def has_memo_file?
+      @memo ? true : false
+    end
+    
+    # The total number of active records.
+    def record_count
+      @db_index.size
+    end
+    
+    # Returns an instance of DBF::Column for <b>column_name</b>.  The <b>column_name</b>
+    # can be a specified as either a symbol or string.
+    def column(column_name)
+      @columns.detect {|f| f.name == column_name.to_s}
+    end
+    
+    # An array of all the records contained in the database file.  Each record is an instance
+    # of DBF::Record (or nil if the record is marked for deletion).
+    def records
+      self.to_a
+    end
+
+    alias_method :rows, :records
+    
+    def each
+      0.upto(@record_count - 1) do |n|
+        seek_to_record(n)
+        unless deleted_record?
+          yield DBF::Record.new(self)
+        end
+      end
+    end
+    
+    # def get_record_from_file(index)
+    #   seek_to_record(@db_index[index])
+    #   Record.new(self)
+    # end
+    
+    # Returns a DBF::Record (or nil if the record has been marked for deletion) for the record at <tt>index</tt>.
+    def record(index)
+      records[index]
+    end
+    
+    # Find records using a simple ActiveRecord-like syntax.
+    #
+    # Examples:
+    #   table = DBF::Table.new 'mydata.dbf'
+    #   
+    #   # Find record number 5
+    #   table.find(5)
+    #
+    #   # Find all records for Keith Morrison
+    #   table.find :all, :first_name => "Keith", :last_name => "Morrison"
+    # 
+    #   # Find first record
+    #   table.find :first, :first_name => "Keith"
+    #
+    # The <b>command</b> can be an id, :all, or :first.
+    # <b>options</b> is optional and, if specified, should be a hash where the keys correspond
+    # to column names in the database.  The values will be matched exactly with the value
+    # in the database.  If you specify more than one key, all values must match in order 
+    # for the record to be returned.  The equivalent SQL would be "WHERE key1 = 'value1'
+    # AND key2 = 'value2'".
+    def find(command, options = {})
+      results = options.empty? ? records : records.select {|record| all_values_match?(record, options)}
+      
+      case command
+      when Fixnum
+        record(command)
+      when :all
+        results
+      when :first
+        results.first
+      end
+    end
+    
+    alias_method :row, :record
+    
+    # Returns a description of the current database file.
+    def version_description
+      VERSION_DESCRIPTIONS[version]
+    end
+    
+    # Returns a database schema in the portable ActiveRecord::Schema format.
+    # 
+    # xBase data types are converted to generic types as follows:
+    # - Number columns are converted to :integer if there are no decimals, otherwise
+    #   they are converted to :float
+    # - Date columns are converted to :datetime
+    # - Logical columns are converted to :boolean
+    # - Memo columns are converted to :text
+    # - Character columns are converted to :string and the :limit option is set
+    #   to the length of the character column
+    #
+    # Example:
+    #   create_table "mydata" do |t|
+    #     t.column :name, :string, :limit => 30
+    #     t.column :last_update, :datetime
+    #     t.column :is_active, :boolean
+    #     t.column :age, :integer
+    #     t.column :notes, :text
+    #   end
+    def schema(path = nil)
+      s = "ActiveRecord::Schema.define do\n"
+      s << "  create_table \"#{File.basename(@data.path, ".*")}\" do |t|\n"
+      columns.each do |column|
+        s << "    t.column #{column.schema_definition}"
+      end
+      s << "  end\nend"
+      
+      if path
+        File.open(path, 'w') {|f| f.puts(s)}
+      else
+        s
+      end
+    end
+    
+    # Returns the record at <tt>index</tt> by seeking to the record in the
+    # physical database file. See the documentation for the records method for
+    # information on how these two methods differ.
+    def get_record_from_file(index)
+      seek_to_record(@db_index[index])
+      Record.new(self)
+    end
+    
+    private
+    
+      def open_memo(file)
+        %w(fpt FPT dbt DBT).each do |extname|
+          filename = replace_extname(file, extname)
+          if File.exists?(filename)
+            @memo_file_format = extname.downcase.to_sym
+            return File.open(filename, 'rb')
+          end
+        end
+        nil
+      end
+      
+      def replace_extname(filename, extension)
+        filename.sub(/#{File.extname(filename)[1..-1]}$/, extension)
+      end
+    
+      def deleted_record?
+        if @data.read(1).unpack('a') == ['*']
+          @data.rewind
+          true
+        else
+          false
+        end
+      end
+    
+      def get_header_info
+        @data.rewind
+        @version, @record_count, @header_length, @record_length = @data.read(DBF_HEADER_SIZE).unpack('H2 x3 V v2')
+        @column_count = (@header_length - DBF_HEADER_SIZE + 1) / DBF_HEADER_SIZE
+      end
+    
+      def get_column_descriptors
+        @columns = []
+        @column_count.times do
+          name, type, length, decimal = @data.read(32).unpack('a10 x a x4 C2')
+          if length > 0
+            @columns << Column.new(name.strip, type, length, decimal)
+          end
+        end
+        # Reset the column count in case any were skipped
+        @column_count = @columns.size
+        
+        @columns
+      end
+    
+      def get_memo_header_info
+        @memo.rewind
+        if @memo_file_format == :fpt
+          @memo_next_available_block, @memo_block_size = @memo.read(FPT_HEADER_SIZE).unpack('N x2 n')
+          @memo_block_size = 0 if @memo_block_size.nil?
+        else
+          @memo_block_size = 512
+          @memo_next_available_block = File.size(@memo.path) / @memo_block_size
+        end
+      end
+    
+      def seek(offset)
+        @data.seek(@header_length + offset)
+      end
+    
+      def seek_to_record(index)
+        seek(index * @record_length)
+      end
+      
+      def build_db_index
+        @db_index = []
+        @deleted_records = []
+        0.upto(@record_count - 1) do |n|
+          seek_to_record(n)
+          if deleted_record?
+            @deleted_records << n
+          else
+            @db_index << n
+          end
+        end
+      end
+      
+      def all_values_match?(record, options)
+        options.map {|key, value| record.attributes[key.to_s.underscore] == value}.all?
+      end
+  end
+  
+end

data/lib/dbf.rb

@@ -0,0 +1,7 @@
+require 'date'
+require 'activesupport'
+
+require 'dbf/globals'
+require 'dbf/record'
+require 'dbf/column'
+require 'dbf/table'

data/spec/fixtures/dbase_83_schema.txt

@@ -0,0 +1,19 @@
+ActiveRecord::Schema.define do
+  create_table "dbase_83" do |t|
+    t.column "id", :integer
+    t.column "catcount", :integer
+    t.column "agrpcount", :integer
+    t.column "pgrpcount", :integer
+    t.column "order", :integer
+    t.column "code", :string, :limit => 50
+    t.column "name", :string, :limit => 100
+    t.column "thumbnail", :string, :limit => 254
+    t.column "image", :string, :limit => 254
+    t.column "price", :float
+    t.column "cost", :float
+    t.column "desc", :text
+    t.column "weight", :float
+    t.column "taxable", :boolean
+    t.column "active", :boolean
+  end
+end

data/spec/functional/dbf_shared.rb

@@ -0,0 +1,45 @@
+describe DBF, :shared => true do
+  specify "sum of column lengths should equal record length specified in header" do
+    header_record_length = @table.instance_eval {@record_length}
+    sum_of_column_lengths = @table.columns.inject(1) {|sum, column| sum + column.length}
+    
+    header_record_length.should == sum_of_column_lengths
+  end
+
+  specify "records should be instances of DBF::Record" do
+    @table.records.all? {|record| record.should be_an_instance_of(DBF::Record)}
+  end
+  
+  specify "columns should be instances of DBF::Column" do
+    @table.columns.all? {|column| column.should be_an_instance_of(DBF::Column)}
+  end
+  
+  specify "column names should not be blank" do
+    @table.columns.all? {|column| column.name.should_not be_empty}
+  end
+  
+  specify "column types should be valid" do
+    valid_column_types = %w(C N L D M F B G P Y T I V X @ O +)
+    @table.columns.all? {|column| valid_column_types.should include(column.type)}
+  end
+  
+  specify "column lengths should be instances of Fixnum" do
+    @table.columns.all? {|column| column.length.should be_an_instance_of(Fixnum)}
+  end
+  
+  specify "column lengths should be larger than 0" do
+    @table.columns.all? {|column| column.length.should > 0}
+  end
+  
+  specify "column decimals should be instances of Fixnum" do
+    @table.columns.all? {|column| column.decimal.should be_an_instance_of(Fixnum)}
+  end
+  
+  specify "column read accessors should return the attribute after typecast" do
+    @table.columns do |column|
+      record = table.records.first
+      record.send(column.name).should == record[column.name]
+    end
+  end
+  
+end

data/spec/functional/format_03_spec.rb

@@ -0,0 +1,23 @@
+require File.dirname(__FILE__) + "/../spec_helper"
+require File.dirname(__FILE__) + "/dbf_shared"
+
+describe DBF, "of type 03 (dBase III without memo file)" do
+  before(:each) do
+    @table = DBF::Table.new "#{DB_PATH}/dbase_03.dbf"
+  end
+  
+  it_should_behave_like "DBF"
+  
+  it "should report the correct version number" do
+    @table.version.should == "03"
+  end
+  
+  it "should have a memo file" do
+    @table.should_not have_memo_file
+  end
+  
+  it "should report the correct memo type" do
+    @table.memo_file_format.should be_nil
+  end
+  
+end

data/spec/functional/format_30_spec.rb

@@ -0,0 +1,23 @@
+require File.dirname(__FILE__) + "/../spec_helper"
+require File.dirname(__FILE__) + "/dbf_shared"
+
+describe DBF, "of type 30 (Visual FoxPro)" do
+  before(:each) do
+    @table = DBF::Table.new "#{DB_PATH}/dbase_30.dbf"
+  end
+  
+  it_should_behave_like "DBF"
+  
+  it "should report the correct version number" do
+    @table.version.should == "30"
+  end
+  
+  it "should have a memo file" do
+    @table.should have_memo_file
+  end
+  
+  it "should report the correct memo type" do
+    @table.memo_file_format.should == :fpt
+  end
+  
+end

data/spec/functional/format_83_spec.rb

@@ -0,0 +1,23 @@
+require File.dirname(__FILE__) + "/../spec_helper"
+require File.dirname(__FILE__) + "/dbf_shared"
+
+describe DBF, "of type 83 (dBase III with memo file)" do
+  before(:each) do
+    @table = DBF::Table.new "#{DB_PATH}/dbase_83.dbf"
+  end
+  
+  it_should_behave_like "DBF"
+  
+  it "should report the correct version number" do
+    @table.version.should == "83"
+  end
+  
+  it "should have a memo file" do
+    @table.should have_memo_file
+  end
+  
+  it "should report the correct memo type" do
+    @table.memo_file_format.should == :dbt
+  end
+  
+end

data/spec/functional/format_8b_spec.rb

@@ -0,0 +1,23 @@
+require File.dirname(__FILE__) + "/../spec_helper"
+require File.dirname(__FILE__) + "/dbf_shared"
+
+describe DBF, "of type 8b (dBase IV with memo file)" do
+  before(:each) do
+    @table = DBF::Table.new "#{DB_PATH}/dbase_8b.dbf"
+  end
+  
+  it_should_behave_like "DBF"
+  
+  it "should report the correct version number" do
+    @table.version.should == "8b"
+  end
+  
+  it "should have a memo file" do
+    @table.should have_memo_file
+  end
+  
+  it "should report the correct memo type" do
+    @table.memo_file_format.should == :dbt
+  end
+  
+end

data/spec/functional/format_f5_spec.rb

@@ -0,0 +1,23 @@
+require File.dirname(__FILE__) + "/../spec_helper"
+require File.dirname(__FILE__) + "/dbf_shared"
+
+describe DBF, "of type f5 (FoxPro with memo file)" do
+  before(:each) do
+    @table = DBF::Table.new "#{DB_PATH}/dbase_f5.dbf"
+  end
+  
+  it_should_behave_like "DBF"
+  
+  it "should report the correct version number" do
+    @table.version.should == "f5"
+  end
+  
+  it "should have a memo file" do
+    @table.should have_memo_file
+  end
+  
+  it "should report the correct memo type" do
+    @table.memo_file_format.should == :fpt
+  end
+  
+end

data/spec/spec_helper.rb

@@ -0,0 +1,10 @@
+$:.unshift(File.dirname(__FILE__) + "/../lib/")
+require "rubygems"
+require "spec"
+require "dbf"
+
+DB_PATH = File.dirname(__FILE__) + '/fixtures' unless defined?(DB_PATH)
+
+Spec::Runner.configure do |config|
+  
+end

data/spec/unit/column_spec.rb

@@ -0,0 +1,124 @@
+require File.dirname(__FILE__) + "/../spec_helper"
+
+describe DBF::Column do
+  
+  context "when initialized" do
+    before do
+      @column = DBF::Column.new "ColumnName", "N", 1, 0
+    end
+
+    it "should set the #name accessor" do
+      @column.name.should == "ColumnName"
+    end
+  
+    it "should set the #type accessor" do
+      @column.type.should == "N"
+    end
+  
+    it "should set the #length accessor" do
+      @column.length.should == 1
+    end
+  
+    it "should set the #decimal accessor" do
+      @column.decimal.should == 0
+    end
+  
+    it "should raise an error if length is greater than 0" do
+      lambda { column = DBF::Column.new "ColumnName", "N", -1, 0 }.should raise_error(DBF::ColumnLengthError)
+    end
+  end
+  
+  context "#type_cast" do
+    it "should cast numbers with decimals to Float" do
+      value = "13.5"
+      column = DBF::Column.new "ColumnName", "N", 2, 1
+      column.type_cast(value).should == 13.5
+    end
+    
+    it "should cast numbers with no decimals to Integer" do
+      value = "135"
+      column = DBF::Column.new "ColumnName", "N", 3, 0
+      column.type_cast(value).should == 13105
+    end
+    
+    it "should cast :integer to Integer" do
+      value = "135"
+      column = DBF::Column.new "ColumnName", "I", 3, 0
+      column.type_cast(value).should == 13105
+    end
+    
+    it "should cast boolean to True" do
+      value = "y"
+      column = DBF::Column.new "ColumnName", "L", 1, 0
+      column.type_cast(value).should == true
+    end
+    
+    it "should cast boolean to False" do
+      value = "n"
+      column = DBF::Column.new "ColumnName", "L", 1, 0
+      column.type_cast(value).should == false
+    end
+    
+    it "should cast :datetime columns to DateTime" do
+      value = "Nl%\000\300Z\252\003"
+      column = DBF::Column.new "ColumnName", "T", 16, 0
+      column.type_cast(value).should == "2002-10-10T17:04:56+00:00"
+    end
+    
+    it "should cast :date columns to Date" do
+      value = "20050712"
+      column = DBF::Column.new "ColumnName", "D", 8, 0
+      column.type_cast(value).should == Date.new(2005,7,12)
+    end
+  end
+  
+  context "#schema_definition" do
+    it "should define an integer column if type is (N)umber with 9 decimals" do
+      column = DBF::Column.new "ColumnName", "N", 1, 0
+      column.schema_definition.should == "\"column_name\", :integer\n"
+    end
+    
+    it "should define a float colmn if type is (N)umber with more than 0 decimals" do
+      column = DBF::Column.new "ColumnName", "N", 1, 2
+      column.schema_definition.should == "\"column_name\", :float\n"
+    end
+    
+    it "should define a date column if type is (D)ate" do
+      column = DBF::Column.new "ColumnName", "D", 8, 0
+      column.schema_definition.should == "\"column_name\", :date\n"
+    end
+    
+    it "should define a datetime column if type is (D)ate" do
+      column = DBF::Column.new "ColumnName", "T", 16, 0
+      column.schema_definition.should == "\"column_name\", :datetime\n"
+    end
+    
+    it "should define a boolean column if type is (L)ogical" do
+      column = DBF::Column.new "ColumnName", "L", 1, 0
+      column.schema_definition.should == "\"column_name\", :boolean\n"
+    end
+    
+    it "should define a text column if type is (M)emo" do
+      column = DBF::Column.new "ColumnName", "M", 1, 0
+      column.schema_definition.should == "\"column_name\", :text\n"
+    end
+    
+    it "should define a string column with length for any other data types" do
+      column = DBF::Column.new "ColumnName", "X", 20, 0
+      column.schema_definition.should == "\"column_name\", :string, :limit => 20\n"
+    end
+  end
+  
+  context "#strip_non_ascii_chars" do
+    it "should strip characters below decimal 32 and above decimal 127" do
+      column = DBF::Column.new "ColumnName", "N", 1, 0
+      column.send(:strip_non_ascii_chars, "--\x1F-\x68\x65\x6C\x6C\x6F world-\x80--").should == "---hello world---"
+    end
+
+    it "should truncate characters with decimal 0" do
+      column = DBF::Column.new "ColumnName", "N", 1, 0
+      column.send(:strip_non_ascii_chars, "--\x1F-\x68\x65\x6C\x6C\x6F \x00 world-\x80--").should == "---hello "
+    end
+  end
+  
+end