vexyl 1.4.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.
data/lib/vexyl/kdl.rb ADDED
@@ -0,0 +1,709 @@
1
+ # SPDX-License-Identifier: Apache-2.0
2
+ # Copyright 2026 Naomi Persephone Amethyst <naomi@amethyst.name>
3
+
4
+ module Vexyl
5
+ # A KDL v2 parser, written to the grammar in the KDL 2.0.0 specification. It keeps what Vexyl
6
+ # needs: where each node and value is, whether a value had a type annotation, and how a string
7
+ # was written. Every offset counts code points from the start of the document.
8
+ module Kdl
9
+ # A document that isn't KDL v2, at the offset where the parser gave up.
10
+ class SyntaxError < StandardError
11
+ attr_reader :offset
12
+
13
+ def initialize(message, offset)
14
+ super(message)
15
+ @offset = offset
16
+ end
17
+ end
18
+
19
+ # An argument or a property's value. +kind+ is :string, :number, :bool or :null; +number+ is
20
+ # always a Float. +bare+ says a string was written without quotes.
21
+ class Value
22
+ attr_reader :kind, :string, :number, :bool, :bare, :annotated, :offset
23
+
24
+ def initialize(kind, string, number, bool, bare, annotated, offset)
25
+ @kind = kind
26
+ @string = string
27
+ @number = number
28
+ @bool = bool
29
+ @bare = bare
30
+ @annotated = annotated
31
+ @offset = offset
32
+ end
33
+
34
+ def string?
35
+ @kind == :string
36
+ end
37
+ end
38
+
39
+ # A node, with where it starts and just past its last character. +repeated_props+ are
40
+ # properties given more than once, which KDL would let the last of win.
41
+ class Node
42
+ attr_accessor :name, :annotated, :start, :stop
43
+ attr_reader :args, :props, :repeated_props, :children
44
+
45
+ def initialize
46
+ @name = nil
47
+ @annotated = false
48
+ @start = 0
49
+ @stop = 0
50
+ @args = []
51
+ @props = {}
52
+ @repeated_props = []
53
+ @children = []
54
+ end
55
+
56
+ def prop(key)
57
+ @props[key]
58
+ end
59
+ end
60
+
61
+ def self.parse(src)
62
+ Reader.new(src).document
63
+ end
64
+
65
+ # Whether a code point is one of KDL's newlines, counting CR LF as one at the CR.
66
+ def self.newline?(c)
67
+ c == 0x0A || c == 0x0D || c == 0x85 || c == 0x0B || c == 0x0C || c == 0x2028 || c == 0x2029
68
+ end
69
+
70
+ def self.space?(c)
71
+ c == 0x09 || c == 0x20 || c == 0xA0 || c == 0x1680 || (c >= 0x2000 && c <= 0x200A) ||
72
+ c == 0x202F || c == 0x205F || c == 0x3000
73
+ end
74
+
75
+ # Code points that can't be anywhere in a document, not even in a comment.
76
+ def self.disallowed?(c)
77
+ c <= 0x08 || (c >= 0x0E && c <= 0x1F) || c == 0x7F || (c >= 0xD800 && c <= 0xDFFF) ||
78
+ c == 0x200E || c == 0x200F || (c >= 0x202A && c <= 0x202E) || (c >= 0x2066 && c <= 0x2069) ||
79
+ c == 0xFEFF
80
+ end
81
+
82
+ NOT_IDENTIFIER = '\\/(){};[]"#='.codepoints.freeze
83
+
84
+ def self.identifier_char?(c)
85
+ return false if space?(c) || newline?(c) || disallowed?(c)
86
+ !NOT_IDENTIFIER.include?(c)
87
+ end
88
+
89
+ # Reads one document, keeping its code points and a position among them.
90
+ class Reader
91
+ SLASH = 0x2F
92
+ STAR = 0x2A
93
+ BACKSLASH = 0x5C
94
+ QUOTE = 0x22
95
+ HASH = 0x23
96
+
97
+ def initialize(src)
98
+ @c = src.codepoints
99
+ @n = @c.length
100
+ @pos = 0
101
+ end
102
+
103
+ def document
104
+ @c.each_with_index do |c, i|
105
+ next unless Kdl.disallowed?(c) && !(c == 0xFEFF && i.zero?)
106
+ @pos = i
107
+ raise error(format("U+%04X can't be in a KDL document", c))
108
+ end
109
+ @pos += 1 if peek == 0xFEFF
110
+ nodes = nodes(false)
111
+ raise error("unexpected `#{[peek].pack("U")}`") unless eof?
112
+ nodes
113
+ end
114
+
115
+ private
116
+
117
+ def error(message)
118
+ SyntaxError.new(message, @pos)
119
+ end
120
+
121
+ def eof?
122
+ @pos >= @n
123
+ end
124
+
125
+ def peek
126
+ @pos < @n ? @c[@pos] : -1
127
+ end
128
+
129
+ def peek_at(at)
130
+ at < @n ? @c[at] : -1
131
+ end
132
+
133
+ def at2?(a, b)
134
+ @c[@pos] == a && @c[@pos + 1] == b
135
+ end
136
+
137
+ def at?(text)
138
+ cps = text.codepoints
139
+ cps.each_with_index { |c, i| return false unless @c[@pos + i] == c }
140
+ true
141
+ end
142
+
143
+ def text(from, to)
144
+ @c[from...to].pack("U*")
145
+ end
146
+
147
+ def advance
148
+ @pos += 1
149
+ end
150
+
151
+ def nodes(in_children)
152
+ nodes = []
153
+ loop do
154
+ line_space
155
+ if eof?
156
+ raise error("a `{` is never closed") if in_children
157
+ return nodes
158
+ end
159
+ if peek == 0x7D
160
+ return nodes if in_children
161
+ raise error("a `}` closes nothing")
162
+ end
163
+ if at2?(SLASH, 0x2D)
164
+ @pos += 2
165
+ line_space
166
+ node(in_children)
167
+ next
168
+ end
169
+ nodes << node(in_children)
170
+ end
171
+ end
172
+
173
+ # Skips whitespace, newlines and comments, as KDL's line-space does.
174
+ def line_space
175
+ until eof?
176
+ next if node_space
177
+ c = peek
178
+ if Kdl.newline?(c)
179
+ newline
180
+ elsif at2?(SLASH, SLASH)
181
+ line_comment
182
+ else
183
+ return
184
+ end
185
+ end
186
+ end
187
+
188
+ def newline
189
+ if at2?(0x0D, 0x0A)
190
+ @pos += 2
191
+ else
192
+ advance
193
+ end
194
+ end
195
+
196
+ def line_comment
197
+ advance while !eof? && !Kdl.newline?(peek)
198
+ end
199
+
200
+ def block_comment
201
+ start = @pos
202
+ @pos += 2
203
+ depth = 1
204
+ while depth.positive?
205
+ if eof?
206
+ @pos = start
207
+ raise error("a `/*` comment is never closed")
208
+ end
209
+ if at2?(SLASH, STAR)
210
+ depth += 1
211
+ @pos += 2
212
+ elsif at2?(STAR, SLASH)
213
+ depth -= 1
214
+ @pos += 2
215
+ else
216
+ advance
217
+ end
218
+ end
219
+ end
220
+
221
+ # Skips node-space, which is whitespace, block comments and escaped newlines.
222
+ def node_space
223
+ was = @pos
224
+ until eof?
225
+ c = peek
226
+ if Kdl.space?(c)
227
+ advance
228
+ elsif at2?(SLASH, STAR)
229
+ block_comment
230
+ elsif c == BACKSLASH
231
+ back = @pos
232
+ @pos += 1
233
+ while !eof? && (Kdl.space?(peek) || at2?(SLASH, STAR))
234
+ if at2?(SLASH, STAR)
235
+ block_comment
236
+ else
237
+ advance
238
+ end
239
+ end
240
+ if at2?(SLASH, SLASH)
241
+ line_comment
242
+ newline unless eof?
243
+ elsif !eof? && Kdl.newline?(peek)
244
+ newline
245
+ elsif !eof?
246
+ @pos = back
247
+ raise error("a `\\` outside a string has to end its line")
248
+ end
249
+ else
250
+ break
251
+ end
252
+ end
253
+ @pos > was
254
+ end
255
+
256
+ def node(in_children)
257
+ n = Node.new
258
+ n.start = @pos
259
+ if peek == 0x28
260
+ annotation
261
+ n.annotated = true
262
+ node_space
263
+ end
264
+ name = string
265
+ raise error("expected a node's name") if name.nil?
266
+ n.name = name.string
267
+ n.stop = @pos
268
+ children_done = false
269
+ loop do
270
+ spaced = node_space
271
+ return n if eof?
272
+ c = peek
273
+ if Kdl.newline?(c) || c == 0x3B || at2?(SLASH, SLASH)
274
+ @pos += 1 if c == 0x3B
275
+ return n
276
+ end
277
+ if c == 0x7D
278
+ raise error("a `}` closes nothing") unless in_children
279
+ return n
280
+ end
281
+ if at2?(SLASH, 0x2D)
282
+ @pos += 2
283
+ line_space
284
+ if peek == 0x7B
285
+ children(Node.new)
286
+ elsif children_done
287
+ raise error("nothing but children can follow a node's children")
288
+ else
289
+ entry(Node.new)
290
+ end
291
+ next
292
+ end
293
+ if c == 0x7B
294
+ raise error("a node has one block of children") if children_done
295
+ children(n)
296
+ n.stop = @pos
297
+ children_done = true
298
+ next
299
+ end
300
+ raise error("nothing but children can follow a node's children") if children_done
301
+ raise error("expected a space") unless spaced
302
+ entry(n)
303
+ n.stop = @pos
304
+ end
305
+ end
306
+
307
+ def children(n)
308
+ @pos += 1
309
+ n.children.concat(nodes(true))
310
+ @pos += 1
311
+ end
312
+
313
+ def annotation
314
+ @pos += 1
315
+ node_space
316
+ raise error("expected a type in the annotation") if string.nil?
317
+ node_space
318
+ raise error("expected `)`") unless peek == 0x29
319
+ @pos += 1
320
+ end
321
+
322
+ # Reads an argument or a property into n.
323
+ def entry(n)
324
+ start = @pos
325
+ annotated = false
326
+ if peek == 0x28
327
+ annotation
328
+ annotated = true
329
+ node_space
330
+ end
331
+ v = value(annotated, start)
332
+ if v.kind == :string && !annotated
333
+ back = @pos
334
+ node_space
335
+ if peek == 0x3D
336
+ @pos += 1
337
+ node_space
338
+ value_start = @pos
339
+ value_annotated = false
340
+ if peek == 0x28
341
+ annotation
342
+ value_annotated = true
343
+ node_space
344
+ end
345
+ value = value(value_annotated, value_start)
346
+ if n.props.key?(v.string)
347
+ n.repeated_props << v.string
348
+ n.props.delete(v.string)
349
+ end
350
+ n.props[v.string] = value
351
+ return
352
+ end
353
+ @pos = back
354
+ elsif peek == 0x3D || look_ahead_equals?
355
+ raise error("a property's name has to be a string, without a type")
356
+ end
357
+ n.args << v
358
+ end
359
+
360
+ def look_ahead_equals?
361
+ back = @pos
362
+ node_space
363
+ equals = peek == 0x3D
364
+ @pos = back
365
+ equals
366
+ end
367
+
368
+ def value(annotated, start)
369
+ c = peek
370
+ at = @pos
371
+ if c == HASH && peek_at(@pos + 1) != QUOTE && peek_at(@pos + 1) != HASH
372
+ return keyword(annotated, start)
373
+ end
374
+ if digit?(c) || ((c == 0x2B || c == 0x2D) && digit?(peek_at(@pos + 1)))
375
+ return number(annotated, start)
376
+ end
377
+ v = string
378
+ if v.nil?
379
+ @pos = at
380
+ raise error("expected a value")
381
+ end
382
+ Value.new(:string, v.string, 0.0, false, v.bare, annotated, start)
383
+ end
384
+
385
+ def digit?(c)
386
+ c >= 0x30 && c <= 0x39
387
+ end
388
+
389
+ def delimited
390
+ return if eof? || !Kdl.identifier_char?(peek)
391
+ raise error("unexpected `#{[peek].pack("U")}` after a value")
392
+ end
393
+
394
+ KEYWORDS = {
395
+ "#true" => [:bool, 0.0, true],
396
+ "#false" => [:bool, 0.0, false],
397
+ "#null" => [:null, 0.0, false],
398
+ "#inf" => [:number, Float::INFINITY, false],
399
+ "#-inf" => [:number, -Float::INFINITY, false],
400
+ "#nan" => [:number, Float::NAN, false],
401
+ }.freeze
402
+
403
+ def keyword(annotated, start)
404
+ from = @pos
405
+ @pos += 1
406
+ advance while !eof? && Kdl.identifier_char?(peek)
407
+ word = text(from, @pos)
408
+ kind, number, bool = KEYWORDS[word]
409
+ if kind.nil?
410
+ @pos = from
411
+ raise error("unknown keyword `#{word}`")
412
+ end
413
+ Value.new(kind, nil, number, bool, false, annotated, start)
414
+ end
415
+
416
+ def radix_digit?(c, radix)
417
+ case radix
418
+ when 16 then digit?(c) || (c >= 0x61 && c <= 0x66) || (c >= 0x41 && c <= 0x46)
419
+ when 8 then c >= 0x30 && c <= 0x37
420
+ else c == 0x30 || c == 0x31
421
+ end
422
+ end
423
+
424
+ def number(annotated, start)
425
+ from = @pos
426
+ negative = false
427
+ if peek == 0x2B || peek == 0x2D
428
+ negative = peek == 0x2D
429
+ @pos += 1
430
+ end
431
+ radix = 10
432
+ if peek == 0x30
433
+ case peek_at(@pos + 1)
434
+ when 0x78 then radix = 16
435
+ when 0x6F then radix = 8
436
+ when 0x62 then radix = 2
437
+ end
438
+ end
439
+ if radix != 10
440
+ @pos += 2
441
+ digits_from = @pos
442
+ raise error("expected a digit") unless radix_digit?(peek, radix)
443
+ @pos += 1 while !eof? && (radix_digit?(peek, radix) || peek == 0x5F)
444
+ whole = text(digits_from, @pos).delete("_").to_i(radix)
445
+ value = quietly { (negative ? -whole : whole).to_f }
446
+ else
447
+ digits
448
+ if peek == 0x2E
449
+ @pos += 1
450
+ raise error("expected a digit after `.`") unless digit?(peek)
451
+ digits
452
+ end
453
+ if peek == 0x65 || peek == 0x45
454
+ @pos += 1
455
+ @pos += 1 if peek == 0x2B || peek == 0x2D
456
+ raise error("expected an exponent") unless digit?(peek)
457
+ digits
458
+ end
459
+ written = text(from, @pos).delete("_")
460
+ value = decimal(written)
461
+ # A value too small to hold isn't zero, so it's kept as the smallest there is, which
462
+ # is still beyond the format's limits.
463
+ value = negative ? -5e-324 : 5e-324 if value.zero? && written.split(/[eE]/, 2)[0].match?(/[1-9]/)
464
+ end
465
+ delimited
466
+ Value.new(:number, nil, value, false, false, annotated, start)
467
+ end
468
+
469
+ # Converts decimal digits to the nearest Float. Ruby's Float() handles any length of
470
+ # digits and exponent, rounding correctly, apart from exponents so large they overflow.
471
+ def decimal(written)
472
+ quietly { Float(written) }
473
+ end
474
+
475
+ # Runs a conversion without its warning about a value out of a Float's range, which the
476
+ # format's limits refuse anyway.
477
+ def quietly
478
+ verbose = $VERBOSE
479
+ $VERBOSE = nil
480
+ yield
481
+ ensure
482
+ $VERBOSE = verbose
483
+ end
484
+
485
+ def digits
486
+ @pos += 1 while !eof? && (digit?(peek) || peek == 0x5F)
487
+ end
488
+
489
+ # Reads a string in any of its forms, or gives nil if none starts here.
490
+ def string
491
+ start = @pos
492
+ c = peek
493
+ return Value.new(:string, quoted, 0.0, false, false, false, start) if c == QUOTE
494
+ if c == HASH && (peek_at(@pos + 1) == QUOTE || peek_at(@pos + 1) == HASH)
495
+ return Value.new(:string, raw, 0.0, false, false, false, start)
496
+ end
497
+ return nil if c.negative? || !Kdl.identifier_char?(c)
498
+ raise error("a bare string can't start with a digit") if digit?(c)
499
+ if (c == 0x2B || c == 0x2D) &&
500
+ (digit?(peek_at(@pos + 1)) || (peek_at(@pos + 1) == 0x2E && digit?(peek_at(@pos + 2))))
501
+ raise error("a bare string can't look like a number")
502
+ end
503
+ raise error("a bare string can't look like a number") if c == 0x2E && digit?(peek_at(@pos + 1))
504
+ advance while !eof? && Kdl.identifier_char?(peek)
505
+ word = text(start, @pos)
506
+ case word
507
+ when "true", "false", "null", "inf", "-inf", "nan"
508
+ @pos = start
509
+ raise error("`#{word}` has to be quoted to be a string, or written `##{word}`")
510
+ end
511
+ Value.new(:string, word, 0.0, false, true, false, start)
512
+ end
513
+
514
+ def quoted
515
+ if at?('"""')
516
+ start = @pos
517
+ @pos += 3
518
+ if eof? || !Kdl.newline?(peek)
519
+ raise error("a multi-line string starts a new line after its `\"\"\"`")
520
+ end
521
+ body_start = @pos
522
+ loop do
523
+ if eof?
524
+ @pos = start
525
+ raise error("a string is never closed")
526
+ end
527
+ if peek == BACKSLASH
528
+ @pos += 1
529
+ advance unless eof?
530
+ elsif at?('"""')
531
+ break
532
+ else
533
+ advance
534
+ end
535
+ end
536
+ body = @c[body_start...@pos]
537
+ @pos += 3
538
+ return unescape(dedent(body, start), start)
539
+ end
540
+ start = @pos
541
+ @pos += 1
542
+ loop do
543
+ if eof?
544
+ @pos = start
545
+ raise error("a string is never closed")
546
+ end
547
+ c = peek
548
+ if c == BACKSLASH
549
+ @pos += 1
550
+ advance unless eof?
551
+ elsif c == QUOTE
552
+ break
553
+ elsif Kdl.newline?(c)
554
+ raise error("a string on one line can't hold a newline; use `\"\"\"`")
555
+ else
556
+ advance
557
+ end
558
+ end
559
+ body = @c[(start + 1)...@pos]
560
+ @pos += 1
561
+ unescape(body, start + 1)
562
+ end
563
+
564
+ def raw
565
+ start = @pos
566
+ hashes = 0
567
+ while peek == HASH
568
+ hashes += 1
569
+ @pos += 1
570
+ end
571
+ close = "\"#{"#" * hashes}"
572
+ multi = at?('"""')
573
+ if multi
574
+ @pos += 3
575
+ if eof? || !Kdl.newline?(peek)
576
+ raise error("a multi-line string starts a new line after its `\"\"\"`")
577
+ end
578
+ close = "\"\"\"#{"#" * hashes}"
579
+ else
580
+ @pos += 1
581
+ end
582
+ body_start = @pos
583
+ close_cps = close.codepoints
584
+ finish = find(close_cps, @pos)
585
+ if finish.nil?
586
+ @pos = start
587
+ raise error("a raw string is never closed")
588
+ end
589
+ body = @c[body_start...finish]
590
+ @pos = finish + close_cps.length
591
+ return dedent(body, start).pack("U*") if multi
592
+ body.each_with_index do |c, i|
593
+ next unless Kdl.newline?(c)
594
+ @pos = body_start + i
595
+ raise error("a raw string on one line can't hold a newline")
596
+ end
597
+ body.pack("U*")
598
+ end
599
+
600
+ def find(cps, from)
601
+ first = cps[0]
602
+ i = from
603
+ last = @n - cps.length
604
+ while i <= last
605
+ if @c[i] == first
606
+ j = 1
607
+ j += 1 while j < cps.length && @c[i + j] == cps[j]
608
+ return i if j == cps.length
609
+ end
610
+ i += 1
611
+ end
612
+ nil
613
+ end
614
+
615
+ # Removes a multi-line string's indentation, which is whatever is before its closing
616
+ # quotes, from each of its lines. KDL does this before it resolves escapes. Takes and gives
617
+ # code points.
618
+ def dedent(body, start)
619
+ lines = []
620
+ from = 0
621
+ i = 0
622
+ while i < body.length
623
+ c = body[i]
624
+ if Kdl.newline?(c)
625
+ lines << body[from...i]
626
+ i += c == 0x0D && body[i + 1] == 0x0A ? 2 : 1
627
+ from = i
628
+ else
629
+ i += 1
630
+ end
631
+ end
632
+ lines << body[from..]
633
+ prefix = lines[-1]
634
+ unless blank?(prefix)
635
+ @pos = start
636
+ raise error("a multi-line string's closing `\"\"\"` has to be on a line of its own")
637
+ end
638
+ out = []
639
+ (1...(lines.length - 1)).each do |k|
640
+ line = lines[k]
641
+ out << 0x0A if k > 1
642
+ next if blank?(line)
643
+ unless line[0, prefix.length] == prefix
644
+ @pos = start
645
+ raise error("each line of a multi-line string has to start with the indentation of its last")
646
+ end
647
+ out.concat(line[prefix.length..])
648
+ end
649
+ out
650
+ end
651
+
652
+ def blank?(cps)
653
+ cps.all? { |c| Kdl.space?(c) }
654
+ end
655
+
656
+ ESCAPES = { 0x6E => 0x0A, 0x72 => 0x0D, 0x74 => 0x09, 0x5C => 0x5C, 0x22 => 0x22,
657
+ 0x62 => 0x08, 0x66 => 0x0C, 0x73 => 0x20 }.freeze
658
+
659
+ # Resolves escapes in code points, giving a String.
660
+ def unescape(body, start)
661
+ return body.pack("U*") unless body.include?(BACKSLASH)
662
+ out = []
663
+ i = 0
664
+ while i < body.length
665
+ c = body[i]
666
+ if c != BACKSLASH
667
+ out << c
668
+ i += 1
669
+ next
670
+ end
671
+ if i + 1 >= body.length
672
+ @pos = start
673
+ raise error("a string ends in the middle of an escape")
674
+ end
675
+ e = body[i + 1]
676
+ if (r = ESCAPES[e])
677
+ out << r
678
+ i += 2
679
+ elsif e == 0x75
680
+ close = (i...body.length).find { |k| body[k] == 0x7D }
681
+ if i + 2 >= body.length || body[i + 2] != 0x7B || close.nil? || close - (i + 3) < 1 || close - (i + 3) > 6
682
+ @pos = start
683
+ raise error("a `\\u` escape is written `\\u{` and 1 to 6 hexadecimal digits `}`")
684
+ end
685
+ hex = body[(i + 3)...close]
686
+ unless hex.all? { |h| radix_digit?(h, 16) }
687
+ @pos = start
688
+ raise error("a `\\u` escape is written `\\u{` and 1 to 6 hexadecimal digits `}`")
689
+ end
690
+ code = hex.pack("U*").to_i(16)
691
+ if code > 0x10FFFF || (code >= 0xD800 && code <= 0xDFFF)
692
+ @pos = start
693
+ raise error("a `\\u` escape has to be a Unicode scalar value")
694
+ end
695
+ out << code
696
+ i = close + 1
697
+ elsif Kdl.space?(e) || Kdl.newline?(e)
698
+ i += 1
699
+ i += 1 while i < body.length && (Kdl.space?(body[i]) || Kdl.newline?(body[i]))
700
+ else
701
+ @pos = start
702
+ raise error("unknown escape `\\#{[e].pack("U")}`")
703
+ end
704
+ end
705
+ out.pack("U*")
706
+ end
707
+ end
708
+ end
709
+ end