infused-dbf 1.0.7

data/History.txt

@@ -0,0 +1,55 @@
+== 1.0.7
+
+* Remove support for original column names.  All columns names are now downcased/underscored.
+
+== 1.0.6
+
+* DBF::Table now includes the Enumerable module
+* Return nil for memo values if the memo file is missing
+* Finder conditions now support the original and downcased/underscored column names
+
+== 1.0.5
+
+* Strip non-ascii characters from column names
+
+== 1.0.4
+
+* Underscore column names when dumping schemas (FieldId becomes field_id)
+
+== 1.0.3
+
+* Add support for Visual Foxpro Integer and Datetime columns
+
+== 1.0.2
+
+* Compatibility fix for Visual Foxpro memo files (ignore negative memo index values)
+
+== 1.0.1
+
+* Fixes error when using the command-line interface [#11984]
+
+== 1.0.0
+
+* Renamed classes and refactored code in preparation for adding the
+  ability to save records and create/compact databases.
+* The Reader class has been renamed to Table
+* Attributes are no longer accessed directly from the record.  Use record.attribute['column_name']
+  instead, or use the new attribute accessors detailed under Basic Usage.
+
+== 0.5.4
+
+* Ignore deleted records in both memory modes
+
+== 0.5.3
+
+* Added a standalone dbf utility (try dbf -h for help)
+
+== 0.5.0 / 2007-05-25
+
+* New find method
+* Full compatibility with the two flavors of memo file
+* Two modes of operation:
+  * In memory (default): All records are loaded into memory on the first
+    request. Records are retrieved from memory for all subsequent requests.
+  * File I/O: All records are retrieved from disk on every request
+* Improved documentation and more usage examples

data/Manifest.txt

@@ -0,0 +1,31 @@
+History.txt
+Manifest.txt
+README.txt
+Rakefile
+bin/dbf
+dbf.gemspec
+lib/dbf.rb
+lib/dbf/column.rb
+lib/dbf/globals.rb
+lib/dbf/record.rb
+lib/dbf/table.rb
+spec/fixtures/dbase_03.dbf
+spec/fixtures/dbase_30.dbf
+spec/fixtures/dbase_30.fpt
+spec/fixtures/dbase_83.dbf
+spec/fixtures/dbase_83.dbt
+spec/fixtures/dbase_83_schema.txt
+spec/fixtures/dbase_8b.dbf
+spec/fixtures/dbase_8b.dbt
+spec/fixtures/dbase_f5.dbf
+spec/fixtures/dbase_f5.fpt
+spec/functional/dbf_shared.rb
+spec/functional/format_03_spec.rb
+spec/functional/format_30_spec.rb
+spec/functional/format_83_spec.rb
+spec/functional/format_8b_spec.rb
+spec/functional/format_f5_spec.rb
+spec/spec_helper.rb
+spec/unit/column_spec.rb
+spec/unit/record_spec.rb
+spec/unit/table_spec.rb

data/README.txt

@@ -0,0 +1,115 @@
+= DBF
+
+DBF is a small fast library for reading dBase, xBase, Clipper and FoxPro database files
+
+Copyright (c) 2006-2008 Keith Morrison <keithm@infused.org, www.infused.org>
+
+* Official project page: http://rubyforge.org/projects/dbf
+* API Documentation: http://dbf.rubyforge.org/docs
+* To report bugs: http://www.rubyforge.org/tracker/?group_id=2009
+* Questions: Email keithm@infused.org and put DBF somewhere in the subject
+  line
+
+== Features
+
+* No external dependencies
+* Fields are type cast to the appropriate Ruby types
+* Ability to dump the database schema in the portable ActiveRecord::Schema
+  format
+
+== Installation
+  
+  gem install dbf
+  
+== Basic Usage
+
+  require 'rubygems'
+  require 'dbf'
+
+  table = DBF::Table.new("widgets.dbf")
+  
+  # Tables are enumerable
+  widget_ids = table.map { |row| row.id }
+  abc_names = table.select { |row| row.name =~ /^[a-cA-C] }
+  sorted = table.sort_by { |row| row.name }
+  
+  # Print the 'name' field from record number 4
+  puts table.record(4).name
+
+	# Attributes can also be accessed using the column name as a Hash key
+	puts table.record(4).attributes["name"]
+  
+  # Print the 'name' and 'address' fields from each record
+  table.records.each do |record|
+    puts record.name
+    puts record.email
+  end
+
+  # Find records
+  table.find :all, :first_name => 'Keith'
+  table.find :all, :first_name => 'Keith', :last_name => 'Morrison'
+  table.find :first, :first_name => 'Keith'
+  table.find(10)
+  
+== Migrating to ActiveRecord
+
+An example of migrating a DBF book table to ActiveRecord using a migration:
+
+  require 'dbf'
+  
+  class CreateBooks < ActiveRecord::Migration
+    def self.up
+      table = DBF::Table.new('db/dbf/books.dbf')
+      eval(table.schema)
+
+      table.records.each do |record|
+        Book.create(record.attributes)
+      end
+    end
+
+    def self.down
+      drop_table :books
+    end
+  end
+  
+== Command-line utility
+
+A small command-line utility called dbf is installed along with the gem.
+
+  $ dbf -h
+  usage: dbf [-h|-s|-a] filename
+    -h = print this message
+    -s = print summary information
+    -a = create an ActiveRecord::Schema
+  
+== Limitations and known bugs
+  
+* DBF is read-only
+* Index files are not used
+
+== License
+
+(The MIT Licence)
+
+Copyright (c) 2006-2008 Keith Morrison <keithm@infused.org>
+
+Permission is hereby granted, free of charge, to any person
+obtaining a copy of this software and associated documentation
+files (the "Software"), to deal in the Software without
+restriction, including without limitation the rights to use,
+copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the
+Software is furnished to do so, subject to the following
+conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+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.

data/Rakefile

@@ -0,0 +1,37 @@
+require 'hoe'
+require 'spec/rake/spectask'
+
+PKG_NAME = "dbf"
+PKG_VERSION = "1.0.7"
+PKG_FILE_NAME = "#{PKG_NAME}-#{PKG_VERSION}"
+
+Hoe.new PKG_NAME, PKG_VERSION do |p|
+  p.rubyforge_name = PKG_NAME
+  p.author = "Keith Morrison"
+  p.email = "keithm@infused.org"
+  p.summary = "A small fast library for reading dBase, xBase, Clipper and FoxPro database files."
+  p.description = p.paragraphs_of("README.txt", 1..3).join("\n\n")
+  p.changes = p.paragraphs_of("History.txt", 0..1).join("\n\n")
+  p.url = "http://github.com/infused/dm-dbf/tree/master"
+  p.need_tar = true
+  p.need_zip = true
+  p.extra_deps << ['activesupport', '>= 2.1.0']
+end
+
+task :default => :spec
+
+desc "Run specs"
+Spec::Rake::SpecTask.new :spec do |t|
+  t.spec_files = FileList['spec/**/*spec.rb']
+end
+
+desc "Run spec docs"
+Spec::Rake::SpecTask.new :specdoc do |t|
+  t.spec_opts = ["-f specdoc"]
+  t.spec_files = FileList['spec/**/*spec.rb']
+end
+
+desc "Generate gemspec"
+task :gemspec do |t|
+  `rake debug_gem > dbf.gemspec`
+end

data/bin/dbf

@@ -0,0 +1,40 @@
+#!/usr/bin/env ruby -ws
+
+require 'rubygems'
+require 'dbf'
+
+$a ||= false
+$s ||= false
+
+if defined? $h then
+  puts "usage: #{File.basename(__FILE__)} [-h|-s|-a] filename"
+  puts "  -h = print this message"
+  puts "  -s = print summary information"
+  puts "  -a = create an ActiveRecord::Schema"
+else
+
+  filename = ARGV.shift
+  abort "You must supply a filename on the command line" unless filename
+
+  # create an ActiveRecord::Schema
+  if $a
+    table = DBF::Table.new filename
+    puts table.schema
+  end
+  
+  if $s
+    table = DBF::Table.new filename
+    puts
+    puts "Database: #{filename}"
+    puts "Type: (#{table.version}) #{table.version_description}"
+    puts "Memo Type: #{table.memo_file_format}" if table.has_memo_file?
+    puts "Records: #{table.record_count}"
+    
+    puts "\nFields:"
+    puts "Name             Type       Length     Decimal"
+    puts "-" * 78
+    table.columns.each do |f|
+      puts "%-16s %-10s %-10s %-10s" % [f.name, f.type, f.length, f.decimal]
+    end
+  end
+end

data/dbf.gemspec

@@ -0,0 +1,37 @@
+Gem::Specification.new do |s|
+  s.name = %q{dbf}
+  s.version = "1.0.7"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Keith Morrison"]
+  s.date = %q{2009-01-01}
+  s.default_executable = %q{dbf}
+  s.description = %q{DBF is a small fast library for reading dBase, xBase, Clipper and FoxPro database files  Copyright (c) 2006-2008 Keith Morrison <keithm@infused.org, www.infused.org>  * Official project page: http://rubyforge.org/projects/dbf * API Documentation: http://dbf.rubyforge.org/docs * To report bugs: http://www.rubyforge.org/tracker/?group_id=2009 * Questions: Email keithm@infused.org and put DBF somewhere in the subject line}
+  s.email = %q{keithm@infused.org}
+  s.executables = ["dbf"]
+  s.extra_rdoc_files = ["History.txt", "Manifest.txt", "README.txt"]
+  s.files = ["History.txt", "Manifest.txt", "README.txt", "Rakefile", "bin/dbf", "dbf.gemspec", "lib/dbf.rb", "lib/dbf/column.rb", "lib/dbf/globals.rb", "lib/dbf/record.rb", "lib/dbf/table.rb", "spec/fixtures/dbase_03.dbf", "spec/fixtures/dbase_30.dbf", "spec/fixtures/dbase_30.fpt", "spec/fixtures/dbase_83.dbf", "spec/fixtures/dbase_83.dbt", "spec/fixtures/dbase_83_schema.txt", "spec/fixtures/dbase_8b.dbf", "spec/fixtures/dbase_8b.dbt", "spec/fixtures/dbase_f5.dbf", "spec/fixtures/dbase_f5.fpt", "spec/functional/dbf_shared.rb", "spec/functional/format_03_spec.rb", "spec/functional/format_30_spec.rb", "spec/functional/format_83_spec.rb", "spec/functional/format_8b_spec.rb", "spec/functional/format_f5_spec.rb", "spec/spec_helper.rb", "spec/unit/column_spec.rb", "spec/unit/record_spec.rb", "spec/unit/table_spec.rb"]
+  s.has_rdoc = true
+  s.homepage = %q{http://github.com/infused/dm-dbf/tree/master}
+  s.rdoc_options = ["--main", "README.txt"]
+  s.require_paths = ["lib"]
+  s.rubyforge_project = %q{dbf}
+  s.rubygems_version = %q{1.3.1}
+  s.summary = %q{A small fast library for reading dBase, xBase, Clipper and FoxPro database files.}
+
+  if s.respond_to? :specification_version then
+    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
+    s.specification_version = 2
+
+    if Gem::Version.new(Gem::RubyGemsVersion) >= Gem::Version.new('1.2.0') then
+      s.add_runtime_dependency(%q<activesupport>, [">= 2.1.0"])
+      s.add_development_dependency(%q<hoe>, [">= 1.8.2"])
+    else
+      s.add_dependency(%q<activesupport>, [">= 2.1.0"])
+      s.add_dependency(%q<hoe>, [">= 1.8.2"])
+    end
+  else
+    s.add_dependency(%q<activesupport>, [">= 2.1.0"])
+    s.add_dependency(%q<hoe>, [">= 1.8.2"])
+  end
+end

data/lib/dbf/column.rb

@@ -0,0 +1,85 @@
+module DBF
+  class ColumnLengthError < DBFError; end
+  class ColumnNameError < DBFError; end
+  
+  class Column
+    attr_reader :name, :type, :length, :decimal
+    
+    def initialize(name, type, length, decimal)
+      raise ColumnLengthError, "field length must be greater than 0" unless length > 0
+      @name, @type, @length, @decimal = strip_non_ascii_chars(name), type, length, decimal
+    end
+    
+    def type_cast(value)
+      value = value.is_a?(Array) ? value.first : value
+      
+      case type
+      when 'N' # number
+        decimal.zero? ? unpack_integer(value) : value.to_f
+      when 'D' # date
+        value.to_date unless value.blank?
+      when 'L' # logical
+        value.strip =~ /^(y|t)$/i ? true : false
+      when 'I' # integer
+        unpack_integer(value)
+      when 'T' # datetime
+        decode_datetime(value)
+      else
+        value.to_s.strip
+      end
+    end
+    
+    def decode_datetime(value)
+      days, milliseconds = value.unpack('l2')
+      hours = (milliseconds / MS_PER_HOUR).to_i
+      minutes = ((milliseconds - (hours * MS_PER_HOUR)) / MS_PER_MINUTE).to_i
+      seconds = ((milliseconds - (hours * MS_PER_HOUR) - (minutes * MS_PER_MINUTE)) / MS_PER_SECOND).to_i
+      DateTime.jd(days, hours, minutes, seconds)
+    end
+    
+    def unpack_integer(value)
+      value.unpack('v').first.to_i
+    end
+    
+    def schema_definition
+      data_type = case type
+      when "N" # number
+        if decimal > 0
+          ":float"
+        else
+          ":integer"
+        end
+      when "I" # integer
+        ":integer"
+      when "D" # date
+        ":date"
+      when "T" # datetime
+        ":datetime"
+      when "L" # boolean
+        ":boolean"
+      when "M" # memo
+        ":text"
+      else
+        ":string, :limit => #{length}"
+      end
+      
+      "\"#{name.underscore}\", #{data_type}\n"
+    end
+    
+    private
+    
+    def strip_non_ascii_chars(s)
+      clean = ''
+      s.each_byte do |char|
+        if char > 31 && char < 127
+          clean << char
+        else
+          raise ColumnNameError 'column name must not be empty' if clean.length == 0
+          return clean if char == 0
+        end
+      end
+      clean
+    end
+  end
+  
+end

data/lib/dbf/globals.rb

@@ -0,0 +1,27 @@
+module DBF
+  DBF_HEADER_SIZE = 32
+  FPT_HEADER_SIZE = 512
+  BLOCK_HEADER_SIZE = 8
+  DATE_REGEXP = /([\d]{4})([\d]{2})([\d]{2})/
+  VERSION_DESCRIPTIONS = {
+    "02" => "FoxBase",
+    "03" => "dBase III without memo file",
+    "04" => "dBase IV without memo file",
+    "05" => "dBase V without memo file",
+    "30" => "Visual FoxPro",
+    "31" => "Visual FoxPro with AutoIncrement field",
+    "7b" => "dBase IV with memo file",
+    "83" => "dBase III with memo file",
+    "8b" => "dBase IV with memo file",
+    "8e" => "dBase IV with SQL table",
+    "f5" => "FoxPro with memo file",
+    "fb" => "FoxPro without memo file"
+  }
+  
+  MS_PER_SECOND = 1000
+  MS_PER_MINUTE = MS_PER_SECOND * 60
+  MS_PER_HOUR   = MS_PER_MINUTE * 60
+  
+  class DBFError < StandardError; end
+
+end

data/lib/dbf/record.rb

@@ -0,0 +1,99 @@
+module DBF
+  class Record
+    attr_reader :attributes
+    
+    def initialize(table)
+      @table, @data, @memo = table, table.data, table.memo
+      initialize_values(table.columns)
+      define_accessors
+    end
+    
+    def ==(other)
+      other.respond_to?(:attributes) && other.attributes == attributes
+    end
+    
+    private
+    
+    def define_accessors
+      @table.columns.each do |column|
+        underscored_column_name = column.name.underscore
+        unless respond_to?(underscored_column_name)
+          self.class.send :define_method, underscored_column_name do
+            @attributes[column.name.underscore]
+          end
+        end
+      end
+    end
+    
+    def initialize_values(columns)
+      @attributes = columns.inject({}) do |hash, column|
+        if column.type == 'M'
+          starting_block = unpack_string(column).to_i
+          hash[column.name.underscore] = read_memo(starting_block)
+        else
+          value = unpack_column(column)
+          hash[column.name.underscore] = column.type_cast(value)
+        end
+        hash
+      end
+    end
+  
+    def unpack_column(column)
+      @data.read(column.length).to_s.unpack("a#{column.length}")
+    end
+  
+    def unpack_string(column)
+      unpack_column(column).to_s
+    end
+  
+    def read_memo(start_block)
+      return nil if !@table.has_memo_file? || start_block < 1
+
+      @table.memo_file_format == :fpt ? build_fpt_memo(start_block) : build_dbt_memo(start_block)
+    end
+    
+    def build_fpt_memo(start_block)
+      @memo.seek(start_block * memo_block_size)
+      
+      memo_type, memo_size, memo_string = @memo.read(memo_block_size).unpack("NNa56")
+      return nil unless memo_type == 1 and memo_size > 0
+      
+      if memo_size > memo_block_content_size
+        memo_string << @memo.read(memo_content_size(memo_size))
+      else
+        memo_string = memo_string[0, memo_size]
+      end
+      memo_string
+    end
+    
+    def build_dbt_memo(start_block)
+      @memo.seek(start_block * memo_block_size)
+      
+      case @table.version
+      when "83" # dbase iii
+        memo_string = ""
+        loop do
+          memo_string << block = @memo.read(memo_block_size)
+          break if block.rstrip.size < memo_block_size
+        end
+      when "8b" # dbase iv
+        memo_type, memo_size = @memo.read(BLOCK_HEADER_SIZE).unpack("LL")
+        memo_string = @memo.read(memo_size)
+      end
+      memo_string
+    end
+    
+    def memo_block_size
+      @memo_block_size ||= @table.memo_block_size
+    end
+    
+    def memo_block_content_size
+      memo_block_size - BLOCK_HEADER_SIZE
+    end
+    
+    def memo_content_size(memo_size)
+      (memo_size - memo_block_size) + BLOCK_HEADER_SIZE
+    end
+    
+  end
+end