dbf 5.4.0 → 5.6.0

data/lib/dbf/table.rb

@@ -1,12 +1,6 @@
 # frozen_string_literal: true
 
 module DBF
-  class FileNotFoundError < StandardError
-  end
-
-  class NoColumnsDefined < StandardError
-  end
-
   # Leading bytes that make a spreadsheet treat a CSV cell as a formula:
   # "=", "+", "-", "@", tab, and carriage return.
   CSV_FORMULA_TRIGGERS = [0x3D, 0x2B, 0x2D, 0x40, 0x09, 0x0D].freeze
@@ -37,6 +31,9 @@ module DBF
     #   # working with a dbf in memory
     #   table = DBF::Table.new StringIO.new(dbf_data)
     #
+    #   # working with an open IO object
+    #   table = DBF::Table.new File.open('data.dbf', 'rb')
+    #
     #   # working with a dbf and memo in memory
     #   table = DBF::Table.new StringIO.new(dbf_data), StringIO.new(memo_data)
     #
@@ -44,14 +41,41 @@ module DBF
     #   table = DBF::Table.new 'data.dbf', nil, 'cp437'
     #   table = DBF::Table.new 'data.dbf', 'memo.dbt', Encoding::US_ASCII
     #
-    # @param data [String, StringIO] data Path to the dbf file or a StringIO object
-    # @param memo [optional String, StringIO] memo Path to the memo file or a StringIO object
+    #   # reading at most the first 64 KB of each memo
+    #   table = DBF::Table.new 'data.dbf', max_memo_size: 65_536
+    #
+    # Opens a table like .new, but when given a block, yields the table,
+    # closes it when the block returns, and returns the block's value —
+    # the same contract as File.open.
+    #
+    #   DBF::Table.open('data.dbf') do |table|
+    #     table.each { |record| ... }
+    #   end
+    #
+    # Takes the same arguments as .new. Without a block, equivalent to .new.
+    def self.open(data, memo = nil, encoding = nil, name: nil, max_memo_size: nil)
+      table = new(data, memo, encoding, name:, max_memo_size:)
+      return table unless block_given?
+
+      begin
+        yield table
+      ensure
+        table.close
+      end
+    end
+
+    # @param data [String, StringIO, IO] data Path to the dbf file or an IO-like object
+    # @param memo [optional String, StringIO, IO] memo Path to the memo file or an IO-like object
     # @param encoding [optional String, Encoding] encoding Name of the encoding or an Encoding object
-    def initialize(data, memo = nil, encoding = nil, name: nil)
+    # @param max_memo_size [optional Integer] Bytes to read from each memo;
+    #   longer memos are cut off. Every memo is read in full by default.
+    def initialize(data, memo = nil, encoding = nil, name: nil, max_memo_size: nil)
+      Encoder.check(encoding) if encoding
+      validate_max_memo_size(max_memo_size)
       @data = FileHandler.open_data(data)
       @user_encoding = encoding
       @encoding = determine_encoding
-      @memo = FileHandler.open_memo(data, memo, version_config.memo_class, version)
+      @memo = open_memo(data, memo, max_memo_size)
       @name = name
       yield self if block_given?
     end
@@ -110,7 +134,7 @@ module DBF
 
     # @return [String]
     def filename
-      File.basename(@data.path) if @data.is_a?(File)
+      File.basename(@data.path) if @data.respond_to?(:path)
     end
 
     # @return [TrueClass, FalseClass]
@@ -131,6 +155,9 @@ module DBF
     # @return [DBF::Record, NilClass]
     def record(index)
       raise DBF::NoColumnsDefined, 'The DBF file has no columns defined' if columns.empty?
+      # A negative index would read header bytes as a record (or raise
+      # Errno::EINVAL); treat it, like any index past the end, as absent.
+      return nil unless index >= 0 && index < record_count
 
       seek_to_record(index)
       return nil if deleted_record?
@@ -150,14 +177,11 @@ module DBF
     #
     # @param [optional String, IO] path_or_io String path, IO-like object, or nil for STDOUT
     def to_csv(path_or_io = nil)
-      io = case path_or_io
-      when nil then $stdout
-      when String then File.open(path_or_io, 'w')
-      else path_or_io
+      if path_or_io.is_a?(String)
+        File.open(path_or_io, 'w') { |file| write_csv(file) }
+      else
+        write_csv(path_or_io || $stdout)
       end
-      csv = CSV.new(io, force_quotes: true)
-      csv << column_names.map { |name| csv_safe_value(name) }
-      each { |record| csv << record.to_a.map { |value| csv_safe_value(value) } }
     end
 
     # Human readable version description
@@ -184,6 +208,12 @@ module DBF
 
     private
 
+    def write_csv(io) # :nodoc:
+      csv = CSV.new(io, force_quotes: true)
+      csv << column_names.map { |name| csv_safe_value(name) }
+      each { |record| csv << record.to_a.map { |value| csv_safe_value(value) } }
+    end
+
     # Neutralizes spreadsheet formula injection (CWE-1236) on CSV export by
     # prefixing a single quote to string cells that begin with a formula
     # trigger character. Non-string values (numbers, dates, booleans) are
@@ -217,8 +247,23 @@ module DBF
       @user_encoding || header.encoding || Encoding.default_external
     end
 
+    # Close a data file opened from a path if its memo cannot be opened, so
+    # the failed Table does not leak a file handle.
+    def open_memo(data, memo, max_size) # :nodoc:
+      FileHandler.open_memo(data, memo, version_config.memo_class, version, max_size:)
+    rescue DBF::Error
+      @data.close if data.is_a?(String)
+      raise
+    end
+
+    def validate_max_memo_size(max_memo_size) # :nodoc:
+      return if max_memo_size.nil? || (max_memo_size.is_a?(Integer) && max_memo_size.positive?)
+
+      raise ArgumentError, 'max_memo_size must be a positive Integer or nil'
+    end
+
     def build_columns # :nodoc:
-      ColumnBuilder.new(self, @data, version_config).build
+      ColumnBuilder.new(self, @data, version_config, header_length:, record_length:).build
     end
 
     def deleted_record? # :nodoc:

data/lib/dbf/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module DBF
-  VERSION = '5.4.0'
+  VERSION = '5.6.0'
 end

data/lib/dbf.rb

@@ -7,6 +7,7 @@ require 'json'
 require 'time'
 
 require 'dbf/version'
+require 'dbf/errors'
 require 'dbf/schema'
 require 'dbf/find'
 require 'dbf/record'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: dbf
 version: !ruby/object:Gem::Version
-  version: 5.4.0
+  version: 5.6.0
 platform: ruby
 authors:
 - Keith Morrison
@@ -13,16 +13,16 @@ dependencies:
   name: csv
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '3.3'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '3.3'
 description: A small fast library for reading dBase, xBase, Clipper and FoxPro database
   files.
 email: keithm@infused.org
@@ -44,6 +44,7 @@ files:
 - lib/dbf/database/foxpro.rb
 - lib/dbf/encoder.rb
 - lib/dbf/encodings.rb
+- lib/dbf/errors.rb
 - lib/dbf/file_handler.rb
 - lib/dbf/find.rb
 - lib/dbf/header.rb
@@ -63,8 +64,12 @@ licenses:
 - MIT
 metadata:
   rubygems_mfa_required: 'true'
+  homepage_uri: https://github.com/infused/dbf
   source_code_uri: https://github.com/infused/dbf
   changelog_uri: https://github.com/infused/dbf/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/infused/dbf/issues
+  documentation_uri: https://dbf.infused.org
+  funding_uri: https://github.com/sponsors/infused
 rdoc_options: []
 require_paths:
 - lib
@@ -79,7 +84,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.17
+rubygems_version: 4.0.20
 specification_version: 4
 summary: Read xBase files
 test_files: []