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.
- checksums.yaml +4 -4
- data/LICENSE-UNICODE +39 -0
- data/README.md +278 -34
- data/ext/hypertabular_native/3.4/hypertabular_native.a.gz +0 -0
- data/ext/hypertabular_native/4.0/hypertabular_native.a.gz +0 -0
- data/lib/hypertabular/batch.rb +219 -24
- data/lib/hypertabular/column.rb +166 -21
- data/lib/hypertabular/delimited_reader.rb +319 -94
- data/lib/hypertabular/dialect.rb +92 -10
- data/lib/hypertabular/guarded.rb +116 -0
- data/lib/hypertabular/header.rb +59 -22
- data/lib/hypertabular/row.rb +17 -4
- data/lib/hypertabular/runtime/columns.rb +78 -12
- data/lib/hypertabular/runtime/delimited.rb +63 -37
- data/lib/hypertabular/runtime/workbook.rb +39 -15
- data/lib/hypertabular/runtime.rb +255 -17
- data/lib/hypertabular/suggest.rb +283 -0
- data/lib/hypertabular/tabular_error.rb +9 -3
- data/lib/hypertabular/workbook.rb +185 -45
- data/lib/hypertabular.rb +14 -8
- metadata +7 -3
|
@@ -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)
|
|
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
|
|
8
|
-
#
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
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
|
-
|
|
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.
|
|
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
|
|
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
|
-
|
|
243
|
+
exclusive do
|
|
244
|
+
raise "the sheet already has a plan: a plan is bound once" if bound?
|
|
170
245
|
|
|
171
|
-
|
|
172
|
-
|
|
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
|
-
|
|
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
|
-
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
|
|
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
|
-
|
|
272
|
+
atomically { step } ? hand_over : nil
|
|
197
273
|
end
|
|
198
|
-
|
|
274
|
+
end
|
|
199
275
|
|
|
200
|
-
|
|
201
|
-
|
|
202
|
-
|
|
203
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
#
|
|
240
|
-
def
|
|
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
|
-
|
|
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
|