hypertabular-wasm 1.0.0 → 1.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,283 @@
1
+ module HyperTabular
2
+ # How a sample is taken and read: DelimitedReader.suggest, Sheet#suggest. Declaring the locale
3
+ # here is what settles what a sample can't.
4
+ #
5
+ # +sample_rows+ is the most rows the sample holds, 0 taken as 1; it stops at 4096 rows of delimited
6
+ # text, and at a sheet's own batch size, read in as many batches as the core says fit: a sample is
7
+ # never refused for the size of its batch. +format+ reads every column's numbers
8
+ # in this HyperCast::NumFormat, which settles what "," and "." mean in them. +column_formats+ is
9
+ # per source column, ahead of +format+, the last given winning: a Hash or an Array of pairs, and
10
+ # every format given is judged first of anything, whether it's replaced or the sample ever reaches
11
+ # its ordinal. +date_order+ reads every column's dates in this order where the sample leaves the
12
+ # order open, as 01/02/2026 does, and +column_date_orders+ is per source column, ahead of it.
13
+ SuggestOptions = Data.define(:sample_rows, :format, :column_formats, :date_order, :column_date_orders) do
14
+ # ArgumentError for a negative count of rows or an entry that isn't [ordinal, value]; KeyError
15
+ # for an undeclared date order. A format the core can't honour is the suggest's to refuse.
16
+ def initialize(sample_rows: 1000, format: nil, column_formats: [], date_order: nil, column_date_orders: [])
17
+ raise ArgumentError, "sample_rows must be an Integer at least 0; got #{sample_rows.inspect}" unless
18
+ sample_rows.is_a?(Integer) && sample_rows >= 0
19
+
20
+ HyperCast::DATE_ORDERS.fetch(date_order) unless date_order.nil?
21
+ orders = SuggestOptions.pairs("column_date_orders", column_date_orders)
22
+ orders.each { |_ordinal, order| HyperCast::DATE_ORDERS.fetch(order) }
23
+ super(sample_rows: [sample_rows, 1].max, format: format, date_order: date_order, column_date_orders: orders,
24
+ column_formats: SuggestOptions.pairs("column_formats", column_formats))
25
+ end
26
+
27
+ # +entries+ as a frozen Array of [ordinal, value] pairs.
28
+ def self.pairs(field, entries)
29
+ entries.map do |entry|
30
+ raise ArgumentError, "#{field} must hold [ordinal, value] pairs; got #{entry.inspect}" unless
31
+ entry.is_a?(Array) && entry.size == 2 && entry[0].is_a?(Integer) && entry[0] >= 0
32
+
33
+ entry.dup.freeze
34
+ end.freeze
35
+ end
36
+
37
+ # The format declared for source column +ordinal+, or nil.
38
+ def declared_format(ordinal)
39
+ column_formats.reverse_each { |at, declared| return declared if at == ordinal }
40
+ format
41
+ end
42
+
43
+ # The date order declared for source column +ordinal+, or nil.
44
+ def declared_order(ordinal)
45
+ column_date_orders.reverse_each { |at, order| return order if at == ordinal }
46
+ date_order
47
+ end
48
+
49
+ # ArgumentError for something that isn't SuggestOptions, or for the first format given that the
50
+ # core would refuse, naming its ordinal: the first thing a suggest does, before any source is
51
+ # opened.
52
+ def self.judged(options)
53
+ raise ArgumentError, "options must be a HyperTabular::SuggestOptions; got #{options.inspect}" unless
54
+ options.is_a?(SuggestOptions)
55
+
56
+ options.check_formats
57
+ end
58
+
59
+ # ArgumentError for the first format given that the core would refuse, naming its ordinal.
60
+ def check_formats
61
+ declared = format.nil? ? column_formats : [[0, format], *column_formats]
62
+ declared.each do |ordinal, candidate|
63
+ Column.specs([Column.i32(0, candidate)])
64
+ rescue ArgumentError => e
65
+ raise ArgumentError, e.message.sub("plan column 0", "plan column #{ordinal}")
66
+ end
67
+ nil
68
+ end
69
+ end
70
+
71
+ # Reads one thousand rows, declaring nothing.
72
+ SuggestOptions::DEFAULT = SuggestOptions.new
73
+
74
+ # What a sample says of one source column.
75
+ #
76
+ # +ordinal+ is the zero-based source column, as a Column names it, and +name+ the header's name
77
+ # for it, or nil. +door+ is the door found (a key of DOORS), text when unresolved and under the
78
+ # first candidate when ambiguous, and +declared+ what that door declares. +format+ is the notation
79
+ # the plan reads a resolved numeric column in: the one declared for it, or else the one candidate
80
+ # the sample left, or otherwise HyperCast::NumFormat::INVARIANT; both of those are Western, so a
81
+ # later 1,23,456 is refused. nil for any other column. +candidates+ is what to choose between,
82
+ # empty unless ambiguous: date orders as HyperCast names them, or HyperCast::NumFormats. Declare
83
+ # one in SuggestOptions and ask again, since the door can differ under each. +status+ is how far
84
+ # the sample settles it: :resolved (one door and one declaration take every cell, and the plan
85
+ # reads the column through them), :ambiguous (every cell is read, but the sample can't say which
86
+ # declaration it's written in, as 1,234 can't) or :unresolved (nothing to go on, or a cell no door
87
+ # took beside cells one did). +matched+ is the cells +door+ took: resolved or ambiguous, all of
88
+ # +sampled+; unresolved, the most any one door but the text door took. +sampled+ is the cells that
89
+ # aren't blank.
90
+ SuggestedColumn = Data.define(:ordinal, :name, :door, :declared, :format, :candidates, :status, :matched, :sampled)
91
+
92
+ # What DelimitedReader.suggest, DelimitedReader.suggest_string and Sheet#suggest found.
93
+ #
94
+ # +plan+ is a frozen Array with a Column for each source column, in order, to change or to hand to
95
+ # a read: only a resolved column reads through its door, and the rest read as text, which refuses
96
+ # nothing and loses nothing. +report+ is a SuggestedColumn for each, in the plan's order.
97
+ # +truncated+ says whether the source has rows past the sample: a source with exactly the sample's
98
+ # rows hasn't.
99
+ Suggestion = Data.define(:plan, :report, :truncated)
100
+
101
+ # The sample, in the shape the core takes it, and what is made of the core's answer. Rust's
102
+ # suggest.rs is where this comes from.
103
+ class Sample
104
+ # The one notation a suggestion can name besides Western and what's declared.
105
+ COMMA_DECIMAL = HyperCast::NumFormat.new(decimal_sep: ",", group_sep: ".", flags: HyperCast::ALL_STYLES)
106
+
107
+ # What the core's status codes mean.
108
+ STATUSES = { 1 => :resolved, 2 => :ambiguous, 3 => :unresolved }.freeze
109
+
110
+ # The notation bits in an ambiguous number's param, and a resolved one's value.
111
+ NOTATIONS = { 2 => HyperCast::NumFormat::INVARIANT, 4 => COMMA_DECIMAL }.freeze
112
+
113
+ # A span holds a u32 offset. A sample that far along stops, and says it did.
114
+ MAX_BYTES = 0xFFFF_FFFF
115
+
116
+ class << self
117
+ # A delimited sample: the block opens a reader of the given batch size on the source, and is
118
+ # called twice for a source with no header, whose width is its first record's.
119
+ def delimited(dialect, options)
120
+ limit = [options.sample_rows, DelimitedReader::DEFAULT_BATCH_ROWS].min
121
+ width = nil
122
+ unless dialect.has_header
123
+ first = yield 1
124
+ begin
125
+ width = first.send(:first_width)
126
+ ensure
127
+ first.close
128
+ end
129
+ end
130
+ reader = yield 1
131
+ begin
132
+ width ||= reader.header.size
133
+ check_width(width)
134
+ sample = new(width, limit)
135
+ unless width.zero?
136
+ # One row more than the sample, so that a row past it costs no second batch, in as many
137
+ # batches as the core says that takes.
138
+ reader.send(:sample_in, Array.new(width) { |ordinal| Column.text(ordinal) }, limit + 1)
139
+ sample.read_from(reader)
140
+ end
141
+ sample.judge(reader.header, options)
142
+ ensure
143
+ reader.close
144
+ end
145
+ end
146
+
147
+ # The plan a sheet's sample is read through: a text column for each source column, and after
148
+ # them a UUID column for each, which takes only a text cell, so a typed cell says so.
149
+ def sheet_plan(width)
150
+ Array.new(width) { |ordinal| Column.text(ordinal) } + Array.new(width) { |ordinal| Column.uuid(ordinal) }
151
+ end
152
+
153
+ # ArgumentError for a source wider than a plan can say.
154
+ def check_width(width)
155
+ return if width <= Column::MAX_ORDINAL + 1
156
+
157
+ raise ArgumentError,
158
+ "plan column #{Column::MAX_ORDINAL + 1} cannot be honoured: the source has #{width} columns"
159
+ end
160
+ end
161
+
162
+ # A sample of +width+ columns and at most +limit+ rows, with +typed+ a sheet's marks.
163
+ def initialize(width, limit, typed: false)
164
+ @width = width
165
+ @limit = limit
166
+ @typed = typed ? "".b : nil
167
+ @bytes = "".b
168
+ @spans = Array.new(width) { [] }
169
+ @marks = Array.new(width) { "".b }
170
+ @rows = 0
171
+ @truncated = false
172
+ end
173
+
174
+ # Reads until the sample is whole and a row past it, or the end, says whether it's the source's
175
+ # last. A failure among the sampled rows is the caller's, and a failure just past them, of the
176
+ # source or of its structure, only says there's more.
177
+ def read_from(source)
178
+ until @truncated
179
+ begin
180
+ batch = source.read
181
+ rescue TabularError, IOError, SystemCallError
182
+ raise unless @rows == @limit
183
+
184
+ @truncated = true
185
+ break
186
+ end
187
+ return if batch.nil?
188
+
189
+ take(batch)
190
+ end
191
+ end
192
+
193
+ # Asks the core, and builds the plan and the report from its answer.
194
+ def judge(header, options)
195
+ declared = Array.new(@width) { |ordinal| options.declared_format(ordinal) }
196
+ formats = declared.map { |format| format.nil? ? Column::NO_FORMAT : format.packed }.join
197
+ cells = @spans.flatten.pack("L<*")
198
+ typed = @typed && @marks.join
199
+ found = Runtime.suggest(@bytes, cells, typed, @rows, @width, formats)
200
+ # Every format was checked and every span was made here.
201
+ raise ArgumentError, "plan column 0 cannot be honoured: the core refuses the sample" if found.nil?
202
+
203
+ columns = found.each_slice(5).with_index.map do |said, ordinal|
204
+ column_of(ordinal, header&.at(ordinal), declared[ordinal], options.declared_order(ordinal), *said)
205
+ end
206
+ Suggestion.new(plan: columns.map(&:first).freeze, report: columns.map(&:last).freeze, truncated: @truncated)
207
+ end
208
+
209
+ private
210
+
211
+ # Takes what the sample still wants of +batch+. A blank, a token and padding are all a blank
212
+ # span. A refused cell keeps its bytes, for the core's own text door to refuse.
213
+ def take(batch)
214
+ texts = Array.new(@width) { |column| batch.values(column) }
215
+ batch.rows.times do |row|
216
+ if @rows == @limit
217
+ @truncated = true
218
+ return
219
+ end
220
+ cells = Array.new(@width) { |column| texts[column][row] || refused(batch, column, row) }
221
+ if @bytes.bytesize + cells.sum(&:bytesize) > MAX_BYTES
222
+ @truncated = true
223
+ return
224
+ end
225
+ cells.each_with_index do |cell, column|
226
+ @spans[column] << @bytes.bytesize << cell.bytesize
227
+ @bytes << cell.b
228
+ end
229
+ mark(batch, row) if @typed
230
+ @rows += 1
231
+ end
232
+ end
233
+
234
+ # The bytes of a cell the text door refused: none for a blank.
235
+ def refused(batch, column, row)
236
+ batch.get(column, row).reason == :empty ? "" : batch.raw(column, row)
237
+ end
238
+
239
+ # A cell the UUID door refuses with no detail isn't text: it's typed.
240
+ def mark(batch, row)
241
+ @width.times do |column|
242
+ verdict = batch.get(@width + column, row)
243
+ typed = verdict.is_a?(HyperCast::Fault) && verdict.reason == :malformed && verdict.detail.nil?
244
+ @marks[column] << (typed ? 1 : 0)
245
+ end
246
+ end
247
+
248
+ # One column of the core's answer as a plan column and a report entry.
249
+ def column_of(ordinal, name, format, order, door, param, status, matched, sampled)
250
+ status = STATUSES.fetch(status, :unresolved)
251
+ candidates = status == :ambiguous ? candidates_of(door, param) : []
252
+ # An ambiguous date's param is a set: the door it names is the first of the set's orders.
253
+ said = Column.of_code(ordinal, door, status == :ambiguous ? lowest_bit(param) : param) || Column.text(ordinal)
254
+ # An order declared for a date the sample left open is the answer to its question.
255
+ if order && candidates.include?(order)
256
+ status = :resolved
257
+ candidates = []
258
+ said = Column.date_ordered(ordinal, order)
259
+ end
260
+ numeric = status == :resolved && Column::NUMERIC.include?(said.door)
261
+ planned = numeric ? format || (param == 4 ? COMMA_DECIMAL : HyperCast::NumFormat::INVARIANT) : nil
262
+ plan = status == :resolved ? said.with(format: planned) : Column.text(ordinal)
263
+ report = SuggestedColumn.new(ordinal: ordinal, name: name, door: said.door, declared: said.declared,
264
+ format: planned, candidates: candidates.freeze, status: status,
265
+ matched: matched, sampled: sampled)
266
+ [plan, report]
267
+ end
268
+
269
+ # What an ambiguous column's param offers: date orders for a date door, notations otherwise.
270
+ def candidates_of(door, param)
271
+ if [HyperTabular::DOORS.fetch(:date_ordered), HyperTabular::DOORS.fetch(:datetime)].include?(door)
272
+ HyperCast::DATE_ORDERS.select { |_order, code| param.anybits?(1 << code) }.keys
273
+ else
274
+ NOTATIONS.select { |bit, _format| param.anybits?(bit) }.values
275
+ end
276
+ end
277
+
278
+ # The lowest bit set in +param+, as its number.
279
+ def lowest_bit(param)
280
+ param.zero? ? 0 : (param & -param).bit_length - 1
281
+ end
282
+ end
283
+ end
@@ -23,12 +23,13 @@ module HyperTabular
23
23
  KINDS = {
24
24
  1 => :unclosed_quote, 2 => :column_count, 3 => :row_too_long, 16 => :not_a_zip, 17 => :container,
25
25
  18 => :encrypted, 19 => :method, 20 => :missing_part, 21 => :xml, 22 => :deflate,
26
- 23 => :not_a_workbook, 24 => :shared_string, 25 => :too_large, 26 => :iwa
26
+ 23 => :not_a_workbook, 24 => :shared_string, 25 => :too_large, 26 => :iwa, 27 => :encoding
27
27
  }.freeze
28
28
 
29
29
  # What is wrong: :unclosed_quote (the input ended inside a quoted cell), :column_count
30
30
  # (a record's cell count disagrees with the first record's), :row_too_long (a single
31
- # record is larger than DelimitedReader::MAX_ROW_BYTES); for a workbook :not_a_zip,
31
+ # record is larger than DelimitedReader::MAX_ROW_BYTES), :encoding (the input holds a unit
32
+ # its declared Dialect encoding has no character for); for a workbook :not_a_zip,
32
33
  # :container (the zip's own structure is broken), :encrypted, :method (a part is
33
34
  # compressed by neither stored nor deflate), :missing_part, :xml (a part ends inside an
34
35
  # XML construct), :deflate (a part is not a whole deflate stream), :not_a_workbook,
@@ -46,7 +47,9 @@ module HyperTabular
46
47
  # One-based line the offending record starts on.
47
48
  attr_reader :line
48
49
 
49
- # Absolute byte offset of the offending record's start, a byte-order mark included.
50
+ # Absolute byte offset of the offending record's start, a byte-order mark included, in the
51
+ # decoded text under a declared encoding. For :encoding alone it is the unit's offset in the
52
+ # original input.
50
53
  attr_reader :byte
51
54
 
52
55
  # Cells in the first record, for :column_count; 0 otherwise.
@@ -86,6 +89,9 @@ module HyperTabular
86
89
  case kind
87
90
  when :column_count then "Record #{at} has #{found} cells; the first record had #{expected}."
88
91
  when :unclosed_quote then "The input ended inside a quoted cell in record #{at}."
92
+ when :encoding
93
+ "Record #{record} (line #{line}) holds a unit its declared encoding has no character for, " \
94
+ "at byte #{byte} of the input."
89
95
  when :row_too_long then "Record #{at} exceeds the #{DelimitedReader::MAX_ROW_BYTES}-byte row ceiling."
90
96
  when :not_a_zip then "The workbook is not a zip file."
91
97
  when :encrypted then "The workbook is encrypted."
@@ -3,19 +3,83 @@ module HyperTabular
3
3
  # hides it. A hidden sheet reads like any other.
4
4
  SheetInfo = Data.define(:name, :hidden)
5
5
 
6
+ # A rectangle of a sheet to read, as a 1-based row and column on each side, 0 being no limit on
7
+ # that side. A plan's ordinal 0 is its first column; Batch#line and Problem#source_column stay
8
+ # the sheet's own. A range past the sheet's end invents no rows.
9
+ #
10
+ # HyperTabular::Range.parse("A5:F200")
11
+ # HyperTabular::Range.new(first_row: 5, first_column: 1, last_row: 0, last_column: 6)
12
+ Range = Data.define(:first_row, :first_column, :last_row, :last_column) do
13
+ # ArgumentError for a side that isn't a count, or one whose first is past its last.
14
+ def initialize(first_row: 0, first_column: 0, last_row: 0, last_column: 0)
15
+ [[first_row, last_row, "row"], [first_column, last_column, "column"]].each do |first, last, side|
16
+ Declared.count("first #{side}", first)
17
+ Declared.count("last #{side}", last)
18
+ raise ArgumentError, "the range's first #{side} #{first} is past its last, #{last}" if
19
+ first.positive? && last.positive? && first > last
20
+ end
21
+ super
22
+ end
23
+
24
+ # The range +text+ says, in the spreadsheet's own spelling: capitals, both corners, the first
25
+ # not past the last, as "A5:F200". ArgumentError for anything else.
26
+ def self.parse(text)
27
+ raise ArgumentError, "a range is a String; got #{text.inspect}" unless text.is_a?(String)
28
+
29
+ corners = Runtime.range_parse(text)
30
+ raise ArgumentError, "#{text.inspect} is not a range such as A5:F200" if corners.nil?
31
+
32
+ new(first_row: corners[0], first_column: corners[1], last_row: corners[2], last_column: corners[3])
33
+ end
34
+ end
35
+
6
36
  # How a sheet is read: whether its first row is a header (exposed through Sheet#header
7
- # and never delivered as a row), whether a row with no cells is skipped, and the most rows
8
- # a batch holds.
9
- SheetOptions = Data.define(:has_header, :skip_empty_rows, :batch_rows) do
10
- # Every option has a default; ArgumentError unless +batch_rows+ is a positive Integer.
11
- def initialize(has_header: true, skip_empty_rows: true, batch_rows: DelimitedReader::DEFAULT_BATCH_ROWS)
12
- raise ArgumentError, "batch_rows must be a positive Integer; got #{batch_rows.inspect}" unless
13
- batch_rows.is_a?(Integer) && batch_rows.positive?
37
+ # and never delivered as a row), whether an empty row is skipped, and the most rows a batch
38
+ # holds.
39
+ #
40
+ # A row of only formulas with nothing cached counts as empty, so +skip_empty_rows+ filters it
41
+ # by default: `skip_empty_rows: false` keeps every row. +skip+ is how many rows to pass over at
42
+ # the range's start, empty ones included, their cells not judged. +header_row+ is how many rows
43
+ # to read and discard after those, counted after the empty-row filter. +range+ is the Range to
44
+ # read, or nil for the whole sheet. +tokens+ is what stands for no value in a text cell of every
45
+ # column without tokens of its own. +notes+, on by default, is whether each cell's detail and
46
+ # origin are kept: off, a Fault has no detail, Batch#origin says :cell, and Batch#faults lists
47
+ # no uncached formula.
48
+ SheetOptions = Data.define(:has_header, :skip_empty_rows, :batch_rows, :skip, :header_row, :range, :tokens,
49
+ :notes) do
50
+ # Every option has a default; ArgumentError unless +skip+ and +header_row+ are counts, +range+
51
+ # a Range or nil and +tokens+ an Array of Strings. The core judges +batch_rows+ when the sheet
52
+ # is opened.
53
+ def initialize(has_header: true, skip_empty_rows: true, batch_rows: DelimitedReader::DEFAULT_BATCH_ROWS,
54
+ skip: 0, header_row: 0, range: nil, tokens: [], notes: true)
55
+ raise ArgumentError, "range must be a HyperTabular::Range; got #{range.inspect}" unless
56
+ range.nil? || range.is_a?(Range)
57
+
58
+ super(has_header: has_header, skip_empty_rows: skip_empty_rows, batch_rows: batch_rows,
59
+ skip: Declared.count("skip", skip), header_row: Declared.count("header_row", header_row), range: range,
60
+ tokens: Declared.tokens(tokens), notes: notes ? true : false)
61
+ end
14
62
 
15
- super
63
+ # The 36 bytes of the core's RawSheetOptions.
64
+ def packed_with
65
+ [SheetOptions::OPTIONS_BYTES, has_header ? 1 : 0, skip_empty_rows ? 1 : 0, skip, header_row,
66
+ range&.first_row.to_i, range&.first_column.to_i, range&.last_row.to_i, range&.last_column.to_i].pack("L<9")
67
+ end
68
+
69
+ # The tokens as the core takes them, or nil for none.
70
+ def packed_tokens
71
+ tokens.empty? ? nil : Declared.packed_tokens(tokens)
72
+ end
73
+
74
+ # The source column a plan's ordinal 0 is: the range's first, A being 0.
75
+ def first_column
76
+ [range&.first_column.to_i - 1, 0].max
16
77
  end
17
78
  end
18
79
 
80
+ # The size of SheetOptions#packed_with: what RawSheetOptions' first word carries.
81
+ SheetOptions::OPTIONS_BYTES = 36
82
+
19
83
  # A header, empty rows skipped, DelimitedReader::DEFAULT_BATCH_ROWS rows a batch.
20
84
  SheetOptions::DEFAULT = SheetOptions.new
21
85
 
@@ -123,8 +187,14 @@ module HyperTabular
123
187
  # to become an Integer — and a text cell goes through the door as delimited text would. A
124
188
  # sheet that is structurally broken raises a TabularError after every intact row before
125
189
  # the break has been delivered, and the same error again on every later read.
190
+ #
191
+ # A sheet is called into once at a time, as a DelimitedReader is: a call back into it from a
192
+ # plan's #each while it binds raises RuntimeError naming it busy. An exception that lands in a
193
+ # read (Timeout.timeout, Thread#raise, Ctrl-C's Interrupt) waits until the core's step and the
194
+ # sheet's own state agree, and a batch it lands on is handed over by the next #read.
126
195
  class Sheet
127
196
  include Enumerable
197
+ include Guarded
128
198
 
129
199
  # The SheetOptions the sheet is read with.
130
200
  attr_reader :options
@@ -142,19 +212,22 @@ module HyperTabular
142
212
  raise ArgumentError, "options must be a HyperTabular::SheetOptions; got #{options.inspect}" unless
143
213
  options.is_a?(SheetOptions)
144
214
 
215
+ Runtime.check_sizes([], options.batch_rows, 1, Runtime.batch_flags(options.notes, false, sheet: true))
145
216
  planned = Column.plan(plan) unless plan.nil?
217
+ specs = Column.specs(planned) if planned
146
218
  @book = book
219
+ @entry = sheet
147
220
  @options = options
148
221
  @plan = UNBOUND
149
- @reading = Runtime::Book::Reading.new(book, sheet, options.has_header, options.skip_empty_rows,
150
- options.batch_rows)
222
+ @reading = Runtime::Book::Reading.new(book, sheet, options.packed_with, options.batch_rows, options.packed_tokens)
151
223
  # A plan handed over here is bound before the header is read, as #bind would bind it;
152
224
  # without one the header row is read into slots enough for every cell it has, and
153
225
  # binding later keeps them (a row the sheet repeats is delivered from them again).
154
- bind_reading(planned) if planned
226
+ bind_reading(planned, specs) if planned
155
227
  @header = options.has_header ? Header.new(@reading.read_header).freeze : nil
156
228
  @pending = nil
157
229
  @failure = nil
230
+ @handing = @in_flight = nil
158
231
  rescue Runtime::Book::StructureError => e
159
232
  raise TabularError.from(e.failure)
160
233
  end
@@ -163,13 +236,18 @@ module HyperTabular
163
236
  # Columns, in output order, typically built from the #header's ordinals — once, before
164
237
  # the first read. Returns the sheet.
165
238
  #
166
- # ArgumentError for a plan that is not Columns, which leaves the sheet unbound;
167
- # RuntimeError if the sheet already has a plan.
239
+ # ArgumentError for a plan that is not Columns or that the core refuses, which leaves the
240
+ # sheet unbound; RuntimeError if the sheet already has a plan, and from inside one of this
241
+ # sheet's own calls (busy).
168
242
  def bind(plan)
169
- raise "the sheet already has a plan: a plan is bound once" if bound?
243
+ exclusive do
244
+ raise "the sheet already has a plan: a plan is bound once" if bound?
170
245
 
171
- bind_reading(Column.plan(plan))
172
- self
246
+ plan = Column.plan(plan)
247
+ specs = Column.specs(plan)
248
+ atomically { bind_reading(plan, specs) }
249
+ self
250
+ end
173
251
  end
174
252
 
175
253
  # Whether a plan has been bound: always, for a sheet opened with one.
@@ -178,39 +256,55 @@ module HyperTabular
178
256
  end
179
257
 
180
258
  # Reads the next batch: a Batch of up to the options' batch_rows rows, or nil once the
181
- # sheet has no more. RuntimeError before a plan is bound, which #bind then cures.
259
+ # sheet has no more. RuntimeError before a plan is bound, which #bind then cures, and from
260
+ # inside one of this sheet's own calls (busy).
182
261
  def read
183
- raise "the sheet has no plan yet: bind one before reading" unless bound?
262
+ handing_out do
263
+ raise "the sheet has no plan yet: bind one before reading" unless bound?
264
+ next hand_over if @handing
184
265
 
185
- if @pending
186
- @failure = @pending
187
- @pending = nil
188
- end
189
- raise @failure if @failure
190
-
191
- rows, cells, arena, failure = @reading.fill
192
- if failure
193
- broken = TabularError.from(failure)
194
- raise @failure = broken if rows.zero?
266
+ if @pending
267
+ @failure = @pending
268
+ @pending = nil
269
+ end
270
+ raise @failure if @failure
195
271
 
196
- @pending = broken
272
+ atomically { step } ? hand_over : nil
197
273
  end
198
- return nil if rows.zero?
274
+ end
199
275
 
200
- columns = @reading.columns
201
- values = Array.new(@plan.size) { |column| columns.values(column, rows) }
202
- Batch.new(@plan, rows, values, Array.new(@plan.size) { |column| columns.verdicts(column, rows) },
203
- cells, @reading.per_row, @book.strings, 0, arena, workbook: true)
276
+ # Offers a plan for this sheet from a sample, and applies nothing: a Suggestion to inspect,
277
+ # change and hand to a read. It opens the sheet again, so what has been read of this one
278
+ # doesn't matter. The options' batch_rows caps +options+' sample_rows, and the rows are read in
279
+ # as many batches as the core says fit. A typed number has no notation to ask about, so it reads
280
+ # by its value, whichever is declared; a sheet's date column suggests text. A format the core would refuse is an
281
+ # ArgumentError before anything is read, and a structural failure among the sampled rows a
282
+ # TabularError.
283
+ def suggest(options = SuggestOptions::DEFAULT)
284
+ exclusive do
285
+ SuggestOptions.judged(options)
286
+ limit = [options.sample_rows, @options.batch_rows].min
287
+ # Notes on whatever this sheet says, for what the sample's second door says of a cell.
288
+ read = @options.with(notes: true, batch_rows: 1)
289
+ open = ->(opening) { Sheet.new(@book, @entry, opening, nil) }
290
+ width = read.has_header ? nil : open.call(read).first_width
291
+ sheet = open.call(read)
292
+ width ||= sheet.header.size
293
+ Sample.check_width(width)
294
+ # One row more than the sample, so that a row past it costs no second batch, in as many batches
295
+ # as the core says that takes.
296
+ sheet.sample_in(Sample.sheet_plan(width), limit + 1) unless width.zero?
297
+ sample = Sample.new(width, limit, typed: true)
298
+ sample.read_from(sheet) unless width.zero?
299
+ sample.judge(sheet.header, options)
300
+ end
204
301
  end
205
302
 
206
303
  # Every remaining batch. Without a block, an Enumerator.
207
304
  def each_batch
208
305
  return to_enum(:each_batch) unless block_given?
209
306
 
210
- while (batch = read)
211
- yield batch
212
- end
213
- self
307
+ batches { |batch| yield batch }
214
308
  end
215
309
 
216
310
  # Every remaining row, batch after batch, as a Row — which, its batch being a copy,
@@ -219,10 +313,7 @@ module HyperTabular
219
313
  def each(&block)
220
314
  return to_enum(:each) unless block
221
315
 
222
- while (batch = read)
223
- batch.each(&block)
224
- end
225
- self
316
+ batches { |batch| batch.each(&block) }
226
317
  end
227
318
 
228
319
  # The sheet in a line.
@@ -230,17 +321,66 @@ module HyperTabular
230
321
  "#<#{self.class.name} columns=#{@plan.size}#{' unbound' unless bound?}>"
231
322
  end
232
323
 
324
+ # A first read's one text column, one row a batch, and the cells that row had: how a suggestion
325
+ # learns a headerless sheet's width. 0 for a sheet with no row.
326
+ protected def first_width
327
+ plan = [Column.text(0)]
328
+ bind_reading(plan, Column.specs(plan), widths: true)
329
+ read.nil? ? 0 : @reading.columns.widths(1).unpack1("L<")
330
+ end
331
+
233
332
  private
234
333
 
235
334
  # The plan of a sheet that has none yet.
236
335
  UNBOUND = [].freeze
237
336
  private_constant :UNBOUND
238
337
 
239
- # Sizes the reading's arrays for +plan+ (already checked to be Columns) and takes it.
240
- def bind_reading(plan)
338
+ # What a sampler reads this sheet in: batches of as many rows as the core says fit +wanted+.
339
+ protected def sample_in(plan, wanted)
340
+ flags = Runtime.batch_flags(@options.notes, false, sheet: true)
341
+ @options = @options.with(batch_rows: Runtime.sample_rows(Column.specs(plan), wanted, flags))
342
+ bind(plan)
343
+ end
344
+
345
+ # The noun the busy and spoiled messages name.
346
+ def noun = "sheet"
347
+
348
+ # One fill and the batch made of it, inside the wait for asynchronous exceptions: true with the
349
+ # batch held in @handing, or false once the sheet has no more. The core can't be asked again for
350
+ # rows it has gone past, so an exception raised along the way is kept as the sheet's failure.
351
+ def step
352
+ rows, cells, arena, failure = @reading.fill
353
+ if failure
354
+ broken = TabularError.from(failure)
355
+ raise @failure = broken if rows.zero?
356
+
357
+ @pending = broken
358
+ end
359
+ return false if rows.zero?
360
+
361
+ columns = @reading.columns
362
+ values = Array.new(@plan.size) { |column| columns.values(column, rows) }
363
+ notes = @options.notes ? Array.new(@plan.size) { |column| columns.notes(column, rows) } : nil
364
+ @handing = Batch.new(@plan, rows, values, Array.new(@plan.size) { |column| columns.verdicts(column, rows) },
365
+ cells, @reading.per_row, @book.strings, 0, arena,
366
+ workbook: true, notes: notes, checks: Batch.checks_of(@plan, columns, rows),
367
+ first_column: @options.first_column)
368
+ true
369
+ rescue Exception => e
370
+ unless e.equal?(@failure)
371
+ @pending = nil
372
+ @failure = spoiled(e)
373
+ end
374
+ raise
375
+ end
376
+
377
+ # Sizes the reading's arrays for +plan+ (already checked to be Columns) and takes it, keeping
378
+ # each row's width if a caller here wants it.
379
+ def bind_reading(plan, specs, widths: false)
241
380
  # Slots the core assembles a row in: one for every source column the plan reaches.
242
381
  width = (plan.map(&:ordinal).max || -1) + 1
243
- @reading.bind(plan.map(&:packed), plan.map(&:value_bytes), width)
382
+ Runtime.check_sizes(specs, @options.batch_rows, 1, Runtime.batch_flags(@options.notes, widths, sheet: true))
383
+ @reading.bind(specs, plan.map(&:value_bytes), width, @options.notes, widths)
244
384
  @plan = plan
245
385
  end
246
386
  end