dbf 5.4.0 → 5.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f296a6fc75892231410af21b2ee94490666f740f425f671078b5c28ded1e2977
-  data.tar.gz: eed4dfd84582cdf9c8e125ca2ddb1e882ebe75147321469db26166f7777a1ea1
+  metadata.gz: ff36c9c3d6b7a558cd5bf0f703f64f0cb7b22cbf6b4c52b843c855328a712a0a
+  data.tar.gz: ac0f725043e7dc9102a32381f6041e54ebd852a67a264778ae58b2a59430b01e
 SHA512:
-  metadata.gz: 578f0f6cc7c88a205c38fd2ef93af2d8e5c924483018af4b96fb349dd12f40386c13547dfc67cd6fbdd47e191a0d04ef46bf0e1c38f9baec6057197661cd6945
-  data.tar.gz: 6960aba5a5b253cc6041c0822a504714ab5a511fee4ea1ff84f43cde10c8cf7db4d74d46f84e670d49f3a4d7110525a3196ea2f76cbcc37174a657e56a755fae
+  metadata.gz: 269035188f9741d80575efca78ae0bda153c4f27c79dbe3f3e6221fc714be22eb2fb9ec39899dcfc9d489f76d60bfaf1f892d6eeaaeea80fa406f5f401e909d7
+  data.tar.gz: 6203ede51060bad9d193b15bb98d814aa870d99dd29d6eb8ddd4cb2b5e04f078f522fb7f3051befcbebe11be86a13307da38f9981bbcb704c5307ebdb16dd6a3

data/CHANGELOG.md

@@ -1,5 +1,51 @@
 # Changelog
 
+## 5.5.0
+
+### Added
+
+- `DBF::Table.new` accepts any IO-like object responding to `#read` and `#seek` (`File`, `Tempfile`, …) in addition to a path or `StringIO`, matching what the README already documented; IO inputs are switched to binary mode, and memo auto-discovery works from the IO's path when it has one
+- `DBF::Error` base class: all library errors (`FileNotFoundError`, `NoColumnsDefined`, `Column::LengthError`, `Column::InvalidNameError`) now inherit from it, so callers can `rescue DBF::Error` to catch anything the library raises
+- `Table#filename` now works for any IO input with a path, not only `File`
+- `DBF::Table.open`: same arguments as `.new`, but the block form yields the table, closes it when the block returns, and returns the block's value — the same contract as `File.open`
+- CI: lint job running RuboCop and Reek on every push and pull request
+- CI: test on Windows and macOS (Ruby 3.4) in addition to Linux, since much real-world DBF data originates on Windows/FoxPro systems
+- CI: observe-only (non-blocking) test jobs for JRuby, TruffleRuby, and Ruby head
+- CI: enforce a 99% minimum test coverage floor via SimpleCov
+- Docs site (dbf.infused.org): YARD docs are now built and deployed by CI instead of being committed to the repository; the Pages workflow's deprecated v2/v3 actions (whose artifact backend was shut down in early 2025) are updated to current versions, repairing the broken deploy
+- Dependabot updates for GitHub Actions and gems (weekly), a security policy (SECURITY.md) with private vulnerability reporting, and contributor documentation (CONTRIBUTING.md)
+- Automated releases: pushing a `vX.Y.Z` tag now builds and publishes the gem to RubyGems.org from CI via Trusted Publishing (OIDC) — no long-lived API key. `bundler/gem_tasks` is loaded in the Rakefile, providing `rake build` / `rake release`. Git tags resume at v5.4.0; versions 4.0.0–5.3.0 were released without tags
+
+- Ractor safety: all library constants are verified Ractor-shareable and reading/exporting tables inside non-main Ractors is covered by specs
+- CLI: `-j` exports records as a JSON array and `-J` as JSON Lines (one record per line, streamed in constant memory); deleted records are skipped, control bytes are escaped by JSON itself, and binary cells are scrubbed instead of raising
+
+### Fixed
+
+- `Table#to_csv(path)` closes the file it opens, so the CSV is fully flushed to disk when the method returns (previously the data could stay buffered until garbage collection)
+- Visual FoxPro: a `.dbc` container supplying fewer long names than the table has columns no longer crashes column building; missing long names fall back to the table's own column names. Column rebuilding is also no longer O(n²)
+- `Table#schema` validates the format against the documented list up front; a `NoMethodError` raised inside a valid schema generator is no longer misreported as "not a valid schema"
+- FoxPro memo files shorter than their 512-byte header no longer crash memo reads (they return nil like other truncations)
+- RuboCop config: restore the default `vendor/**/*` exclusion (overriding `Exclude` replaces the defaults), fixing a CI lint crash where RuboCop descended into cached vendored gems and tried to load plugins from their configs
+- CLI: close the table when finished, so the DBF file can be deleted or replaced immediately afterwards on Windows (an open handle blocks deletion there)
+
+### Removed
+
+- CodeClimate config and README badges: the service is sunset, and coverage is now enforced directly in CI
+
+### Changed
+
+- Streaming reads: `Table#each` now reads records in 4 MB chunks of whole records instead of loading the entire record section into memory, so enumerating multi-gigabyte files (for example shapefile `.dbf` sidecars) uses bounded memory. On a 190 MB file, peak process memory drops from ~222 MB to ~35 MB with identical results. No API change; all malformed-file bounds are preserved
+- Internal: `DBF::RecordContext` is now an immutable `Data` class instead of a `Struct`
+- Internal: remove a redundant `Memo::Foxpro#initialize` and the duplicate `Header::HEADER_SIZE` constant (now sourced from `VersionConfig`)
+- README: replace the stack of version-support notes with a compatibility table, point API docs at dbf.infused.org, and refer to LICENSE instead of inlining the full MIT text; copyright years updated through 2026
+- Gemspec: add `homepage_uri`, `bug_tracker_uri`, `documentation_uri`, and `funding_uri` metadata (shown on the rubygems.org sidebar), and constrain the `csv` runtime dependency to `~> 3.3`
+- `DBF::Column::NameError` is renamed to `DBF::Column::InvalidNameError` (it shadowed Ruby's `::NameError` without being one); the old constant remains as a deprecated alias
+- Rescues in date/datetime decoding and FoxPro memo reads are narrowed to the specific expected errors, so genuine programmer errors surface instead of silently returning nil
+- Declare `reek` and `simplecov` as direct development dependencies instead of relying on rubycritic's transitive dependencies
+- Restrict `debug` and `ruby-lsp` to MRI so `bundle install` succeeds on JRuby/TruffleRuby
+- Test matrix no longer fails fast, and a Ruby head regression no longer fails the build
+- Update pinned `ruby/setup-ruby` action to v1.321.0
+
 ## 5.4.0
 
 - CLI: replace terminal control bytes in file-derived output so a crafted DBF cannot emit escape sequences to an interactive terminal; CSV and schema output are only filtered when writing to a terminal, so redirected exports are unchanged

data/LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2006-2024 Keith Morrison <keithm@infused.org>
+Copyright (c) 2006-2026 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

data/README.md

@@ -2,36 +2,37 @@
 
 [![Version](https://img.shields.io/gem/v/dbf.svg?style=flat)](https://rubygems.org/gems/dbf)
 [![Build Status](https://github.com/infused/dbf/actions/workflows/build.yml/badge.svg)](https://github.com/infused/dbf/actions/workflows/build.yml)
-[![Code Quality](https://img.shields.io/codeclimate/maintainability/infused/dbf.svg?style=flat)](https://codeclimate.com/github/infused/dbf)
-[![Code Coverage](https://img.shields.io/codeclimate/c/infused/dbf.svg?style=flat)](https://codeclimate.com/github/infused/dbf)
 [![Total Downloads](https://img.shields.io/gem/dt/dbf.svg)](https://rubygems.org/gems/dbf/)
 [![License](https://img.shields.io/github/license/infused/dbf.svg)](https://github.com/infused/dbf)
 
 DBF is a small, fast Ruby library for reading dBase, xBase, Clipper, and FoxPro database files.
 
 * Project page: <https://github.com/infused/dbf>
-* API Documentation: <https://rdoc.info/gems/dbf>
+* API Documentation: <https://dbf.infused.org>
 * Report bugs: <https://github.com/infused/dbf/issues>
 * Questions: Email <mailto:keithm@infused.org> and put DBF somewhere in the
   subject line
 * Change log: <https://github.com/infused/dbf/blob/main/CHANGELOG.md>
 
-NOTE: Beginning with version 5.2 we have dropped support for Ruby 3.2 and earlier.
-
-NOTE: Beginning with version 4.3 we have dropped support for Ruby 3.0 and earlier.
-
-NOTE: Beginning with version 4 we have dropped support for Ruby 2.0, 2.1, 2.2, and 2.3. If you need support for these older Rubies,
-please use 3.0.x (<https://github.com/infused/dbf/tree/3_stable>)
-
-NOTE: Beginning with version 3 we have dropped support for Ruby 1.8 and 1.9. If you need support for older Rubies,
-please use 2.0.x (<https://github.com/infused/dbf/tree/2_stable>)
-
 ## Compatibility
 
 DBF is tested to work with the following versions of Ruby:
 
 * Ruby 3.3.x, 3.4.x, 4.0.x
 
+Older Rubies are supported by older DBF release lines:
+
+| DBF version | Ruby support |
+| ----------- | ------------ |
+| 5.2+        | 3.3+         |
+| 4.3 – 5.1   | 3.1+         |
+| 4.0 – 4.2   | 2.4+         |
+| 3.x ([3_stable](https://github.com/infused/dbf/tree/3_stable)) | 2.0 – 2.3 |
+| 2.x ([2_stable](https://github.com/infused/dbf/tree/2_stable)) | 1.8 – 1.9 |
+
+DBF is Ractor-friendly: all library constants are deeply frozen, so tables
+can be opened, enumerated, and exported inside non-main Ractors.
+
 ## Installation
 
 Install the gem manually:
@@ -58,16 +59,35 @@ widgets = DBF::Table.new("widgets.dbf")
 Open a DBF file using an IO object:
 
 ```ruby
-data = File.open('widgets.dbf')
+data = File.open('widgets.dbf', 'rb')
 widgets = DBF::Table.new(data)
 ```
 
+All errors raised by the library inherit from DBF::Error, so you can rescue
+the library as a unit:
+
+```ruby
+begin
+  widgets = DBF::Table.new("widgets.dbf")
+rescue DBF::Error => e
+  puts "Unable to read DBF file: #{e.message}"
+end
+```
+
 Open a DBF by passing in raw data (wrap the raw data with StringIO):
 
 ```ruby
 widgets = DBF::Table.new(StringIO.new('raw binary data'))
 ```
 
+Use the block form to close the table automatically, like File.open:
+
+```ruby
+DBF::Table.open('widgets.dbf') do |table|
+  table.each { |record| puts record.name }
+end
+```
+
 Enumerate all records
 
 ```ruby
@@ -287,13 +307,15 @@ table.name = 'my_table_name'
 A small command-line utility called dbf is installed with the gem.
 
     $ dbf -h
-    usage: dbf [-h|-s|-a] filename
+    usage: dbf [-h|-s|-a|-c|-r|-j|-J] filename
       -h = print this message
-      -v = print the version number
+      -v = print the DBF gem version
       -s = print summary information
       -a = create an ActiveRecord::Schema
-      -r = create a Sequel Migration
+      -r = create a Sequel migration
       -c = export as CSV
+      -j = export as a JSON array
+      -J = export as JSON Lines (one record per line)
 
 Create an executable ActiveRecord schema:
 
@@ -307,6 +329,15 @@ Dump all records to a CSV file:
 
     dbf -c books.dbf > books.csv
 
+Dump all records as JSON or JSON Lines:
+
+    dbf -j books.dbf > books.json
+    dbf -J books.dbf > books.jsonl
+
+JSON Lines output is streamed record by record, so it works well for very
+large files and pipelines (for example `dbf -J books.dbf | jq` or importing
+into DuckDB).
+
 ## Reading a Visual Foxpro database (v8, v9)
 
 A special Database::Foxpro class is available to read Visual Foxpro container
@@ -374,25 +405,6 @@ Data type descriptions
 
 ## License
 
-Copyright (c) 2006-2024 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.
+Copyright (c) 2006-2026 Keith Morrison <<keithm@infused.org>>
+
+Released under the MIT License. See [LICENSE](LICENSE) for the full text.

data/dbf.gemspec

@@ -15,7 +15,11 @@ Gem::Specification.new do |s|
   s.require_paths = ['lib']
   s.required_ruby_version = '>= 3.3.0'
   s.metadata['rubygems_mfa_required'] = 'true'
+  s.metadata['homepage_uri'] = 'https://github.com/infused/dbf'
   s.metadata['source_code_uri'] = 'https://github.com/infused/dbf'
   s.metadata['changelog_uri'] = 'https://github.com/infused/dbf/blob/main/CHANGELOG.md'
-  s.add_dependency 'csv'
+  s.metadata['bug_tracker_uri'] = 'https://github.com/infused/dbf/issues'
+  s.metadata['documentation_uri'] = 'https://dbf.infused.org'
+  s.metadata['funding_uri'] = 'https://github.com/sponsors/infused'
+  s.add_dependency 'csv', '~> 3.3'
 end

data/lib/dbf/cli.rb

@@ -5,13 +5,15 @@ require 'optparse'
 module DBF
   class CLI
     USAGE = <<~HELP
-      usage: dbf [-h|-s|-a|-c|-r] filename
+      usage: dbf [-h|-s|-a|-c|-r|-j|-J] filename
         -h = print this message
         -v = print the DBF gem version
         -s = print summary information
         -a = create an ActiveRecord::Schema
         -r = create a Sequel migration
         -c = export as CSV
+        -j = export as a JSON array
+        -J = export as JSON Lines (one record per line)
     HELP
 
     # Bytes a terminal interprets as control or escape sequences. A crafted
@@ -68,8 +70,17 @@ module DBF
       @stderr = stderr
     end
 
+    ACTIONS = {
+      'a' => :print_ar_schema,
+      'r' => :print_sequel_schema,
+      's' => :print_summary,
+      'c' => :print_csv,
+      'j' => :print_json,
+      'J' => :print_jsonl
+    }.freeze
+
     def run
-      params = OptionParser.new.getopts(@argv, 'h', 's', 'a', 'c', 'r', 'v')
+      params = OptionParser.new.getopts(@argv, 'hsacrvjJ')
 
       if params['v']
         print_version
@@ -79,13 +90,8 @@ module DBF
         filename = @argv.shift
         return missing_filename unless filename
 
-        action = %w[a r s c].find { |flag| params[flag] }
-        case action
-        when 'a' then print_ar_schema(filename)
-        when 'r' then print_sequel_schema(filename)
-        when 's' then print_summary(filename)
-        when 'c' then print_csv(filename)
-        end
+        action = ACTIONS.find { |flag, _method| params[flag] }&.last
+        send(action, filename) if action
       end
       0
     rescue DBF::FileNotFoundError => e
@@ -108,16 +114,23 @@ module DBF
       1
     end
 
+    # Always close the table when done: an open handle prevents deleting or
+    # replacing the file on Windows.
+    def with_table(filename, &) = DBF::Table.open(filename, &)
+
     def print_ar_schema(filename)
-      @stdout.puts terminal_safe(DBF::Table.new(filename).schema(:activerecord))
+      with_table(filename) { |table| @stdout.puts terminal_safe(table.schema(:activerecord)) }
     end
 
     def print_sequel_schema(filename)
-      @stdout.puts terminal_safe(DBF::Table.new(filename).schema(:sequel))
+      with_table(filename) { |table| @stdout.puts terminal_safe(table.schema(:sequel)) }
     end
 
     def print_summary(filename)
-      table = DBF::Table.new(filename)
+      with_table(filename) { |table| write_summary(filename, table) }
+    end
+
+    def write_summary(filename, table)
       @stdout.puts
       @stdout.puts "Database: #{filename}"
       @stdout.puts "Type: (#{table.version}) #{table.version_description}"
@@ -136,7 +149,54 @@ module DBF
     end
 
     def print_csv(filename)
-      DBF::Table.new(filename).to_csv(interactive? ? TerminalFilter.new(@stdout) : @stdout)
+      with_table(filename) { |table| table.to_csv(interactive? ? TerminalFilter.new(@stdout) : @stdout) }
+    end
+
+    # Streams a JSON array without materializing all records in memory.
+    # JSON string escaping makes the output terminal-safe by construction:
+    # control bytes are emitted as \uXXXX escapes.
+    def print_json(filename)
+      with_table(filename) { |table| write_json(table) }
+    end
+
+    def write_json(table)
+      first = true
+      @stdout.write('[')
+      each_present_record(table) do |record|
+        @stdout.write(first ? "\n" : ",\n")
+        @stdout.write(json_record(record))
+        first = false
+      end
+      @stdout.write("\n]\n")
+    end
+
+    # One JSON object per line (JSON Lines). Combined with chunked record
+    # reading this exports arbitrarily large files in constant memory.
+    def print_jsonl(filename)
+      with_table(filename) { |table| write_jsonl(table) }
+    end
+
+    def write_jsonl(table)
+      each_present_record(table) { |record| @stdout.write("#{json_record(record)}\n") }
+    end
+
+    # Deleted records have no attributes, so JSON export skips them.
+    def each_present_record(table, &)
+      table.each { |record| yield record if record }
+    end
+
+    def json_record(record)
+      JSON.generate(record.attributes.to_h { |key, value| [json_safe(key), json_safe(value)] })
+    end
+
+    # JSON.generate raises on binary or invalidly encoded strings; represent
+    # their bytes instead of raising, mirroring the CSV export behavior.
+    def json_safe(value)
+      return value unless value.is_a?(::String)
+
+      value.encode(Encoding::UTF_8, invalid: :replace, undef: :replace, replace: '?')
+    rescue Encoding::ConverterNotFoundError
+      value.dup.force_encoding(Encoding::UTF_8).scrub('?')
     end
 
     # Exported data is only filtered when it is going to a terminal, so

data/lib/dbf/column.rb

@@ -2,12 +2,17 @@
 
 module DBF
   class Column
-    class LengthError < StandardError
+    class LengthError < DBF::Error
     end
 
-    class NameError < StandardError
+    class InvalidNameError < DBF::Error
     end
 
+    # Deprecated alias, kept for backward compatibility. It shadowed
+    # ::NameError (without being one), so it was renamed.
+    NameError = InvalidNameError
+    deprecate_constant :NameError
+
     attr_reader :name, :type, :length, :decimal
 
     # rubocop:disable Style/MutableConstant
@@ -105,7 +110,7 @@ module DBF
     end
 
     def validate_name # :nodoc:
-      raise NameError, 'column name cannot be empty' if @name.empty?
+      raise InvalidNameError, 'column name cannot be empty' if @name.empty?
     end
   end
 end

data/lib/dbf/column_type.rb

@@ -112,7 +112,7 @@ module DBF
       # @param value [String]
       def type_cast(value)
         value.match?(/\d{8}/) && ::Date.strptime(value, '%Y%m%d')
-      rescue StandardError
+      rescue ArgumentError, RangeError, TypeError
         nil
       end
     end
@@ -125,7 +125,7 @@ module DBF
 
         secs = (msecs / 1000).to_i
         ::DateTime.jd(days, (secs / 3600).to_i, (secs / 60).to_i % 60, secs % 60).to_time
-      rescue StandardError
+      rescue ArgumentError, RangeError, TypeError
         nil
       end
     end

data/lib/dbf/database/foxpro.rb

@@ -114,12 +114,10 @@ module DBF
       end
 
       def build_columns # :nodoc:
-        columns = super
-
         # modify the column definitions to use the long names as the
         # columnname property is readonly, recreate the column definitions
-        columns.map do |column|
-          long_name = long_names[columns.index(column)]
+        super.each_with_index.map do |column, index|
+          long_name = long_names[index] || column.name
           Column.new(self, long_name, column.type, column.length, column.decimal)
         end
       end

data/lib/dbf/errors.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module DBF
+  # Base class for all errors raised by the DBF library, so callers can
+  # rescue DBF::Error to catch anything the library raises.
+  class Error < StandardError
+  end
+
+  class FileNotFoundError < Error
+  end
+
+  class NoColumnsDefined < Error
+  end
+end

data/lib/dbf/file_handler.rb

@@ -11,7 +11,12 @@ module DBF
       when String
         File.open(data, 'rb')
       else
-        raise ArgumentError, 'data must be a file path or StringIO object'
+        raise ArgumentError, 'data must be a file path or an IO-like object responding to #read and #seek' unless data.respond_to?(:read) && data.respond_to?(:seek)
+
+        # DBF is a binary format; a File opened in text mode would corrupt
+        # reads on Windows.
+        data.binmode if data.respond_to?(:binmode)
+        data
       end
     rescue Errno::ENOENT
       raise DBF::FileNotFoundError, "file not found: #{data}"
@@ -19,17 +24,23 @@ module DBF
 
     def open_memo(data, memo, memo_class, version)
       if memo
-        meth = memo.is_a?(StringIO) ? :new : :open
+        meth = memo.is_a?(String) ? :open : :new
         memo_class.send(meth, memo, version)
-      elsif !data.is_a?(StringIO)
-        path = Dir.glob(memo_search_path(data)).first
-        path && memo_class.open(path, version)
+      elsif (path = data_path(data))
+        found = Dir.glob(memo_search_path(path)).first
+        found && memo_class.open(found, version)
       end
     end
 
-    def memo_search_path(io)
-      dirname = File.dirname(io)
-      basename = File.basename(io, '.*')
+    def data_path(data)
+      return data if data.is_a?(String)
+
+      data.path if data.respond_to?(:path)
+    end
+
+    def memo_search_path(path)
+      dirname = File.dirname(path)
+      basename = File.basename(path, '.*')
       "#{dirname}/#{basename}*.{fpt,FPT,dbt,DBT}"
     end
   end

data/lib/dbf/header.rb

@@ -2,14 +2,12 @@
 
 module DBF
   class Header
-    HEADER_SIZE = 32
-
     attr_reader :version, :record_count, :header_length, :record_length, :encoding_key, :encoding
 
     def initialize(data)
       # Pad a nil or truncated header read so unpacking a short file yields
       # empty values instead of raising.
-      data = data.to_s.b.ljust(HEADER_SIZE, "\x00")
+      data = data.to_s.b.ljust(VersionConfig::DBASE3_HEADER_SIZE, "\x00")
       @version = data.unpack1('H2')
       @encoding_key = nil
       @encoding = nil

data/lib/dbf/memo/foxpro.rb

@@ -5,18 +5,17 @@ module DBF
     class Foxpro < Base
       FPT_HEADER_SIZE = 512
 
-      def initialize(data, version)
-        @data = data
-        super
-      end
-
       def build_memo(start_block) # :nodoc:
-        @data.seek offset(start_block)
-        memo_type, memo_size, memo_string = @data.read(block_size).unpack('NNa*')
-        return nil unless memo_type == 1 && memo_size > 0
+        data.seek offset(start_block)
+        block = data.read(block_size)
+        return nil unless block
+
+        # memo_size is nil when the block header is truncated (< 8 bytes)
+        memo_type, memo_size, memo_string = block.unpack('NNa*')
+        return nil unless memo_type == 1 && memo_size.to_i.positive?
 
         read_memo_content(memo_string, memo_size)
-      rescue StandardError
+      rescue IOError, SystemCallError, RangeError
         nil
       end
 
@@ -28,16 +27,18 @@ module DBF
         # Bound the read by the bytes remaining so a crafted 32-bit memo_size
         # cannot force a ~4 GiB allocation from a small memo file.
         length = content_size(memo_size)
-        remaining = @data.size - @data.pos
+        remaining = data.size - data.pos
         length = remaining if length > remaining
-        memo_string << @data.read(length) if length.positive?
+        memo_string << data.read(length) if length.positive?
         memo_string
       end
 
       def block_size # :nodoc:
         @block_size ||= begin
-          @data.rewind
-          @data.read(FPT_HEADER_SIZE).unpack1('x6n') || 0
+          data.rewind
+          header = data.read(FPT_HEADER_SIZE)
+          # A header shorter than 8 bytes cannot contain the block size field
+          header && header.bytesize >= 8 ? header.unpack1('x6n') : 0
         end
       end
     end

data/lib/dbf/record.rb

@@ -20,9 +20,7 @@ module DBF
     # @param [DBF::Record] other
     # @return [Boolean]
     def ==(other)
-      attributes == other.attributes
-    rescue NoMethodError
-      false
+      other.respond_to?(:attributes) && attributes == other.attributes
     end
 
     # Reads attributes by column name

data/lib/dbf/record_context.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
 module DBF
-  RecordContext = Struct.new(:columns, :version, :memo, :column_offsets, keyword_init: true)
+  # Immutable per-table state shared by every record during decoding
+  RecordContext = Data.define(:columns, :version, :memo, :column_offsets)
 end

data/lib/dbf/record_iterator.rb

@@ -2,46 +2,75 @@
 
 module DBF
   class RecordIterator
-    def initialize(data, context, header_length, record_length, record_count)
+    # Records are read in chunks of whole records totalling roughly this many
+    # bytes, so enumerating a multi-gigabyte file (for example a shapefile
+    # sidecar) needs only chunk-sized memory instead of the entire record
+    # section at once.
+    CHUNK_SIZE = 4 * 1024 * 1024
+
+    def initialize(data, context, header_length, record_length, record_count, chunk_size: CHUNK_SIZE)
       @data = data
       @context = context
       @header_length = header_length
       @record_length = record_length
       @record_count = record_count
+      @chunk_size = chunk_size
+    end
+
+    def each(&)
+      return enum_for(:each) unless block_given?
+
+      # A record_length of 0 from a crafted header cannot drive an unbounded
+      # loop: capacity is 0 and enumeration ends immediately.
+      remaining = record_capacity
+      @data.seek(@header_length)
+
+      while remaining.positive?
+        wanted = [per_chunk, remaining].min
+        buffer = @data.read(wanted * @record_length)
+        break unless buffer
+
+        whole_records = buffer.bytesize / @record_length
+        break if whole_records.zero?
+
+        yield_chunk(buffer, whole_records, &)
+        remaining -= whole_records
+
+        # A short read means the file ended earlier than the header promised
+        break if whole_records < wanted
+      end
     end
 
-    def each
-      buf = read_buffer
-      return unless buf
+    private
 
-      # Bound the iteration by the bytes actually read so a crafted
-      # record_count (or record_length == 0) cannot drive an unbounded loop.
-      max_records = @record_length > 0 ? buf.bytesize / @record_length : 0
-      count = @record_count < max_records ? @record_count : max_records
+    # Whole records per read; at least one so a record larger than the chunk
+    # size still makes progress. Only called when record_length is positive.
+    def per_chunk
+      @per_chunk ||= [@chunk_size / @record_length, 1].max
+    end
 
+    def yield_chunk(buffer, count)
       pos = 0
       count.times do
-        if buf.getbyte(pos) == 0x2A
+        if buffer.getbyte(pos) == 0x2A
           yield nil
         else
-          yield Record.new(buf, @context, pos + 1)
+          yield Record.new(buffer, @context, pos + 1)
         end
         pos += @record_length
       end
     end
 
-    private
-
-    def read_buffer
-      @data.seek(@header_length)
+    # Bound enumeration by the bytes actually available so a crafted header
+    # (huge record_length * record_count) cannot force reads past the real
+    # file size, while record_count still caps a file with trailing garbage.
+    def record_capacity
+      return 0 unless @record_length.positive?
 
-      # Bound the allocation by the bytes actually available so a crafted
-      # header (huge record_length * record_count) cannot force a giant read
-      # from a tiny file.
-      requested = @record_length * @record_count
       available = @data.size - @header_length
-      available = 0 if available.negative?
-      @data.read(requested < available ? requested : available)
+      return 0 if available.negative?
+
+      [@record_count, available / @record_length].min
     end
   end
 end

data/lib/dbf/schema.rb

@@ -43,10 +43,9 @@ module DBF
     # @param table_only [Boolean]
     # @return [String]
     def schema(format = :activerecord, table_only: false)
-      schema_method_name = schema_name(format)
-      send(schema_method_name, table_only: table_only)
-    rescue NameError
-      raise ArgumentError, ":#{format} is not a valid schema. Valid schemas are: #{FORMATS.join(', ')}."
+      raise ArgumentError, ":#{format} is not a valid schema. Valid schemas are: #{FORMATS.join(', ')}." unless FORMATS.include?(format.to_s.to_sym)
+
+      send(schema_name(format), table_only: table_only)
     end
 
     def schema_name(format) # :nodoc:

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,8 +41,28 @@ 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
+    # 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)
+      table = new(data, memo, encoding, name: name)
+      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)
       @data = FileHandler.open_data(data)
@@ -110,7 +127,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]
@@ -150,14 +167,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 +198,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

data/lib/dbf/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module DBF
-  VERSION = '5.4.0'
+  VERSION = '5.5.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.5.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: 3.6.9
 specification_version: 4
 summary: Read xBase files
 test_files: []