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.
@@ -1,4 +1,19 @@
1
1
  module HyperTabular
2
+ # One thing that went wrong in a Batch: an entry of Batch#faults.
3
+ #
4
+ # +row+ is the row in the batch, from zero. +line+ is where it came from, Batch#line.
5
+ # +plan_column+ is the column of the plan, and +source_column+ the column in the source, from
6
+ # zero (for delimited text the plan column's ordinal, for a sheet its own column, A being 0,
7
+ # wherever the range starts), each nil for an entry about the row as a whole. +reason+ is the
8
+ # verdict's: :malformed, :out_of_range, or :empty for a formula with no cached value, and nil
9
+ # for a violation or an entry about the row as a whole. +detail+ is what failed in the cell, a
10
+ # HyperCast::Detail or nil. +origin+ is where the verdict came from, Batch#origin. +offset+ and
11
+ # +length+ are the fault's or the violation's span in the characters String#[] slices the cell's
12
+ # text by, 0 where there is none, and +expected+ and +found+ a long row's widths, otherwise 0.
13
+ # +keyword+ is the HyperCast::Keyword a violation broke, and nil for anything else.
14
+ Problem = Data.define(:row, :line, :plan_column, :source_column, :reason, :detail, :origin, :offset, :length,
15
+ :expected, :found, :keyword)
16
+
2
17
  # The rows one DelimitedReader#read or Sheet#read delivered, as typed columns: the same
3
18
  # class for delimited text and for a sheet of a workbook.
4
19
  #
@@ -12,8 +27,15 @@ module HyperTabular
12
27
  # end
13
28
  # end
14
29
  #
30
+ # A column that declares HyperCast::Constraints is read with #get_checked, which says what
31
+ # passed (a HyperCast::Checked), what broke a rule (a HyperCast::Violation) and what didn't cast
32
+ # (a HyperCast::Fault). #get and #verdicts would read a violation as passed, so they raise
33
+ # TypeError for one; #values holds a violation's value as cast.
34
+ #
15
35
  # A batch owns what it shows — the arrays the core wrote are copied out of the reader's
16
- # buffers as it is made — so it stays good after the reader has moved on. Values are
36
+ # buffers as it is made — so it stays good after the reader has moved on, and so do its rows
37
+ # and its #faults. A Fault carries the HyperCast::Detail of what failed in the cell, and #origin
38
+ # says where a verdict came from. Values are
17
39
  # HyperCast's gem's own for the same doors: true/false, Integer, Float, HyperCast::Decimal,
18
40
  # a hyphenated UUID String, a UTC Time, Date, DateTime, Integer nanoseconds since midnight,
19
41
  # Rational seconds, and a UTF-8 String for text.
@@ -25,9 +47,13 @@ module HyperTabular
25
47
  class Batch
26
48
  include Enumerable
27
49
 
28
- # The verdict of every cell that had no bytes at all: one shared, frozen Fault.
50
+ # The verdict of every cell that had no bytes at all in a read with notes off: one shared,
51
+ # frozen Fault.
29
52
  EMPTY = HyperCast::Fault.new(reason: :empty, offset: 0, length: 0)
30
53
 
54
+ # The same in a read with notes on, which says it was blank: one shared, frozen Fault.
55
+ BLANK = HyperCast::Fault.new(reason: :empty, offset: 0, length: 0, detail: HyperCast::Detail::BLANK)
56
+
31
57
  # The doors whose column is one String#unpack directive away from its values: HyperCast's
32
58
  # directive for one value, repeated down the column.
33
59
  SCALARS = HyperCast::Interop::SCALARS.transform_values { |directive| "#{directive}*" }.freeze
@@ -44,8 +70,13 @@ module HyperTabular
44
70
 
45
71
  # Made by a reader from what the core just wrote, copied: +values+ and +verdicts+ per
46
72
  # plan column, the cell table (+per_row+ spans a row), what an unflagged span indexes
47
- # (+base+, from +origin+) and what a flagged one does (+arena+).
48
- def initialize(plan, rows, values, verdicts, cells, per_row, base, origin, arena, workbook:)
73
+ # (+base+, from +origin+) and what a flagged one does (+arena+). +notes+ is each column's
74
+ # CellNote array, or nil with notes off, +checks+ each column's RawCheck array (nil for an
75
+ # unconstrained column) or nil for a plan that declares no constraints, +widths+ the row widths
76
+ # of a read that reports long rows, with the +expected+ width and the +long_rows+ code, and
77
+ # +first_column+ the source column a plan's ordinal 0 is.
78
+ def initialize(plan, rows, values, verdicts, cells, per_row, base, origin, arena, workbook:, notes: nil,
79
+ checks: nil, widths: nil, expected: 0, long_rows: 0, first_column: 0)
49
80
  @columns = plan
50
81
  @rows = rows
51
82
  @bytes = values
@@ -56,9 +87,24 @@ module HyperTabular
56
87
  @origin = origin
57
88
  @arena = arena.force_encoding(Encoding::UTF_8)
58
89
  @workbook = workbook
90
+ @notes = notes
91
+ @checks = checks
92
+ @widths = widths
93
+ @expected = expected
94
+ @long_rows = long_rows
95
+ @first_column = first_column
59
96
  @values = Array.new(plan.size)
60
97
  @verdicts = Array.new(plan.size)
61
- @faults = Array.new(plan.size)
98
+ @checked_verdicts = Array.new(plan.size)
99
+ @words = Array.new(plan.size)
100
+ end
101
+
102
+ # What a reader hands a Batch as +checks+: each column's RawCheck array for its first +rows+ rows,
103
+ # from the runtime's +columns+, or nil for a plan that declares no constraints.
104
+ def self.checks_of(plan, columns, rows)
105
+ return nil unless plan.any?(&:checked?)
106
+
107
+ Array.new(plan.size) { |column| columns.checks(column, rows) }
62
108
  end
63
109
 
64
110
  # Where row +row+ came from: for delimited text the 1-based line its record starts on,
@@ -69,17 +115,28 @@ module HyperTabular
69
115
  end
70
116
 
71
117
  # A column's values, one per row, as a frozen Array: the Ruby value HyperCast's gem
72
- # returns from the same door, and nil for a cell that did not cast. Decoded in one pass
73
- # the first time it is asked for.
118
+ # returns from the same door, and nil for a cell that did not cast. A cell of a constrained
119
+ # column that broke a rule cast, so its value is here as cast, never rounded. Decoded in one
120
+ # pass the first time it is asked for.
74
121
  def values(column)
75
122
  @values[column] ||= decode(@columns.fetch(column), column)
76
123
  end
77
124
 
78
125
  # A column's verdicts, one per row, as a frozen Array of HyperCast::Success and
79
126
  # HyperCast::Fault. A Fault's span is in the units String#[] slices by on the cell's own
80
- # text, as HyperCast's are: `raw(column, row)[offset, length]` is the offending text.
127
+ # text, as HyperCast's are: `raw(column, row)[offset, length]` is the offending text. TypeError
128
+ # for a column that declares constraints: read it with #checked_verdicts.
81
129
  def verdicts(column)
82
- @verdicts[column] ||= judge(column)
130
+ @verdicts[column] ||= judge(unchecked(column))
131
+ end
132
+
133
+ # A column's verdicts as HyperCast's checked door judges them, one per row, as a frozen Array:
134
+ # each cell as #get_checked reads it. Any column can be read this way, a constrained one and
135
+ # one that declares nothing alike. Built in one pass the first time it is asked for.
136
+ # IndexError for a column outside the plan.
137
+ def checked_verdicts(column)
138
+ @columns.fetch(column)
139
+ @checked_verdicts[column] ||= Array.new(@rows) { |row| get_checked(column, row) }.freeze
83
140
  end
84
141
 
85
142
  # The cell at (+column+, +row+) as HyperCast judged it — made for `case`/`in`:
@@ -91,13 +148,54 @@ module HyperTabular
91
148
  # end
92
149
  #
93
150
  # Only this cell's verdict is built. IndexError for a column outside the plan or a row
94
- # outside the batch.
151
+ # outside the batch, and TypeError for a column that declares constraints: read it with
152
+ # #get_checked.
95
153
  def get(column, row)
154
+ unchecked(column)
96
155
  index = at(row)
97
156
  judged = @verdicts[column]
98
157
  return judged[index] if judged
99
158
 
100
- cell(column, index, values(column), faults(column))
159
+ cell(column, index, values(column), verdict_words(column))
160
+ end
161
+
162
+ # The cell at (+column+, +row+) as HyperCast's checked door judges it — made for `case`/`in`:
163
+ #
164
+ # case batch.get_checked(0, row)
165
+ # in HyperCast::Checked(value:) then value
166
+ # in HyperCast::Violation(keyword:, value:) then warn "#{value} breaks #{keyword}"
167
+ # in HyperCast::Fault(reason:) then warn reason.to_s
168
+ # end
169
+ #
170
+ # A HyperCast::Checked when the cell cast and met every constraint its column declares:
171
+ # +adjusted+ when a multiple_of rounding changed the value, and for a text enum match the entry
172
+ # as declared, the very String the Constraints holds, with its +enum_index+. A
173
+ # HyperCast::Violation when it cast and broke one: the Keyword, the value as cast, and the span
174
+ # of the judged text. A HyperCast::Fault when it didn't cast, as #get says it. A column that
175
+ # declares none is read too: every cell that cast passes, unadjusted. IndexError for a column
176
+ # outside the plan or a row outside the batch.
177
+ def get_checked(column, row)
178
+ plan = @columns.fetch(column)
179
+ index = at(row)
180
+ faults = verdict_words(column)
181
+ reason = faults.nil? ? 0 : faults[index * 3 + 2]
182
+ unless reason.zero? || reason == VIOLATION
183
+ return fault(column, index, reason, faults[index * 3], faults[index * 3 + 1])
184
+ end
185
+
186
+ value = values(column)[index]
187
+ return HyperCast::Checked.new(value: value, adjusted: false, enum_index: nil) unless plan.checked?
188
+
189
+ keyword, adjusted, enum_index = @checks.fetch(column).unpack("L<3", offset: index * CHECK_BYTES)
190
+ if reason == VIOLATION
191
+ offset, length = span(column, index, faults[index * 3], faults[index * 3 + 1])
192
+ return HyperCast::Violation.new(keyword: HyperCast::Keyword.new(code: keyword), value: value,
193
+ offset: offset, length: length)
194
+ end
195
+
196
+ enum_index = nil if enum_index == NO_ENTRY
197
+ value = plan.constraints.enum.fetch(enum_index) if enum_index && plan.door == :text
198
+ HyperCast::Checked.new(value: value, adjusted: adjusted != 0, enum_index: enum_index)
101
199
  end
102
200
 
103
201
  # The text the cell at (+column+, +row+) was cast from, whatever its door and whatever
@@ -117,6 +215,30 @@ module HyperTabular
117
215
  Runtime.unescape(quoted).force_encoding(Encoding::UTF_8)
118
216
  end
119
217
 
218
+ # Where the verdict of the cell at (+column+, +row+) came from: :cell, a door judged the cell's
219
+ # own text; :token, its exact unquoted bytes are a declared token, so it is :empty and no door
220
+ # ran; :padded, the row has no such cell; or :uncached, a workbook's formula with no cached
221
+ # value, :empty with no door run. With notes off, always :cell. IndexError for a column outside
222
+ # the plan or a row outside the batch.
223
+ def origin(column, row)
224
+ @columns.fetch(column)
225
+ index = at(row)
226
+ return :cell if @notes.nil?
227
+
228
+ ORIGINS.fetch(@notes.fetch(column).unpack1("S<", offset: index * NOTE_BYTES + 2))
229
+ end
230
+
231
+ # Everything wrong in this batch, by row then column, a row's entry first: a frozen Array of
232
+ # Problem. Listed: :malformed and :out_of_range cells, a workbook's formulas with no cached
233
+ # value, and long rows a :report dialect cut. Not listed: blanks, tokens, padding, or a row
234
+ # :truncate cut. With notes off a refused cell has no detail and an uncached formula isn't
235
+ # listed. A row the empty-row filter dropped can't be named. Made the first time it is asked
236
+ # for, from what the batch holds, so a read nobody asks this of pays nothing for it, and a
237
+ # batch kept past the next read answers for itself.
238
+ def faults
239
+ @problems ||= listed
240
+ end
241
+
120
242
  # Yields a Row for each row of the batch, in order, and returns the batch; without a
121
243
  # block, an Enumerator.
122
244
  def each
@@ -138,6 +260,71 @@ module HyperTabular
138
260
 
139
261
  private
140
262
 
263
+ # Bytes in one CellNote: a detail code and an origin code, two u16s.
264
+ NOTE_BYTES = 4
265
+ # Bytes in one RawProblem.
266
+ PROBLEM_BYTES = 36
267
+ # Bytes in one RawCheck: the keyword, adjusted and the enum index, three u32s.
268
+ CHECK_BYTES = 12
269
+ # The reason a verdict carries for a cell that cast and broke a declared constraint.
270
+ VIOLATION = 4
271
+ # A RawCheck's enum index when no text enum entry matched.
272
+ NO_ENTRY = 0xFFFF_FFFF
273
+ # What each origin code in a CellNote means.
274
+ ORIGINS = %i[cell token padded uncached].freeze
275
+ private_constant :NOTE_BYTES, :PROBLEM_BYTES, :CHECK_BYTES, :VIOLATION, :NO_ENTRY, :ORIGINS
276
+
277
+ # What the core lists for this batch, as Problems.
278
+ def listed
279
+ raw = Runtime.faults(@verdict_bytes, @notes, @checks, @rows, @widths, @expected, @long_rows)
280
+ Array.new(raw.bytesize / PROBLEM_BYTES) do |entry|
281
+ problem(*raw.unpack("L<3S<2L<5", offset: entry * PROBLEM_BYTES))
282
+ end.freeze
283
+ end
284
+
285
+ # One RawProblem as a Problem: the source column worked out, the span moved to characters.
286
+ def problem(row, plan_column, reason, detail, origin, offset, length, expected, found, keyword)
287
+ whole_row = plan_column == ROW_LEVEL
288
+ offset, length = span(plan_column, row, offset, length) unless whole_row
289
+ Problem.new(row: row, line: line(row), plan_column: whole_row ? nil : plan_column,
290
+ source_column: whole_row ? nil : @columns.fetch(plan_column).ordinal + @first_column,
291
+ reason: HyperCast::REASONS[reason], detail: detail.zero? ? nil : HyperCast::Detail.of(detail),
292
+ origin: ORIGINS.fetch(origin), offset: offset, length: length, expected: expected, found: found,
293
+ keyword: keyword.zero? ? nil : HyperCast::Keyword.new(code: keyword))
294
+ end
295
+
296
+ # A span the core counts in bytes of the cell's text, in the characters String#[] slices it
297
+ # by — an identity unless the text has a multi-byte character.
298
+ def span(column, row, offset, length)
299
+ return [offset, length] if offset.zero? && length.zero?
300
+
301
+ HyperCast::Interop.characters(raw(column, row), offset, length)
302
+ end
303
+
304
+ # +column+, or TypeError for a column that declares constraints, which a reader of verdicts
305
+ # without them would read a violation of as passed.
306
+ def unchecked(column)
307
+ return column unless @columns.fetch(column).checked?
308
+
309
+ raise TypeError, "column #{column} declares constraints: read it with get_checked"
310
+ end
311
+
312
+ # The verdict of the cell at (+column+, +row+) as its column is read: #get_checked's for a
313
+ # column that declares constraints, #get's for one that doesn't. Row#to_a and
314
+ # DelimitedReader#each_row read with it.
315
+ def verdict_of(column, row)
316
+ @columns.fetch(column).checked? ? get_checked(column, row) : get(column, row)
317
+ end
318
+
319
+ # A column's verdicts as #verdict_of reads them.
320
+ def verdicts_of(column)
321
+ @columns.fetch(column).checked? ? checked_verdicts(column) : verdicts(column)
322
+ end
323
+
324
+ # The plan column of an entry about the row as a whole.
325
+ ROW_LEVEL = 0xFFFF_FFFF
326
+ private_constant :ROW_LEVEL
327
+
141
328
  # The bytes a span names: in the arena when it is flagged, in the base when not.
142
329
  def slice(offset, length)
143
330
  return @arena.byteslice(offset, length & Runtime::Delimited::SPAN_LENGTH) if length >= Runtime::Delimited::SPAN_FLAG
@@ -155,11 +342,11 @@ module HyperTabular
155
342
  # A column's verdict array as the core wrote it — offset, length, reason per row, flat
156
343
  # — or nil when every cell cast, which one pass over the bytes answers without
157
344
  # unpacking anything.
158
- def faults(index)
159
- flat = @faults[index]
345
+ def verdict_words(index)
346
+ flat = @words[index]
160
347
  if flat.nil?
161
348
  bytes = @verdict_bytes.fetch(index)
162
- flat = @faults[index] = bytes.count("\0") == bytes.bytesize ? false : bytes.unpack("L<*")
349
+ flat = @words[index] = bytes.count("\0") == bytes.bytesize ? false : bytes.unpack("L<*")
163
350
  end
164
351
  flat || nil
165
352
  end
@@ -169,18 +356,18 @@ module HyperTabular
169
356
  def decode(column, index)
170
357
  door = column.door
171
358
  bytes = @bytes.fetch(index)
172
- faults = faults(index)
359
+ faults = verdict_words(index)
173
360
  if (directive = SCALARS[door])
174
361
  values = bytes.unpack(directive)
175
362
  values.map! { |byte| byte != 0 } if door == :bool
176
- @rows.times { |row| values[row] = nil unless faults[row * 3 + 2].zero? } if faults
363
+ @rows.times { |row| values[row] = nil unless cast?(faults, row) } if faults
177
364
  elsif door == :text
178
365
  values = texts(bytes.unpack("L<*"), faults)
179
366
  else
180
367
  directive, width, build = RECORDS.fetch(door)
181
368
  fields = bytes.unpack(directive * @rows)
182
369
  values = Array.new(@rows) do |row|
183
- build.call(fields, row * width) if faults.nil? || faults[row * 3 + 2].zero?
370
+ build.call(fields, row * width) if faults.nil? || cast?(faults, row)
184
371
  end
185
372
  end
186
373
  values.freeze
@@ -190,14 +377,20 @@ module HyperTabular
190
377
  # flagged — out of the arena.
191
378
  def texts(spans, faults)
192
379
  Array.new(@rows) do |row|
193
- slice(spans[row * 2], spans[row * 2 + 1]) if faults.nil? || faults[row * 3 + 2].zero?
380
+ slice(spans[row * 2], spans[row * 2 + 1]) if faults.nil? || cast?(faults, row)
194
381
  end
195
382
  end
196
383
 
384
+ # Whether the cell at +row+ cast: it passed, or broke a constraint with the value it cast to.
385
+ def cast?(faults, row)
386
+ reason = faults[row * 3 + 2]
387
+ reason.zero? || reason == VIOLATION
388
+ end
389
+
197
390
  # A column's verdicts: a Success around each value, a Fault where the core says so.
198
391
  def judge(column)
199
392
  values = values(column)
200
- faults = faults(column)
393
+ faults = verdict_words(column)
201
394
  return values.map { |value| HyperCast::Success.new(value: value) }.freeze if faults.nil?
202
395
 
203
396
  Array.new(@rows) { |row| cell(column, row, values, faults) }.freeze
@@ -214,12 +407,14 @@ module HyperTabular
214
407
  # One Fault, its span moved from the bytes the core counts in to the characters
215
408
  # String#[] slices by — an identity unless the cell's text has a multi-byte character.
216
409
  def fault(column, row, reason, offset, length)
217
- return EMPTY if reason == 1 && offset.zero? && length.zero?
218
-
219
- unless offset.zero? && length.zero?
220
- offset, length = HyperCast::Interop.characters(raw(column, row), offset, length)
410
+ detail = @notes.nil? ? 0 : @notes.fetch(column).unpack1("S<", offset: row * NOTE_BYTES)
411
+ if reason == 1 && offset.zero? && length.zero?
412
+ return EMPTY if detail.zero?
413
+ return BLANK if detail == BLANK.detail.code
221
414
  end
222
- HyperCast::Interop.fault(reason, offset, length)
415
+
416
+ offset, length = span(column, row, offset, length)
417
+ HyperCast::Interop.fault(reason, offset, length, detail)
223
418
  end
224
419
  end
225
420
  end
@@ -25,13 +25,20 @@ module HyperTabular
25
25
  # +ordinal+ is the zero-based source column; past a record's last cell it reads as empty.
26
26
  # +door+ is a key of DOORS. +declared+ is the Symbol the door was declared with — a Unix
27
27
  # precision, a date order, an Excel epoch, as HyperCast names them — or nil. +format+ is
28
- # the HyperCast::NumFormat of a numeric door, or nil.
29
- Column = Data.define(:ordinal, :door, :declared, :format) do
28
+ # the HyperCast::NumFormat of a numeric door, or nil: no format is Western grouping, as
29
+ # HyperCast::NumFormat::INVARIANT is, and Indian grouping is declared per column. +tokens+ is
30
+ # the list this column answers to in place of its dialect's or sheet's (#with_tokens), nil to
31
+ # inherit theirs. +date_options+ and +months+ are the HyperCast::DateOptions and
32
+ # HyperCast::MonthNames the date doors read (#with_date_options), or nil. +constraints+ is the
33
+ # HyperCast::Constraints every cell of a numeric or text column must also meet, declared for this
34
+ # column's door, or nil: a constrained column is read with Batch#get_checked.
35
+ Column = Data.define(:ordinal, :door, :declared, :format, :tokens, :date_options, :months, :constraints) do
30
36
  # Checks the column as the caller bug it would otherwise become at the first read: an
31
- # ordinal that is not a non-negative Integer or a format that is not a
32
- # HyperCast::NumFormat (ArgumentError), an unknown door or an undeclared option
33
- # (KeyError, as HyperCast raises for the same).
34
- def initialize(ordinal:, door:, declared: nil, format: nil)
37
+ # ordinal that is not a non-negative Integer, a format that is not a HyperCast::NumFormat or
38
+ # constraints that are not a HyperCast::Constraints for this door (ArgumentError), an unknown
39
+ # door or an undeclared option (KeyError, as HyperCast raises for the same).
40
+ def initialize(ordinal:, door:, declared: nil, format: nil, tokens: nil, date_options: nil, months: nil,
41
+ constraints: nil)
35
42
  raise ArgumentError, "ordinal must be an Integer at least 0, and an ordinal must be below 2^20 " \
36
43
  "(1,048,576); got #{ordinal.inspect}" unless
37
44
  ordinal.is_a?(Integer) && ordinal.between?(0, Column::MAX_ORDINAL)
@@ -50,48 +57,101 @@ module HyperTabular
50
57
  raise ArgumentError, "the #{door} door reads no numeric format"
51
58
  end
52
59
 
53
- super(ordinal: ordinal, door: door, declared: declared, format: format)
60
+ raise ArgumentError, "date_options must be a HyperCast::DateOptions; got #{date_options.inspect}" unless
61
+ date_options.nil? || date_options.is_a?(HyperCast::DateOptions)
62
+ raise ArgumentError, "months must be a HyperCast::MonthNames; got #{months.inspect}" unless
63
+ months.nil? || months.is_a?(HyperCast::MonthNames)
64
+
65
+ unless constraints.nil?
66
+ raise ArgumentError, "constraints must be a HyperCast::Constraints; got #{constraints.inspect}" unless
67
+ constraints.is_a?(HyperCast::Constraints)
68
+
69
+ # One that never went through Constraints.new raises what HyperCast raises for it.
70
+ constraints.send(:declaration) if constraints.door.nil?
71
+ raise ArgumentError, Column.mismatched(constraints.door, door) unless constraints.door == door
72
+ end
73
+
74
+ super(ordinal: ordinal, door: door, declared: declared, format: format,
75
+ tokens: tokens.nil? ? nil : Declared.tokens(tokens), date_options: date_options, months: months,
76
+ constraints: constraints)
77
+ end
78
+
79
+ # The same column answering to these tokens rather than its dialect's or its sheet's: a cell
80
+ # whose exact, unquoted bytes are one of them is an :empty Fault, whatever its door, at Origin
81
+ # :token. An empty list means none, so a column can opt out of what it would inherit. On a
82
+ # sheet, only a text cell can be one.
83
+ def with_tokens(list)
84
+ with(tokens: list)
85
+ end
86
+
87
+ # The same column reading dates under these HyperCast::DateOptions and, optionally, this
88
+ # HyperCast::MonthNames: the timestamp, date, date_ordered and datetime doors read them, as
89
+ # HyperCast's own do. On a sheet they reach only a text cell, since a typed date cell has no
90
+ # text for them to read. A declaration the core refuses is an ArgumentError when the plan is
91
+ # bound.
92
+ def with_date_options(options, months = nil)
93
+ with(date_options: options, months: months)
54
94
  end
55
95
 
56
96
  # A boolean column: HyperCast's boolean lexicon, as true or false.
57
97
  def self.bool(ordinal) = new(ordinal: ordinal, door: :bool)
58
98
 
59
99
  # A signed 8-bit column, as an Integer. Invariant notation unless one is declared.
60
- def self.i8(ordinal, format = HyperCast::NumFormat::INVARIANT) = new(ordinal: ordinal, door: :i8, format: format)
100
+ def self.i8(ordinal, format = HyperCast::NumFormat::INVARIANT, constraints: nil)
101
+ new(ordinal: ordinal, door: :i8, format: format, constraints: constraints)
102
+ end
61
103
 
62
104
  # A signed 16-bit column, as an Integer. Invariant notation unless one is declared.
63
- def self.i16(ordinal, format = HyperCast::NumFormat::INVARIANT) = new(ordinal: ordinal, door: :i16, format: format)
105
+ def self.i16(ordinal, format = HyperCast::NumFormat::INVARIANT, constraints: nil)
106
+ new(ordinal: ordinal, door: :i16, format: format, constraints: constraints)
107
+ end
64
108
 
65
109
  # A signed 32-bit column, as an Integer. Invariant notation unless one is declared.
66
- def self.i32(ordinal, format = HyperCast::NumFormat::INVARIANT) = new(ordinal: ordinal, door: :i32, format: format)
110
+ def self.i32(ordinal, format = HyperCast::NumFormat::INVARIANT, constraints: nil)
111
+ new(ordinal: ordinal, door: :i32, format: format, constraints: constraints)
112
+ end
67
113
 
68
114
  # A signed 64-bit column, as an Integer. Invariant notation unless one is declared.
69
- def self.i64(ordinal, format = HyperCast::NumFormat::INVARIANT) = new(ordinal: ordinal, door: :i64, format: format)
115
+ def self.i64(ordinal, format = HyperCast::NumFormat::INVARIANT, constraints: nil)
116
+ new(ordinal: ordinal, door: :i64, format: format, constraints: constraints)
117
+ end
70
118
 
71
119
  # An unsigned 8-bit column, as an Integer. Invariant notation unless one is declared.
72
- def self.u8(ordinal, format = HyperCast::NumFormat::INVARIANT) = new(ordinal: ordinal, door: :u8, format: format)
120
+ def self.u8(ordinal, format = HyperCast::NumFormat::INVARIANT, constraints: nil)
121
+ new(ordinal: ordinal, door: :u8, format: format, constraints: constraints)
122
+ end
73
123
 
74
124
  # An unsigned 16-bit column, as an Integer. Invariant notation unless one is declared.
75
- def self.u16(ordinal, format = HyperCast::NumFormat::INVARIANT) = new(ordinal: ordinal, door: :u16, format: format)
125
+ def self.u16(ordinal, format = HyperCast::NumFormat::INVARIANT, constraints: nil)
126
+ new(ordinal: ordinal, door: :u16, format: format, constraints: constraints)
127
+ end
76
128
 
77
129
  # An unsigned 32-bit column, as an Integer. Invariant notation unless one is declared.
78
- def self.u32(ordinal, format = HyperCast::NumFormat::INVARIANT) = new(ordinal: ordinal, door: :u32, format: format)
130
+ def self.u32(ordinal, format = HyperCast::NumFormat::INVARIANT, constraints: nil)
131
+ new(ordinal: ordinal, door: :u32, format: format, constraints: constraints)
132
+ end
79
133
 
80
134
  # An unsigned 64-bit column, as the true unsigned Integer. Invariant notation unless
81
135
  # one is declared.
82
- def self.u64(ordinal, format = HyperCast::NumFormat::INVARIANT) = new(ordinal: ordinal, door: :u64, format: format)
136
+ def self.u64(ordinal, format = HyperCast::NumFormat::INVARIANT, constraints: nil)
137
+ new(ordinal: ordinal, door: :u64, format: format, constraints: constraints)
138
+ end
83
139
 
84
140
  # An IEEE single column, widened losslessly to a Float. Invariant notation unless one
85
141
  # is declared.
86
- def self.f32(ordinal, format = HyperCast::NumFormat::INVARIANT) = new(ordinal: ordinal, door: :f32, format: format)
142
+ def self.f32(ordinal, format = HyperCast::NumFormat::INVARIANT, constraints: nil)
143
+ new(ordinal: ordinal, door: :f32, format: format, constraints: constraints)
144
+ end
87
145
 
88
146
  # An IEEE double column, as a Float. Invariant notation unless one is declared.
89
- def self.f64(ordinal, format = HyperCast::NumFormat::INVARIANT) = new(ordinal: ordinal, door: :f64, format: format)
147
+ def self.f64(ordinal, format = HyperCast::NumFormat::INVARIANT, constraints: nil)
148
+ new(ordinal: ordinal, door: :f64, format: format, constraints: constraints)
149
+ end
90
150
 
91
151
  # An exact decimal column, as a HyperCast::Decimal; no float is ever formed. Invariant
92
152
  # notation unless one is declared.
93
- def self.decimal(ordinal, format = HyperCast::NumFormat::INVARIANT)
94
- new(ordinal: ordinal, door: :decimal, format: format)
153
+ def self.decimal(ordinal, format = HyperCast::NumFormat::INVARIANT, constraints: nil)
154
+ new(ordinal: ordinal, door: :decimal, format: format, constraints: constraints)
95
155
  end
96
156
 
97
157
  # A UUID column, as the lowercase hyphenated String.
@@ -131,7 +191,7 @@ module HyperTabular
131
191
 
132
192
  # A text column: the cell's bytes themselves, untrimmed, quotes resolved, as a UTF-8
133
193
  # String. A cell with no bytes at all is the one way text fails (an :empty Fault).
134
- def self.text(ordinal) = new(ordinal: ordinal, door: :text)
194
+ def self.text(ordinal, constraints: nil) = new(ordinal: ordinal, door: :text, constraints: constraints)
135
195
 
136
196
  # +plan+ as a reader holds it: a frozen Array of its own, every entry a Column — what
137
197
  # DelimitedReader and Sheet check a plan with. ArgumentError naming the first entry that
@@ -145,12 +205,80 @@ module HyperTabular
145
205
  plan
146
206
  end
147
207
 
208
+ # +plan+ as the runtime takes it: for each column its fixed bytes, its month vocabulary, its
209
+ # tokens (see #packed_with), and its constraints' packed bytes and packed enum, or nils. What a
210
+ # column declares is judged here, ahead of any input, so a plan the core would refuse is an
211
+ # ArgumentError naming the column at bind or open, a retired grouping word among them, and never
212
+ # a read that fails later.
213
+ def self.specs(plan)
214
+ specs = plan.each_with_index.map do |column, index|
215
+ [column.packed_with, column.months&.packed, column.packed_tokens, *column.packed_constraints]
216
+ rescue ArgumentError => e
217
+ raise ArgumentError, "plan column #{index} cannot be honoured: #{e.message}"
218
+ end
219
+ refused = Runtime.refused(specs)
220
+ return specs if refused.nil?
221
+
222
+ raise ArgumentError, "plan column #{refused} cannot be honoured: the core refuses what it declares"
223
+ end
224
+
225
+ # The column a door's code and what it declares name, as the core numbers them, or nil for
226
+ # a code this version does not know. A numeric door reads +format+.
227
+ def self.of_code(ordinal, code, param, format = nil)
228
+ door = DOORS.key(code)
229
+ return nil if door.nil?
230
+
231
+ declares = Column::DECLARES[door]
232
+ declared = declares&.key(param)
233
+ return nil if declares && declared.nil?
234
+
235
+ new(ordinal: ordinal, door: door, declared: declared, format: Column::NUMERIC.include?(door) ? format : nil)
236
+ end
237
+
148
238
  # Bytes one value of this column's door takes in a column buffer.
149
239
  def value_bytes
150
240
  Column::VALUE_BYTES.fetch(door)
151
241
  end
152
242
 
153
- # The 104 little-endian bytes of the core's ColumnSpec: ordinal, door code, what the
243
+ # The fixed part of the core's ColumnSpecWith, the one every read goes through: its size,
244
+ # the ordinal, the door code, what the door declares, the notation (see #packed), and the date
245
+ # options in HyperCast's packed form (twelve zeros, a size of zero, for none). The runtime
246
+ # appends the two pointers and lengths its months and tokens live at. A format holding the
247
+ # retired grouping bit raises ArgumentError here, from NumFormat#raw_flags.
248
+ def packed_with
249
+ param = declared.nil? ? 0 : Column::DECLARES.fetch(door).fetch(declared)
250
+ [Column::SPEC_WITH_BYTES, ordinal, DOORS.fetch(door), param].pack("L<4") +
251
+ (format.nil? ? Column::NO_FORMAT : format.packed) +
252
+ (date_options.nil? ? Column::NO_DATE_OPTIONS : date_options.packed)
253
+ end
254
+
255
+ # The column's own tokens as the core takes them: nil to inherit, an empty String for none.
256
+ def packed_tokens
257
+ tokens.nil? ? nil : Declared.packed_tokens(tokens)
258
+ end
259
+
260
+ # The constraints as the core takes them: HyperCast's 104 packed bytes and its packed enum, or
261
+ # two nils for none. HyperCast judges the declaration again here, so one that never went
262
+ # through Constraints.new, or a column whose door is not the declaration's however it was
263
+ # built, is the ArgumentError Constraints.new or Column.new raises.
264
+ def packed_constraints
265
+ return [nil, nil] if constraints.nil?
266
+ raise ArgumentError, "constraints must be a HyperCast::Constraints; got #{constraints.inspect}" unless
267
+ constraints.is_a?(HyperCast::Constraints)
268
+
269
+ code, packed, packed_enum = constraints.send(:declaration)
270
+ raise ArgumentError, Column.mismatched(constraints.door, door) unless code == DOORS[door]
271
+
272
+ [packed, packed_enum]
273
+ end
274
+
275
+ # Whether the column declares constraints, and so is read with Batch#get_checked.
276
+ def checked?
277
+ !constraints.nil?
278
+ end
279
+
280
+ # The 104 little-endian bytes of the core's 1.0 ColumnSpec, which no read takes and the 1.0
281
+ # exports stay proved with: ordinal, door code, what the
154
282
  # door declares (numbered as HyperCast numbers it), then the notation in HyperCast's
155
283
  # own packed form (its 92-byte size-tagged layout) — all zeros, which the core reads
156
284
  # as invariant, for a door that reads none.
@@ -160,6 +288,11 @@ module HyperTabular
160
288
  end
161
289
  end
162
290
 
291
+ # The words a declaration for one door given to a column of another is refused in.
292
+ def Column.mismatched(declared, door)
293
+ "Constraints for :#{declared} were given to a :#{door} column"
294
+ end
295
+
163
296
  # The widest source ordinal a column can name: an ordinal must be below 2^20. No workbook
164
297
  # format has that many columns (XLSX and ODS stop at 16,384, Numbers at 1,000), and at the
165
298
  # cap one row of cell table is at most 8 MiB.
@@ -182,4 +315,16 @@ module HyperTabular
182
315
 
183
316
  # The notation of a door that reads none: ninety-two zero bytes, a size of zero.
184
317
  Column::NO_FORMAT = ("\0" * HyperCast::NumFormat::PACKED_BYTES).b.freeze
318
+
319
+ # The date options of a column that declares none: a size of zero.
320
+ Column::NO_DATE_OPTIONS = ("\0" * HyperCast::DateOptions::PACKED_BYTES).b.freeze
321
+
322
+ # Bytes in the fixed part of a ColumnSpecWith, Column#packed_with: four words, the notation and
323
+ # the date options.
324
+ Column::SPEC_WITH_FIXED = 16 + HyperCast::NumFormat::PACKED_BYTES + HyperCast::DateOptions::PACKED_BYTES
325
+
326
+ # Bytes in a whole ColumnSpecWith, what its first word carries: the fixed part, then the month
327
+ # names and tokens, each a pointer and its length, then the constraints' pointer and the packed
328
+ # enum's pointer and length.
329
+ Column::SPEC_WITH_BYTES = Column::SPEC_WITH_FIXED + 7 * [0].pack("J").bytesize
185
330
  end