hypercast 1.0.0 → 1.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -5,26 +5,27 @@ module HyperCast
5
5
  # word, and where a gem's native library is. The Fiddle backend's doors decode with exactly
6
6
  # these, so a value read out of another library's buffer is the value the door would have.
7
7
  #
8
- # Every directive below unpacks one value. A gem decoding a whole column appends "*" and
9
- # steps +fields+ at a time.
8
+ # Every directive below unpacks one value in the host's native byte order, the order the
9
+ # core writes its out-values in (on a big-endian host such as s390x too). A gem decoding a
10
+ # whole column appends "*" and steps +fields+ at a time.
10
11
  module Interop
11
12
  # The doors whose value is one String#unpack directive away: the directive for one value.
12
13
  # A bool is the byte 0 or 1, unpacked as "C" and compared with zero.
13
14
  SCALARS = {
14
- bool: "C", i8: "c", i16: "s<", i32: "l<", i64: "q<", u8: "C", u16: "S<", u32: "L<",
15
- u64: "Q<", f32: "e", f64: "E", time: "Q<"
15
+ bool: "C", i8: "c", i16: "s", i32: "l", i64: "q", u8: "C", u16: "S", u32: "L",
16
+ u64: "Q", f32: "f", f64: "d", time: "Q"
16
17
  }.freeze
17
18
 
18
19
  # The doors whose value is a record: the directive that unpacks one, how many fields that
19
20
  # yields, and what builds the door's Ruby value from them, starting at field +at+.
20
21
  RECORDS = {
21
- char: ["L<", 1, ->(fields, at) { fields[at].chr(Encoding::UTF_8) }],
22
- decimal: ["Q<L<CCx2", 4, ->(fields, at) { decimal(fields[at], fields[at + 1], fields[at + 2], fields[at + 3]) }],
22
+ char: ["L", 1, ->(fields, at) { fields[at].chr(Encoding::UTF_8) }],
23
+ decimal: ["QLCCx2", 4, ->(fields, at) { decimal(fields[at], fields[at + 1], fields[at + 2], fields[at + 3]) }],
23
24
  uuid: ["H8H4H4H4H12", 5, ->(fields, at) { fields[at, 5].join("-") }],
24
- timestamp: ["q<l<x4", 2, ->(fields, at) { instant(fields[at], fields[at + 1]) }],
25
- date: ["S<CC", 3, ->(fields, at) { Date.new(fields[at], fields[at + 1], fields[at + 2]) }],
26
- datetime: ["S<CCx4Q<", 4, ->(fields, at) { civil(fields[at], fields[at + 1], fields[at + 2], fields[at + 3]) }],
27
- duration: ["q<l<x4", 2, ->(fields, at) { duration(fields[at], fields[at + 1]) }]
25
+ timestamp: ["qlx4", 2, ->(fields, at) { instant(fields[at], fields[at + 1]) }],
26
+ date: ["SCC", 3, ->(fields, at) { Date.new(fields[at], fields[at + 1], fields[at + 2]) }],
27
+ datetime: ["SCCx4Q", 4, ->(fields, at) { civil(fields[at], fields[at + 1], fields[at + 2], fields[at + 3]) }],
28
+ duration: ["qlx4", 2, ->(fields, at) { duration(fields[at], fields[at + 1]) }]
28
29
  }.tap do |records|
29
30
  records[:unix] = records[:excel_serial] = records[:timestamp]
30
31
  records[:date_ordered] = records[:date]
@@ -37,7 +38,8 @@ module HyperCast
37
38
  decimal: 16, uuid: 16, timestamp: 16, unix: 16, excel_serial: 16, datetime: 16, duration: 16
38
39
  }.freeze
39
40
 
40
- # Encodings whose bytes already are the UTF-8 (or byte-identical) form the core reads.
41
+ # Encodings whose bytes already are the UTF-8 (or byte-identical) form the core reads. A
42
+ # US-ASCII String is one only while it is ASCII: see HyperCast.utf8.
41
43
  BYTE_COMPATIBLE = [Encoding::UTF_8, Encoding::US_ASCII, Encoding::ASCII_8BIT].freeze
42
44
 
43
45
  module_function
@@ -80,10 +82,28 @@ module HyperCast
80
82
  Decimal.new(magnitude: (hi << 64) | lo, scale: scale, negative: negative != 0)
81
83
  end
82
84
 
83
- # The Fault a nonzero verdict code and its span name. A code that names no reason is a
84
- # binding bug, not data: a KeyError.
85
- def fault(code, offset, length)
86
- Fault.new(reason: REASONS.fetch(code), offset: offset, length: length)
85
+ # The bytes of the ABI's size-tagged RawFaultDetail: the size word (16), then the span's
86
+ # offset and length and the detail code, each a u32 in the host's byte order. The core never
87
+ # writes the size word, and a caller's buffer larger than this is accepted (it writes only
88
+ # the last twelve bytes of these sixteen).
89
+ FAULT_BYTES = 16
90
+
91
+ # The Fault a nonzero verdict code and its span name, with the core's detail code when one
92
+ # is given (nil, or 0 for "no detail", leaves Fault#detail nil). A code that names no reason
93
+ # is a binding bug, not data: a KeyError. A detail code this gem does not name is kept, as a
94
+ # Detail whose #name is :unknown.
95
+ def fault(code, offset, length, detail = nil)
96
+ Fault.new(reason: REASONS.fetch(code), offset: offset, length: length,
97
+ detail: detail.nil? || detail.zero? ? nil : Detail.of(detail))
98
+ end
99
+
100
+ # The Fault a verdict code and the 16 bytes of a RawFaultDetail name. With +bytes+ (the
101
+ # UTF-8 the core read) the span is mapped to the units String#[] slices by, as #characters
102
+ # does; without them (a typed door has no text) it is as written.
103
+ def raw_fault(code, raw, bytes = nil)
104
+ offset, length, detail = raw.unpack("x4L3")
105
+ offset, length = characters(bytes, offset, length) if bytes
106
+ fault(code, offset, length, detail)
87
107
  end
88
108
 
89
109
  # The core's byte span over +bytes+, in the units String#[] slices by: an identity for a
@@ -14,13 +14,20 @@ module HyperCast
14
14
  module Runtime
15
15
  NATIVE_DIR = File.join(__dir__, "native")
16
16
 
17
- # Each door's C signature, by shape — resolved to Fiddle types only in load_functions,
18
- # so nothing here touches Fiddle until the Fiddle backend actually runs: plain is
19
- # (text, len, out, fault), numeric adds the packed NumFormat pointer before out,
20
- # declared a caller-declared u32 (precision, epoch, field order) in the same place, and
21
- # civil the field order then the packed DayPeriods pointer (null for none). The typed
22
- # doors take a double instead of the text and its length: typed is (value, out, fault),
23
- # typed_declared adds the u32 after the value.
17
+ # Each export's C signature, by shape — resolved to Fiddle types only in load_functions,
18
+ # so nothing here touches Fiddle until the Fiddle backend actually runs. The doors cross
19
+ # through the four detailed exports: detailed is (door, param, format, periods, date options,
20
+ # vocabulary, vocabulary length, text, len, out, fault), the one export every text door goes
21
+ # through; detailed_from_f64 is (door, param, value, out, fault) for the typed doors;
22
+ # checked_detailed is (door, param, format, constraints, enum, enum length, text, len, out,
23
+ # fault, check) and checked_detailed_from_f64 the same with a double for the format and the
24
+ # text. The 1.0 exports stay declared and resolved, the 1.0 surface: plain is (text, len, out,
25
+ # fault), numeric adds the packed NumFormat pointer before out, declared a caller-declared u32
26
+ # (precision, epoch, field order) in the same place, and civil the field order then the
27
+ # packed DayPeriods pointer (null for none); typed is (value, out, fault) and typed_declared
28
+ # adds the u32 after the value; checked and checked_from_f64 are the detailed pair without
29
+ # the fault's detail. constraints_check is (door, param, constraints, enum, enum length),
30
+ # returning a refusal code rather than a verdict; and declared_decimal is (text, len, out).
24
31
  DOORS = {
25
32
  cast_bool: :plain, cast_char: :plain,
26
33
  cast_i8: :numeric, cast_i16: :numeric, cast_i32: :numeric, cast_i64: :numeric,
@@ -31,9 +38,19 @@ module HyperCast
31
38
  cast_date: :plain, cast_date_ordered: :declared, cast_datetime: :civil,
32
39
  cast_time: :plain, cast_duration: :plain,
33
40
  cast_decimal_from_f64: :typed, cast_excel_serial_from_f64: :typed_declared,
34
- cast_excel_time: :typed, cast_excel_duration: :typed
41
+ cast_excel_time: :typed, cast_excel_duration: :typed,
42
+ cast_text: :plain, cast_checked: :checked, cast_checked_from_f64: :checked_from_f64,
43
+ cast_constraints_check: :constraints_check, cast_declared_decimal: :declared_decimal,
44
+ cast_detailed: :detailed, cast_detailed_from_f64: :detailed_from_f64,
45
+ cast_checked_detailed: :checked_detailed, cast_checked_detailed_from_f64: :checked_detailed_from_f64
35
46
  }.freeze
36
47
 
48
+ # What a core older than 1.1 lacks: the four detailed exports. The grouping policies and
49
+ # every detail ride on them, and a 1.0 core would read any format by 1.0's rules without a
50
+ # word, so a library missing any of them is refused when it loads.
51
+ DETAILED_EXPORTS = %w[cast_detailed cast_detailed_from_f64 cast_checked_detailed
52
+ cast_checked_detailed_from_f64].freeze
53
+
37
54
  # The one export that is not a door: the zero-argument version probe, returning the
38
55
  # core's packed version word (major << 16 | minor << 8 | patch) rather than a verdict
39
56
  # code — so it gets its own Fiddle signature beside DOORS instead of a row in it.
@@ -105,19 +122,55 @@ module HyperCast
105
122
  @functions || @mutex.synchronize { @functions ||= load_functions }
106
123
  end
107
124
 
125
+ # Refuses a library without the detailed exports, naming the core it found: a LoadError,
126
+ # which HyperCast.available? answers false for. The check is for the exports themselves,
127
+ # which are what a 1.1 core is, so it holds for a build of the unreleased tree as well.
128
+ def require_detailed(handle, path)
129
+ return if DETAILED_EXPORTS.all? { |name| handle.sym_defined?(name) }
130
+
131
+ found =
132
+ if handle.sym_defined?(VERSION_PROBE.to_s)
133
+ Interop.version(Fiddle::Function.new(handle[VERSION_PROBE.to_s], [], Fiddle::TYPE_UINT32_T).call)
134
+ else
135
+ "of no known version"
136
+ end
137
+ raise LoadError, "hypercast: #{path} is core #{found}, which predates 1.1: the grouping " \
138
+ "policies and fault details need the detailed exports (cast_detailed, ...), " \
139
+ "and a 1.0 core would read every format by 1.0's rules. Install a 1.1 core"
140
+ end
141
+
108
142
  def load_functions
109
143
  path = library_path
110
144
  raise LoadError, missing_library_message if path.nil?
111
145
 
112
146
  handle = Fiddle.dlopen(path)
147
+ require_detailed(handle, path)
113
148
  plain = [Fiddle::TYPE_VOIDP, Fiddle::TYPE_SIZE_T, Fiddle::TYPE_VOIDP, Fiddle::TYPE_VOIDP]
114
149
  signatures = {
115
150
  plain: plain,
116
151
  numeric: plain.dup.insert(2, Fiddle::TYPE_VOIDP),
117
152
  declared: plain.dup.insert(2, Fiddle::TYPE_UINT32_T),
118
153
  civil: plain.dup.insert(2, Fiddle::TYPE_UINT32_T, Fiddle::TYPE_VOIDP),
154
+ detailed: [Fiddle::TYPE_UINT32_T, Fiddle::TYPE_UINT32_T, Fiddle::TYPE_VOIDP, Fiddle::TYPE_VOIDP,
155
+ Fiddle::TYPE_VOIDP, Fiddle::TYPE_VOIDP, Fiddle::TYPE_SIZE_T, Fiddle::TYPE_VOIDP,
156
+ Fiddle::TYPE_SIZE_T, Fiddle::TYPE_VOIDP, Fiddle::TYPE_VOIDP],
157
+ detailed_from_f64: [Fiddle::TYPE_UINT32_T, Fiddle::TYPE_UINT32_T, Fiddle::TYPE_DOUBLE, Fiddle::TYPE_VOIDP,
158
+ Fiddle::TYPE_VOIDP],
159
+ checked_detailed: [Fiddle::TYPE_UINT32_T, Fiddle::TYPE_UINT32_T, Fiddle::TYPE_VOIDP, Fiddle::TYPE_VOIDP,
160
+ Fiddle::TYPE_VOIDP, Fiddle::TYPE_SIZE_T, Fiddle::TYPE_VOIDP, Fiddle::TYPE_SIZE_T,
161
+ Fiddle::TYPE_VOIDP, Fiddle::TYPE_VOIDP, Fiddle::TYPE_VOIDP],
162
+ checked_detailed_from_f64: [Fiddle::TYPE_UINT32_T, Fiddle::TYPE_UINT32_T, Fiddle::TYPE_VOIDP,
163
+ Fiddle::TYPE_VOIDP, Fiddle::TYPE_SIZE_T, Fiddle::TYPE_DOUBLE,
164
+ Fiddle::TYPE_VOIDP, Fiddle::TYPE_VOIDP, Fiddle::TYPE_VOIDP],
119
165
  typed: [Fiddle::TYPE_DOUBLE, Fiddle::TYPE_VOIDP, Fiddle::TYPE_VOIDP],
120
- typed_declared: [Fiddle::TYPE_DOUBLE, Fiddle::TYPE_UINT32_T, Fiddle::TYPE_VOIDP, Fiddle::TYPE_VOIDP]
166
+ typed_declared: [Fiddle::TYPE_DOUBLE, Fiddle::TYPE_UINT32_T, Fiddle::TYPE_VOIDP, Fiddle::TYPE_VOIDP],
167
+ checked: [Fiddle::TYPE_UINT32_T, Fiddle::TYPE_UINT32_T, Fiddle::TYPE_VOIDP, Fiddle::TYPE_VOIDP,
168
+ Fiddle::TYPE_VOIDP, Fiddle::TYPE_SIZE_T, *plain, Fiddle::TYPE_VOIDP],
169
+ checked_from_f64: [Fiddle::TYPE_UINT32_T, Fiddle::TYPE_DOUBLE, Fiddle::TYPE_VOIDP, Fiddle::TYPE_VOIDP,
170
+ Fiddle::TYPE_SIZE_T, Fiddle::TYPE_VOIDP, Fiddle::TYPE_VOIDP, Fiddle::TYPE_VOIDP],
171
+ constraints_check: [Fiddle::TYPE_UINT32_T, Fiddle::TYPE_UINT32_T, Fiddle::TYPE_VOIDP, Fiddle::TYPE_VOIDP,
172
+ Fiddle::TYPE_SIZE_T],
173
+ declared_decimal: [Fiddle::TYPE_VOIDP, Fiddle::TYPE_SIZE_T, Fiddle::TYPE_VOIDP]
121
174
  }
122
175
  functions = DOORS.to_h do |name, shape|
123
176
  [name, Fiddle::Function.new(handle[name.to_s], signatures.fetch(shape), Fiddle::TYPE_INT32_T)]