hypertabular-wasm 0.7.0

data/lib/hypertabular/tabular_error.rb

@@ -0,0 +1,99 @@
+module HyperTabular
+  # A structural failure: the input is not rows of cells — a record of the wrong width,
+  # input that ends inside a quoted cell, a workbook whose container or parts cannot be
+  # read. Never a cell's verdict: a value that does not cast is a HyperCast::Fault in its
+  # column, and the read goes on. A structural failure ends the input, after every intact
+  # row before it has been delivered.
+  #
+  # For a workbook, #record is the part the failure is in, #line the sheet row and #byte the
+  # offset within the part's inflated bytes.
+  #
+  #   begin
+  #     reader.read
+  #   rescue HyperTabular::TabularError => e
+  #     case e
+  #     in { kind: :column_count, line:, expected:, found: }
+  #       warn "line #{line}: #{found} cells, not #{expected}"
+  #     in { kind: :unclosed_quote, line: }
+  #       warn "line #{line}: a quote is never closed"
+  #     end
+  #   end
+  class TabularError < StandardError
+    # What the core's failure codes mean.
+    KINDS = {
+      1 => :unclosed_quote, 2 => :column_count, 3 => :row_too_long, 16 => :not_a_zip, 17 => :container,
+      18 => :encrypted, 19 => :method, 20 => :missing_part, 21 => :xml, 22 => :deflate,
+      23 => :not_a_workbook, 24 => :shared_string, 25 => :too_large
+    }.freeze
+
+    # What is wrong: :unclosed_quote (the input ended inside a quoted cell), :column_count
+    # (a record's cell count disagrees with the first record's), :row_too_long (a single
+    # record is larger than DelimitedReader::MAX_ROW_BYTES); for a workbook :not_a_zip,
+    # :container (the zip's own structure is broken), :encrypted, :method (a part is
+    # compressed by neither stored nor deflate), :missing_part, :xml (a part ends inside an
+    # XML construct), :deflate (a part is not a whole deflate stream), :not_a_workbook,
+    # :shared_string (a cell names a shared string the table does not have) or :too_large.
+    attr_reader :kind
+
+    # Zero-based index of the offending record — the header and skipped blank lines
+    # included.
+    attr_reader :record
+
+    # One-based line the offending record starts on.
+    attr_reader :line
+
+    # Absolute byte offset of the offending record's start, a byte-order mark included.
+    attr_reader :byte
+
+    # Cells in the first record, for :column_count; 0 otherwise.
+    attr_reader :expected
+
+    # Cells in this record, for :column_count; 0 otherwise.
+    attr_reader :found
+
+    # The failure the core reported, as [code, line, record, byte, expected, found]. A code
+    # this binding does not know is the container's: the most general refusal.
+    def self.from(failure)
+      code, line, record, byte, expected, found = failure
+      new(KINDS.fetch(code, :container), record, line, byte, expected, found)
+    end
+
+    # Raised by the readers; nothing else builds one.
+    def initialize(kind, record, line, byte, expected = 0, found = 0)
+      @kind = kind
+      @record = record
+      @line = line
+      @byte = byte
+      @expected = expected
+      @found = found
+      super(describe)
+    end
+
+    # The failure as a Hash, which is what lets `case error in { kind:, line: }` match.
+    def deconstruct_keys(_keys)
+      { kind: kind, record: record, line: line, byte: byte, expected: expected, found: found }
+    end
+
+    private
+
+    # The message, in the words the other bindings use.
+    def describe
+      at = "#{record} (line #{line}, byte #{byte})"
+      case kind
+      when :column_count then "Record #{at} has #{found} cells; the first record had #{expected}."
+      when :unclosed_quote then "The input ended inside a quoted cell in record #{at}."
+      when :row_too_long then "Record #{at} exceeds the #{DelimitedReader::MAX_ROW_BYTES}-byte row ceiling."
+      when :not_a_zip then "The workbook is not a zip file."
+      when :encrypted then "The workbook is encrypted."
+      when :method then "Part #{record} of the workbook is compressed by method #{found}, neither stored nor deflate."
+      when :missing_part then "Part #{record}, which the workbook cannot be read without, is missing."
+      when :xml then "Part #{record} of the workbook ends inside an XML construct (byte #{byte})."
+      when :deflate then "Part #{record} of the workbook is not a whole deflate stream (byte #{byte})."
+      when :not_a_workbook then "The zip is neither an XLSX nor an ODS workbook."
+      when :shared_string then "Row #{line} names shared string #{found}; the table has #{expected}."
+      when :too_large then "The workbook holds more text than a batch can address."
+      else "The workbook's zip structure is broken."
+      end
+    end
+  end
+end

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,107 @@
+--- !ruby/object:Gem::Specification
+name: hypertabular-wasm
+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-wasm
+  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: 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: |
+  The hypertabular gem's Magnus extension, prebuilt for wasm32-wasip1, for a ruby.wasm
+  interpreter built with `rbwasm build`: put this gem in that Gemfile instead of
+  hypertabular and the extension is linked into the interpreter, with hypercast-wasm beside
+  it. Same API and the same Rust core as the hypertabular gem. Not for a host Ruby, where
+  the hypertabular gem is the one to install.
+executables: []
+extensions:
+- ext/hypertabular_native/extconf.rb
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- ext/hypertabular_native/3.4/hypertabular_native.a.gz
+- ext/hypertabular_native/4.0/hypertabular_native.a.gz
+- ext/hypertabular_native/extconf.rb
+- lib/hypertabular.rb
+- lib/hypertabular/batch.rb
+- lib/hypertabular/column.rb
+- lib/hypertabular/delimited_reader.rb
+- lib/hypertabular/dialect.rb
+- 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#ruby-in-the-browser
+  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: 'HyperTabular for ruby.wasm: the Magnus extension, linked in by rbwasm build'
+test_files: []