hypertabular 0.7.0 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ad43df079742ea93176f0167a3189f4ec714adfe29ec4379b25a88d8ef500edb
-  data.tar.gz: 5073a2aaa4d69f2d5198fd02f946e78f5559816f7997be2a600db9664b19edfc
+  metadata.gz: 77fbc1e69617eb9fcd260821290db1bb81a84dccd309d2590e12292492e3230e
+  data.tar.gz: f5c2592bafcb5cbff3b763970ea4b11cf2ec1214ffb275429a06c02a63191346
 SHA512:
-  metadata.gz: f331637842578a2c3fae1398eb9e17572656aed61529f6e2eb954249ec347a3c68d5d3be515a30800dc37f3788f9f6e03dcb57ae2dc2856d028e22e657b67a7d
-  data.tar.gz: 0f3bf0326dd2111d31bdabc5c0149422b7614f10fa71212a463db1a7f1c1e73fbcea5b0b73d2a69898fa3eec7fbc5750f31c6d06d5cb69373af04eece0ccd38a
+  metadata.gz: ab0f0d11368749e31fb9fa517dc4e317d9e70c05f30f76151018507fb4bd507c554d01c85e2e916759745ec9430c5dd869dcb3af400d9761a634c206b4f7854a
+  data.tar.gz: 836188c6db4875e3dba668206514f2b4c3f1cc424781a52833aff8d6b9d4e99582e02d04265569397668170f398401d8fa4caff7b0ab823f1a166f5008d3e73e

data/README.md

@@ -7,14 +7,14 @@ read a batch at a time into typed columns, with a
 ```ruby
 require "hypertabular"
 
-plan = [
-  HyperTabular::Column.i32(0),
-  HyperTabular::Column.text(1),
-  HyperTabular::Column.f64(2)
-]
-
-HyperTabular::DelimitedReader.open("orders.csv", HyperTabular::Dialect::CSV, plan) do |reader|
-  reader.header                       # => ["id", "name", "score"]
+HyperTabular::DelimitedReader.open("orders.csv", HyperTabular::Dialect::CSV) do |reader|
+  # The header is read first; the plan is built from where its names are.
+  header = reader.header              # => ["id", "name", "score"]
+  reader.bind([
+    HyperTabular::Column.i32(header.ordinal("id")),
+    HyperTabular::Column.text(header.ordinal("name")),
+    HyperTabular::Column.f64(header.ordinal("score"))
+  ])
 
   while (batch = reader.read)
     # A column at a time, decoded in one pass — nil where a cell did not cast…
@@ -32,17 +32,44 @@ HyperTabular::DelimitedReader.open("orders.csv", HyperTabular::Dialect::CSV, pla
   end
 end
 
-# A workbook reads into the same batch.
+# Or a row at a time: a reader, a sheet and a batch are Enumerable over Rows.
+reader = HyperTabular::DelimitedReader.open("orders.csv", HyperTabular::Dialect::CSV)
+reader.bind([HyperTabular::Column.i32(reader.header.ordinal("id"))])
+reader.each { |row| puts "line #{row.line}: #{row.value(0).inspect}" }
+
+# A workbook reads into the same batch — from a path, a String or an IO.
 book = HyperTabular::Workbook.open("orders.xlsx")
 book.sheets                           # => [#<data HyperTabular::SheetInfo name="Orders", hidden=false>]
-sheet = book.sheet("Orders", HyperTabular::SheetOptions::DEFAULT, plan)
+sheet = book.sheet("Orders", HyperTabular::SheetOptions::DEFAULT)
+sheet.bind([HyperTabular::Column.decimal(sheet.header.ordinal("Total"))])
 while (batch = sheet.read)
   # …
 end
 ```
 
-`reader.each_row` walks every remaining row as an Array of verdicts, for when a row at a
-time is what the caller wants; `sheet.each_batch` walks a sheet's batches.
+A plan known up front can be handed over at once —
+`DelimitedReader.open(path, dialect, plan)`, `book.sheet(which, options, plan)` — which binds it
+before the header is read.
+
+- **The header** (`reader.header`, `sheet.header`) is a `HyperTabular::Header`: the frozen
+  Array of frozen names it always was, which also says where a name is. `header.ordinal(name)`
+  is the first column with exactly that name — case and spaces included — and a `KeyError`
+  naming it when there is none (or, with a block, the block's value, as `Hash#fetch` does);
+  `header.find_ordinal(name)` answers `nil` instead.
+- **Binding** happens once, before the first read: `bind` again raises `RuntimeError`, and so
+  does a `read` before `bind` — which `bind` then cures. A plan that is not Columns is an
+  `ArgumentError` and leaves the reader unbound. `bound?` says which it is. A `nil` plan
+  means "bind later"; `[]` is an empty plan, bound at once.
+  `reader.column_count` is the header's count, or the first record's once it has been read.
+- **Rows.** `batch.each`, `reader.each` and `sheet.each` yield a `HyperTabular::Row` —
+  `index`, `line`, `get(column)` (also `[]` and `verdict`), `value(column)`, `raw(column)`,
+  `to_a` — each answering what the batch's own accessor does for that row. A batch is a copy,
+  so a row stays good after the read has moved on. A Row deconstructs as its verdicts, for
+  `case row in [HyperCast::Success(value: id), *]`. `reader.each_row` still yields each row as
+  a frozen Array of verdicts, and `sheet.each_batch` walks a sheet's batches.
+- **A workbook from an IO.** `Workbook.new(io)` reads anything with `#read` to its end into a
+  String the workbook owns, as soon as it is opened; `close_source: true` closes the IO once it
+  has been read. The kind of workbook is read from its bytes, never from a name.
 
 ## The shape
 
@@ -53,11 +80,13 @@ native call per batch, and a column comes out of its buffer in one `String#unpac
 boundary is crossed once per few thousand rows, not once per cell.
 
 - **One batch class.** `read` returns a `HyperTabular::Batch` — `rows`, `columns`,
-  `line(row)`, `values(column)`, `verdicts(column)`, `get(column, row)` and `raw(column,
-  row)` — or `nil` once there are no more rows, for delimited text and a sheet alike. A
-  batch owns what it shows: it stays good after the reader has moved on.
+  `line(row)`, `values(column)`, `verdicts(column)`, `get(column, row)`, `raw(column,
+  row)`, and a `Row` for each row through `each` — or `nil` once there are no more rows,
+  for delimited text and a sheet alike. A batch owns what it shows: it stays good after the
+  reader has moved on.
 - **Nothing is sniffed.** The `Dialect` states the separator, the quoting and the header;
-  `SheetOptions` states a sheet's header and whether empty rows are skipped; the plan
+  `SheetOptions` states a sheet's header, whether empty rows are skipped and the batch size;
+  the plan
   states each column's door and, for numbers, its `HyperCast::NumFormat`.
 - **HyperCast is the judge.** `HyperCast::Success`, `HyperCast::Fault`,
   `HyperCast::NumFormat`, `HyperCast::Decimal` and the declared options (`:milliseconds`,
@@ -75,6 +104,9 @@ boundary is crossed once per few thousand rows, not once per cell.
   offending text.
 - **A String is read in place.** An IO is read forward only, through a buffer that grows
   when a record does not fit it.
+- **No async API, and none needed.** An IO is read with `#readpartial` or `#read`, which yield
+  to the Fiber scheduler (the `async` gem's, or any other) instead of blocking, and a task
+  cancelled in one is interrupted there; the core's work between reads is on memory.
 
 ## The doors
 

data/lib/hypertabular/batch.rb

@@ -17,7 +17,14 @@ module HyperTabular
   # HyperCast's gem's own for the same doors: true/false, Integer, Float, HyperCast::Decimal,
   # a hyphenated UUID String, a UTC Time, Date, DateTime, Integer nanoseconds since midnight,
   # Rational seconds, and a UTF-8 String for text.
+  #
+  # A batch is also Enumerable over its rows, for a caller that thinks in rows: #each yields
+  # a Row per row, in order.
+  #
+  #   batch.each { |row| orders << Order.new(row.value(0), row.value(1), row.line) }
   class Batch
+    include Enumerable
+
     # The verdict of every cell that had no bytes at all: one shared, frozen Fault.
     EMPTY = HyperCast::Fault.new(reason: :empty, offset: 0, length: 0)
 
@@ -110,6 +117,20 @@ module HyperTabular
       Runtime.unescape(quoted).force_encoding(Encoding::UTF_8)
     end
 
+    # Yields a Row for each row of the batch, in order, and returns the batch; without a
+    # block, an Enumerator.
+    def each
+      return to_enum(:each) { @rows } unless block_given?
+
+      @rows.times { |index| yield Row.new(self, index) }
+      self
+    end
+
+    # The Row at +row+. IndexError for a row outside the batch.
+    def row(row)
+      Row.new(self, at(row))
+    end
+
     # The batch in a line — not its cells.
     def inspect
       "#<#{self.class.name} rows=#{@rows} columns=#{@columns.size}>"

data/lib/hypertabular/column.rb

@@ -132,6 +132,18 @@ module HyperTabular
     # String. A cell with no bytes at all is the one way text fails (an :empty Fault).
     def self.text(ordinal) = new(ordinal: ordinal, door: :text)
 
+    # +plan+ as a reader holds it: a frozen Array of its own, every entry a Column — what
+    # DelimitedReader and Sheet check a plan with. ArgumentError naming the first entry that
+    # is not a Column.
+    def self.plan(plan)
+      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
+      plan
+    end
+
     # Bytes one value of this column's door takes in a column buffer.
     def value_bytes
       Column::VALUE_BYTES.fetch(door)

data/lib/hypertabular/delimited_reader.rb

@@ -27,9 +27,21 @@ module HyperTabular
   # not rows of cells at all — a record of the wrong width, a quote never closed — is a
   # TabularError, raised after every intact row before it has been delivered.
   #
+  # The plan may also wait for the header. Opened without one, the reader reads the header
+  # and stops: its names say where each column is, and #bind declares the plan built from
+  # them, once, before the first read:
+  #
+  #   reader = HyperTabular::DelimitedReader.open("orders.csv", HyperTabular::Dialect::CSV)
+  #   header = reader.header                           # => ["id", "name", "score"]
+  #   reader.bind([HyperTabular::Column.i32(header.ordinal("id")),
+  #                HyperTabular::Column.f64(header.ordinal("score"))])
+  #   reader.each { |row| total += row.value(1) || 0 } # a Row at a time, batch after batch
+  #
   # Each #read returns a Batch, which owns what it shows: it stays good after the next
   # #read. Not thread-safe.
   class DelimitedReader
+    include Enumerable
+
     # The row ceiling: a single record larger than this is a :row_too_long TabularError.
     MAX_ROW_BYTES = 1 << 30
 
@@ -42,10 +54,11 @@ module HyperTabular
     # Encodings whose bytes already are the UTF-8 (or byte-identical) form the core reads.
     BYTE_COMPATIBLE = HyperCast::Interop::BYTE_COMPATIBLE
 
-    # Opens a file of UTF-8 delimited text. With a block, yields the reader, closes it —
-    # and the file — when the block ends, and returns the block's value; without one,
-    # returns the reader, whose #close closes the file.
-    def self.open(path, dialect, plan, batch_rows: DEFAULT_BATCH_ROWS, buffer_bytes: DEFAULT_BUFFER_BYTES)
+    # Opens a file of UTF-8 delimited text, through +plan+ — or, with none, header first,
+    # for #bind. With a block, yields the reader, closes it — and the file — when the block
+    # ends, and returns the block's value; without one, returns the reader, whose #close
+    # closes the file.
+    def self.open(path, dialect, plan = nil, batch_rows: DEFAULT_BATCH_ROWS, buffer_bytes: DEFAULT_BUFFER_BYTES)
       file = File.open(path, "rb")
       begin
         reader = new(file, dialect, plan, batch_rows: batch_rows, buffer_bytes: buffer_bytes, close_source: true)
@@ -67,14 +80,15 @@ module HyperTabular
     # of +buffer_bytes+ that grows when a record does not fit it. An IO is read as bytes;
     # one opened in text mode on Windows should be in binmode first.
     #
-    # +dialect+ is the declared Dialect and +plan+ the output Columns, in output order.
+    # +dialect+ is the declared Dialect and +plan+ the output Columns, in output order — or
+    # nil, for a reader that reads its header first and is given its plan by #bind.
     # +batch_rows+ is the most rows one #read delivers. +close_source+ says whether #close
     # also closes the IO.
     #
     # A dialect the scanner cannot honour, or a plan that is not Columns, is an
     # ArgumentError. With a header declared the header record is read here, so a header
     # that is structurally broken is a TabularError here.
-    def initialize(source, dialect, plan, batch_rows: DEFAULT_BATCH_ROWS, buffer_bytes: DEFAULT_BUFFER_BYTES,
+    def initialize(source, dialect, plan = nil, batch_rows: DEFAULT_BATCH_ROWS, buffer_bytes: DEFAULT_BUFFER_BYTES,
                    close_source: false)
       raise ArgumentError, "dialect must be a HyperTabular::Dialect; got #{dialect.inspect}" unless
         dialect.is_a?(Dialect)
@@ -83,22 +97,18 @@ module HyperTabular
       raise ArgumentError, "buffer_bytes must be a positive Integer; got #{buffer_bytes.inspect}" unless
         buffer_bytes.is_a?(Integer) && buffer_bytes.positive?
 
-      @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
+      planned = Column.plan(plan) unless plan.nil?
       @dialect = dialect
       @batch_rows = batch_rows
       @buffer_bytes = buffer_bytes
       @close_source = close_source
-      # Cell-table entries one row takes: the widest ordinal the plan reads, plus two.
-      per_row = (@plan.map(&:ordinal).max || -1) + 2
-      @kernel = Runtime::Delimited.start(dialect.packed, @plan.map(&:packed), @plan.map(&:value_bytes),
-                                         batch_rows, per_row)
+      @kernel = Runtime::Delimited.start(dialect.packed)
       raise ArgumentError, "separator #{dialect.separator.inspect} is not tab or printable ASCII other than '\"'" if
         @kernel.nil?
 
+      @plan = UNBOUND
+      # A plan handed over here is bound before the header is read, as #bind would bind it.
+      bind_kernel(planned) if planned
       @start = 0
       @closed = false
       @failure = nil
@@ -106,14 +116,42 @@ module HyperTabular
       @header = dialect.has_header ? read_header : nil
     end
 
-    # The header's names, when the dialect declares a header: frozen UTF-8 Strings, quotes
-    # resolved. Empty for an input with no record at all; nil when the dialect declares no
-    # header.
+    # The header's names, when the dialect declares a header: a Header — the frozen Array of
+    # frozen UTF-8 Strings, quotes resolved, that also says where a name is
+    # (Header#ordinal). Empty for an input with no record at all; nil when the dialect
+    # declares no header.
     attr_reader :header
 
     # The plan: the output Columns, in output order. Column +i+ of every batch is +plan[i]+.
+    # Empty until one is bound.
     attr_reader :plan
 
+    # Declares the plan a reader opened without one reads through — +plan+, the output
+    # Columns, in output order, typically built from the #header's ordinals — once, before
+    # the first read. Returns the reader.
+    #
+    # ArgumentError for a plan that is not Columns, which leaves the reader unbound;
+    # RuntimeError if the reader already has a plan; IOError on a closed reader.
+    def bind(plan)
+      raise IOError, "closed reader" if @closed
+      raise "the reader already has a plan: a plan is bound once" if bound?
+
+      bind_kernel(Column.plan(plan))
+      self
+    end
+
+    # Whether a plan has been bound: always, for a reader opened with one.
+    def bound?
+      !@plan.equal?(UNBOUND)
+    end
+
+    # How many cells a record has: the header's count once it has been read, otherwise the
+    # first record's once it has been; nil before either.
+    def column_count
+      expected = @kernel.expected
+      expected.zero? ? nil : expected
+    end
+
     # The declared Dialect.
     attr_reader :dialect
 
@@ -128,10 +166,12 @@ module HyperTabular
     # Reads the next batch: a Batch of up to #batch_rows rows, or nil once the input is
     # exhausted. A TabularError when the input is structurally broken — raised after every
     # intact row before the break has been delivered, and the same error again on every
-    # later call. IOError on a closed reader.
+    # later call. IOError on a closed reader; RuntimeError before a plan is bound, which
+    # #bind then cures.
     def read
       raise IOError, "closed reader" if @closed
       raise @failure if @failure
+      raise UNBOUND_MESSAGE unless bound?
 
       loop do
         length, last = window
@@ -162,6 +202,18 @@ module HyperTabular
       self
     end
 
+    # Every remaining row, batch after batch, as a Row — which, its batch being a copy,
+    # stays good after the read has moved on. Returns the reader; without a block, an
+    # Enumerator, and the reader is Enumerable through it. Raises what #read raises.
+    def each(&block)
+      return to_enum(:each) unless block
+
+      while (batch = read)
+        batch.each(&block)
+      end
+      self
+    end
+
     # Closes the IO if this reader was told to (+close_source+, or DelimitedReader.open).
     # Batches already read stay good. Safe to call twice.
     def close
@@ -179,11 +231,26 @@ module HyperTabular
 
     # The reader in a line — not its buffers.
     def inspect
-      "#<#{self.class.name} columns=#{@plan.size} records=#{records}#{' closed' if @closed}>"
+      "#<#{self.class.name} columns=#{@plan.size} records=#{records}#{' unbound' unless bound?}" \
+        "#{' closed' if @closed}>"
     end
 
     private
 
+    # The plan of a reader that has none yet.
+    UNBOUND = [].freeze
+    # What a read before a plan is bound says.
+    UNBOUND_MESSAGE = "the reader has no plan yet: bind one before reading".freeze
+    private_constant :UNBOUND, :UNBOUND_MESSAGE
+
+    # Sizes the kernel's arrays for +plan+ (already checked to be Columns) and takes it.
+    def bind_kernel(plan)
+      # Cell-table entries one row takes: the widest ordinal the plan reads, plus two.
+      per_row = (plan.map(&:ordinal).max || -1) + 2
+      @kernel.bind(plan.map(&:packed), plan.map(&:value_bytes), @batch_rows, per_row)
+      @plan = plan
+    end
+
     # Takes the source: a String becomes the whole input, an IO the thing to refill from.
     def take(source)
       if source.is_a?(String)
@@ -271,7 +338,7 @@ module HyperTabular
         end
         @start += consumed
         # An empty input has no header and no rows; the width is unknown.
-        return [].freeze if last && (consumed == length || consumed.zero?)
+        return Header.new.freeze if last && (consumed == length || consumed.zero?)
 
         refill if consumed.zero?
       end
@@ -282,7 +349,7 @@ module HyperTabular
     def header_names
       spans = @kernel.names
       arena = nil
-      Array.new(@kernel.rows) do |index|
+      names = Header.new(@kernel.rows) do |index|
         offset = spans[index * 2]
         length = spans[index * 2 + 1]
         name =
@@ -293,7 +360,8 @@ module HyperTabular
             arena.byteslice(offset, length & Runtime::Delimited::SPAN_LENGTH)
           end
         name.freeze
-      end.freeze
+      end
+      names.freeze
     end
 
     # The structural failure the core just reported, kept: it is final.

data/lib/hypertabular/header.rb

@@ -0,0 +1,52 @@
+module HyperTabular
+  # A header's names, in column order: what DelimitedReader#header and Sheet#header return.
+  # It is the frozen Array of frozen UTF-8 Strings those have always returned — it equals
+  # the Array of the same names, indexes, iterates and pattern-matches as one — and it can
+  # also say where a name is, which is what a plan built from names reads with:
+  #
+  #   reader = HyperTabular::DelimitedReader.open("orders.csv", HyperTabular::Dialect::CSV)
+  #   header = reader.header                  # => ["id", "name", "score"]
+  #   reader.bind([HyperTabular::Column.text(header.ordinal("name")),
+  #                HyperTabular::Column.f64(header.ordinal("score"))])
+  #
+  # A name matches exactly — byte for byte, case and spaces included — and a name the header
+  # has twice is found where it is first.
+  class Header < Array
+    # The ordinal of the first column named +name+ (a String). A name the header does not
+    # have is a KeyError that says which — or, with a block, the block's value, the block
+    # handed the name, as Hash#fetch does:
+    #
+    #   header.ordinal("id")                  # => 0
+    #   header.ordinal("missing")             # KeyError: the header has no column named "missing"
+    #   header.ordinal("missing") { nil }     # => nil
+    #
+    # A binary String is matched as the bytes it holds; a String in another encoding is
+    # matched as its UTF-8 transcoding. TypeError for anything that is not a String.
+    def ordinal(name)
+      found = find_ordinal(name)
+      return found unless found.nil?
+      return yield(name) if block_given?
+
+      raise KeyError.new("the header has no column named #{name.inspect}", receiver: self, key: name)
+    end
+
+    # The ordinal of the first column named +name+, or nil when the header has none: #ordinal
+    # without the KeyError, matched the same way.
+    def find_ordinal(name)
+      raise TypeError, "a column name is a String; got #{name.class}" unless name.is_a?(String)
+
+      wanted =
+        case name.encoding
+        when Encoding::UTF_8 then name
+        when Encoding::BINARY then name.dup.force_encoding(Encoding::UTF_8)
+        else
+          begin
+            name.encode(Encoding::UTF_8)
+          rescue EncodingError
+            return nil
+          end
+        end
+      index(wanted)
+    end
+  end
+end

data/lib/hypertabular/row.rb

@@ -0,0 +1,74 @@
+module HyperTabular
+  # One row of a Batch: what Batch#each, DelimitedReader#each and Sheet#each yield, for a
+  # caller that thinks in rows — "for each record, build an object from these columns" —
+  # rather than in columns. A view of (batch, index): every member answers what the batch's
+  # own accessor answers for that row, nothing is copied, and since a batch owns what it
+  # shows, a row stays good after the reader has moved on.
+  #
+  #   reader.each do |row|
+  #     case row.get(0)
+  #     in HyperCast::Success(value: id) then orders << Order.new(id, row.value(1), row.line)
+  #     in HyperCast::Fault(reason:) then warn "line #{row.line}: #{reason} in #{row.raw(0).inspect}"
+  #     end
+  #   end
+  #
+  # It deconstructs as its verdicts, one per plan column, so a whole row can be matched at
+  # once: `in [HyperCast::Success(value: id), HyperCast::Success(value: name)]`.
+  class Row
+    # The batch the row is in.
+    attr_reader :batch
+
+    # The row's 0-based index within its batch.
+    attr_reader :index
+
+    # Made by Batch#each.
+    def initialize(batch, index)
+      @batch = batch
+      @index = index
+      freeze
+    end
+
+    # Where the row came from — Batch#line: for delimited text the 1-based line its record
+    # starts on, for a sheet its 1-based row number.
+    def line
+      @batch.line(@index)
+    end
+
+    # The cell in plan column +column+ as HyperCast judged it — Batch#get. IndexError for a
+    # column outside the plan.
+    def get(column)
+      @batch.get(column, @index)
+    end
+    alias [] get
+    alias verdict get
+
+    # The cell's value, or nil where it did not cast — Batch#values' entry for this row.
+    # IndexError for a column outside the plan.
+    def value(column)
+      @batch.values(column)[@index]
+    end
+
+    # The text the cell was cast from, whatever its door and verdict — Batch#raw.
+    def raw(column)
+      @batch.raw(column, @index)
+    end
+
+    # How many cells the row has: one per plan column.
+    def size
+      @batch.columns.size
+    end
+    alias length size
+
+    # Every cell's verdict, in plan order, as a frozen Array — the Array
+    # DelimitedReader#each_row yields for the same row.
+    def to_a
+      Array.new(size) { |column| get(column) }.freeze
+    end
+    alias deconstruct to_a
+
+    # The row in a line — not its cells.
+    def inspect
+      "#<#{self.class.name} index=#{@index} line=#{line}>"
+    end
+  end
+end

data/lib/hypertabular/runtime/delimited.rb

@@ -7,7 +7,9 @@ module HyperTabular
     #
     # The memory is allocated once and reused for every batch: the state block, the plan,
     # one value array and one verdict array per column, the cell table, the arena. The core
-    # keeps none of it between calls beyond what it writes into the state block.
+    # keeps none of it between calls beyond what it writes into the state block. The plan's
+    # arrays and the cell table wait for #bind, so the header can be read before there is a
+    # plan.
     class Delimited
       # The call did what it could; the result says how far it got.
       OK = 0
@@ -51,7 +53,8 @@ module HyperTabular
       attr_reader :rows, :consumed, :arena_used, :failure
 
       # The plan's arrays (Columns), and the cell-table entries one row takes: the widest
-      # ordinal the plan reads, plus two — or more, if the core asked for more.
+      # ordinal the plan reads, plus two — or more, if the core asked for more. Nil until
+      # #bind.
       attr_reader :columns, :per_row
 
       # The loaded core's version word, major << 16 | minor << 8 | patch.
@@ -59,24 +62,17 @@ module HyperTabular
         Runtime.function(:hypertabular_version).call
       end
 
-      # +dialect+ is the four bytes of a RawDialect; +specs+ one packed ColumnSpec per plan
-      # column and +sizes+ the bytes one value of each takes; +per_row+ the cell-table
-      # entries one row takes. Nil when the core refuses the dialect.
-      def self.start(dialect, specs, sizes, batch_rows, per_row)
-        reader = new(specs, sizes, batch_rows, per_row)
+      # +dialect+ is the four bytes of a RawDialect. Nil when the core refuses it.
+      def self.start(dialect)
+        reader = new
         reader.send(:init, dialect) ? reader : nil
       end
 
-      def initialize(specs, sizes, batch_rows, per_row)
+      def initialize
         @header = Runtime.function(:hypertabular_delimited_header)
         @fill = Runtime.function(:hypertabular_delimited_fill)
         @state = Runtime.buffer(Runtime.function(:hypertabular_delimited_state_size).call)
-        @batch_rows = batch_rows
-        @columns = Columns.new(specs, sizes, batch_rows)
-        @per_row = per_row
         @cramped = false
-        @cells_cap = per_row * batch_rows
-        @cells = Runtime.buffer(SPAN_BYTES * @cells_cap)
         @arena_cap = ARENA_BYTES
         @arena = Runtime.buffer(@arena_cap)
         @out = Runtime.buffer(FILLED_BYTES)
@@ -84,6 +80,17 @@ module HyperTabular
         @rows = @consumed = @arena_used = 0
       end
 
+      # Takes the plan: +specs+ is one packed ColumnSpec per plan column and +sizes+ the
+      # bytes one value of each takes, +batch_rows+ the most rows a fill writes and +per_row+
+      # the cell-table entries one row takes. Once, before the first #fill.
+      def bind(specs, sizes, batch_rows, per_row)
+        @batch_rows = batch_rows
+        @columns = Columns.new(specs, sizes, batch_rows)
+        @per_row = per_row
+        @cells_cap = per_row * batch_rows
+        @cells = Runtime.buffer(SPAN_BYTES * @cells_cap)
+      end
+
       # Names the String the calls that follow read: +start+ and +offset+ below index its
       # bytes. It is held where it is, not copied, and must not be modified until another
       # one is attached.
@@ -173,6 +180,11 @@ module HyperTabular
         @state[16, 8].unpack1("Q<")
       end
 
+      # Cells per record, fixed by the header or the first record; 0 before either.
+      def expected
+        @state[24, 4].unpack1("L<")
+      end
+
       private
 
       def init(dialect)

data/lib/hypertabular/runtime/workbook.rb

@@ -51,7 +51,11 @@ module HyperTabular
       # it opens, one for each sheet.
       class Scratch
         # The buffers, each a Fiddle::Pointer, and their sizes (in bytes, spans, slots).
-        attr_reader :window, :arena, :cells, :arena_cap, :cells_cap
+        attr_reader :window, :arena, :cells, :arena_cap, :cells_cap, :row_cap
+
+        # Whether the row's slots grow with the cell table: what a header read before there
+        # is a plan needs, so that there is a slot for every cell the header names.
+        attr_accessor :row_follows_cells
 
         def initialize(window, arena, cells, row)
           @window_cap = window
@@ -84,9 +88,22 @@ module HyperTabular
           @arena, @arena_cap = grown(@arena, @arena_cap, needed, 1)
         end
 
-        # Makes the cell table at least +needed+ spans, what it held kept.
+        # Makes the cell table at least +needed+ spans, what it held kept — and, while the
+        # row follows it, the row's slots as many.
         def grow_cells(needed)
           @cells, @cells_cap = grown(@cells, @cells_cap, needed, SPAN_BYTES)
+          reserve_row(@cells_cap) if @row_follows_cells
+        end
+
+        # Makes the cell table at least +needed+ spans if it is smaller, what it held kept.
+        def reserve_cells(needed)
+          @cells, @cells_cap = grown(@cells, @cells_cap, needed, SPAN_BYTES) if @cells_cap < needed
+        end
+
+        # Makes the row at least +needed+ slots if it is smaller, what it held kept: a header
+        # row still to be repeated is never dropped.
+        def reserve_row(needed)
+          @row, @row_cap = grown(@row, @row_cap, needed, SLOT_BYTES) if @row_cap < needed
         end
 
         # Makes +call+ (a block taking the Buffers block and the out block) until it stops
@@ -210,18 +227,19 @@ module HyperTabular
         end
       end
 
-      # One sheet being read: its own copy of the state, its plan's arrays, its scratch.
+      # One sheet being read: its own copy of the state, its plan's arrays, its scratch. The
+      # plan's arrays wait for #bind, so that the header can be read before there is a plan.
       class Reading
         # The plan's arrays, and the cell-table entries one row takes: one per plan column,
-        # and one for the row's number.
-        attr_reader :columns, :per_row, :header
+        # and one for the row's number. Nil until #bind.
+        attr_reader :columns, :per_row
 
-        def initialize(book, sheet, has_header, skip_empty_rows, specs, sizes, batch_rows, width)
+        # Positions a copy of the workbook's state on +sheet+ (an entry of Opened#sheets).
+        def initialize(book, sheet, has_header, skip_empty_rows, batch_rows)
           @book = book
           @state = book.copy_of_state
-          @columns = Columns.new(specs, sizes, batch_rows)
-          @per_row = specs.size + 1
-          @scratch = Book.stingy ? Scratch.new(1, 1, 1, width) : Scratch.new(0, 4096, batch_rows * @per_row, width)
+          @batch_rows = batch_rows
+          @scratch = Book.stingy ? Scratch.new(1, 1, 1, 0) : Scratch.new(0, 4096, 64, 0)
           @out = Runtime.buffer(FILLED_BYTES)
           _name, _hidden, part, index = sheet
           code = Runtime.function(:hypertabular_workbook_sheet).call(
@@ -229,7 +247,19 @@ module HyperTabular
             has_header ? 1 : 0, skip_empty_rows ? 1 : 0, @out
           )
           Book.settle(code, @out[0, FILLED_BYTES].unpack(FILLED))
-          @header = read_header if has_header
+        end
+
+        # Takes the plan: +specs+ is one packed ColumnSpec per plan column, +sizes+ the bytes
+        # one value of each takes, and +width+ the slots a row needs to reach every source
+        # column the plan reads. Once, before the first #fill. The core keeps a header row's
+        # cells in the row's slots — a row the sheet repeats (an ODS number-rows-repeated) is
+        # delivered again from them — so the slots are only ever grown here, never replaced.
+        def bind(specs, sizes, width)
+          @columns = Columns.new(specs, sizes, @batch_rows)
+          @per_row = specs.size + 1
+          # A stingy scratch is left to grow into the cell table the hard way, mid-read.
+          @scratch.reserve_cells(@batch_rows * @per_row) unless Book.stingy
+          @scratch.reserve_row(width)
         end
 
         # The next batch's rows, its cell table, the arena as far as the core wrote into it
@@ -249,13 +279,18 @@ module HyperTabular
            code == OK ? nil : filled[4..]]
         end
 
-        private
-
+        # Reads the header row: its names, as frozen UTF-8 Strings in a frozen Array. Read
+        # before #bind, the row's slots are made — and kept — as many as the cell table has
+        # spans, which is a slot for every name.
         def read_header
           call = Runtime.function(:hypertabular_workbook_header)
+          unbound = @columns.nil?
+          @scratch.reserve_row(@scratch.cells_cap) if unbound
+          @scratch.row_follows_cells = unbound
           code, filled = @scratch.drive(@out, @book.tables) do |buffers|
             call.call(@state, @book.container, @book.length, buffers, @out)
           end
+          @scratch.row_follows_cells = false
           rows = Book.settle(code, filled).first
           spans = @scratch.cells[0, SPAN_BYTES * rows].unpack("L<*")
           arena = nil

data/lib/hypertabular/workbook.rb

@@ -24,7 +24,8 @@ module HyperTabular
   #
   #   book = HyperTabular::Workbook.open("orders.xlsx")
   #   book.sheets                  # => [#<data HyperTabular::SheetInfo name="Orders", hidden=false>]
-  #   sheet = book.sheet("Orders", HyperTabular::SheetOptions::DEFAULT, plan)
+  #   sheet = book.sheet("Orders", HyperTabular::SheetOptions::DEFAULT)
+  #   sheet.bind([HyperTabular::Column.i32(sheet.header.ordinal("id"))])
   #   while (batch = sheet.read) ... end
   #
   # A workbook that cannot be read — not a zip, encrypted, a part missing or broken — is a
@@ -36,12 +37,23 @@ module HyperTabular
       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?
+    # Opens the workbook in +source+: a String, which is read in place — a frozen String is
+    # the workbook's as it is, anything else is copied once — or an IO (anything with
+    # #read), read to its end into a String the workbook owns, as soon as it is opened; the
+    # IO is closed once it has been read if +close_source+ says so. Which kind of workbook
+    # it is is read from its bytes, never from a name.
+    def initialize(source, close_source: false)
+      bytes =
+        if source.is_a?(String)
+          source.frozen? ? source : source.b.freeze
+        elsif defined?(::Pathname) && source.is_a?(::Pathname)
+          # It has a #read, but it is a path, and Workbook.open is what reads one.
+          raise ArgumentError, "source is a Pathname; Workbook.open reads a path"
+        elsif source.respond_to?(:read)
+          drain(source, close_source)
+        else
+          raise ArgumentError, "source must be a String or an IO; got #{source.class}"
+        end
       @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
@@ -64,10 +76,11 @@ module HyperTabular
     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)
+    # +plan+, as +options+ (SheetOptions) says; or, with no plan, header first, the plan to
+    # be given by Sheet#bind once the header has said where each column is. 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 = nil)
       index =
         case which
         when Integer
@@ -89,6 +102,18 @@ module HyperTabular
     def inspect
       "#<#{self.class.name} #{format} sheets=#{@sheets.size}>"
     end
+
+    private
+
+    # Everything +io+ has left, as a frozen binary String of the workbook's own; the IO
+    # closed after, if +close+ says so, whether or not the read went well.
+    def drain(io, close)
+      bytes = io.read
+      bytes = bytes.nil? ? String.new : bytes.dup
+      bytes.force_encoding(Encoding::BINARY).freeze
+    ensure
+      io.close if close
+    end
   end
 
   # A forward-only read of one sheet of a Workbook, a batch at a time, through a plan — into
@@ -99,14 +124,17 @@ module HyperTabular
   # 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
+    include Enumerable
+
     # The SheetOptions the sheet is read with.
     attr_reader :options
 
-    # The plan: the output Columns, in output order.
+    # The plan: the output Columns, in output order. Empty until one is bound.
     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.
+    # The header row's names — a typed cell said the way the text door says it — as a
+    # Header (the frozen Array of frozen UTF-8 Strings, which also says where a name is), or
+    # nil when the options declare no header.
     attr_reader :header
 
     # Made by Workbook#sheet.
@@ -114,26 +142,46 @@ module HyperTabular
       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
+      planned = Column.plan(plan) unless plan.nil?
       @book = book
       @options = options
-      width = (@plan.map(&:ordinal).max || -1) + 1
+      @plan = UNBOUND
       @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
+                                            options.batch_rows)
+      # A plan handed over here is bound before the header is read, as #bind would bind it;
+      # without one the header row is read into slots enough for every cell it has, and
+      # binding later keeps them (a row the sheet repeats is delivered from them again).
+      bind_reading(planned) if planned
+      @header = options.has_header ? Header.new(@reading.read_header).freeze : nil
       @pending = nil
       @failure = nil
     rescue Runtime::Book::StructureError => e
       raise TabularError.from(e.failure)
     end
 
+    # Declares the plan a sheet opened without one reads through — +plan+, the output
+    # Columns, in output order, typically built from the #header's ordinals — once, before
+    # the first read. Returns the sheet.
+    #
+    # ArgumentError for a plan that is not Columns, which leaves the sheet unbound;
+    # RuntimeError if the sheet already has a plan.
+    def bind(plan)
+      raise "the sheet already has a plan: a plan is bound once" if bound?
+
+      bind_reading(Column.plan(plan))
+      self
+    end
+
+    # Whether a plan has been bound: always, for a sheet opened with one.
+    def bound?
+      !@plan.equal?(UNBOUND)
+    end
+
     # Reads the next batch: a Batch of up to the options' batch_rows rows, or nil once the
-    # sheet has no more.
+    # sheet has no more. RuntimeError before a plan is bound, which #bind then cures.
     def read
+      raise "the sheet has no plan yet: bind one before reading" unless bound?
+
       if @pending
         @failure = @pending
         @pending = nil
@@ -165,9 +213,35 @@ module HyperTabular
       self
     end
 
+    # Every remaining row, batch after batch, as a Row — which, its batch being a copy,
+    # stays good after the read has moved on. Returns the sheet; without a block, an
+    # Enumerator, and the sheet is Enumerable through it. Raises what #read raises.
+    def each(&block)
+      return to_enum(:each) unless block
+
+      while (batch = read)
+        batch.each(&block)
+      end
+      self
+    end
+
     # The sheet in a line.
     def inspect
-      "#<#{self.class.name} columns=#{@plan.size}>"
+      "#<#{self.class.name} columns=#{@plan.size}#{' unbound' unless bound?}>"
+    end
+
+    private
+
+    # The plan of a sheet that has none yet.
+    UNBOUND = [].freeze
+    private_constant :UNBOUND
+
+    # Sizes the reading's arrays for +plan+ (already checked to be Columns) and takes it.
+    def bind_reading(plan)
+      # Slots the core assembles a row in: one for every source column the plan reaches.
+      width = (plan.map(&:ordinal).max || -1) + 1
+      @reading.bind(plan.map(&:packed), plan.map(&:value_bytes), width)
+      @plan = plan
     end
   end
 end

data/lib/hypertabular.rb

@@ -22,6 +22,12 @@ require_relative "hypertabular/runtime/workbook"
 #   sheet = book.sheet("Orders", HyperTabular::SheetOptions::DEFAULT, plan)
 #   sheet.read                    # => the same Batch
 #
+# Or header first, the plan built from the names the header says are there:
+#
+#   reader = HyperTabular::DelimitedReader.new("id,name\n1,alice\n", HyperTabular::Dialect::CSV)
+#   reader.bind([HyperTabular::Column.text(reader.header.ordinal("name"))])
+#   reader.map { |row| row.value(0) }  # => ["alice"]
+#
 # 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:
@@ -32,7 +38,7 @@ require_relative "hypertabular/runtime/workbook"
 module HyperTabular
   # This gem's own version — kept in lockstep with hypertabular.gemspec and the core's
   # rust/Cargo.toml.
-  VERSION = "0.7.0"
+  VERSION = "0.8.0"
 
   class << self
     # Whether the native core loaded and exports the ABI this binding was built against.
@@ -62,6 +68,8 @@ end
 require_relative "hypertabular/dialect"
 require_relative "hypertabular/column"
 require_relative "hypertabular/tabular_error"
+require_relative "hypertabular/header"
+require_relative "hypertabular/row"
 require_relative "hypertabular/batch"
 require_relative "hypertabular/delimited_reader"
 require_relative "hypertabular/workbook"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: hypertabular
 version: !ruby/object:Gem::Version
-  version: 0.7.0
+  version: 0.8.0
 platform: ruby
 authors:
 - Brian Buvinghausen
@@ -15,14 +15,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.7.0
+        version: 0.8.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.7.0
+        version: 0.8.0
 - !ruby/object:Gem::Dependency
   name: fiddle
   requirement: !ruby/object:Gem::Requirement
@@ -84,6 +84,7 @@ files:
 - lib/hypertabular/column.rb
 - lib/hypertabular/delimited_reader.rb
 - lib/hypertabular/dialect.rb
+- lib/hypertabular/header.rb
 - lib/hypertabular/native/linux-arm64/libhypertabular.so
 - lib/hypertabular/native/linux-musl-arm64/libhypertabular.so
 - lib/hypertabular/native/linux-musl-x64/libhypertabular.so
@@ -92,6 +93,7 @@ files:
 - lib/hypertabular/native/osx-x64/libhypertabular.dylib
 - lib/hypertabular/native/win-arm64/hypertabular.dll
 - lib/hypertabular/native/win-x64/hypertabular.dll
+- lib/hypertabular/row.rb
 - lib/hypertabular/runtime.rb
 - lib/hypertabular/runtime/columns.rb
 - lib/hypertabular/runtime/delimited.rb