hypercast 1.0.0-aarch64-linux-gnu → 1.1.0-aarch64-linux-gnu
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 +318 -43
- data/lib/hypercast/3.4/hypercast_native.so +0 -0
- data/lib/hypercast/4.0/hypercast_native.so +0 -0
- data/lib/hypercast/interop.rb +35 -15
- data/lib/hypercast/runtime.rb +62 -9
- data/lib/hypercast.rb +1197 -148
- metadata +3 -1
data/lib/hypercast.rb
CHANGED
|
@@ -9,9 +9,11 @@ require_relative "hypercast/runtime"
|
|
|
9
9
|
# platform gems), or the native libhypercast shared library called through Fiddle (the
|
|
10
10
|
# universal gem bundles one per supported platform). HyperCast::BACKEND names the one that
|
|
11
11
|
# loaded; the selection logic is at the bottom of this file. Every door returns a verdict: Success or
|
|
12
|
-
# Fault (a closed reason plus the offending span),
|
|
13
|
-
#
|
|
14
|
-
#
|
|
12
|
+
# Fault (a closed reason plus the offending span), and every checked door — the doors that
|
|
13
|
+
# also judge a value by declared Constraints — a Checked, a Fault or a Violation; never an
|
|
14
|
+
# exception for bad data. The only exceptions here are caller bugs (a malformed NumFormat, a
|
|
15
|
+
# refused Constraints, an undeclared option, text that is not a String), never data, and the
|
|
16
|
+
# same exception on every backend.
|
|
15
17
|
#
|
|
16
18
|
# Consume with Ruby's own pattern matching over the two Data case types:
|
|
17
19
|
#
|
|
@@ -30,7 +32,7 @@ require_relative "hypercast/runtime"
|
|
|
30
32
|
module HyperCast
|
|
31
33
|
# This gem's own version — kept in lockstep with hypercast.gemspec by the
|
|
32
34
|
# prepare-release workflow, so the two can never drift apart again.
|
|
33
|
-
VERSION = "1.
|
|
35
|
+
VERSION = "1.1.0"
|
|
34
36
|
|
|
35
37
|
# The success case of a verdict: a cast value.
|
|
36
38
|
Success = Data.define(:value)
|
|
@@ -41,11 +43,127 @@ module HyperCast
|
|
|
41
43
|
# byte offsets for a binary (ASCII-8BIT) String, whose characters are its bytes. Either
|
|
42
44
|
# way `text[offset, length]` is the offending text, with no mapping on your side.
|
|
43
45
|
# Nothing is captured — slicing it out of the input is the caller's choice.
|
|
44
|
-
|
|
46
|
+
#
|
|
47
|
+
# A fault the core reports also carries #detail, what exactly was wrong (a Detail), beside the
|
|
48
|
+
# broad reason. It is not a member: equality, #hash, #to_h, #inspect, the members and the
|
|
49
|
+
# positional and keyword constructors are what they were, so a Fault built by hand with three
|
|
50
|
+
# arguments is #== to the same fault read from a door, and its #detail is nil. A pattern asks
|
|
51
|
+
# for it by name: `in Fault(reason: :malformed, detail: Detail::GROUP_SIZE)`.
|
|
52
|
+
Fault = Data.define(:reason, :offset, :length) do
|
|
53
|
+
# The three members, and optionally the Detail (or nil) the core reported.
|
|
54
|
+
def initialize(reason:, offset:, length:, detail: nil)
|
|
55
|
+
@detail = detail
|
|
56
|
+
super(reason: reason, offset: offset, length: length)
|
|
57
|
+
end
|
|
58
|
+
|
|
59
|
+
# What exactly was wrong, a Detail; nil for a Fault built without one.
|
|
60
|
+
attr_reader :detail
|
|
61
|
+
|
|
62
|
+
# The members, and #detail when a pattern names it.
|
|
63
|
+
def deconstruct_keys(keys)
|
|
64
|
+
return super unless keys&.include?(:detail)
|
|
65
|
+
|
|
66
|
+
super(keys - [:detail]).merge(detail: @detail)
|
|
67
|
+
end
|
|
68
|
+
|
|
69
|
+
# A copy with the given members replaced, keeping #detail unless one is given.
|
|
70
|
+
def with(**changes)
|
|
71
|
+
return self if changes.empty?
|
|
72
|
+
|
|
73
|
+
self.class.new(**to_h, detail: @detail, **changes)
|
|
74
|
+
end
|
|
75
|
+
|
|
76
|
+
# Marshal's form: the members and the detail, so a loaded fault keeps its detail.
|
|
77
|
+
def marshal_dump
|
|
78
|
+
to_h.merge(detail: @detail)
|
|
79
|
+
end
|
|
80
|
+
|
|
81
|
+
# Restores a fault from #marshal_dump's form through #initialize.
|
|
82
|
+
def marshal_load(members)
|
|
83
|
+
initialize(**members)
|
|
84
|
+
end
|
|
85
|
+
end
|
|
45
86
|
|
|
46
87
|
# The native core's failure codes, mapped to the closed reason Symbols a Fault carries.
|
|
47
88
|
REASONS = { 1 => :empty, 2 => :malformed, 3 => :out_of_range }.freeze
|
|
48
89
|
|
|
90
|
+
# What exactly a Fault found wrong: the native core's numeric code and its published name. The
|
|
91
|
+
# codes keep their numbers and meanings, and a later core may add more, so a case over details
|
|
92
|
+
# needs an else branch: a code this gem does not name is kept, its #name :unknown. The reason
|
|
93
|
+
# and span of a fault stay usable either way. The constants (Detail::BLANK ...
|
|
94
|
+
# Detail::NOT_A_SCALAR, one per published code) compare equal to every detail of their code, so
|
|
95
|
+
# `in Fault(detail: Detail::GROUP_SIZE)` matches.
|
|
96
|
+
Detail = Data.define(:code) do
|
|
97
|
+
# The published name as a Symbol (:group_size), or :unknown for a code this gem does not name.
|
|
98
|
+
def name
|
|
99
|
+
self.class::NAMES.fetch(code, :unknown)
|
|
100
|
+
end
|
|
101
|
+
|
|
102
|
+
# True for a code this gem does not name; #code still holds it.
|
|
103
|
+
def unknown?
|
|
104
|
+
!self.class::NAMES.key?(code)
|
|
105
|
+
end
|
|
106
|
+
|
|
107
|
+
# The name, as text ("group_size"; "unknown" for an unknown code).
|
|
108
|
+
def to_s
|
|
109
|
+
name.to_s
|
|
110
|
+
end
|
|
111
|
+
|
|
112
|
+
# The constant that names this detail (HyperCast::Detail::GROUP_SIZE), or the Data form for
|
|
113
|
+
# a code this gem does not name.
|
|
114
|
+
def inspect
|
|
115
|
+
unknown? ? super : "HyperCast::Detail::#{name.to_s.upcase}"
|
|
116
|
+
end
|
|
117
|
+
|
|
118
|
+
# The detail of a core's code: the constant of a published one, a new Detail for any other.
|
|
119
|
+
def self.of(code)
|
|
120
|
+
self::BY_CODE.fetch(code) { new(code: code) }
|
|
121
|
+
end
|
|
122
|
+
end
|
|
123
|
+
|
|
124
|
+
# The published name of each detail, by code.
|
|
125
|
+
Detail::NAMES = {
|
|
126
|
+
1 => :blank, 2 => :unexpected_character, 3 => :digit_expected, 4 => :delimiter_expected,
|
|
127
|
+
5 => :trailing_text, 6 => :no_digits, 7 => :sign_misplaced, 8 => :parentheses_unbalanced,
|
|
128
|
+
9 => :mark_repeated, 10 => :group_misplaced, 11 => :group_size, 12 => :group_in_fraction,
|
|
129
|
+
13 => :ambiguous_separator, 14 => :fraction_not_allowed, 15 => :field_width, 16 => :wrong_length,
|
|
130
|
+
17 => :component_missing, 18 => :not_recognized, 19 => :unknown_unit, 20 => :invalid_utf8,
|
|
131
|
+
21 => :too_long, 22 => :not_finite, 23 => :not_whole, 24 => :negative_not_allowed,
|
|
132
|
+
25 => :too_large, 26 => :too_small, 27 => :too_precise, 28 => :date_field_out_of_range,
|
|
133
|
+
29 => :time_field_out_of_range, 30 => :outside_window, 31 => :nonexistent_date, 32 => :not_a_scalar
|
|
134
|
+
}.freeze
|
|
135
|
+
|
|
136
|
+
# Each published detail by code, one frozen constant apiece (Detail::BLANK is code 1, and so
|
|
137
|
+
# on through Detail::NOT_A_SCALAR, code 32): a Fault's #detail is one of these.
|
|
138
|
+
Detail::BY_CODE = Detail::NAMES.to_h do |code, name|
|
|
139
|
+
[code, Detail.const_set(name.to_s.upcase, Detail.new(code: code))]
|
|
140
|
+
end.freeze
|
|
141
|
+
|
|
142
|
+
# The 25 code points of Unicode's White_Space property, the core's one notion of white
|
|
143
|
+
# space: a character class the declaration checks match with (the Magnus backend's designator
|
|
144
|
+
# check reads the core's own predicate). Held to corpus/formats.json by the suite.
|
|
145
|
+
WHITE_SPACE = /[\t\n\v\f\r \u0085\u00A0\u1680\u2000-\u200A\u2028\u2029\u202F\u205F\u3000]/
|
|
146
|
+
private_constant :WHITE_SPACE
|
|
147
|
+
|
|
148
|
+
class << self
|
|
149
|
+
private
|
|
150
|
+
|
|
151
|
+
# A declared symbol's text as the UTF-8 the core reads, transcoded from its own encoding.
|
|
152
|
+
# Text with no UTF-8 form (a lone UTF-16 surrogate, bytes its encoding does not allow, a
|
|
153
|
+
# character with no Unicode counterpart) is data at a door, MALFORMED at that character
|
|
154
|
+
# (#kept); in a declaration it is the caller's bug, refused with the same ArgumentError on
|
|
155
|
+
# every backend, never declared as a stand-in for the character it could not spell.
|
|
156
|
+
def declared_utf8(field, text)
|
|
157
|
+
symbol = text.encode(Encoding::UTF_8)
|
|
158
|
+
return symbol if symbol.valid_encoding?
|
|
159
|
+
|
|
160
|
+
raise ArgumentError, "#{field} #{text.inspect} must be whole characters with a UTF-8 form"
|
|
161
|
+
rescue Encoding::InvalidByteSequenceError, Encoding::UndefinedConversionError,
|
|
162
|
+
Encoding::ConverterNotFoundError
|
|
163
|
+
raise ArgumentError, "#{field} #{text.inspect} must be whole characters with a UTF-8 form"
|
|
164
|
+
end
|
|
165
|
+
end
|
|
166
|
+
|
|
49
167
|
# Caller-declared numeric notation for the integer, real and decimal doors — declared out
|
|
50
168
|
# loud (INVARIANT, or a literal), never defaulted, the same stance every binding takes.
|
|
51
169
|
# Past the separators and the flags, every field is one a culture table would fill in,
|
|
@@ -63,24 +181,47 @@ module HyperCast
|
|
|
63
181
|
# percent symbol while PERCENT is. A separator may be wider than one character (", " —
|
|
64
182
|
# comma, space — is a separator), up to 8 UTF-8 bytes. A malformed format is a caller bug
|
|
65
183
|
# (ArgumentError), never a verdict: an empty or over-long separator, equal separators (or
|
|
66
|
-
# an equal pair in force for currency amounts), a symbol
|
|
67
|
-
#
|
|
68
|
-
#
|
|
184
|
+
# an equal pair in force for currency amounts), a symbol with no UTF-8 form (a lone UTF-16
|
|
185
|
+
# surrogate, bytes its encoding does not allow), a symbol carrying an ASCII digit, a sign,
|
|
186
|
+
# percent symbol, or a decimal separator, carrying white space (a group separator may be
|
|
187
|
+
# white space), a currency symbol longer than 16 bytes or starting or ending in white
|
|
188
|
+
# space (inside it white space is fine: "F CFA"), or a digit zero that is ASCII or starts
|
|
189
|
+
# no digit block.
|
|
190
|
+
#
|
|
191
|
+
# Grouping is a policy, declared apart from the flags: `grouping:` is :western (the default:
|
|
192
|
+
# once a numeral uses the group separator, groups of exactly three digits counted from the
|
|
193
|
+
# decimal separator, the leftmost one to three and not starting with a zero, so "1,234,567"
|
|
194
|
+
# reads and "12,34" and "0,125" are :malformed Faults with the detail Detail::GROUP_SIZE),
|
|
195
|
+
# or :indian (the group beside the decimal separator three digits, every group to its left two,
|
|
196
|
+
# the leftmost one or two: "12,34,567"), which reads only when declared. An ungrouped
|
|
197
|
+
# numeral reads under every policy, and a policy only judges groups: without the GROUPING flag
|
|
198
|
+
# a group separator is still refused. `flags` is the style mask (GROUPING ... TRAILING_SIGN)
|
|
199
|
+
# and never carries a policy: bits 8 and 9 or any other bit this version does not define is an
|
|
200
|
+
# ArgumentError.
|
|
69
201
|
NumFormat = Data.define(:decimal_sep, :group_sep, :flags, :currency,
|
|
70
202
|
:currency_decimal_sep, :currency_group_sep,
|
|
71
203
|
:minus_sign, :plus_sign, :percent, :digit_zero) do
|
|
72
204
|
# Validates every declared field up front — the separators (1 to 8 UTF-8 bytes each,
|
|
73
205
|
# distinct from each other, and so the pair in force for currency amounts), the signs,
|
|
74
206
|
# the percent and currency symbols (no ASCII digit, since a digit is a digit before it
|
|
75
|
-
# is anything else, and no
|
|
76
|
-
#
|
|
77
|
-
#
|
|
78
|
-
#
|
|
79
|
-
#
|
|
80
|
-
#
|
|
81
|
-
#
|
|
207
|
+
# is anything else, and no white space, which would collide with the trimming around
|
|
208
|
+
# them; the decimal separators carry none either, and a currency symbol only at its
|
|
209
|
+
# edges) and the digit zero (one non-ASCII
|
|
210
|
+
# character whose ten successors share its UTF-8 prefix, which every Unicode digit
|
|
211
|
+
# block's zero does) — so a malformed format fails loudly as the caller bug it is. Every
|
|
212
|
+
# field is stored transcoded to UTF-8, the encoding the core reads — a separator handed
|
|
213
|
+
# over in another encoding (a no-break space read from a Latin-1 file, say) is the same
|
|
214
|
+
# code point on every backend rather than whatever its bytes happened to spell in the
|
|
215
|
+
# encoding it arrived in.
|
|
82
216
|
def initialize(decimal_sep:, group_sep:, flags:, currency: "", currency_decimal_sep: "",
|
|
83
|
-
currency_group_sep: "", minus_sign: "", plus_sign: "", percent: "", digit_zero: ""
|
|
217
|
+
currency_group_sep: "", minus_sign: "", plus_sign: "", percent: "", digit_zero: "",
|
|
218
|
+
grouping: :western)
|
|
219
|
+
check_flags(flags)
|
|
220
|
+
raise ArgumentError, "grouping must be one of #{GROUPING_POLICIES.keys.inspect}; got #{grouping.inspect}" unless
|
|
221
|
+
GROUPING_POLICIES.key?(grouping)
|
|
222
|
+
|
|
223
|
+
@grouping = grouping
|
|
224
|
+
|
|
84
225
|
limit = self.class::SYMBOL_MAX_BYTES
|
|
85
226
|
decimal_sep = declared("decimal separator", decimal_sep, limit, required: true)
|
|
86
227
|
group_sep = declared("group separator", group_sep, limit, required: true)
|
|
@@ -89,20 +230,90 @@ module HyperCast
|
|
|
89
230
|
|
|
90
231
|
currency_decimal_sep = declared("currency decimal separator", currency_decimal_sep, limit)
|
|
91
232
|
currency_group_sep = declared("currency group separator", currency_group_sep, limit)
|
|
233
|
+
currency = declared("currency symbol", currency, self.class::CURRENCY_MAX_BYTES)
|
|
234
|
+
minus_sign = declared("minus sign", minus_sign, limit)
|
|
235
|
+
plus_sign = declared("plus sign", plus_sign, limit)
|
|
236
|
+
percent = declared("percent symbol", percent, limit)
|
|
92
237
|
money_decimal = currency_decimal_sep.empty? ? decimal_sep : currency_decimal_sep
|
|
93
238
|
money_group = currency_group_sep.empty? ? group_sep : currency_group_sep
|
|
94
239
|
raise ArgumentError, "currency decimal and group separators must differ; both are #{money_decimal.inspect}" if
|
|
95
240
|
money_decimal == money_group
|
|
96
241
|
|
|
242
|
+
# White space comes last, after every field's length and digit and the equal separators.
|
|
243
|
+
{ "decimal separator" => decimal_sep, "currency decimal separator" => currency_decimal_sep,
|
|
244
|
+
"minus sign" => minus_sign, "plus sign" => plus_sign, "percent symbol" => percent }.each do |field, symbol|
|
|
245
|
+
raise ArgumentError, "#{field} #{symbol.inspect} must not contain white space" if
|
|
246
|
+
symbol.match?(WHITE_SPACE)
|
|
247
|
+
end
|
|
248
|
+
# A currency symbol may hold white space inside ("F CFA"), never at an edge.
|
|
249
|
+
raise ArgumentError, "currency symbol #{currency.inspect} must not start or end with white space" if
|
|
250
|
+
currency.match?(/\A#{WHITE_SPACE.source}|#{WHITE_SPACE.source}\z/)
|
|
251
|
+
|
|
97
252
|
super(decimal_sep: decimal_sep, group_sep: group_sep, flags: flags,
|
|
98
|
-
currency:
|
|
99
|
-
|
|
100
|
-
minus_sign: declared("minus sign", minus_sign, limit, flush: true),
|
|
101
|
-
plus_sign: declared("plus sign", plus_sign, limit, flush: true),
|
|
102
|
-
percent: declared("percent symbol", percent, limit, flush: true),
|
|
253
|
+
currency: currency, currency_decimal_sep: currency_decimal_sep, currency_group_sep: currency_group_sep,
|
|
254
|
+
minus_sign: minus_sign, plus_sign: plus_sign, percent: percent,
|
|
103
255
|
digit_zero: digit_zero_of(digit_zero))
|
|
104
256
|
end
|
|
105
257
|
|
|
258
|
+
# The grouping policy, :western or :indian. It is not a member, as Fault#detail is
|
|
259
|
+
# not: the ten members, #to_h, #inspect and the positional and keyword constructors are
|
|
260
|
+
# 1.0's, and the policy rides beside them, counting in #==, #eql? and #hash (an :indian and a
|
|
261
|
+
# :western format must never be one memo key). A NumFormat restored from a 1.0 Marshal
|
|
262
|
+
# payload carries no policy and is :western, like everything that records none.
|
|
263
|
+
def grouping
|
|
264
|
+
@grouping || :western
|
|
265
|
+
end
|
|
266
|
+
|
|
267
|
+
# The flags word the native layout carries: #flags with the grouping policy in bits 8 and 9.
|
|
268
|
+
# A 1.0 Marshal payload is restored member by member with no call this class can hook, so a
|
|
269
|
+
# flags word it stored is judged here, on its first use.
|
|
270
|
+
def raw_flags
|
|
271
|
+
check_flags(flags)
|
|
272
|
+
flags | GROUPING_POLICIES.fetch(grouping)
|
|
273
|
+
end
|
|
274
|
+
|
|
275
|
+
# Equal when every member and the grouping policy are.
|
|
276
|
+
def ==(other)
|
|
277
|
+
super && grouping == other.grouping
|
|
278
|
+
end
|
|
279
|
+
|
|
280
|
+
# Eql when every member and the grouping policy are.
|
|
281
|
+
def eql?(other)
|
|
282
|
+
super && grouping.eql?(other.grouping)
|
|
283
|
+
end
|
|
284
|
+
|
|
285
|
+
# A hash over the members and the grouping policy.
|
|
286
|
+
def hash
|
|
287
|
+
[super, grouping].hash
|
|
288
|
+
end
|
|
289
|
+
|
|
290
|
+
# The members, and #grouping when a pattern names it.
|
|
291
|
+
def deconstruct_keys(keys)
|
|
292
|
+
return super unless keys&.include?(:grouping)
|
|
293
|
+
|
|
294
|
+
super(keys - [:grouping]).merge(grouping: grouping)
|
|
295
|
+
end
|
|
296
|
+
|
|
297
|
+
# A copy with the given members (or grouping:) replaced, keeping the policy unless one is
|
|
298
|
+
# given, and validated as NumFormat.new validates. With none given it is the format itself.
|
|
299
|
+
def with(**changes)
|
|
300
|
+
return self if changes.empty?
|
|
301
|
+
|
|
302
|
+
self.class.new(**to_h, grouping: grouping, **changes)
|
|
303
|
+
end
|
|
304
|
+
|
|
305
|
+
# Marshal's form: the members and the policy, so a loaded format keeps its policy and is
|
|
306
|
+
# judged again as a new one is, and a stored policy that isn't one is an ArgumentError here. A
|
|
307
|
+
# 1.0 payload (the struct form) loads without a policy, which #grouping reads as :western.
|
|
308
|
+
def marshal_dump
|
|
309
|
+
to_h.merge(grouping: grouping)
|
|
310
|
+
end
|
|
311
|
+
|
|
312
|
+
# Restores a format from #marshal_dump's form through #initialize.
|
|
313
|
+
def marshal_load(members)
|
|
314
|
+
initialize(**members)
|
|
315
|
+
end
|
|
316
|
+
|
|
106
317
|
# This format with the fields Ruby's number vocabulary names replaced — the words Rails'
|
|
107
318
|
# number helpers and I18n's number.format use: separator: (the decimal mark),
|
|
108
319
|
# delimiter: (grouping) and unit: (the currency symbol). A nil keyword leaves its
|
|
@@ -151,7 +362,11 @@ module HyperCast
|
|
|
151
362
|
# (U+2212 for Estonian and Basque, for instance) declares it on the result with
|
|
152
363
|
# Data#with (minus_sign: "−"). Every lenience is on, radix prefixes and percent included;
|
|
153
364
|
# narrow flags: for anything stricter.
|
|
154
|
-
|
|
365
|
+
#
|
|
366
|
+
# The Hash says nothing about how a locale groups digits, so grouping: declares it — :western,
|
|
367
|
+
# the default, reads groups of three ("1.234.567,89"), and :indian is lakh and crore
|
|
368
|
+
# ("12,34,567").
|
|
369
|
+
def self.from_i18n(number_format, currency_format: nil, flags: ALL_STYLES, grouping: :western)
|
|
155
370
|
entries = i18n_entries(number_format)
|
|
156
371
|
separator = entries[:separator] || (entries[:delimiter] == "." ? "," : ".")
|
|
157
372
|
delimiter = entries[:delimiter]
|
|
@@ -176,7 +391,7 @@ module HyperCast
|
|
|
176
391
|
flags |= TRAILING_SIGN if trailing_sign?(money[:negative_format])
|
|
177
392
|
end
|
|
178
393
|
new(decimal_sep: separator, group_sep: delimiter, flags: flags, currency: currency,
|
|
179
|
-
currency_decimal_sep: currency_separator, currency_group_sep: currency_delimiter)
|
|
394
|
+
currency_decimal_sep: currency_separator, currency_group_sep: currency_delimiter, grouping: grouping)
|
|
180
395
|
end
|
|
181
396
|
|
|
182
397
|
# The I18n Hash's entries under Symbol keys, whatever keys it arrived with.
|
|
@@ -199,15 +414,16 @@ module HyperCast
|
|
|
199
414
|
end
|
|
200
415
|
private_class_method :trailing_sign?
|
|
201
416
|
|
|
202
|
-
# The 92-byte little-endian form of the
|
|
203
|
-
#
|
|
204
|
-
#
|
|
205
|
-
#
|
|
206
|
-
#
|
|
207
|
-
#
|
|
208
|
-
#
|
|
417
|
+
# The 92-byte little-endian form of the ABI's size-tagged NumFormat struct (what the
|
|
418
|
+
# core's RawNumFormat::from_le_bytes reads, and Python's NumFormat.packed is): the size
|
|
419
|
+
# word (92), the flags with the grouping policy in bits 8 and 9 (#raw_flags), the digit
|
|
420
|
+
# zero's code point (0 for none), each a little-endian u32 on every host, then each symbol
|
|
421
|
+
# as its UTF-8 bytes zero-padded to its field followed by its byte length — eight bytes
|
|
422
|
+
# and a length for each of the two number separators, the two currency separators, the two
|
|
423
|
+
# signs and the percent symbol, in that order; sixteen and a length for the currency
|
|
424
|
+
# symbol. A length of 0 declares nothing.
|
|
209
425
|
def packed
|
|
210
|
-
head = [self.class::PACKED_BYTES,
|
|
426
|
+
head = [self.class::PACKED_BYTES, raw_flags, digit_zero.empty? ? 0 : digit_zero.ord].pack("L<L<L<")
|
|
211
427
|
symbols = [decimal_sep, group_sep, currency_decimal_sep, currency_group_sep, minus_sign, plus_sign, percent]
|
|
212
428
|
head + symbols.map { |symbol| [symbol, symbol.bytesize].pack("a8C") }.join +
|
|
213
429
|
[currency, currency.bytesize].pack("a16C")
|
|
@@ -215,14 +431,25 @@ module HyperCast
|
|
|
215
431
|
|
|
216
432
|
private
|
|
217
433
|
|
|
434
|
+
# The style mask: an Integer of the defined flag bits (0 through 7) and nothing else. The
|
|
435
|
+
# grouping policy has its own keyword, so bits 8 and 9 are refused as a policy in the wrong
|
|
436
|
+
# place, and any bit above them as one this version does not define.
|
|
437
|
+
def check_flags(flags)
|
|
438
|
+
raise ArgumentError, "flags must be an Integer; got #{flags.inspect}" unless flags.is_a?(Integer)
|
|
439
|
+
raise ArgumentError, "flags #{flags} must not carry a grouping policy (bits 8 and 9); declare it with " \
|
|
440
|
+
"grouping:" if flags.anybits?(GROUPING_POLICY)
|
|
441
|
+
raise ArgumentError, "flags #{flags} sets a bit this version does not define (bit 10 and above)" unless
|
|
442
|
+
flags.between?(0, 0xFF)
|
|
443
|
+
end
|
|
444
|
+
|
|
218
445
|
# The declared text of one field as the UTF-8 the core reads: a String of 1 to `limit`
|
|
219
|
-
# UTF-8 bytes with no ASCII digit
|
|
220
|
-
#
|
|
221
|
-
#
|
|
222
|
-
def declared(field, text, limit,
|
|
446
|
+
# UTF-8 bytes with no ASCII digit, or "" where the field may be left undeclared. Anything
|
|
447
|
+
# else is the caller bug it names. White space is refused by the caller, once every
|
|
448
|
+
# field has passed this and the separators are known to differ.
|
|
449
|
+
def declared(field, text, limit, required: false)
|
|
223
450
|
raise ArgumentError, "#{field} must be a String; got #{text.inspect}" unless text.is_a?(String)
|
|
224
451
|
|
|
225
|
-
symbol =
|
|
452
|
+
symbol = HyperCast.send(:declared_utf8, field, text)
|
|
226
453
|
if symbol.empty?
|
|
227
454
|
raise ArgumentError, "#{field} must not be empty" if required
|
|
228
455
|
|
|
@@ -230,12 +457,8 @@ module HyperCast
|
|
|
230
457
|
end
|
|
231
458
|
raise ArgumentError, "#{field} #{text.inspect} exceeds #{limit} UTF-8 bytes" if symbol.bytesize > limit
|
|
232
459
|
|
|
233
|
-
if
|
|
234
|
-
|
|
235
|
-
symbol.match?(/[0-9\t\n\f\r ]/)
|
|
236
|
-
elsif symbol.match?(/[0-9]/)
|
|
237
|
-
raise ArgumentError, "#{field} #{text.inspect} must not contain an ASCII digit"
|
|
238
|
-
end
|
|
460
|
+
raise ArgumentError, "#{field} #{text.inspect} must not contain an ASCII digit" if symbol.match?(/[0-9]/)
|
|
461
|
+
|
|
239
462
|
symbol
|
|
240
463
|
end
|
|
241
464
|
|
|
@@ -246,7 +469,7 @@ module HyperCast
|
|
|
246
469
|
def digit_zero_of(text)
|
|
247
470
|
raise ArgumentError, "digit zero must be a String; got #{text.inspect}" unless text.is_a?(String)
|
|
248
471
|
|
|
249
|
-
zero =
|
|
472
|
+
zero = HyperCast.send(:declared_utf8, "digit zero", text)
|
|
250
473
|
return zero if zero.empty?
|
|
251
474
|
|
|
252
475
|
raise ArgumentError, "digit zero #{text.inspect} must be one non-ASCII character that starts a digit block" unless
|
|
@@ -268,7 +491,8 @@ module HyperCast
|
|
|
268
491
|
# The size of NumFormat#packed — the native ABI's size-tagged NumFormat layout — in bytes.
|
|
269
492
|
NumFormat::PACKED_BYTES = 92
|
|
270
493
|
|
|
271
|
-
# Permit the group separator between digits
|
|
494
|
+
# Permit the group separator between digits. The NumFormat's grouping policy judges the sizes
|
|
495
|
+
# (Western by default, :indian when declared).
|
|
272
496
|
GROUPING = 1
|
|
273
497
|
# Permit accounting parentheses as negation: (1,234) is -1234.
|
|
274
498
|
PARENTHESES = 1 << 1
|
|
@@ -289,13 +513,13 @@ module HyperCast
|
|
|
289
513
|
SEPARATOR_DETECT = 1 << 5
|
|
290
514
|
# Permit the format's declared currency symbol at either edge of the numeric body —
|
|
291
515
|
# leading ("$5", "-$5", "$ -5") or trailing ("5 €", "1.234,50 kr."), once, with optional
|
|
292
|
-
#
|
|
516
|
+
# white space between symbol and digits; accounting parentheses wrap the symbol
|
|
293
517
|
# along with the digits ("($5)"). With no symbol declared the flag matches nothing.
|
|
294
518
|
# Integer, real and decimal doors.
|
|
295
519
|
CURRENCY = 1 << 6
|
|
296
520
|
# Permit the sign after the digits ("5-", "5 -", "5 €-", "5- €"), the way a locale whose
|
|
297
521
|
# negative_format is "%n-" writes it: ASCII - and + or the format's declared signs, once,
|
|
298
|
-
# with optional
|
|
522
|
+
# with optional white space before it, and never beside a leading sign or inside
|
|
299
523
|
# accounting parentheses. Not part of ALL_STYLES — NumFormat.from_i18n sets it from the
|
|
300
524
|
# locale's own negative_format rather than assuming it.
|
|
301
525
|
TRAILING_SIGN = 1 << 7
|
|
@@ -304,12 +528,26 @@ module HyperCast
|
|
|
304
528
|
# lenience, and is deliberately not included either).
|
|
305
529
|
ALL_STYLES = GROUPING | PARENTHESES | EXPONENT | RADIX_PREFIXES | PERCENT | CURRENCY
|
|
306
530
|
|
|
307
|
-
#
|
|
308
|
-
#
|
|
531
|
+
# Grouping policy Western, no bits, the default: groups of exactly three digits from the
|
|
532
|
+
# decimal separator, the leftmost one to three.
|
|
533
|
+
GROUPING_WESTERN = 0
|
|
534
|
+
# Grouping policy Indian, bit 9, only when declared: three digits beside the decimal separator,
|
|
535
|
+
# two in each group to its left, the leftmost one or two.
|
|
536
|
+
GROUPING_INDIAN = 2 << 8
|
|
537
|
+
# The two policy bits, 8 and 9, of the native flags word. Bit 8 (256) is retired and never
|
|
538
|
+
# reused, so 256 and 768 name no policy and are refused. A NumFormat declares its policy with
|
|
539
|
+
# grouping:, never in flags.
|
|
540
|
+
GROUPING_POLICY = 3 << 8
|
|
541
|
+
|
|
542
|
+
# The grouping policies a NumFormat's grouping: names, with their bits in the native flags word.
|
|
543
|
+
GROUPING_POLICIES = { western: GROUPING_WESTERN, indian: GROUPING_INDIAN }.freeze
|
|
544
|
+
|
|
545
|
+
# The invariant profile — '.' decimal, ',' grouping, every lenience on, Western
|
|
546
|
+
# grouping, no currency symbol declared.
|
|
309
547
|
NumFormat::INVARIANT = NumFormat.new(decimal_sep: ".", group_sep: ",", flags: ALL_STYLES)
|
|
310
548
|
|
|
311
|
-
# The detection profile — every lenience on, ./, roles resolved per
|
|
312
|
-
# SEPARATOR_DETECT's structural rules.
|
|
549
|
+
# The detection profile — every lenience on, Western grouping, ./, roles resolved per
|
|
550
|
+
# input by SEPARATOR_DETECT's structural rules.
|
|
313
551
|
NumFormat::DETECT = NumFormat.new(decimal_sep: ".", group_sep: ",",
|
|
314
552
|
flags: ALL_STYLES | SEPARATOR_DETECT)
|
|
315
553
|
|
|
@@ -326,6 +564,184 @@ module HyperCast
|
|
|
326
564
|
# en-GB order) only because the caller said which.
|
|
327
565
|
DATE_ORDERS = { year_month_day: 1, month_day_year: 2, day_month_year: 3 }.freeze
|
|
328
566
|
|
|
567
|
+
# The date shapes the doors read only when the caller opts in: a flag set (the doors' own
|
|
568
|
+
# shapes stay exactly as they are without it) and a pivot for two-digit years. Passed as
|
|
569
|
+
# `options:` to the doors that read them — COMPACT_DATE at #date, SPACE_SEPARATOR and
|
|
570
|
+
# HOUR_OFFSET at #timestamp, the pivot at #date with an order and at #datetime — and a known
|
|
571
|
+
# option a door does not read is ignored. #flags is an Integer of the defined bits and nothing
|
|
572
|
+
# else (any other bit is an ArgumentError); #pivot is nil for none, or the last year of the
|
|
573
|
+
# 100-year window a two-digit year is read in, 100 through 9999: with a pivot of 2029, "26"
|
|
574
|
+
# is 2026 and "30" is 1930. A pivot of 0 is none, too.
|
|
575
|
+
DateOptions = Data.define(:flags, :pivot) do
|
|
576
|
+
# Validates the flags and the pivot up front, so options a door could not honour are the
|
|
577
|
+
# caller bug they are, never a verdict.
|
|
578
|
+
def initialize(flags: 0, pivot: nil)
|
|
579
|
+
raise ArgumentError, "date option flags must be an Integer; got #{flags.inspect}" unless flags.is_a?(Integer)
|
|
580
|
+
raise ArgumentError, "date option flags #{flags} set a bit this version does not define" unless
|
|
581
|
+
flags.nobits?(~self.class::DEFINED)
|
|
582
|
+
unless pivot.nil? || (pivot.is_a?(Integer) && (pivot.zero? || pivot.between?(100, 9999)))
|
|
583
|
+
raise ArgumentError, "date pivot must be nil, 0, or 100 to 9999; got #{pivot.inspect}"
|
|
584
|
+
end
|
|
585
|
+
|
|
586
|
+
super(flags: flags, pivot: pivot&.zero? ? nil : pivot)
|
|
587
|
+
end
|
|
588
|
+
|
|
589
|
+
# The 12 bytes the native layout carries, in the host's byte order: the size (12), the
|
|
590
|
+
# flags and the pivot (0 for none), as u32s.
|
|
591
|
+
def packed
|
|
592
|
+
[self.class::PACKED_BYTES, flags, pivot || 0].pack("L3")
|
|
593
|
+
end
|
|
594
|
+
end
|
|
595
|
+
|
|
596
|
+
# `cast_date` also reads `yyyyMMdd`, eight ASCII digits.
|
|
597
|
+
DateOptions::COMPACT_DATE = 1
|
|
598
|
+
# `cast_timestamp` also reads a single space where the `T` goes.
|
|
599
|
+
DateOptions::SPACE_SEPARATOR = 2
|
|
600
|
+
# `cast_timestamp` also reads an offset of `±hh`, with no minutes (`+00`, `-05`).
|
|
601
|
+
DateOptions::HOUR_OFFSET = 4
|
|
602
|
+
# Every flag this version defines.
|
|
603
|
+
DateOptions::DEFINED = DateOptions::COMPACT_DATE | DateOptions::SPACE_SEPARATOR | DateOptions::HOUR_OFFSET
|
|
604
|
+
# The size of DateOptions#packed, the native layout, in bytes.
|
|
605
|
+
DateOptions::PACKED_BYTES = 12
|
|
606
|
+
# COMPACT_DATE, SPACE_SEPARATOR and HOUR_OFFSET together: the shapes real feeds mix with
|
|
607
|
+
# RFC 3339. It supplies no pivot and no month names (`COMMON_FORMS.with(pivot: 2029)` adds one).
|
|
608
|
+
DateOptions::COMMON_FORMS = DateOptions.new(flags: DateOptions::DEFINED)
|
|
609
|
+
|
|
610
|
+
# Declared month names for the doors that read a month field (#date with an order, and
|
|
611
|
+
# #datetime): "Jan", "janvier", "janv.". Built by the caller, never looked up for a locale —
|
|
612
|
+
# aliases, abbreviations and grammatical forms are the caller's decisions — from a Hash of
|
|
613
|
+
# name => month, or an Array of [month, name] pairs (the order the native layout packs them in).
|
|
614
|
+
# Passed as `months:` it replaces the numeric month field, in the position the declared field
|
|
615
|
+
# order selects and with the date's own `/`, `-` or `.` separator: "07-Jan-26" reads with a
|
|
616
|
+
# pivot, "7-Jan-2026" without one, and a vocabulary never reorders fields.
|
|
617
|
+
#
|
|
618
|
+
# Names match under simple case folding, the longest name followed by the separator winning;
|
|
619
|
+
# punctuation is part of a name and never stripped, so with "janv." declared and "." as the
|
|
620
|
+
# separator "7.janv..2026" reads and "7.janv.2026" is :malformed unless "janv" is declared too.
|
|
621
|
+
# The vocabulary rules, each an ArgumentError here: every entry a month 1 through 12 and a
|
|
622
|
+
# String with a UTF-8 form of 1 to 64 bytes holding no ASCII digit, "/", "-" or white space ("."
|
|
623
|
+
# is fine anywhere); every month named at least once; no two names equal under case folding,
|
|
624
|
+
# even for one month.
|
|
625
|
+
MonthNames = Data.define(:entries) do
|
|
626
|
+
# Judges the entries against the rules, then has the core judge the vocabulary once more
|
|
627
|
+
# (the one rule Ruby cannot restate is the core's simple case folding), through the date
|
|
628
|
+
# door: on the Fiddle backend that is a native call, so building a vocabulary raises a
|
|
629
|
+
# LoadError, as every door does, when the shared library is missing.
|
|
630
|
+
def initialize(entries:)
|
|
631
|
+
list = self.class.send(:judged, self.class.send(:pairs, entries))
|
|
632
|
+
@packed = self.class.send(:pack, list)
|
|
633
|
+
super(entries: list)
|
|
634
|
+
self.class.send(:core_judges, self)
|
|
635
|
+
end
|
|
636
|
+
|
|
637
|
+
# The vocabulary in the packed layout the native core reads: each entry a month byte, a
|
|
638
|
+
# little-endian u32 byte length and the name's UTF-8 bytes, with no padding.
|
|
639
|
+
def packed
|
|
640
|
+
@packed
|
|
641
|
+
end
|
|
642
|
+
|
|
643
|
+
# Marshal's form: the entries, so a loaded vocabulary is judged again as a new one is.
|
|
644
|
+
def marshal_dump
|
|
645
|
+
entries
|
|
646
|
+
end
|
|
647
|
+
|
|
648
|
+
# Restores a vocabulary from #marshal_dump's entries through #initialize.
|
|
649
|
+
def marshal_load(list)
|
|
650
|
+
initialize(entries: list)
|
|
651
|
+
end
|
|
652
|
+
|
|
653
|
+
# The vocabulary read from its packed layout (what #packed returns), judged by the same rules
|
|
654
|
+
# as one built from entries; an entry cut short or bytes trailing the last one is an
|
|
655
|
+
# ArgumentError, as is a name that is not UTF-8.
|
|
656
|
+
def self.from_packed(bytes)
|
|
657
|
+
raise ArgumentError, "packed month names must be a String; got #{bytes.inspect}" unless bytes.is_a?(String)
|
|
658
|
+
|
|
659
|
+
bytes = bytes.b
|
|
660
|
+
list = []
|
|
661
|
+
at = 0
|
|
662
|
+
while at < bytes.bytesize
|
|
663
|
+
head = bytes.byteslice(at, self::ENTRY_HEAD)
|
|
664
|
+
raise ArgumentError, "month names are cut short, or bytes trail the last entry" if
|
|
665
|
+
head.bytesize < self::ENTRY_HEAD
|
|
666
|
+
|
|
667
|
+
month, length = head.unpack("CL<")
|
|
668
|
+
# Measured before slicing: where a C long is 32 bits (Windows), byteslice raises RangeError
|
|
669
|
+
# for a declared length past 2^31 - 1.
|
|
670
|
+
raise ArgumentError, "month names are cut short, or bytes trail the last entry" if
|
|
671
|
+
length > bytes.bytesize - at - self::ENTRY_HEAD
|
|
672
|
+
|
|
673
|
+
name = bytes.byteslice(at + self::ENTRY_HEAD, length)
|
|
674
|
+
list << [month, name.force_encoding(Encoding::UTF_8)]
|
|
675
|
+
at += self::ENTRY_HEAD + length
|
|
676
|
+
end
|
|
677
|
+
new(entries: list)
|
|
678
|
+
end
|
|
679
|
+
|
|
680
|
+
# Entries as [month, name] pairs: from a Hash of name => month, or any Enumerable of pairs.
|
|
681
|
+
def self.pairs(entries)
|
|
682
|
+
case entries
|
|
683
|
+
when Hash then entries.map { |name, month| [month, name] }
|
|
684
|
+
else
|
|
685
|
+
raise ArgumentError, "month names must be a Hash or an Array of [month, name] pairs; " \
|
|
686
|
+
"got #{entries.inspect}" unless entries.respond_to?(:to_a)
|
|
687
|
+
|
|
688
|
+
entries.to_a.map do |pair|
|
|
689
|
+
raise ArgumentError, "a month name entry must be a [month, name] pair; got #{pair.inspect}" unless
|
|
690
|
+
pair.respond_to?(:to_ary) && pair.to_ary.size == 2
|
|
691
|
+
|
|
692
|
+
pair.to_ary
|
|
693
|
+
end
|
|
694
|
+
end
|
|
695
|
+
end
|
|
696
|
+
|
|
697
|
+
# The entries as frozen [month, UTF-8 name] pairs, once every rule holds, in the order the
|
|
698
|
+
# core meets them: each entry's month, UTF-8 form, length and characters; then each month's
|
|
699
|
+
# entry.
|
|
700
|
+
def self.judged(pairs)
|
|
701
|
+
list = pairs.map do |month, name|
|
|
702
|
+
raise ArgumentError, "month #{month.inspect} must be an Integer from 1 to 12" unless
|
|
703
|
+
month.is_a?(Integer) && month.between?(1, 12)
|
|
704
|
+
raise ArgumentError, "month name must be a String; got #{name.inspect}" unless name.is_a?(String)
|
|
705
|
+
|
|
706
|
+
text = name.encoding == Encoding::BINARY ? name.dup.force_encoding(Encoding::UTF_8) : name
|
|
707
|
+
text = HyperCast.send(:declared_utf8, "month name", text)
|
|
708
|
+
raise ArgumentError, "month name #{name.inspect} must be 1 to 64 UTF-8 bytes" unless
|
|
709
|
+
text.bytesize.between?(1, 64)
|
|
710
|
+
raise ArgumentError, "month name #{name.inspect} must not contain an ASCII digit, a slash, a hyphen " \
|
|
711
|
+
"or white space" if text.match?(%r{[0-9/-]|#{WHITE_SPACE.source}})
|
|
712
|
+
|
|
713
|
+
[month, text.dup.freeze].freeze
|
|
714
|
+
end
|
|
715
|
+
missing = (1..12).reject { |month| list.any? { |entry, _| entry == month } }
|
|
716
|
+
raise ArgumentError, "month names must name every month; none for #{missing.join(', ')}" unless missing.empty?
|
|
717
|
+
|
|
718
|
+
list.freeze
|
|
719
|
+
end
|
|
720
|
+
|
|
721
|
+
# The vocabulary in its packed layout, a frozen binary String.
|
|
722
|
+
def self.pack(list)
|
|
723
|
+
list.map { |month, name| [month, name.bytesize].pack("CL<") + name.b }.join.b.freeze
|
|
724
|
+
end
|
|
725
|
+
|
|
726
|
+
# The core's last word on a vocabulary Ruby accepted, which only a folded duplicate can
|
|
727
|
+
# still fail: the core's simple case folding is not String#downcase(:fold)'s full one.
|
|
728
|
+
def self.core_judges(names)
|
|
729
|
+
HyperCast.date("", :year_month_day, months: names)
|
|
730
|
+
rescue RefusedDeclaration
|
|
731
|
+
raise ArgumentError, "two month names fold to the same spelling"
|
|
732
|
+
end
|
|
733
|
+
private_class_method :pairs, :judged, :pack, :core_judges
|
|
734
|
+
end
|
|
735
|
+
|
|
736
|
+
# A declaration Ruby accepted and the core refused: date options or month names that passed
|
|
737
|
+
# their own checks and still broke a rule only the core judges (a folded duplicate), or that
|
|
738
|
+
# were built without going through their constructors (Data#allocate, Marshal). The
|
|
739
|
+
# constructors turn it into the ArgumentError they document; a door raises it as it is.
|
|
740
|
+
class RefusedDeclaration < ArgumentError; end
|
|
741
|
+
|
|
742
|
+
# The bytes an entry takes before its name in MonthNames#packed: the month byte and the length.
|
|
743
|
+
MonthNames::ENTRY_HEAD = 5
|
|
744
|
+
|
|
329
745
|
# An exact decimal, the decimal door's value: an unbounded Integer magnitude (the core's
|
|
330
746
|
# 96-bit unsigned, so at most 2**96 - 1), an Integer base-10 scale (0..28 — the number of
|
|
331
747
|
# places the magnitude is shifted right), and a negative flag. The value is
|
|
@@ -366,6 +782,363 @@ module HyperCast
|
|
|
366
782
|
end
|
|
367
783
|
end
|
|
368
784
|
|
|
785
|
+
# The doors a Constraints can be bound to, mapped to the native core's door codes: the
|
|
786
|
+
# integer, real and decimal doors, and :text.
|
|
787
|
+
CHECKED_DOORS = {
|
|
788
|
+
i8: 2, i16: 3, i32: 4, i64: 5, u8: 6, u16: 7, u32: 8, u64: 9, f32: 10, f64: 11, text: 18, decimal: 19
|
|
789
|
+
}.freeze
|
|
790
|
+
|
|
791
|
+
# Every door that reads text, by name, mapped to the native core's door code (the numbering
|
|
792
|
+
# of its detailed exports).
|
|
793
|
+
DETAILED_DOORS = {
|
|
794
|
+
bool: 1, i8: 2, i16: 3, i32: 4, i64: 5, u8: 6, u16: 7, u32: 8, u64: 9, f32: 10, f64: 11, uuid: 12,
|
|
795
|
+
timestamp: 13, unix: 14, date: 15, time: 16, duration: 17, text: 18, decimal: 19, date_ordered: 20,
|
|
796
|
+
datetime: 21, excel_serial: 22, char: 23
|
|
797
|
+
}.freeze
|
|
798
|
+
|
|
799
|
+
# What a value that is not a multiple of a declared multiple_of becomes, mapped to the
|
|
800
|
+
# native core's rounding codes: :strict (a :multiple_of Violation, the default), :midpoint
|
|
801
|
+
# (the nearest multiple, ties to even), :floor (toward negative infinity) and :ceiling
|
|
802
|
+
# (toward positive infinity). An unknown rounding is a caller bug (KeyError).
|
|
803
|
+
ROUNDINGS = { strict: 0, midpoint: 1, floor: 2, ceiling: 3 }.freeze
|
|
804
|
+
|
|
805
|
+
# The success case of a checked door: the value (rounded to multiple_of when the declaration
|
|
806
|
+
# rounds; at the :text door with an enum, the very String the declaration was given),
|
|
807
|
+
# adjusted (true only when rounding changed the value) and, at the :text door with an enum,
|
|
808
|
+
# the index of the entry matched — nil otherwise, a numeric enum included, where the value
|
|
809
|
+
# is the answer.
|
|
810
|
+
Checked = Data.define(:value, :adjusted, :enum_index)
|
|
811
|
+
|
|
812
|
+
# A value that cast and broke a declared rule: the Keyword broken, the value exactly as the
|
|
813
|
+
# door cast it (in the door's own type, as a Checked's value is, and never rounded: a
|
|
814
|
+
# rounding is part of the judgement, not of the value; at :text the judged String, after
|
|
815
|
+
# trim, never an enum entry) and the value's span, in the units a Fault's span is in
|
|
816
|
+
# (characters for text, bytes for a binary String). A number the caller already held has no
|
|
817
|
+
# text, and an empty span. A Fault means the input is not the door's type at all; a
|
|
818
|
+
# Violation means it is, and breaks a rule.
|
|
819
|
+
Violation = Data.define(:keyword, :value, :offset, :length)
|
|
820
|
+
|
|
821
|
+
# The rule a Violation broke: the native core's code, named the OpenAPI way by #name
|
|
822
|
+
# ("exclusiveMinimum"). Open to additions — format and pattern may join in a minor release —
|
|
823
|
+
# so a case over keywords needs an else branch; a code this gem does not name yet is kept,
|
|
824
|
+
# its name "keyword N". The constants (Keyword::MINIMUM ... Keyword::ENUM) compare equal to
|
|
825
|
+
# every keyword of their code, so `in Violation(keyword: Keyword::MINIMUM)` matches.
|
|
826
|
+
Keyword = Data.define(:code) do
|
|
827
|
+
# The OpenAPI spelling: "minimum", "exclusiveMinimum", ... "enum"; "keyword N" for a code
|
|
828
|
+
# this gem does not name.
|
|
829
|
+
def name
|
|
830
|
+
self.class::NAMES.fetch(code) { "keyword #{code}" }
|
|
831
|
+
end
|
|
832
|
+
|
|
833
|
+
alias_method :to_s, :name
|
|
834
|
+
|
|
835
|
+
# The constant that names this keyword (HyperCast::Keyword::MINIMUM), or the Data form
|
|
836
|
+
# for a code this gem does not name.
|
|
837
|
+
def inspect
|
|
838
|
+
constant = self.class::CONSTANTS[code]
|
|
839
|
+
constant ? "HyperCast::Keyword::#{constant}" : super
|
|
840
|
+
end
|
|
841
|
+
end
|
|
842
|
+
|
|
843
|
+
# The OpenAPI spelling of each keyword the core names, by code.
|
|
844
|
+
Keyword::NAMES = {
|
|
845
|
+
1 => "minimum", 2 => "exclusiveMinimum", 3 => "maximum", 4 => "exclusiveMaximum", 5 => "multipleOf",
|
|
846
|
+
6 => "minLength", 7 => "maxLength", 8 => "enum"
|
|
847
|
+
}.freeze
|
|
848
|
+
|
|
849
|
+
# The constant each named keyword is published as, by code.
|
|
850
|
+
Keyword::CONSTANTS = {
|
|
851
|
+
1 => "MINIMUM", 2 => "EXCLUSIVE_MINIMUM", 3 => "MAXIMUM", 4 => "EXCLUSIVE_MAXIMUM", 5 => "MULTIPLE_OF",
|
|
852
|
+
6 => "MIN_LENGTH", 7 => "MAX_LENGTH", 8 => "ENUM"
|
|
853
|
+
}.freeze
|
|
854
|
+
|
|
855
|
+
# `minimum`, broken by a value below it.
|
|
856
|
+
Keyword::MINIMUM = Keyword.new(code: 1)
|
|
857
|
+
# `exclusiveMinimum`, broken by a value at or below it.
|
|
858
|
+
Keyword::EXCLUSIVE_MINIMUM = Keyword.new(code: 2)
|
|
859
|
+
# `maximum`, broken by a value above it.
|
|
860
|
+
Keyword::MAXIMUM = Keyword.new(code: 3)
|
|
861
|
+
# `exclusiveMaximum`, broken by a value at or above it.
|
|
862
|
+
Keyword::EXCLUSIVE_MAXIMUM = Keyword.new(code: 4)
|
|
863
|
+
# `multipleOf`, broken by a value that is not a multiple of it under :strict rounding.
|
|
864
|
+
Keyword::MULTIPLE_OF = Keyword.new(code: 5)
|
|
865
|
+
# `minLength`, broken by text of fewer code points.
|
|
866
|
+
Keyword::MIN_LENGTH = Keyword.new(code: 6)
|
|
867
|
+
# `maxLength`, broken by text of more code points.
|
|
868
|
+
Keyword::MAX_LENGTH = Keyword.new(code: 7)
|
|
869
|
+
# `enum`, broken by a value that is none of the entries.
|
|
870
|
+
Keyword::ENUM = Keyword.new(code: 8)
|
|
871
|
+
|
|
872
|
+
# Validation constraints — the OpenAPI 3.2 Schema Object's keywords — bound to one door and
|
|
873
|
+
# judged once, by the native core, when built: every declaration OpenAPI allows is accepted,
|
|
874
|
+
# an unsatisfiable one included (crossed bounds, an empty enum: every value then violates
|
|
875
|
+
# it), and a keyword for another type is ignored, as JSON Schema ignores it. What the core
|
|
876
|
+
# refuses is an ArgumentError here, its message the rule it breaks ("Constraints refused
|
|
877
|
+
# (code 5): multipleOf is not positive."), and every checked cast after that judges only
|
|
878
|
+
# data. The door is required: no declaration ever silently means "no rules", and
|
|
879
|
+
# `Constraints.new(door: :f64)` is an explicit, empty one.
|
|
880
|
+
#
|
|
881
|
+
# The numeric doors take minimum, exclusive_minimum, maximum and exclusive_maximum (four
|
|
882
|
+
# independent keywords, all four together if declared so), multiple_of with a rounding (a
|
|
883
|
+
# ROUNDINGS Symbol), and enum, matched exactly against the value; :text min_length,
|
|
884
|
+
# max_length (in code points), enum (matched under simple case folding unless
|
|
885
|
+
# case_sensitive: true, which compares byte for byte), and HyperCast's own extensions trim
|
|
886
|
+
# (of Unicode White_Space) and case_sensitive. Every keyword is accepted at every door; the
|
|
887
|
+
# core alone refuses trim, case_sensitive or a rounding where they mean nothing.
|
|
888
|
+
#
|
|
889
|
+
# A bound, step or numeric enum entry is an Integer, a BigDecimal, a String in invariant
|
|
890
|
+
# notation ("0.000001", "-90", "1e-6") or this gem's own Decimal, and crosses the core's own
|
|
891
|
+
# conversion (HyperCast.declared_decimal): never a Float, since 0.1 has no exact binary form
|
|
892
|
+
# and a Float could only declare a neighbour of the value meant. Bounds are kept as the exact
|
|
893
|
+
# Decimal declared. A text enum entry is a String, kept as the very object given when it is
|
|
894
|
+
# frozen and as a frozen copy when it is not, so a match delivers what the core judged. An
|
|
895
|
+
# enum left nil declares none, while `enum: []` declares one no value matches. With
|
|
896
|
+
# duplicate entries, the first match wins.
|
|
897
|
+
#
|
|
898
|
+
# latitude = HyperCast::Constraints.new(door: :f64, minimum: "-90", maximum: "90")
|
|
899
|
+
# HyperCast.checked("91", HyperCast::NumFormat::INVARIANT, latitude)
|
|
900
|
+
# # => #<data HyperCast::Violation keyword=HyperCast::Keyword::MAXIMUM, value=91.0, offset=0, length=2>
|
|
901
|
+
Constraints = Data.define(:door, :minimum, :exclusive_minimum, :maximum, :exclusive_maximum, :multiple_of,
|
|
902
|
+
:rounding, :min_length, :max_length, :trim, :case_sensitive, :enum) do
|
|
903
|
+
# Validates every keyword's type, converts the bounds, steps and numeric entries through
|
|
904
|
+
# the core, and has the core judge the declaration; a refusal is an ArgumentError worded
|
|
905
|
+
# from its code. A wrong type is an ArgumentError, an unknown door or rounding a KeyError.
|
|
906
|
+
def initialize(door:, minimum: nil, exclusive_minimum: nil, maximum: nil, exclusive_maximum: nil,
|
|
907
|
+
multiple_of: nil, rounding: :strict, min_length: nil, max_length: nil, trim: false,
|
|
908
|
+
case_sensitive: false, enum: nil)
|
|
909
|
+
keywords = { door: door, minimum: minimum, exclusive_minimum: exclusive_minimum, maximum: maximum,
|
|
910
|
+
exclusive_maximum: exclusive_maximum, multiple_of: multiple_of, rounding: rounding,
|
|
911
|
+
min_length: min_length, max_length: max_length, trim: trim, case_sensitive: case_sensitive,
|
|
912
|
+
enum: enum }
|
|
913
|
+
code = HyperCast.constraints_check(**keywords)
|
|
914
|
+
raise ArgumentError, self.class.send(:refusal, code) unless code.zero?
|
|
915
|
+
|
|
916
|
+
super(**self.class.send(:members_of, **keywords))
|
|
917
|
+
end
|
|
918
|
+
|
|
919
|
+
# The 104 bytes this declaration crosses a C ABI as, in the native byte order the core
|
|
920
|
+
# reads in place: the size (104), the flags, the rounding code, min_length, max_length and
|
|
921
|
+
# a reserved zero as u32s, then minimum, maximum, multiple_of, exclusive_minimum and
|
|
922
|
+
# exclusive_maximum as 16-byte decimals (the low 64 and high 32 bits of the magnitude, the
|
|
923
|
+
# scale, the sign, two zero bytes) — for a gem that judges values across a C ABI of its
|
|
924
|
+
# own, with #packed_enum beside it.
|
|
925
|
+
def packed
|
|
926
|
+
self.class.send(:pack_raw, to_h)
|
|
927
|
+
end
|
|
928
|
+
|
|
929
|
+
# The enum list as the core reads it beside #packed, "" for none (read only when the
|
|
930
|
+
# flags in #packed carry HAS_ENUM, 256, set whenever an enum is declared): at a numeric
|
|
931
|
+
# door 16-byte decimals in native byte order, at :text each entry a little-endian u32 byte
|
|
932
|
+
# length followed by its UTF-8.
|
|
933
|
+
def packed_enum
|
|
934
|
+
self.class.send(:pack_enum, to_h)
|
|
935
|
+
end
|
|
936
|
+
|
|
937
|
+
# The message a refused declaration raises with, one per refusal code; a code this gem
|
|
938
|
+
# does not name is worded as every binding words it.
|
|
939
|
+
def self.refusal(code)
|
|
940
|
+
"Constraints refused (code #{code}): #{self::REFUSALS.fetch(code, 'a rule this binding does not name')}."
|
|
941
|
+
end
|
|
942
|
+
|
|
943
|
+
# The declaration as both backends hand it to the core: the door code, #packed and
|
|
944
|
+
# #packed_enum. Judged again here, once per object (each backend remembers the answer),
|
|
945
|
+
# because a Constraints can exist without Constraints.new having judged it: one never
|
|
946
|
+
# built (Data's allocate) has no door, and one restored by Marshal from a payload in the
|
|
947
|
+
# Struct form sets its members directly. Either is the caller's bug, raised as
|
|
948
|
+
# Constraints.new raises it, never a declaration of no rules.
|
|
949
|
+
def declaration
|
|
950
|
+
raise ArgumentError, "this HyperCast::Constraints was never built: declare it with Constraints.new(door: ...)" if
|
|
951
|
+
door.nil?
|
|
952
|
+
|
|
953
|
+
code = HyperCast.constraints_check(**to_h)
|
|
954
|
+
raise ArgumentError, self.class.send(:refusal, code) unless code.zero?
|
|
955
|
+
|
|
956
|
+
[CHECKED_DOORS.fetch(door), packed, packed_enum]
|
|
957
|
+
end
|
|
958
|
+
private :declaration
|
|
959
|
+
|
|
960
|
+
# Marshal's form of a declaration: its members, so loading one builds it through
|
|
961
|
+
# #initialize, judged as Constraints.new judges it.
|
|
962
|
+
def marshal_dump
|
|
963
|
+
to_h
|
|
964
|
+
end
|
|
965
|
+
|
|
966
|
+
# Restores a declaration from #marshal_dump's members through #initialize, so a payload
|
|
967
|
+
# that declares something the core refuses raises its refusal.
|
|
968
|
+
def marshal_load(members)
|
|
969
|
+
initialize(**members)
|
|
970
|
+
end
|
|
971
|
+
|
|
972
|
+
# The declaration HyperCast.constraints_check judges: its door code, packed layout and
|
|
973
|
+
# packed enum, or the code 8 the conversion of a bound, step or entry was refused with.
|
|
974
|
+
def self.layout(**keywords)
|
|
975
|
+
members = members_of(**keywords)
|
|
976
|
+
return members if members.is_a?(Integer)
|
|
977
|
+
|
|
978
|
+
[CHECKED_DOORS.fetch(members[:door]), pack_raw(members), pack_enum(members)]
|
|
979
|
+
end
|
|
980
|
+
|
|
981
|
+
# Every keyword validated and converted — a declaration's members — or the code 8 a
|
|
982
|
+
# conversion was refused with.
|
|
983
|
+
def self.members_of(door:, minimum: nil, exclusive_minimum: nil, maximum: nil, exclusive_maximum: nil,
|
|
984
|
+
multiple_of: nil, rounding: :strict, min_length: nil, max_length: nil, trim: false,
|
|
985
|
+
case_sensitive: false, enum: nil)
|
|
986
|
+
CHECKED_DOORS.fetch(door)
|
|
987
|
+
ROUNDINGS.fetch(rounding)
|
|
988
|
+
raise ArgumentError, "trim must be true or false; got #{trim.inspect}" unless [true, false].include?(trim)
|
|
989
|
+
raise ArgumentError, "case_sensitive must be true or false; got #{case_sensitive.inspect}" unless
|
|
990
|
+
[true, false].include?(case_sensitive)
|
|
991
|
+
|
|
992
|
+
bounds = { minimum: minimum, exclusive_minimum: exclusive_minimum, maximum: maximum,
|
|
993
|
+
exclusive_maximum: exclusive_maximum, multiple_of: multiple_of }
|
|
994
|
+
bounds.each do |name, value|
|
|
995
|
+
next if value.nil?
|
|
996
|
+
|
|
997
|
+
bounds[name] = exact(name, value)
|
|
998
|
+
return bounds[name] if bounds[name].is_a?(Integer)
|
|
999
|
+
end
|
|
1000
|
+
entries = entries_of(door, enum)
|
|
1001
|
+
return entries if entries.is_a?(Integer)
|
|
1002
|
+
|
|
1003
|
+
{ door: door, **bounds, rounding: rounding, min_length: length("min_length", min_length),
|
|
1004
|
+
max_length: length("max_length", max_length), trim: trim, case_sensitive: case_sensitive, enum: entries }
|
|
1005
|
+
end
|
|
1006
|
+
|
|
1007
|
+
# A bound, step or numeric enum entry as the core converts it: an Integer, a BigDecimal,
|
|
1008
|
+
# a String or a Decimal, each through its text and HyperCast.declared_decimal — the exact
|
|
1009
|
+
# Decimal, or the code 8 it was refused with. Never a Float, nor true or false.
|
|
1010
|
+
def self.exact(name, value)
|
|
1011
|
+
text =
|
|
1012
|
+
case value
|
|
1013
|
+
when Integer, String, Decimal then value.to_s
|
|
1014
|
+
else
|
|
1015
|
+
raise ArgumentError, "#{name} must be an Integer, a BigDecimal, a String or a HyperCast::Decimal; got " \
|
|
1016
|
+
"#{value.inspect}#{hint(value)}" unless defined?(BigDecimal) && value.is_a?(BigDecimal)
|
|
1017
|
+
|
|
1018
|
+
value.to_s("F")
|
|
1019
|
+
end
|
|
1020
|
+
begin
|
|
1021
|
+
HyperCast.declared_decimal(text)
|
|
1022
|
+
rescue ArgumentError
|
|
1023
|
+
8
|
|
1024
|
+
end
|
|
1025
|
+
end
|
|
1026
|
+
|
|
1027
|
+
# Why a Float is refused, beside the refusal.
|
|
1028
|
+
def self.hint(value)
|
|
1029
|
+
return "" unless value.is_a?(Float)
|
|
1030
|
+
|
|
1031
|
+
" (a Float holds most decimals only approximately: write it as a String or a BigDecimal)"
|
|
1032
|
+
end
|
|
1033
|
+
|
|
1034
|
+
# A declared length: nil, or an Integer in the 32 unsigned bits the core counts code
|
|
1035
|
+
# points in (never true or false, nor a Float).
|
|
1036
|
+
def self.length(name, value)
|
|
1037
|
+
return nil if value.nil?
|
|
1038
|
+
raise ArgumentError, "#{name} must be an Integer from 0 to #{0xFFFF_FFFF}; got #{value.inspect}" unless
|
|
1039
|
+
value.is_a?(Integer) && value.between?(0, 0xFFFF_FFFF)
|
|
1040
|
+
|
|
1041
|
+
value
|
|
1042
|
+
end
|
|
1043
|
+
|
|
1044
|
+
# The enum entries, frozen, as a declaration keeps them: at :text the caller's own
|
|
1045
|
+
# Strings, elsewhere each entry's exact Decimal (or the code 8 one was refused with); nil
|
|
1046
|
+
# for none. An empty list is declared: one no value matches.
|
|
1047
|
+
def self.entries_of(door, enum)
|
|
1048
|
+
return nil if enum.nil?
|
|
1049
|
+
raise ArgumentError, "enum must be an Array of entries; got #{enum.inspect}" unless
|
|
1050
|
+
enum.respond_to?(:to_a) && !enum.is_a?(String)
|
|
1051
|
+
|
|
1052
|
+
entries = enum.to_a
|
|
1053
|
+
if door == :text
|
|
1054
|
+
entries = entries.each_with_index.map do |entry, index|
|
|
1055
|
+
# A number is a valid entry that no String equals (JSON Schema's enum is exact
|
|
1056
|
+
# equality across types): kept as given, and packed empty by pack_enum.
|
|
1057
|
+
next entry if number_entry?(entry)
|
|
1058
|
+
|
|
1059
|
+
raise ArgumentError, "enum entries at :text must be Strings, or numbers (an Integer, a BigDecimal or a " \
|
|
1060
|
+
"HyperCast::Decimal), which never match; entry #{index} is #{entry.inspect}" unless
|
|
1061
|
+
entry.is_a?(String)
|
|
1062
|
+
|
|
1063
|
+
# A Hash key's rule: a frozen String is kept as itself, a mutable one as a frozen
|
|
1064
|
+
# copy, so what a match delivers is always what the core judged.
|
|
1065
|
+
entry.frozen? ? entry : entry.dup.freeze
|
|
1066
|
+
end
|
|
1067
|
+
else
|
|
1068
|
+
entries = entries.map do |entry|
|
|
1069
|
+
decimal = exact("enum entry", entry)
|
|
1070
|
+
return decimal if decimal.is_a?(Integer)
|
|
1071
|
+
|
|
1072
|
+
decimal
|
|
1073
|
+
end
|
|
1074
|
+
end
|
|
1075
|
+
entries.freeze
|
|
1076
|
+
end
|
|
1077
|
+
|
|
1078
|
+
# A declaration's members as the 104-byte native layout #packed describes: each bound in
|
|
1079
|
+
# a slot of its own.
|
|
1080
|
+
def self.pack_raw(members)
|
|
1081
|
+
flags = self::FLAGS.sum { |member, flag| members[member].nil? ? 0 : flag }
|
|
1082
|
+
flags |= 128 if members[:trim]
|
|
1083
|
+
flags |= 512 if members[:case_sensitive]
|
|
1084
|
+
decimals = members.values_at(:minimum, :maximum, :multiple_of, :exclusive_minimum, :exclusive_maximum)
|
|
1085
|
+
[self::PACKED_BYTES, flags, ROUNDINGS.fetch(members[:rounding]), members[:min_length] || 0,
|
|
1086
|
+
members[:max_length] || 0, 0].pack("L6") + decimals.map { |decimal| pack_decimal(decimal) }.join
|
|
1087
|
+
end
|
|
1088
|
+
|
|
1089
|
+
# One Decimal in the core's native 16-byte layout; zero for nil.
|
|
1090
|
+
def self.pack_decimal(decimal)
|
|
1091
|
+
return [0, 0, 0, 0].pack("QLCCx2") if decimal.nil?
|
|
1092
|
+
|
|
1093
|
+
magnitude = decimal.magnitude
|
|
1094
|
+
[magnitude & 0xFFFF_FFFF_FFFF_FFFF, magnitude >> 64, decimal.scale, decimal.negative ? 1 : 0].pack("QLCCx2")
|
|
1095
|
+
end
|
|
1096
|
+
|
|
1097
|
+
# Whether a text enum entry is a number: valid, and never matched.
|
|
1098
|
+
def self.number_entry?(entry)
|
|
1099
|
+
entry.is_a?(Integer) || entry.is_a?(Decimal) || (defined?(BigDecimal) && entry.is_a?(BigDecimal))
|
|
1100
|
+
end
|
|
1101
|
+
|
|
1102
|
+
# A declaration's enum as #packed_enum describes it, a binary String.
|
|
1103
|
+
def self.pack_enum(members)
|
|
1104
|
+
entries = members[:enum] or return "".b
|
|
1105
|
+
return entries.map { |entry| pack_decimal(entry) }.join.b unless members[:door] == :text
|
|
1106
|
+
|
|
1107
|
+
# Each entry as input text crosses (HyperCast.utf8): one with no UTF-8 form is then
|
|
1108
|
+
# refused as an entry that is not UTF-8 (9), never transcoded with a guess.
|
|
1109
|
+
entries.map do |entry|
|
|
1110
|
+
# A number packs as an empty entry, which no input matches (empty input is the door's
|
|
1111
|
+
# Empty fault), so every other entry keeps its index.
|
|
1112
|
+
next [0].pack("L<") unless entry.is_a?(String)
|
|
1113
|
+
|
|
1114
|
+
text = HyperCast.send(:utf8, entry)
|
|
1115
|
+
[text.bytesize].pack("L<") + text.b
|
|
1116
|
+
end.join.b
|
|
1117
|
+
end
|
|
1118
|
+
|
|
1119
|
+
private_class_method :refusal, :layout, :members_of, :exact, :hint, :length, :entries_of, :number_entry?, :pack_raw,
|
|
1120
|
+
:pack_decimal, :pack_enum
|
|
1121
|
+
end
|
|
1122
|
+
|
|
1123
|
+
# The flag each declared member sets in the packed layout, HAS_ENUM (256) by an enum even
|
|
1124
|
+
# with no entries; TRIM (128) is set by trim and CASE_SENSITIVE (512) by case_sensitive.
|
|
1125
|
+
Constraints::FLAGS = { minimum: 1, exclusive_minimum: 2, maximum: 4, exclusive_maximum: 8, multiple_of: 16,
|
|
1126
|
+
min_length: 32, max_length: 64, enum: 256 }.freeze
|
|
1127
|
+
|
|
1128
|
+
# The size of Constraints#packed, the native RawConstraints layout, in bytes.
|
|
1129
|
+
Constraints::PACKED_BYTES = 104
|
|
1130
|
+
|
|
1131
|
+
# The words a refused declaration's message gives, one per code: the native core's own. The
|
|
1132
|
+
# codes between belonged to refusals of declarations OpenAPI allows; they are retired.
|
|
1133
|
+
Constraints::REFUSALS = {
|
|
1134
|
+
1 => "a constraint the door does not take",
|
|
1135
|
+
5 => "multipleOf is not positive",
|
|
1136
|
+
6 => "a rounding without multipleOf",
|
|
1137
|
+
8 => "a bound, step or enum entry the door cannot hold",
|
|
1138
|
+
9 => "an enum entry that is not UTF-8",
|
|
1139
|
+
11 => "a malformed constraints layout"
|
|
1140
|
+
}.freeze
|
|
1141
|
+
|
|
369
1142
|
class << self
|
|
370
1143
|
# Presents a verdict optionally: an :empty fault becomes nil (Ruby's absent),
|
|
371
1144
|
# everything else flows through untouched.
|
|
@@ -391,28 +1164,36 @@ module HyperCast
|
|
|
391
1164
|
false
|
|
392
1165
|
end
|
|
393
1166
|
end
|
|
1167
|
+
end
|
|
394
1168
|
|
|
1169
|
+
# The doors, the Fiddle way. They live in a module HyperCast extends rather than on its
|
|
1170
|
+
# singleton class, so the Magnus extension's define_singleton_method puts its definition on
|
|
1171
|
+
# the singleton class in front of them: an override through the ancestor chain, not a
|
|
1172
|
+
# redefinition, and `ruby -w` has nothing to say about it (1.0.0 defined them on the
|
|
1173
|
+
# singleton class and printed "method redefined" twice per door on every require under -w).
|
|
1174
|
+
# Lookup is unchanged either way: the singleton class first, then this module, so with the
|
|
1175
|
+
# extension loaded no call ever reaches these. Their helpers stay private on HyperCast.
|
|
1176
|
+
module FiddleBackend
|
|
395
1177
|
# Casts boolean text: true/false plus the conventions untrusted sources actually send
|
|
396
1178
|
# (t/f, yes/no, y/n, 1/0, on/off, enabled/disabled, active/inactive,
|
|
397
1179
|
# checked/unchecked, in/out), ASCII case-insensitive.
|
|
398
1180
|
def bool(text)
|
|
399
|
-
|
|
1181
|
+
crossing(1, 0, text, 1) { |out| Interop.decode(:bool, out) }
|
|
400
1182
|
end
|
|
401
1183
|
|
|
402
1184
|
# Casts char text to a one-character UTF-8 String: an input of exactly one character is
|
|
403
1185
|
# that character verbatim (" " is a space), otherwise one declared code point — 65,
|
|
404
|
-
# U+0041, 0x41, &H41, A or A — surrounded by optional
|
|
1186
|
+
# U+0041, 0x41, &H41, A or A — surrounded by optional white space. A code
|
|
405
1187
|
# point past U+10FFFF, or a surrogate, is :out_of_range.
|
|
406
1188
|
def char(text)
|
|
407
|
-
|
|
1189
|
+
crossing(23, 0, text, 4) { |out| Interop.decode(:char, out) }
|
|
408
1190
|
end
|
|
409
1191
|
|
|
410
1192
|
%i[i8 i16 i32 i64 u8 u16 u32 u64].each do |door|
|
|
411
1193
|
unpack = Interop::SCALARS.fetch(door)
|
|
412
1194
|
size = Interop::VALUE_BYTES.fetch(door)
|
|
413
|
-
# Resolved once here, not inside the method
|
|
414
|
-
|
|
415
|
-
symbol = :"cast_#{door}"
|
|
1195
|
+
# Resolved once here, not inside the method.
|
|
1196
|
+
code = DETAILED_DOORS.fetch(door)
|
|
416
1197
|
# Integer doors: the target type's own range, declared grouping, accounting parens,
|
|
417
1198
|
# non-negative exponent, and 0x/&H/0b two's-complement radix prefixes. Ruby Integer
|
|
418
1199
|
# is unbounded, so u64 comes back as the true unsigned value. separator:, delimiter:
|
|
@@ -420,7 +1201,7 @@ module HyperCast
|
|
|
420
1201
|
define_method(door) do |text, format, separator: nil, delimiter: nil, unit: nil|
|
|
421
1202
|
format = format.override(separator: separator, delimiter: delimiter, unit: unit) if
|
|
422
1203
|
separator || delimiter || unit
|
|
423
|
-
|
|
1204
|
+
crossing(code, 0, text, size, format) { |out| out.unpack1(unpack) }
|
|
424
1205
|
end
|
|
425
1206
|
end
|
|
426
1207
|
|
|
@@ -431,14 +1212,14 @@ module HyperCast
|
|
|
431
1212
|
def f32(text, format, separator: nil, delimiter: nil, unit: nil)
|
|
432
1213
|
format = format.override(separator: separator, delimiter: delimiter, unit: unit) if
|
|
433
1214
|
separator || delimiter || unit
|
|
434
|
-
|
|
1215
|
+
crossing(10, 0, text, 4, format) { |out| Interop.decode(:f32, out) }
|
|
435
1216
|
end
|
|
436
1217
|
|
|
437
1218
|
# Casts real text to an IEEE double. Notation rules as f32.
|
|
438
1219
|
def f64(text, format, separator: nil, delimiter: nil, unit: nil)
|
|
439
1220
|
format = format.override(separator: separator, delimiter: delimiter, unit: unit) if
|
|
440
1221
|
separator || delimiter || unit
|
|
441
|
-
|
|
1222
|
+
crossing(11, 0, text, 8, format) { |out| Interop.decode(:f64, out) }
|
|
442
1223
|
end
|
|
443
1224
|
|
|
444
1225
|
# Casts decimal text to an exact Decimal — the real doors' grammar (declared separators
|
|
@@ -450,27 +1231,30 @@ module HyperCast
|
|
|
450
1231
|
def decimal(text, format, separator: nil, delimiter: nil, unit: nil)
|
|
451
1232
|
format = format.override(separator: separator, delimiter: delimiter, unit: unit) if
|
|
452
1233
|
separator || delimiter || unit
|
|
453
|
-
|
|
1234
|
+
crossing(19, 0, text, 16, format) { |out| Interop.decode(:decimal, out) }
|
|
454
1235
|
end
|
|
455
1236
|
|
|
456
1237
|
# Casts UUID text — all five .NET Guid formats (D/N/B/P/X) plus urn:uuid:/GUID:/UUID:
|
|
457
1238
|
# prefixes — to Ruby's UUID lingua franca: the lowercase hyphenated String (the same
|
|
458
1239
|
# shape SecureRandom.uuid returns).
|
|
459
1240
|
def uuid(text)
|
|
460
|
-
|
|
1241
|
+
crossing(12, 0, text, 16) { |out| Interop.decode(:uuid, out) }
|
|
461
1242
|
end
|
|
462
1243
|
|
|
463
1244
|
# Casts an RFC 3339 instant — zone mandatory — to a UTC Time at full nanosecond
|
|
464
|
-
# fidelity across the whole 0001-9999 window.
|
|
465
|
-
|
|
466
|
-
|
|
1245
|
+
# fidelity across the whole 0001-9999 window. options: (a DateOptions) opens the shapes
|
|
1246
|
+
# RFC 3339 itself does not have, each only when asked for: SPACE_SEPARATOR a space where the
|
|
1247
|
+
# T goes, HOUR_OFFSET an offset of ±hh ("+00"); other options are ignored here.
|
|
1248
|
+
def timestamp(text, options: nil)
|
|
1249
|
+
dated(options, nil)
|
|
1250
|
+
crossing(13, 0, text, 16, nil, nil, options) { |out| Interop.decode(:timestamp, out) }
|
|
467
1251
|
end
|
|
468
1252
|
|
|
469
1253
|
# Casts an integer Unix-epoch value under a caller-declared unit Symbol
|
|
470
1254
|
# (:seconds/:milliseconds/:microseconds/:nanoseconds) to a UTC Time. An unknown unit
|
|
471
1255
|
# is a caller bug (KeyError), never a verdict.
|
|
472
1256
|
def unix(text, precision)
|
|
473
|
-
|
|
1257
|
+
crossing(14, UNIX_PRECISIONS.fetch(precision), text, 16) { |out| Interop.decode(:unix, out) }
|
|
474
1258
|
end
|
|
475
1259
|
|
|
476
1260
|
# Casts an Excel date serial under a caller-declared epoch Symbol (:y1900/:y1904) to a
|
|
@@ -484,7 +1268,7 @@ module HyperCast
|
|
|
484
1268
|
# the text "1900-02-29" — so every serial above it is shifted one day against a naive
|
|
485
1269
|
# count. An unknown epoch is a caller bug (KeyError), never a verdict.
|
|
486
1270
|
def excel_serial(text, epoch)
|
|
487
|
-
|
|
1271
|
+
crossing(22, EXCEL_EPOCHS.fetch(epoch), text, 16) { |out| Interop.decode(:excel_serial, out) }
|
|
488
1272
|
end
|
|
489
1273
|
|
|
490
1274
|
# Casts a calendar date to a Date. With no order declared: the strict ISO 8601
|
|
@@ -492,11 +1276,19 @@ module HyperCast
|
|
|
492
1276
|
# :month_day_year, :day_month_year), also the separated forms — "1/7/2026" is
|
|
493
1277
|
# January 7th or July 1st only because the caller said which; an unknown order is a
|
|
494
1278
|
# caller bug (KeyError), never a verdict.
|
|
495
|
-
|
|
1279
|
+
#
|
|
1280
|
+
# options: (a DateOptions) opens shapes only when asked for: COMPACT_DATE, "20260107", at the
|
|
1281
|
+
# ISO form; the pivot, two-digit years ("1/7/26"), with an order. months: (a MonthNames) opens
|
|
1282
|
+
# declared month names in the month field ("7-Jan-2026") with an order. Options a form does
|
|
1283
|
+
# not read are ignored.
|
|
1284
|
+
def date(text, order = nil, options: nil, months: nil)
|
|
1285
|
+
dated(options, months)
|
|
496
1286
|
if order.nil?
|
|
497
|
-
|
|
1287
|
+
crossing(15, 0, text, 4, nil, nil, options) { |out| Interop.decode(:date, out) }
|
|
498
1288
|
else
|
|
499
|
-
|
|
1289
|
+
crossing(20, DATE_ORDERS.fetch(order), text, 4, nil, nil, options, months) do |out|
|
|
1290
|
+
Interop.decode(:date_ordered, out)
|
|
1291
|
+
end
|
|
500
1292
|
end
|
|
501
1293
|
end
|
|
502
1294
|
|
|
@@ -512,30 +1304,36 @@ module HyperCast
|
|
|
512
1304
|
# A 12-hour clock's AM/PM is read, before or after the clock ("3:04 PM", "PM 3:04"),
|
|
513
1305
|
# ASCII case-insensitively; am: and pm: declare a culture's own designators beside
|
|
514
1306
|
# them — "vorm."/"nachm.", "오전"/"오후", "a. m."/"p. m." — matched exactly, after the
|
|
515
|
-
# clock ("3:04 nachm.") or ahead of it ("오후 3:04"), with
|
|
1307
|
+
# clock ("3:04 nachm.") or ahead of it ("오후 3:04"), with any run of white space or none between.
|
|
516
1308
|
# Declared, never looked up, like a NumFormat's symbols; nil (the default) declares
|
|
517
1309
|
# nothing, so a call without them is exactly the call it was. A designator is 1 to 16
|
|
518
|
-
# UTF-8 bytes with no ASCII digit and no
|
|
1310
|
+
# UTF-8 bytes with no ASCII digit and no white space at either end (a space inside
|
|
519
1311
|
# is fine); anything else is a caller bug (ArgumentError). The designators are read,
|
|
520
1312
|
# validated and packed per call: a call that declares them costs about twice the plain
|
|
521
1313
|
# call on the Magnus backend (the keyword scan itself — nil keywords pay the same) and
|
|
522
1314
|
# about half again here on Fiddle.
|
|
523
|
-
|
|
1315
|
+
#
|
|
1316
|
+
# options: (a DateOptions) gives two-digit years a pivot, and months: (a MonthNames) opens
|
|
1317
|
+
# declared month names ("07-Jan-26 3:04 PM"), each only when asked for.
|
|
1318
|
+
def datetime(text, order, am: nil, pm: nil, options: nil, months: nil)
|
|
1319
|
+
dated(options, months)
|
|
524
1320
|
periods = packed_day_periods(am, pm) if am || pm
|
|
525
|
-
|
|
1321
|
+
crossing(21, DATE_ORDERS.fetch(order), text, 16, nil, periods, options, months) do |out|
|
|
1322
|
+
Interop.decode(:datetime, out)
|
|
1323
|
+
end
|
|
526
1324
|
end
|
|
527
1325
|
|
|
528
1326
|
# Casts an ISO 24-hour time-of-day to an exact Integer of nanoseconds since midnight
|
|
529
1327
|
# (Ruby has no time-of-day type; the integer keeps every digit).
|
|
530
1328
|
def time(text)
|
|
531
|
-
|
|
1329
|
+
crossing(16, 0, text, 8) { |out| Interop.decode(:time, out) }
|
|
532
1330
|
end
|
|
533
1331
|
|
|
534
1332
|
# Casts a duration (ISO 8601 fixed components, invariant colon form, or protobuf JSON
|
|
535
1333
|
# seconds) to exact Rational seconds — full fidelity across the core's ±10,000-year
|
|
536
1334
|
# window, no wrapping and no truncation.
|
|
537
1335
|
def duration(text)
|
|
538
|
-
|
|
1336
|
+
crossing(17, 0, text, 16) { |out| Interop.decode(:duration, out) }
|
|
539
1337
|
end
|
|
540
1338
|
|
|
541
1339
|
# Reads a number a caller already holds — an Integer, Float or Rational, the way Ruby's
|
|
@@ -546,7 +1344,7 @@ module HyperCast
|
|
|
546
1344
|
# a magnitude past 2**96 - 1 or more than 28 places is :out_of_range. A typed door's
|
|
547
1345
|
# Fault has no span: offset and length are 0.
|
|
548
1346
|
def decimal_from_float(value)
|
|
549
|
-
typed(
|
|
1347
|
+
typed(19, 0, float(value), 16) { |out| Interop.decode(:decimal, out) }
|
|
550
1348
|
end
|
|
551
1349
|
|
|
552
1350
|
# Reads an Excel serial number under a declared epoch Symbol (:y1900/:y1904) as the
|
|
@@ -555,18 +1353,105 @@ module HyperCast
|
|
|
555
1353
|
# is :out_of_range; a negative, NaN or infinite serial is :malformed.
|
|
556
1354
|
def excel_serial_from_float(value, epoch)
|
|
557
1355
|
number = float(value)
|
|
558
|
-
typed(
|
|
1356
|
+
typed(22, EXCEL_EPOCHS.fetch(epoch), number, 16) { |out| Interop.decode(:datetime, out) }
|
|
559
1357
|
end
|
|
560
1358
|
|
|
561
1359
|
# Reads the fraction of an Excel serial number as an exact Integer of nanoseconds since
|
|
562
1360
|
# midnight, as time does; 0.75 and 45292.75 are both 18:00.
|
|
563
1361
|
def excel_time(value)
|
|
564
|
-
typed(
|
|
1362
|
+
typed(16, 0, float(value), 8) { |out| Interop.decode(:time, out) }
|
|
565
1363
|
end
|
|
566
1364
|
|
|
567
1365
|
# Reads a number of days as exact Rational seconds, as duration does: 1.5 is 129600.
|
|
568
1366
|
def excel_duration(value)
|
|
569
|
-
typed(
|
|
1367
|
+
typed(17, 0, float(value), 16) { |out| Interop.decode(:duration, out) }
|
|
1368
|
+
end
|
|
1369
|
+
|
|
1370
|
+
# Casts text as text: the input itself, as a String, once it is valid UTF-8 — a binary
|
|
1371
|
+
# String's bytes must be, and a UTF-8 String carrying invalid bytes is :malformed at the
|
|
1372
|
+
# first. Empty input is :empty; nothing is trimmed. The value is the String passed when it
|
|
1373
|
+
# is UTF-8 or US-ASCII, else a UTF-8 copy.
|
|
1374
|
+
#
|
|
1375
|
+
# With Constraints for :text it is judged by them, a Checked, a Fault or a Violation:
|
|
1376
|
+
# trimmed of Unicode White_Space when they say so (trimmed to nothing is :empty), lengths
|
|
1377
|
+
# counted in code points, and an enum matched under simple case folding (byte for byte
|
|
1378
|
+
# with case_sensitive), a match delivering the very String declared and its index; a
|
|
1379
|
+
# Violation's value is the judged text. Constraints for another door are an ArgumentError
|
|
1380
|
+
# (they go to checked).
|
|
1381
|
+
def text(text, constraints = nil)
|
|
1382
|
+
if constraints.nil?
|
|
1383
|
+
return crossing(18, 0, text, 8) { |out, bytes| text_value(bytes, *out.unpack("LL")) }
|
|
1384
|
+
end
|
|
1385
|
+
|
|
1386
|
+
bytes = utf8(text)
|
|
1387
|
+
_door, raw, entries = constrained(constraints, :text)
|
|
1388
|
+
rc = checked_call(CHECKED_DOORS.fetch(:text), nil, raw, entries, bytes)
|
|
1389
|
+
checked_verdict(rc, bytes) do |out, check|
|
|
1390
|
+
offset, length = out[0, 8].unpack("LL")
|
|
1391
|
+
index = check && check[8, 4].unpack1("L")
|
|
1392
|
+
index.nil? || index == 0xFFFF_FFFF ? text_value(bytes, offset, length) : constraints.enum.fetch(index)
|
|
1393
|
+
end
|
|
1394
|
+
end
|
|
1395
|
+
|
|
1396
|
+
# Casts numeric text through the door its Constraints are bound to, under the declared
|
|
1397
|
+
# format, then judges the value by them: a Checked, or the door's own Fault, or a
|
|
1398
|
+
# Violation of the first rule it breaks, carrying the value as cast. The value is judged exactly, on the decimal the
|
|
1399
|
+
# door read, never on a float. Spans are in the units a Fault's are. separator:,
|
|
1400
|
+
# delimiter: and unit: override those fields of format for this call
|
|
1401
|
+
# (NumFormat#override). Constraints for :text are an ArgumentError (they go to text).
|
|
1402
|
+
def checked(text, format, constraints, separator: nil, delimiter: nil, unit: nil)
|
|
1403
|
+
format = format.override(separator: separator, delimiter: delimiter, unit: unit) if
|
|
1404
|
+
separator || delimiter || unit
|
|
1405
|
+
bytes = utf8(text)
|
|
1406
|
+
symbol, raw, entries = constrained(constraints, :checked)
|
|
1407
|
+
rc = checked_call(CHECKED_DOORS.fetch(symbol), packed_cache[format], raw, entries, bytes)
|
|
1408
|
+
checked_verdict(rc, bytes) { |out| Interop.decode(symbol, out[0, Interop::VALUE_BYTES.fetch(symbol)]) }
|
|
1409
|
+
end
|
|
1410
|
+
|
|
1411
|
+
# Reads a number the caller already holds — an Integer, Float or Rational, taken as
|
|
1412
|
+
# decimal_from_float takes it — through the door its Constraints are bound to, then judges
|
|
1413
|
+
# it by them on the shortest decimal that names it: 0.1 + 0.2 is 0.30000000000000004,
|
|
1414
|
+
# which breaks multiple_of: "0.1" under :strict and rounds to 0.3 under :midpoint. NaN is
|
|
1415
|
+
# :malformed; an infinity is :out_of_range at a float or decimal door and :malformed at an
|
|
1416
|
+
# integer door. Every fault and violation has an empty span.
|
|
1417
|
+
def checked_from_float(value, constraints)
|
|
1418
|
+
number = float(value)
|
|
1419
|
+
symbol, raw, entries = constrained(constraints, :checked_from_float)
|
|
1420
|
+
out, fault = scratch
|
|
1421
|
+
rc = Runtime.function(:cast_checked_detailed_from_f64).call(CHECKED_DOORS.fetch(symbol), 0, raw,
|
|
1422
|
+
input_ptr(entries), entries.bytesize, number,
|
|
1423
|
+
out, fault, checked_scratch[1])
|
|
1424
|
+
checked_verdict(rc, nil) { |out| Interop.decode(symbol, out[0, Interop::VALUE_BYTES.fetch(symbol)]) }
|
|
1425
|
+
end
|
|
1426
|
+
|
|
1427
|
+
# Judges a declaration without building it, the way Constraints.new does when it is
|
|
1428
|
+
# built, taking the same keywords: 0 when every rule holds, otherwise the code of the first
|
|
1429
|
+
# rule it breaks (Constraints::REFUSALS words each). A wrong argument is still raised, as
|
|
1430
|
+
# Constraints.new raises it.
|
|
1431
|
+
def constraints_check(**keywords)
|
|
1432
|
+
layout = Constraints.send(:layout, **keywords)
|
|
1433
|
+
return layout if layout.is_a?(Integer)
|
|
1434
|
+
|
|
1435
|
+
door, raw, entries = layout
|
|
1436
|
+
pointer, = checked_scratch
|
|
1437
|
+
pointer[0, raw.bytesize] = raw
|
|
1438
|
+
Runtime.function(:cast_constraints_check).call(door, 0, pointer, input_ptr(entries), entries.bytesize)
|
|
1439
|
+
end
|
|
1440
|
+
|
|
1441
|
+
# Converts a bound, step or numeric enum entry written in invariant notation — an
|
|
1442
|
+
# optional sign, digits with an optional "." and fraction, an optional exponent:
|
|
1443
|
+
# "0.000001", "-90", "1e-6" — to the exact Decimal the core declares it as, trailing zeros
|
|
1444
|
+
# dropped: the conversion every bound a Constraints is given crosses. A value past 96 bits
|
|
1445
|
+
# or 28 places, or text in any other notation, is the ArgumentError a refused declaration
|
|
1446
|
+
# raises (code 8).
|
|
1447
|
+
def declared_decimal(text)
|
|
1448
|
+
bytes = utf8(text)
|
|
1449
|
+
out, = scratch
|
|
1450
|
+
rc = Runtime.function(:cast_declared_decimal).call(input_ptr(bytes), bytes.bytesize, out)
|
|
1451
|
+
raise ArgumentError, Constraints.send(:refusal, rc) if rc == 8
|
|
1452
|
+
raise "hypercast: libhypercast reported a contract violation — a binding bug, please report it" unless rc.zero?
|
|
1453
|
+
|
|
1454
|
+
Interop.decode(:decimal, out[0, 16])
|
|
570
1455
|
end
|
|
571
1456
|
|
|
572
1457
|
# The version of the native core actually loaded, as "major.minor.patch" — read from
|
|
@@ -577,13 +1462,23 @@ module HyperCast
|
|
|
577
1462
|
def native_version
|
|
578
1463
|
Interop.version(packed_version)
|
|
579
1464
|
end
|
|
1465
|
+
end
|
|
1466
|
+
|
|
1467
|
+
extend FiddleBackend
|
|
580
1468
|
|
|
1469
|
+
# The byte #kept stands a character with no UTF-8 form in for.
|
|
1470
|
+
NO_UTF8 = "\x80".b.freeze
|
|
1471
|
+
private_constant :NO_UTF8
|
|
1472
|
+
|
|
1473
|
+
class << self
|
|
581
1474
|
private
|
|
582
1475
|
|
|
583
1476
|
# Presents the input as UTF-8 bytes: already-compatible text crosses as-is (Fiddle
|
|
584
1477
|
# passes a String's own bytes for void* — no copy of them); only foreign encodings pay
|
|
585
|
-
# a transcode
|
|
586
|
-
#
|
|
1478
|
+
# a transcode. The Magnus extension calls this same method for a foreign encoding, so
|
|
1479
|
+
# both backends hand the core the same bytes. Text that cannot be transcoded (a lone
|
|
1480
|
+
# UTF-16 surrogate, bytes its encoding does not allow, a character with no Unicode
|
|
1481
|
+
# counterpart) is data, not a caller bug: see #kept.
|
|
587
1482
|
#
|
|
588
1483
|
# Text that is not a String is a caller bug, and the same TypeError on every backend:
|
|
589
1484
|
# the extension takes its argument through Ruby's implicit String conversion (to_str,
|
|
@@ -594,7 +1489,69 @@ module HyperCast
|
|
|
594
1489
|
raise TypeError, "no implicit conversion of #{text.class} into String"
|
|
595
1490
|
text = converted
|
|
596
1491
|
end
|
|
597
|
-
|
|
1492
|
+
encoding = text.encoding
|
|
1493
|
+
# A US-ASCII String with a byte past 0x7F is not ASCII: it transcodes, and that byte is
|
|
1494
|
+
# malformed (#kept), never read as the UTF-8 it might spell.
|
|
1495
|
+
return text if Interop::BYTE_COMPATIBLE.include?(encoding) &&
|
|
1496
|
+
(encoding != Encoding::US_ASCII || text.ascii_only?)
|
|
1497
|
+
|
|
1498
|
+
begin
|
|
1499
|
+
text.encode(Encoding::UTF_8)
|
|
1500
|
+
rescue Encoding::InvalidByteSequenceError, Encoding::UndefinedConversionError,
|
|
1501
|
+
Encoding::ConverterNotFoundError
|
|
1502
|
+
kept(text)
|
|
1503
|
+
end
|
|
1504
|
+
end
|
|
1505
|
+
|
|
1506
|
+
# Text that has no UTF-8 form, as the core reads it: each character transcoded, and each
|
|
1507
|
+
# one that cannot be (a lone surrogate, an invalid sequence, a character with no Unicode
|
|
1508
|
+
# counterpart) as the lone continuation byte 0x80, which no UTF-8 decoder accepts and the
|
|
1509
|
+
# core always judges as one malformed byte. The text is then MALFORMED at that character,
|
|
1510
|
+
# never a replacement standing for it, as at every binding's doors; and since 0x80 is one
|
|
1511
|
+
# character of the UTF-8 form, as the character it stands for is one of the caller's
|
|
1512
|
+
# String, a span still indexes the caller's own String.
|
|
1513
|
+
#
|
|
1514
|
+
# An encoding Ruby has no converter to UTF-8 for (EUC-TW, Windows-1258) gives no character
|
|
1515
|
+
# past ASCII a UTF-8 form, so each such character is one 0x80 too.
|
|
1516
|
+
#
|
|
1517
|
+
# A dummy encoding (UTF-16 and UTF-32 with their byte-order mark, ISO-2022-JP, UTF-7) has
|
|
1518
|
+
# no characters Ruby can split: each_char yields single bytes, and a String in one counts
|
|
1519
|
+
# bytes. Such text is transcoded whole (#transcoded), each conversion error standing as
|
|
1520
|
+
# one 0x80, so a span counts the characters of its UTF-8 form, the String
|
|
1521
|
+
# text.encode(Encoding::UTF_8, invalid: :replace, undef: :replace) spells, one for one.
|
|
1522
|
+
def kept(text)
|
|
1523
|
+
return transcoded(text) if text.encoding.dummy?
|
|
1524
|
+
|
|
1525
|
+
text.each_char.map do |char|
|
|
1526
|
+
char.valid_encoding? ? char.encode(Encoding::UTF_8).b : NO_UTF8
|
|
1527
|
+
rescue Encoding::InvalidByteSequenceError, Encoding::UndefinedConversionError,
|
|
1528
|
+
Encoding::ConverterNotFoundError
|
|
1529
|
+
NO_UTF8
|
|
1530
|
+
end.join.force_encoding(Encoding::UTF_8)
|
|
1531
|
+
end
|
|
1532
|
+
|
|
1533
|
+
# Text in a dummy encoding as UTF-8, through one converter: each invalid sequence, each
|
|
1534
|
+
# character with no Unicode counterpart, and an input cut short as one 0x80. A dummy
|
|
1535
|
+
# encoding with no converter at all (UTF-7, ISO-2022-JP-2) is one 0x80 for each byte, the
|
|
1536
|
+
# unit its String counts.
|
|
1537
|
+
def transcoded(text)
|
|
1538
|
+
converter = begin
|
|
1539
|
+
Encoding::Converter.new(text.encoding, Encoding::UTF_8)
|
|
1540
|
+
rescue Encoding::ConverterNotFoundError
|
|
1541
|
+
return (NO_UTF8 * text.bytesize).force_encoding(Encoding::UTF_8)
|
|
1542
|
+
end
|
|
1543
|
+
source = text.b
|
|
1544
|
+
piece = String.new
|
|
1545
|
+
bytes = String.new(encoding: Encoding::BINARY)
|
|
1546
|
+
loop do
|
|
1547
|
+
status = converter.primitive_convert(source, piece)
|
|
1548
|
+
bytes << piece.b
|
|
1549
|
+
piece.clear
|
|
1550
|
+
break if status == :finished
|
|
1551
|
+
|
|
1552
|
+
bytes << NO_UTF8
|
|
1553
|
+
end
|
|
1554
|
+
bytes.force_encoding(Encoding::UTF_8)
|
|
598
1555
|
end
|
|
599
1556
|
|
|
600
1557
|
# Fiddle spells a null pointer as nil — the core's contract for empty input.
|
|
@@ -602,104 +1559,101 @@ module HyperCast
|
|
|
602
1559
|
bytes.empty? ? nil : bytes
|
|
603
1560
|
end
|
|
604
1561
|
|
|
605
|
-
# One
|
|
606
|
-
#
|
|
607
|
-
#
|
|
608
|
-
#
|
|
609
|
-
#
|
|
610
|
-
#
|
|
611
|
-
#
|
|
612
|
-
#
|
|
613
|
-
#
|
|
1562
|
+
# One 96-byte scratch allocation per thread, reused by every call: out-value at 0 (16 bytes
|
|
1563
|
+
# covers every door, and malloc's alignment covers the decimal's 8), the fault at 16 (a
|
|
1564
|
+
# RawFaultDetail, 16 bytes: its size word written once, here, and never by the core; then the
|
|
1565
|
+
# span and the detail), the datetime door's packed day periods at 32 (40 bytes, 4-aligned,
|
|
1566
|
+
# written only by a call that declares them) and the date options at 72 (12 bytes, 4-aligned,
|
|
1567
|
+
# likewise). Two Fiddle::Pointer.malloc(..., RUBY_FREE) calls per cast — each registering a GC
|
|
1568
|
+
# finalizer — measured as the dominant per-call cost by an order of magnitude. The NumFormat
|
|
1569
|
+
# does not live here: each format owns its own packed pointer (see packed_cache), so a numeric
|
|
1570
|
+
# call copies nothing into scratch before crossing. Allocated through Runtime.buffer, which
|
|
1571
|
+
# loads the library first, so a missing one is reported as such before Fiddle is touched.
|
|
614
1572
|
def scratch
|
|
615
1573
|
Thread.current[:hypercast_scratch] ||= begin
|
|
616
|
-
base = Runtime.buffer(
|
|
617
|
-
[
|
|
1574
|
+
base = Runtime.buffer(96)
|
|
1575
|
+
base[16, 4] = [Interop::FAULT_BYTES].pack("L")
|
|
1576
|
+
[base, base + 16, base + 32, base + 72]
|
|
618
1577
|
end
|
|
619
1578
|
end
|
|
620
1579
|
|
|
621
1580
|
# Presents a native return code as the verdict union: 0 yields a Success, a failure
|
|
622
|
-
# code becomes a Fault over `bytes` (the UTF-8 the core read), and
|
|
623
|
-
# violation) is a binding bug that raises.
|
|
1581
|
+
# code becomes a Fault over `bytes` (the UTF-8 the core read) carrying the core's detail, and
|
|
1582
|
+
# -1 (contract violation) is a binding bug that raises.
|
|
624
1583
|
def verdict(rc, fault, bytes)
|
|
625
1584
|
if rc.zero?
|
|
626
1585
|
Success.new(value: yield)
|
|
627
1586
|
elsif rc == -1
|
|
628
1587
|
raise "hypercast: libhypercast reported a contract violation — a binding bug, please report it"
|
|
629
1588
|
else
|
|
630
|
-
Interop.
|
|
1589
|
+
Interop.raw_fault(rc, fault[0, Interop::FAULT_BYTES], bytes)
|
|
631
1590
|
end
|
|
632
1591
|
end
|
|
633
1592
|
|
|
634
|
-
# The shared body of every
|
|
635
|
-
|
|
1593
|
+
# The shared body of every door that reads text: one detailed native call over the scratch
|
|
1594
|
+
# buffers. door and param are the core's door code and what the door declares (0 for
|
|
1595
|
+
# nothing); format is the numeric doors' NumFormat, periods the datetime door's packed day
|
|
1596
|
+
# periods, options and months the date doors' DateOptions and MonthNames (nil for none), each
|
|
1597
|
+
# crossing only where the door reads it. The block reads the value from the out-bytes and the
|
|
1598
|
+
# UTF-8 the core read.
|
|
1599
|
+
def crossing(door, param, text, out_size, format = nil, periods = nil, options = nil, months = nil)
|
|
636
1600
|
bytes = utf8(text)
|
|
637
|
-
out, fault = scratch
|
|
638
|
-
rc = Runtime.function(symbol).call(input_ptr(bytes), bytes.bytesize, out, fault)
|
|
639
|
-
verdict(rc, fault, bytes) { yield(out[0, out_size]) }
|
|
640
|
-
end
|
|
641
|
-
|
|
642
|
-
# The shared body of the integer/real/decimal doors: plain, plus the format's own
|
|
643
|
-
# packed pointer, passed straight through — no per-call copy of the 92 bytes into
|
|
644
|
-
# scratch.
|
|
645
|
-
def numeric(symbol, text, format, out_size)
|
|
646
|
-
bytes = utf8(text)
|
|
647
|
-
out, fault = scratch
|
|
648
|
-
rc = Runtime.function(symbol).call(input_ptr(bytes), bytes.bytesize, packed_cache[format], out, fault)
|
|
649
|
-
verdict(rc, fault, bytes) { yield(out[0, out_size]) }
|
|
650
|
-
end
|
|
651
|
-
|
|
652
|
-
# The civil date-time door's body: declared, plus the day periods after the order — the
|
|
653
|
-
# 40 packed bytes copied into this thread's scratch and passed from there, or nil
|
|
654
|
-
# (Fiddle's null) when none are declared, which the core reads as English AM/PM only.
|
|
655
|
-
def civil(symbol, text, code, periods, out_size)
|
|
656
|
-
bytes = utf8(text)
|
|
657
|
-
out, fault, slot = scratch
|
|
1601
|
+
out, fault, slot, dates = scratch
|
|
658
1602
|
if periods
|
|
659
1603
|
slot[0, periods.bytesize] = periods
|
|
660
1604
|
else
|
|
661
1605
|
slot = nil
|
|
662
1606
|
end
|
|
663
|
-
|
|
664
|
-
|
|
1607
|
+
if options
|
|
1608
|
+
dates[0, DateOptions::PACKED_BYTES] = options.packed
|
|
1609
|
+
else
|
|
1610
|
+
dates = nil
|
|
1611
|
+
end
|
|
1612
|
+
vocabulary = months&.packed
|
|
1613
|
+
rc = Runtime.function(:cast_detailed).call(door, param, format && packed_cache[format], slot, dates,
|
|
1614
|
+
vocabulary, vocabulary ? vocabulary.bytesize : 0,
|
|
1615
|
+
input_ptr(bytes), bytes.bytesize, out, fault)
|
|
1616
|
+
raise RefusedDeclaration, "the core refused the date options or month names" if rc == -1 && (options || months)
|
|
1617
|
+
|
|
1618
|
+
verdict(rc, fault, bytes) { yield(out[0, out_size], bytes) }
|
|
1619
|
+
end
|
|
1620
|
+
|
|
1621
|
+
# Date options and month names as a date door takes them: each nil or the right type, a
|
|
1622
|
+
# TypeError otherwise (what the Magnus extension raises for them too).
|
|
1623
|
+
def dated(options, months)
|
|
1624
|
+
raise TypeError, "options must be a HyperCast::DateOptions; got #{options.inspect}" unless
|
|
1625
|
+
options.nil? || options.is_a?(DateOptions)
|
|
1626
|
+
raise TypeError, "months must be a HyperCast::MonthNames; got #{months.inspect}" unless
|
|
1627
|
+
months.nil? || months.is_a?(MonthNames)
|
|
665
1628
|
end
|
|
666
1629
|
|
|
667
|
-
# The 40-byte
|
|
668
|
-
# size word (40), then each designator as its
|
|
669
|
-
# its byte length — am, then pm — and two bytes
|
|
670
|
-
# length of 0: nothing declared beside AM or PM.
|
|
1630
|
+
# The 40-byte native form of the ABI's size-tagged DayPeriods struct, which the core
|
|
1631
|
+
# reads in place: the size word (40, in native byte order), then each designator as its
|
|
1632
|
+
# UTF-8 bytes zero-padded to 16 followed by its byte length — am, then pm — and two bytes
|
|
1633
|
+
# of padding. A nil designator is a length of 0: nothing declared beside AM or PM.
|
|
671
1634
|
def packed_day_periods(am, pm)
|
|
672
1635
|
am = designator("am", am)
|
|
673
1636
|
pm = designator("pm", pm)
|
|
674
|
-
[40].pack("L
|
|
1637
|
+
[40].pack("L") + [am, am.bytesize, pm, pm.bytesize].pack("a16Ca16C") + "\0\0"
|
|
675
1638
|
end
|
|
676
1639
|
|
|
677
1640
|
# A declared day-period designator as the UTF-8 the core reads — 1 to 16 bytes, no
|
|
678
|
-
# ASCII digit, no
|
|
1641
|
+
# ASCII digit, no white space at either end (the grammar around it reads that) —
|
|
679
1642
|
# or "" for nil. Anything else is the caller bug it names, the same ArgumentError on
|
|
680
1643
|
# every backend.
|
|
681
1644
|
def designator(name, text)
|
|
682
1645
|
return "" if text.nil?
|
|
683
1646
|
raise ArgumentError, "#{name} designator must be a String; got #{text.inspect}" unless text.is_a?(String)
|
|
684
1647
|
|
|
685
|
-
designator = text
|
|
686
|
-
unless designator.bytesize.between?(1, 16) &&
|
|
1648
|
+
designator = declared_utf8("#{name} designator", text)
|
|
1649
|
+
unless designator.bytesize.between?(1, 16) &&
|
|
1650
|
+
!designator.match?(/[0-9]|\A#{WHITE_SPACE.source}|#{WHITE_SPACE.source}\z/)
|
|
687
1651
|
raise ArgumentError, "#{name} designator #{text.inspect} must be 1 to 16 UTF-8 bytes with no ASCII digit " \
|
|
688
|
-
"and no
|
|
1652
|
+
"and no white space at either end"
|
|
689
1653
|
end
|
|
690
1654
|
designator
|
|
691
1655
|
end
|
|
692
1656
|
|
|
693
|
-
# The shared body of the four doors that take a caller-declared u32 — a precision, an
|
|
694
|
-
# epoch, or a field order — already resolved from its Symbol by the door. These bodies
|
|
695
|
-
# (plain, numeric, declared, and packed_version below) are the whole Fiddle crossing.
|
|
696
|
-
def declared(symbol, text, code, out_size)
|
|
697
|
-
bytes = utf8(text)
|
|
698
|
-
out, fault = scratch
|
|
699
|
-
rc = Runtime.function(symbol).call(input_ptr(bytes), bytes.bytesize, code, out, fault)
|
|
700
|
-
verdict(rc, fault, bytes) { yield(out[0, out_size]) }
|
|
701
|
-
end
|
|
702
|
-
|
|
703
1657
|
# A typed door's number, converted the way the extension's argument is (C's
|
|
704
1658
|
# rb_num2dbl), with the same exception and message: a Numeric converts (a Complex with an
|
|
705
1659
|
# imaginary part is Complex#to_f's RangeError), anything else is a TypeError — a String
|
|
@@ -714,26 +1668,120 @@ module HyperCast
|
|
|
714
1668
|
end
|
|
715
1669
|
end
|
|
716
1670
|
|
|
717
|
-
# The shared body of the typed doors: a double instead of the text,
|
|
718
|
-
#
|
|
719
|
-
def typed(
|
|
1671
|
+
# The shared body of the typed doors: a double instead of the text, through the core's
|
|
1672
|
+
# detailed typed export (door and param as #crossing's; a typed door's span is empty).
|
|
1673
|
+
def typed(door, param, number, out_size)
|
|
720
1674
|
out, fault = scratch
|
|
721
|
-
rc = Runtime.function(
|
|
1675
|
+
rc = Runtime.function(:cast_detailed_from_f64).call(door, param, number, out, fault)
|
|
722
1676
|
if rc.zero?
|
|
723
1677
|
Success.new(value: yield(out[0, out_size]))
|
|
724
1678
|
elsif rc == -1
|
|
725
1679
|
raise "hypercast: libhypercast reported a contract violation — a binding bug, please report it"
|
|
726
1680
|
else
|
|
727
|
-
Interop.
|
|
1681
|
+
Interop.raw_fault(rc, fault[0, Interop::FAULT_BYTES])
|
|
1682
|
+
end
|
|
1683
|
+
end
|
|
1684
|
+
|
|
1685
|
+
# The text door's value at the byte span the core judged valid: the String passed when
|
|
1686
|
+
# the span is all of it and it is UTF-8 or US-ASCII, else that span as a new UTF-8 String
|
|
1687
|
+
# (a trimmed span, or a binary String's bytes).
|
|
1688
|
+
def text_value(bytes, offset, length)
|
|
1689
|
+
return bytes if offset.zero? && length == bytes.bytesize && bytes.encoding != Encoding::ASCII_8BIT
|
|
1690
|
+
|
|
1691
|
+
bytes.byteslice(offset, length).force_encoding(Encoding::UTF_8)
|
|
1692
|
+
end
|
|
1693
|
+
|
|
1694
|
+
# A Constraints as a checked door hands it to the core — its door Symbol, its packed
|
|
1695
|
+
# layout in 8-aligned native memory and its packed enum — checked against the door it was
|
|
1696
|
+
# passed to: a non-Constraints is a TypeError, and one bound to another door an
|
|
1697
|
+
# ArgumentError naming the door that judges it.
|
|
1698
|
+
def constrained(constraints, door)
|
|
1699
|
+
raise TypeError, "constraints must be a HyperCast::Constraints; got #{constraints.inspect}" unless
|
|
1700
|
+
constraints.is_a?(Constraints)
|
|
1701
|
+
|
|
1702
|
+
declared = constraints_cache[constraints]
|
|
1703
|
+
text = declared[0] == :text
|
|
1704
|
+
if text != (door == :text)
|
|
1705
|
+
raise ArgumentError,
|
|
1706
|
+
"Constraints for #{declared[0].inspect} are judged by HyperCast.#{text ? 'text' : 'checked'}"
|
|
1707
|
+
end
|
|
1708
|
+
|
|
1709
|
+
declared
|
|
1710
|
+
end
|
|
1711
|
+
|
|
1712
|
+
# How many declarations constraints_cache remembers before it starts forgetting the
|
|
1713
|
+
# oldest: packed_cache's bound, for the same reason.
|
|
1714
|
+
CONSTRAINTS_CACHE_LIMIT = 64
|
|
1715
|
+
|
|
1716
|
+
# Identity-keyed memo of each Constraints as the core reads it: its door, its 104-byte
|
|
1717
|
+
# layout copied once into native memory (which a String's bytes are not guaranteed to be
|
|
1718
|
+
# aligned for) and its packed enum, frozen. Bounded and evicted as packed_cache is.
|
|
1719
|
+
def constraints_cache
|
|
1720
|
+
@constraints_cache ||= Hash.new do |cache, constraints|
|
|
1721
|
+
cache.shift while cache.size >= CONSTRAINTS_CACHE_LIMIT
|
|
1722
|
+
_code, raw, entries = constraints.send(:declaration)
|
|
1723
|
+
pointer = Runtime.buffer(raw.bytesize)
|
|
1724
|
+
pointer[0, raw.bytesize] = raw
|
|
1725
|
+
cache[constraints] = [constraints.door, pointer, entries.freeze].freeze
|
|
1726
|
+
end.compare_by_identity
|
|
1727
|
+
end
|
|
1728
|
+
|
|
1729
|
+
# One 120-byte scratch allocation per thread for the checked doors, beside #scratch: a
|
|
1730
|
+
# packed layout constraints_check judges at 0 (104 bytes, 8-aligned by malloc), and the
|
|
1731
|
+
# check a checked door writes at 104 (12 bytes).
|
|
1732
|
+
def checked_scratch
|
|
1733
|
+
Thread.current[:hypercast_checked_scratch] ||= begin
|
|
1734
|
+
base = Runtime.buffer(Constraints::PACKED_BYTES + 16)
|
|
1735
|
+
[base, base + Constraints::PACKED_BYTES]
|
|
728
1736
|
end
|
|
729
1737
|
end
|
|
730
1738
|
|
|
1739
|
+
# The shared body of the checked doors that read text: one detailed native call. door is
|
|
1740
|
+
# the core's door code, format the packed NumFormat pointer (nil at :text, which never reads
|
|
1741
|
+
# one), raw the packed constraints pointer and entries the packed enum.
|
|
1742
|
+
def checked_call(door, format, raw, entries, bytes)
|
|
1743
|
+
out, fault = scratch
|
|
1744
|
+
Runtime.function(:cast_checked_detailed).call(door, 0, format, raw, input_ptr(entries), entries.bytesize,
|
|
1745
|
+
input_ptr(bytes), bytes.bytesize, out, fault,
|
|
1746
|
+
checked_scratch[1])
|
|
1747
|
+
end
|
|
1748
|
+
|
|
1749
|
+
# Presents a checked door's return code as its verdict: 0 a Checked of the value the
|
|
1750
|
+
# block reads from the out-value and check, 1 to 3 the door's Fault with its detail, 4 a
|
|
1751
|
+
# Violation of the value the block reads from the out-value (handed no check: the value as
|
|
1752
|
+
# cast, never an enum entry) — each span over `bytes` (the UTF-8 the core read) as a
|
|
1753
|
+
# Fault's is, or as written when there is no text — and -1 a binding bug that raises.
|
|
1754
|
+
def checked_verdict(rc, bytes)
|
|
1755
|
+
out, fault = scratch
|
|
1756
|
+
check = checked_scratch[1]
|
|
1757
|
+
if rc.zero?
|
|
1758
|
+
adjusted, index = check[4, 8].unpack("LL")
|
|
1759
|
+
return Checked.new(value: yield(out, check), adjusted: adjusted != 0,
|
|
1760
|
+
enum_index: index == 0xFFFF_FFFF ? nil : index)
|
|
1761
|
+
end
|
|
1762
|
+
raise "hypercast: libhypercast reported a contract violation — a binding bug, please report it" unless
|
|
1763
|
+
rc.between?(1, 4)
|
|
1764
|
+
return Interop.raw_fault(rc, fault[0, Interop::FAULT_BYTES], bytes) unless rc == 4
|
|
1765
|
+
|
|
1766
|
+
offset, length = fault[4, 8].unpack("LL")
|
|
1767
|
+
offset, length = Interop.characters(bytes, offset, length) if bytes
|
|
1768
|
+
Violation.new(keyword: Keyword.new(code: check[0, 4].unpack1("L")), value: yield(out, nil), offset: offset,
|
|
1769
|
+
length: length)
|
|
1770
|
+
end
|
|
1771
|
+
|
|
731
1772
|
# The loaded core's version word, major << 16 | minor << 8 | patch, straight from the
|
|
732
1773
|
# library's zero-argument hypercast_version export.
|
|
733
1774
|
def packed_version
|
|
734
1775
|
Runtime.function(:hypercast_version).call
|
|
735
1776
|
end
|
|
736
1777
|
|
|
1778
|
+
# NumFormat#packed as the C ABI reads it in place: its three leading words in the host's
|
|
1779
|
+
# native byte order (on a little-endian host, the very bytes), the symbols as they are.
|
|
1780
|
+
def native_packed(format)
|
|
1781
|
+
packed = format.packed
|
|
1782
|
+
packed[0, 12].unpack("L<3").pack("L3") + packed.byteslice(12, packed.bytesize - 12)
|
|
1783
|
+
end
|
|
1784
|
+
|
|
737
1785
|
# How many formats packed_cache remembers before it starts forgetting the oldest. Far
|
|
738
1786
|
# more than a process that reuses its formats ever holds; what it bounds is the one
|
|
739
1787
|
# that builds a NumFormat per request.
|
|
@@ -755,15 +1803,16 @@ module HyperCast
|
|
|
755
1803
|
cache.shift while cache.size >= PACKED_CACHE_LIMIT
|
|
756
1804
|
size = NumFormat::PACKED_BYTES
|
|
757
1805
|
pointer = Runtime.buffer(size)
|
|
758
|
-
pointer[0, size] = format
|
|
1806
|
+
pointer[0, size] = native_packed(format)
|
|
759
1807
|
cache[format] = pointer
|
|
760
1808
|
end.compare_by_identity
|
|
761
1809
|
end
|
|
762
1810
|
end
|
|
763
1811
|
end
|
|
764
1812
|
|
|
765
|
-
# --- backend selection: the Magnus extension, when present,
|
|
766
|
-
#
|
|
1813
|
+
# --- backend selection: the Magnus extension, when present, defines the doors on this
|
|
1814
|
+
# module's singleton class, in front of the FiddleBackend definitions it extends (no
|
|
1815
|
+
# delegation layer, no redefinition) — Fiddle's measured 1.6 µs per-call floor
|
|
767
1816
|
# drops to an ordinary extension call. The pure-Fiddle definitions stay the universal
|
|
768
1817
|
# zero-compile fallback — the last resort, for a Ruby or a platform no platform gem covers;
|
|
769
1818
|
# precompiled platform gems are how the extension ships without ever making a consumer
|