hypertabular 0.7.0

data/lib/hypertabular/workbook.rb

@@ -0,0 +1,173 @@
+module HyperTabular
+  # One sheet of a workbook, as Workbook#sheets lists it: its name, and whether the workbook
+  # hides it. A hidden sheet reads like any other.
+  SheetInfo = Data.define(:name, :hidden)
+
+  # How a sheet is read: whether its first row is a header (exposed through Sheet#header
+  # and never delivered as a row), whether a row with no cells is skipped, and the most rows
+  # a batch holds.
+  SheetOptions = Data.define(:has_header, :skip_empty_rows, :batch_rows) do
+    # Every option has a default; ArgumentError unless +batch_rows+ is a positive Integer.
+    def initialize(has_header: true, skip_empty_rows: true, batch_rows: DelimitedReader::DEFAULT_BATCH_ROWS)
+      raise ArgumentError, "batch_rows must be a positive Integer; got #{batch_rows.inspect}" unless
+        batch_rows.is_a?(Integer) && batch_rows.positive?
+
+      super
+    end
+  end
+
+  # A header, empty rows skipped, DelimitedReader::DEFAULT_BATCH_ROWS rows a batch.
+  SheetOptions::DEFAULT = SheetOptions.new
+
+  # An XLSX or ODS workbook held in memory, its sheets listed and its shared strings and
+  # styles loaded: what a Sheet reads from.
+  #
+  #   book = HyperTabular::Workbook.open("orders.xlsx")
+  #   book.sheets                  # => [#<data HyperTabular::SheetInfo name="Orders", hidden=false>]
+  #   sheet = book.sheet("Orders", HyperTabular::SheetOptions::DEFAULT, plan)
+  #   while (batch = sheet.read) ... end
+  #
+  # A workbook that cannot be read — not a zip, encrypted, a part missing or broken — is a
+  # TabularError from Workbook.new. Its sheets may be read at once, each with buffers of its
+  # own. Not thread-safe.
+  class Workbook
+    # Reads the file at +path+ into memory and opens it.
+    def self.open(path)
+      new(File.binread(path))
+    end
+
+    # Opens the workbook in +bytes+, a String, which is read in place: a frozen String is
+    # the workbook's as it is, anything else is copied once.
+    def initialize(bytes)
+      raise ArgumentError, "bytes must be a String; got #{bytes.class}" unless bytes.is_a?(String)
+
+      bytes = bytes.b.freeze unless bytes.frozen?
+      @book = Runtime::Book::Opened.new(bytes)
+      @sheets = @book.sheets.map { |name, hidden, _part, _index| SheetInfo.new(name: name, hidden: hidden) }.freeze
+    rescue Runtime::Book::StructureError => e
+      raise TabularError.from(e.failure)
+    end
+
+    # The workbook's sheets, in its own order, as SheetInfo. Sheets that hold no cells
+    # (chart sheets, macro sheets) are not among them.
+    attr_reader :sheets
+
+    # Which kind of workbook this is: :xlsx or :ods.
+    def format
+      @book.format
+    end
+
+    # The date system the workbook's serials count in — what a date-formatted number is
+    # read by: :y1900 or :y1904, as HyperCast names them.
+    def date_system
+      HyperCast::EXCEL_EPOCHS.key(@book.epoch)
+    end
+
+    # Starts a read of one sheet — +which+ is its index in #sheets or its name — through
+    # +plan+, as +options+ (SheetOptions) says. With a header declared the header row is
+    # read here. IndexError for an index the workbook has no sheet at, KeyError for a name
+    # it has no sheet by.
+    def sheet(which, options, plan)
+      index =
+        case which
+        when Integer
+          raise IndexError, "the workbook has #{@sheets.size} sheets, and no sheet #{which}" unless
+            which >= 0 && which < @sheets.size
+
+          which
+        when String
+          found = @sheets.index { |sheet| sheet.name == which }
+          raise KeyError, "the workbook has no sheet named #{which.inspect}" if found.nil?
+
+          found
+        else raise ArgumentError, "which must be an Integer or a String; got #{which.inspect}"
+        end
+      Sheet.new(@book, @book.sheets[index], options, plan)
+    end
+
+    # The workbook in a line.
+    def inspect
+      "#<#{self.class.name} #{format} sheets=#{@sheets.size}>"
+    end
+  end
+
+  # A forward-only read of one sheet of a Workbook, a batch at a time, through a plan — into
+  # the same Batch delimited text is read into.
+  #
+  # A typed cell is converted directly by its door — a stored 42.0 never passes through text
+  # to become an Integer — and a text cell goes through the door as delimited text would. A
+  # sheet that is structurally broken raises a TabularError after every intact row before
+  # the break has been delivered, and the same error again on every later read.
+  class Sheet
+    # The SheetOptions the sheet is read with.
+    attr_reader :options
+
+    # The plan: the output Columns, in output order.
+    attr_reader :plan
+
+    # The header row's names — a typed cell said the way the text door says it — as frozen
+    # UTF-8 Strings, or nil when the options declare no header.
+    attr_reader :header
+
+    # Made by Workbook#sheet.
+    def initialize(book, sheet, options, plan)
+      raise ArgumentError, "options must be a HyperTabular::SheetOptions; got #{options.inspect}" unless
+        options.is_a?(SheetOptions)
+
+      @plan = Array(plan).dup.freeze
+      @plan.each_with_index do |column, index|
+        raise ArgumentError, "plan column #{index} must be a HyperTabular::Column; got #{column.inspect}" unless
+          column.is_a?(Column)
+      end
+      @book = book
+      @options = options
+      width = (@plan.map(&:ordinal).max || -1) + 1
+      @reading = Runtime::Book::Reading.new(book, sheet, options.has_header, options.skip_empty_rows,
+                                            @plan.map(&:packed), @plan.map(&:value_bytes), options.batch_rows, width)
+      @header = @reading.header
+      @pending = nil
+      @failure = nil
+    rescue Runtime::Book::StructureError => e
+      raise TabularError.from(e.failure)
+    end
+
+    # Reads the next batch: a Batch of up to the options' batch_rows rows, or nil once the
+    # sheet has no more.
+    def read
+      if @pending
+        @failure = @pending
+        @pending = nil
+      end
+      raise @failure if @failure
+
+      rows, cells, arena, failure = @reading.fill
+      if failure
+        broken = TabularError.from(failure)
+        raise @failure = broken if rows.zero?
+
+        @pending = broken
+      end
+      return nil if rows.zero?
+
+      columns = @reading.columns
+      values = Array.new(@plan.size) { |column| columns.values(column, rows) }
+      Batch.new(@plan, rows, values, Array.new(@plan.size) { |column| columns.verdicts(column, rows) },
+                cells, @reading.per_row, @book.strings, 0, arena, workbook: true)
+    end
+
+    # Every remaining batch. Without a block, an Enumerator.
+    def each_batch
+      return to_enum(:each_batch) unless block_given?
+
+      while (batch = read)
+        yield batch
+      end
+      self
+    end
+
+    # The sheet in a line.
+    def inspect
+      "#<#{self.class.name} columns=#{@plan.size}>"
+    end
+  end
+end

data/lib/hypertabular.rb

@@ -0,0 +1,103 @@
+require "date"
+require "hypercast"
+require_relative "hypertabular/runtime"
+require_relative "hypertabular/runtime/columns"
+require_relative "hypertabular/runtime/delimited"
+require_relative "hypertabular/runtime/workbook"
+
+# Tabular parsing with a HyperCast verdict for every cell: delimited text — CSV, TSV, any
+# single-byte ASCII separator — and workbooks — XLSX and ODS — read a batch at a time into
+# typed columns by one Rust core (libhypertabular), called through Fiddle.
+#
+#   plan = [HyperTabular::Column.i32(0), HyperTabular::Column.text(1)]
+#   reader = HyperTabular::DelimitedReader.new("id,name\n1,alice\nx,bob\n", HyperTabular::Dialect::CSV, plan)
+#   reader.header                 # => ["id", "name"]
+#   batch = reader.read           # => #<HyperTabular::Batch rows=2 columns=2>
+#   batch.values(1)               # => ["alice", "bob"]
+#   batch.get(0, 1)               # => #<data HyperCast::Fault reason=:malformed, offset=0, length=1>
+#   batch.raw(0, 1)               # => "x"
+#   batch.line(1)                 # => 3
+#
+#   book = HyperTabular::Workbook.open("orders.xlsx")
+#   sheet = book.sheet("Orders", HyperTabular::SheetOptions::DEFAULT, plan)
+#   sheet.read                    # => the same Batch
+#
+# Nothing is sniffed: the Dialect states the separator, the quoting and the header,
+# SheetOptions a sheet's header and whether empty rows are skipped, and the plan states each
+# Column's door and, for numbers, its notation. HyperCast is the judge:
+# the verdicts (HyperCast::Success, HyperCast::Fault), the notation (HyperCast::NumFormat),
+# the exact decimal (HyperCast::Decimal) and the declared options are that gem's own types,
+# and a cell means exactly what HyperCast's door would say of the same text. A bad value is
+# a verdict; a broken file is a TabularError.
+module HyperTabular
+  # This gem's own version — kept in lockstep with hypertabular.gemspec and the core's
+  # rust/Cargo.toml.
+  VERSION = "0.7.0"
+
+  class << self
+    # Whether the native core loaded and exports the ABI this binding was built against.
+    # Probed once (a native_version round trip: the cheapest call the core has), cached,
+    # and never raises: a missing shared library and an unsupported platform both answer
+    # false. A reader keeps its own behavior — building one without the core raises the
+    # precise LoadError — this only answers the question quietly.
+    def available?
+      return @available unless @available.nil?
+
+      @available = begin
+        native_version.is_a?(String)
+      rescue LoadError, StandardError
+        false
+      end
+    end
+
+    # The version of the native core actually loaded, as "major.minor.patch" — read from
+    # the library itself, not from this gem, so a consumer can prove the core behind the
+    # reader is the one this binding was built against.
+    def native_version
+      HyperCast::Interop.version(Runtime::Delimited.version)
+    end
+  end
+end
+
+require_relative "hypertabular/dialect"
+require_relative "hypertabular/column"
+require_relative "hypertabular/tabular_error"
+require_relative "hypertabular/batch"
+require_relative "hypertabular/delimited_reader"
+require_relative "hypertabular/workbook"
+
+# --- backend selection, as hypercast makes its own: the Magnus extension, when present,
+# replaces the Fiddle crossing in place. Every native call and every byte of native memory is
+# behind HyperTabular::Runtime (Runtime::Delimited, Runtime::Book::Opened and ::Reading, and
+# Runtime.unescape), so that is all the extension redefines (rust/src/ruby_ext.rs): the
+# constructors hand back objects of its own that answer the same methods with the same bytes,
+# and everything above them — the readers, the workbook, Batch and every value and verdict it
+# builds — is the same Ruby on either backend. It is how the precompiled platform gems ship,
+# carrying no Fiddle library at all, and how the hypertabular-wasm gem runs in ruby.wasm,
+# where there is no Fiddle to call. The Fiddle definitions stay the universal zero-compile
+# fallback, for a Ruby or a platform no platform gem covers.
+#
+# HYPERTABULAR_PURE forces Fiddle, as HYPERCAST_PURE does for hypercast. It is a testing and
+# diagnostic switch — CI runs the whole suite through it — read for presence, not value.
+# Inside a platform gem there is no library for it to load: BACKEND still reads :fiddle,
+# HyperTabular.available? answers false, and the first reader raises the LoadError naming the
+# missing library.
+HyperTabular::BACKEND =
+  if ENV["HYPERTABULAR_PURE"]
+    :fiddle
+  else
+    # A platform gem carries one extension per Ruby ABI under lib/hypertabular/<minor>/, and
+    # `rake native:dev` stages its own build there too; CI's in-job staging drops a single
+    # one flat at lib/. A miss on both is not an error: it is what the Fiddle backend is for.
+    begin
+      require "hypertabular/#{RUBY_VERSION[/\d+\.\d+/]}/hypertabular_native"
+      :native
+    rescue LoadError
+      begin
+        require "hypertabular_native"
+        :native
+      rescue LoadError
+        :fiddle
+      end
+    end
+  end

metadata

@@ -0,0 +1,128 @@
+--- !ruby/object:Gem::Specification
+name: hypertabular
+version: !ruby/object:Gem::Version
+  version: 0.7.0
+platform: ruby
+authors:
+- Brian Buvinghausen
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: hypercast
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.7.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.7.0
+- !ruby/object:Gem::Dependency
+  name: fiddle
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+description: |
+  CSV, TSV and any single-byte ASCII separator, and XLSX and ODS workbooks, read by a
+  native Rust core into typed column batches. The core owns no memory: this gem allocates the buffers once and the
+  core fills them in one native call per batch. Every cell is a HyperCast verdict — the
+  value, or a reason plus the offending span — and a file that is not rows of cells at
+  all is an exception raised after the intact rows. Two backends behind one surface,
+  selected automatically and both shipped prebuilt: a Magnus extension where a precompiled
+  platform gem matches, and stdlib Fiddle everywhere else. No compile on install.
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/hypertabular.rb
+- lib/hypertabular/batch.rb
+- lib/hypertabular/column.rb
+- lib/hypertabular/delimited_reader.rb
+- lib/hypertabular/dialect.rb
+- lib/hypertabular/native/linux-arm64/libhypertabular.so
+- lib/hypertabular/native/linux-musl-arm64/libhypertabular.so
+- lib/hypertabular/native/linux-musl-x64/libhypertabular.so
+- lib/hypertabular/native/linux-x64/libhypertabular.so
+- lib/hypertabular/native/osx-arm64/libhypertabular.dylib
+- lib/hypertabular/native/osx-x64/libhypertabular.dylib
+- lib/hypertabular/native/win-arm64/hypertabular.dll
+- lib/hypertabular/native/win-x64/hypertabular.dll
+- lib/hypertabular/runtime.rb
+- lib/hypertabular/runtime/columns.rb
+- lib/hypertabular/runtime/delimited.rb
+- lib/hypertabular/runtime/workbook.rb
+- lib/hypertabular/tabular_error.rb
+- lib/hypertabular/workbook.rb
+homepage: https://github.com/SkunkWerkx/HyperTabular
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/SkunkWerkx/HyperTabular
+  bug_tracker_uri: https://github.com/SkunkWerkx/HyperTabular/issues
+  changelog_uri: https://github.com/SkunkWerkx/HyperTabular/blob/master/CHANGELOG.md
+  documentation_uri: https://github.com/SkunkWerkx/HyperTabular/tree/master/ruby#readme
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.3'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.20
+specification_version: 4
+summary: Delimited text and workbooks read a batch at a time into typed columns, a
+  HyperCast verdict for every cell
+test_files: []