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.
@@ -0,0 +1,568 @@
1
+ # SPDX-License-Identifier: Apache-2.0
2
+ # Copyright 2026 Naomi Persephone Amethyst <naomi@amethyst.name>
3
+
4
+ module Vexyl
5
+ # What a document says, as the parser reads it. These are the library's own, and change only
6
+ # while a document is read: rendering copies what it changes, so a flag stays as it was.
7
+ module Model
8
+ # Copies a value shallowly, as assigning a struct does in Go.
9
+ module Copyable
10
+ def copy
11
+ dup
12
+ end
13
+ end
14
+
15
+ class Doc
16
+ include Copyable
17
+ attr_accessor :version, :meta, :palette, :color_refs, :gradients, :hoist, :fly, :outline,
18
+ :border, :border_outside, :defines, :layers, :reverse, :adapt, :variants, :folds,
19
+ :id_prefix, :seen_from_behind
20
+
21
+ def initialize
22
+ @version = 0
23
+ @meta = Meta.new
24
+ # Color names to #rrggbb values, in lowercase.
25
+ @palette = {}
26
+ # Colors' values in other systems, for print and dye.
27
+ @color_refs = {}
28
+ @gradients = {}
29
+ @hoist = 0.0
30
+ @fly = 0.0
31
+ @outline = nil
32
+ @border = nil
33
+ @border_outside = false
34
+ @defines = {}
35
+ @layers = []
36
+ @reverse = nil
37
+ @adapt = nil
38
+ @variants = {}
39
+ @folds = {}
40
+ # Unique to the source, so that several flags can be inlined in one page.
41
+ @id_prefix = ""
42
+ # Says that the layers are a reverse's own, as seen from behind, while it's drawn.
43
+ @seen_from_behind = false
44
+ end
45
+ end
46
+
47
+ class Gradient
48
+ attr_accessor :colors, :stops, :along
49
+
50
+ def initialize
51
+ @colors = []
52
+ @stops = nil
53
+ @along = "fly"
54
+ end
55
+ end
56
+
57
+ class Meta
58
+ attr_accessor :name, :description, :version, :date, :until, :series, :notes, :laws,
59
+ :restrictions, :designers, :design_rights, :encoders, :license, :render_license,
60
+ :adapted_from, :sources
61
+
62
+ def initialize
63
+ @name = ""
64
+ @description = ""
65
+ @version = ""
66
+ @date = ""
67
+ @until = ""
68
+ @series = ""
69
+ @notes = []
70
+ @laws = []
71
+ @restrictions = []
72
+ @designers = []
73
+ @design_rights = ""
74
+ @encoders = []
75
+ @license = ""
76
+ @render_license = ""
77
+ @adapted_from = []
78
+ @sources = []
79
+ end
80
+ end
81
+
82
+ class Adaptation
83
+ attr_accessor :url, :authors, :license, :part
84
+
85
+ def initialize
86
+ @url = ""
87
+ @authors = []
88
+ @license = ""
89
+ @part = ""
90
+ end
91
+ end
92
+
93
+ class Reference
94
+ attr_accessor :text, :sources
95
+
96
+ def initialize
97
+ @text = ""
98
+ @sources = []
99
+ end
100
+ end
101
+
102
+ class ColorRef
103
+ # numbers: the same value as numbers, for cmyk. other: a system named in a `reference`,
104
+ # rather than one of the format's own.
105
+ attr_accessor :system, :value, :numbers, :other
106
+
107
+ def initialize
108
+ @system = ""
109
+ @value = ""
110
+ @numbers = nil
111
+ @other = false
112
+ end
113
+ end
114
+
115
+ class Point
116
+ attr_reader :fly, :hoist
117
+
118
+ def initialize(fly, hoist)
119
+ @fly = fly.to_f
120
+ @hoist = hoist.to_f
121
+ end
122
+ end
123
+
124
+ class Edge
125
+ attr_reader :color, :width
126
+
127
+ def initialize(color, width)
128
+ @color = color
129
+ @width = width.to_f
130
+ end
131
+ end
132
+
133
+ class Outline
134
+ include Copyable
135
+ # kind: polygon, path, swallowtail, tongued or pennant.
136
+ attr_accessor :kind, :vertices, :d, :box, :depth, :tip, :tongue, :taper
137
+
138
+ def initialize
139
+ @kind = ""
140
+ @vertices = []
141
+ @d = ""
142
+ @box = [0.0, 0.0, 0.0, 0.0]
143
+ @depth = 0.0
144
+ @tip = 0.0
145
+ @tongue = 0.0
146
+ @taper = 0.0
147
+ end
148
+ end
149
+
150
+ class Define
151
+ # fly, hoist: a design's own grid, scaled to fill where it's used. size, height: worked out
152
+ # when it's read, as SPEC section 15 counts them.
153
+ attr_accessor :shape, :layers, :fly, :hoist, :size, :height
154
+
155
+ def initialize
156
+ @shape = nil
157
+ @layers = []
158
+ @fly = 0.0
159
+ @hoist = 0.0
160
+ @size = 0
161
+ @height = 0
162
+ end
163
+ end
164
+
165
+ class Reverse
166
+ attr_accessor :layers
167
+
168
+ def initialize
169
+ @layers = []
170
+ end
171
+ end
172
+
173
+ class Adapt
174
+ # min, max: limits on the proportion as fly divided by hoist; zero is no limit. wider,
175
+ # narrower: extend, center, scale, hoist-extend, hoist-center or hoist-scale, or "" for none.
176
+ attr_accessor :min, :max, :wider, :narrower
177
+
178
+ def initialize
179
+ @min = 0.0
180
+ @max = 0.0
181
+ @wider = ""
182
+ @narrower = ""
183
+ end
184
+ end
185
+
186
+ class Variant
187
+ attr_accessor :from, :upright, :ratio, :fly, :hoist, :outline, :border, :border_outside, :layers
188
+
189
+ def initialize
190
+ @from = "none"
191
+ @upright = false
192
+ @ratio = 0.0
193
+ @fly = 0.0
194
+ @hoist = 0.0
195
+ @outline = nil
196
+ @border = nil
197
+ @border_outside = false
198
+ @layers = []
199
+ end
200
+ end
201
+
202
+ class Fold
203
+ attr_accessor :description, :sources, :steps
204
+
205
+ def initialize
206
+ @description = ""
207
+ @sources = []
208
+ @steps = []
209
+ end
210
+ end
211
+
212
+ class FoldStep
213
+ # kind: over, under or tuck. along, move, at: for a crease along an axis. through, move_to:
214
+ # for a crease through two points, as written. a, b, moving: the crease's two points, and a
215
+ # point on the side that moves.
216
+ attr_accessor :kind, :along, :move, :at, :through, :move_to, :a, :b, :moving
217
+
218
+ def initialize
219
+ @kind = ""
220
+ @along = ""
221
+ @move = ""
222
+ @at = 0.0
223
+ @through = nil
224
+ @move_to = nil
225
+ @a = nil
226
+ @b = nil
227
+ @moving = nil
228
+ end
229
+ end
230
+
231
+ # A wavy or zigzag edge between divisions.
232
+ class Line
233
+ attr_accessor :kind, :depth, :period, :count
234
+
235
+ def initialize
236
+ @kind = ""
237
+ @depth = 0.0
238
+ @period = 0.0
239
+ @count = 0
240
+ end
241
+
242
+ # How many waves it has across the flag's longer side.
243
+ def waves(longer)
244
+ return @count if @count > 0
245
+ return 0 if @period <= 0
246
+ waves = (longer / @period).ceil
247
+ return Limits::MAX_COPIES + 1 if waves > Limits::MAX_COPIES
248
+ waves.to_i
249
+ end
250
+ end
251
+
252
+ # One of the layers of section 6 of the format, with the properties they all have.
253
+ class Layer
254
+ include Copyable
255
+ # anchor: start, center, end or scale, or "" to follow the flag's rule.
256
+ attr_accessor :anchor, :opacity, :blend, :clip, :cuts
257
+
258
+ def initialize
259
+ @anchor = ""
260
+ @opacity = 1.0
261
+ @blend = "normal"
262
+ @clip = nil
263
+ @cuts = []
264
+ end
265
+ end
266
+
267
+ class Field < Layer
268
+ attr_accessor :color
269
+
270
+ def initialize
271
+ super
272
+ @color = ""
273
+ end
274
+
275
+ def kind = "field"
276
+ end
277
+
278
+ # Where adapting put a rotated bars or band, if it did: the region it was drawn in (w, h),
279
+ # and where its center moved to in the new one (x, y).
280
+ class FixedFrame
281
+ attr_accessor :w, :h, :x, :y
282
+
283
+ def initialize(w, h, x, y)
284
+ @w = w
285
+ @h = h
286
+ @x = x
287
+ @y = y
288
+ end
289
+ end
290
+
291
+ class Bars < Layer
292
+ attr_accessor :colors, :along, :ratio, :rotate, :grow, :line, :fixed
293
+
294
+ def initialize
295
+ super
296
+ @colors = []
297
+ @along = "fly"
298
+ @ratio = nil
299
+ @rotate = 0.0
300
+ @grow = nil
301
+ @line = nil
302
+ @fixed = nil
303
+ end
304
+
305
+ def kind = "bars"
306
+ end
307
+
308
+ class Chevrons < Layer
309
+ # apex is nil when it isn't given.
310
+ attr_accessor :colors, :from, :depth, :angle, :apex, :ratio, :rotate, :fimbriate
311
+
312
+ def initialize
313
+ super
314
+ @colors = []
315
+ @from = "hoist"
316
+ @depth = 0.0
317
+ @angle = 0.0
318
+ @apex = nil
319
+ @ratio = nil
320
+ @rotate = 0.0
321
+ @fimbriate = nil
322
+ end
323
+
324
+ def kind = "chevrons"
325
+ end
326
+
327
+ class Band < Layer
328
+ attr_accessor :color, :along, :width, :offset, :rotate, :fimbriate, :fixed
329
+
330
+ def initialize
331
+ super
332
+ @color = ""
333
+ @along = "fly"
334
+ @width = 0.0
335
+ @offset = 0.0
336
+ @rotate = 0.0
337
+ @fimbriate = nil
338
+ @fixed = nil
339
+ end
340
+
341
+ def kind = "band"
342
+ end
343
+
344
+ class Cross < Layer
345
+ attr_accessor :color, :fly_parts, :hoist_parts, :fimbriate
346
+
347
+ def initialize
348
+ super
349
+ @color = ""
350
+ @fly_parts = [0.0, 1.0, 0.0]
351
+ @hoist_parts = [0.0, 1.0, 0.0]
352
+ @fimbriate = nil
353
+ end
354
+
355
+ def kind = "cross"
356
+ end
357
+
358
+ class Saltire < Layer
359
+ attr_accessor :color, :width, :fimbriate, :counterchange
360
+
361
+ def initialize
362
+ super
363
+ @color = ""
364
+ @width = 0.0
365
+ @fimbriate = nil
366
+ @counterchange = false
367
+ end
368
+
369
+ def kind = "saltire"
370
+ end
371
+
372
+ class Quarters < Layer
373
+ attr_accessor :colors, :diagonal, :split
374
+
375
+ def initialize
376
+ super
377
+ @colors = ["", "", "", ""]
378
+ @diagonal = false
379
+ @split = nil
380
+ end
381
+
382
+ def kind = "quarters"
383
+ end
384
+
385
+ class Checks < Layer
386
+ attr_accessor :colors, :rows, :columns, :flow
387
+
388
+ def initialize
389
+ super
390
+ @colors = []
391
+ @rows = 0
392
+ @columns = 0
393
+ @flow = "bend-sinister"
394
+ end
395
+
396
+ def kind = "checks"
397
+ end
398
+
399
+ class Rays < Layer
400
+ # from: center, a corner or the middle of an edge; at overrides it.
401
+ attr_accessor :colors, :from, :at, :ratio, :rotate, :by_edge
402
+
403
+ def initialize
404
+ super
405
+ @colors = []
406
+ @from = "center"
407
+ @at = nil
408
+ @ratio = nil
409
+ @rotate = 0.0
410
+ @by_edge = false
411
+ end
412
+
413
+ def kind = "rays"
414
+ end
415
+
416
+ # A charge, or a pile or pall, which are read as charges of their own shapes.
417
+ class Charge < Layer
418
+ # color is optional for inline SVG, where it's what currentColor means.
419
+ attr_accessor :shape, :color, :fimbriate, :repeat
420
+
421
+ def initialize
422
+ super
423
+ @shape = Shape.new
424
+ @color = ""
425
+ @fimbriate = nil
426
+ @repeat = nil
427
+ end
428
+
429
+ def kind
430
+ k = @shape.kind
431
+ k == "pile" || k == "pall" ? k : "charge"
432
+ end
433
+ end
434
+
435
+ class Emblem < Layer
436
+ attr_accessor :at, :along, :rotate, :charges
437
+
438
+ def initialize
439
+ super
440
+ @at = nil
441
+ @along = ""
442
+ @rotate = 0.0
443
+ @charges = []
444
+ end
445
+
446
+ def kind = "emblem"
447
+ end
448
+
449
+ class Group < Layer
450
+ attr_accessor :layers
451
+
452
+ def initialize
453
+ super
454
+ @layers = []
455
+ end
456
+
457
+ def kind = "group"
458
+ end
459
+
460
+ class Panel < Layer
461
+ # canton: written as a canton.
462
+ attr_accessor :side, :width, :corner, :at, :fly, :hoist, :line, :layers, :canton
463
+
464
+ def initialize
465
+ super
466
+ @side = ""
467
+ @width = 0.0
468
+ @corner = ""
469
+ @at = nil
470
+ @fly = 0.0
471
+ @hoist = 0.0
472
+ @line = nil
473
+ @layers = []
474
+ @canton = false
475
+ end
476
+
477
+ def kind
478
+ @canton ? "canton" : "panel"
479
+ end
480
+ end
481
+
482
+ class Use < Layer
483
+ # design: the definition it names, which isn't part of the use itself.
484
+ attr_accessor :name, :design
485
+
486
+ def initialize
487
+ super
488
+ @name = ""
489
+ @design = nil
490
+ end
491
+
492
+ def kind = "use"
493
+ end
494
+
495
+ # A shape used by a charge, clip or cut, or a definition.
496
+ class Shape
497
+ include Copyable
498
+ # at: the position, or nil for the center of the region. ats: the positions of a charge
499
+ # given several, each nil for the center. edge: the edge a pile or pall starts from.
500
+ # markup: inline SVG after being sanitized, in its canonical form. placed: an explicit `at`,
501
+ # even `at center`. auto_inner, auto_spread: values worked out from the shape's others, which
502
+ # a charge using a definition works out again. has_flat: a pile's `flat`, even `flat 0`.
503
+ # embedded: the sanitized artwork.
504
+ attr_accessor :kind, :at, :ats, :rotate, :radius, :inner, :points, :width, :spread, :from, :to,
505
+ :has_arc, :offset, :disc, :gap, :hollow, :lines, :d, :box, :even_odd, :edge, :base,
506
+ :tip, :depth, :flat, :junction, :fly, :hoist, :vertices, :markup, :placed,
507
+ :auto_inner, :auto_spread, :has_flat, :embedded
508
+
509
+ def initialize
510
+ @kind = ""
511
+ @at = nil
512
+ @ats = []
513
+ @rotate = 0.0
514
+ @radius = 0.0
515
+ @inner = 0.0
516
+ @points = 0
517
+ @width = 0.0
518
+ @spread = 0.0
519
+ @from = 0.0
520
+ @to = 0.0
521
+ @has_arc = false
522
+ @offset = 0.0
523
+ @disc = 0.0
524
+ @gap = 0.0
525
+ @hollow = 0.0
526
+ @lines = 0.0
527
+ @d = ""
528
+ @box = [0.0, 0.0, 0.0, 0.0]
529
+ @even_odd = false
530
+ @edge = ""
531
+ @base = nil
532
+ @tip = nil
533
+ @depth = 0.0
534
+ @flat = 0.0
535
+ @junction = 0.0
536
+ @fly = 0.0
537
+ @hoist = 0.0
538
+ @vertices = []
539
+ @markup = ""
540
+ @placed = false
541
+ @auto_inner = false
542
+ @auto_spread = false
543
+ @has_flat = false
544
+ @embedded = nil
545
+ end
546
+ end
547
+
548
+ class Repeat
549
+ include Copyable
550
+ # kind: ring, arc, grid or line.
551
+ attr_accessor :kind, :count, :radius, :turn, :from, :to, :rows, :columns, :stagger, :fly, :hoist
552
+
553
+ def initialize
554
+ @kind = ""
555
+ @count = 0
556
+ @radius = 0.0
557
+ @turn = false
558
+ @from = 0.0
559
+ @to = 0.0
560
+ @rows = 0
561
+ @columns = 0
562
+ @stagger = false
563
+ @fly = 0.0
564
+ @hoist = 0.0
565
+ end
566
+ end
567
+ end
568
+ end
@@ -0,0 +1,151 @@
1
+ # SPDX-License-Identifier: Apache-2.0
2
+ # Copyright 2026 Naomi Persephone Amethyst <naomi@amethyst.name>
3
+
4
+ module Vexyl
5
+ # Numbers written inside strings: a box, a fold's crease, and path data.
6
+ module Numbers
7
+ SPACE = [0x20, 0x09, 0x0a, 0x0c, 0x0d].freeze
8
+ COMMANDS = "MmLlHhVvCcSsQqTtAaZz".codepoints.freeze
9
+ ARGUMENTS = { "M" => 2, "L" => 2, "T" => 2, "H" => 1, "V" => 1, "C" => 6, "S" => 4, "Q" => 4, "A" => 7,
10
+ "Z" => 0 }.freeze
11
+
12
+ module_function
13
+
14
+ # Sanitizer's patterns, built when first needed, since Sanitizer may load after this file.
15
+ def patterns
16
+ @patterns ||= begin
17
+ decimal = source(Sanitizer::DECIMAL)
18
+ comma_space = source(Sanitizer::COMMA_SPACE)
19
+ [Regexp.new("\\A[ \\t\\n\\f\\r]*#{decimal}(?:#{comma_space}#{decimal})*[ \\t\\n\\f\\r]*\\z"),
20
+ Regexp.new(comma_space)]
21
+ end
22
+ end
23
+
24
+ def source(pattern)
25
+ pattern.is_a?(Regexp) ? pattern.source : pattern
26
+ end
27
+
28
+ # Reads a string of numbers, separated by whitespace, a comma or both, or gives nil.
29
+ def list(text)
30
+ whole, split = patterns
31
+ return nil unless whole.match?(text)
32
+ out = []
33
+ Sanitizer.trim(text).split(split, -1).each do |part|
34
+ v = Sanitizer.decimal_value(part)
35
+ return nil if v.nil?
36
+ out << v
37
+ end
38
+ out
39
+ end
40
+
41
+ # Checks path data against SVG's grammar, within the format's limits on numbers, so that a bad
42
+ # one can't silently draw part of a shape or nothing.
43
+ def valid_path(d)
44
+ PathCheck.new(d).valid
45
+ end
46
+
47
+ # Parses what matched Sanitizer::DECIMAL to the nearest Float. Float() refuses a
48
+ # trailing ".", and warns of a number too large or small for a Float, so this works around both.
49
+ def parse_decimal(text)
50
+ verbose = $VERBOSE
51
+ $VERBOSE = nil
52
+ Float(text.sub(/\.(?=[eE]|\z)/, ""))
53
+ ensure
54
+ $VERBOSE = verbose
55
+ end
56
+
57
+ class PathCheck
58
+ def initialize(d)
59
+ @d = d.codepoints
60
+ @i = 0
61
+ end
62
+
63
+ def at
64
+ @d[@i]
65
+ end
66
+
67
+ def space
68
+ @i += 1 while @i < @d.size && SPACE.include?(@d[@i])
69
+ end
70
+
71
+ # Skips whitespace and at most one comma, and says if there was a comma.
72
+ def separator
73
+ space
74
+ if @i < @d.size && @d[@i] == 0x2c
75
+ @i += 1
76
+ space
77
+ return true
78
+ end
79
+ false
80
+ end
81
+
82
+ def digit?(j)
83
+ c = @d[j]
84
+ c && c >= 0x30 && c <= 0x39
85
+ end
86
+
87
+ def digits(j)
88
+ j += 1 while digit?(j)
89
+ j
90
+ end
91
+
92
+ # Matches Sanitizer::DECIMAL at the current place, as a regex's lookingAt would.
93
+ def number
94
+ j = @i
95
+ j += 1 if @d[j] == 0x2b || @d[j] == 0x2d
96
+ if digit?(j)
97
+ j = digits(j)
98
+ j += 1 if @d[j] == 0x2e
99
+ j = digits(j)
100
+ elsif @d[j] == 0x2e && digit?(j + 1)
101
+ j = digits(j + 1)
102
+ else
103
+ return false
104
+ end
105
+ if @d[j] == 0x65 || @d[j] == 0x45
106
+ k = j + 1
107
+ k += 1 if @d[k] == 0x2b || @d[k] == 0x2d
108
+ j = digits(k) if digit?(k)
109
+ end
110
+ v = Numbers.parse_decimal(@d[@i...j].pack("U*"))
111
+ return false if v.nan? || v.abs > Limits::NUMBER_LIMIT
112
+ @i = j
113
+ true
114
+ end
115
+
116
+ def command?(j)
117
+ j < @d.size && COMMANDS.include?(@d[j])
118
+ end
119
+
120
+ def valid
121
+ space
122
+ return false if @i >= @d.size || (at != 0x4d && at != 0x6d)
123
+ while @i < @d.size
124
+ ch = at
125
+ c = ch < 128 ? ch.chr.upcase : ""
126
+ count = ARGUMENTS.fetch(c, -1)
127
+ return false if count < 0
128
+ @i += 1
129
+ space
130
+ # A command can repeat its arguments with no letter, except for Z, which has none.
131
+ first = true
132
+ while count > 0 && (first || (@i < @d.size && !COMMANDS.include?(at)))
133
+ first = false
134
+ count.times do |arg|
135
+ if c == "A" && (arg == 3 || arg == 4)
136
+ return false if @i >= @d.size || (at != 0x30 && at != 0x31)
137
+ @i += 1
138
+ elsif !number
139
+ return false
140
+ end
141
+ separator if arg < count - 1
142
+ end
143
+ return false if separator && (@i >= @d.size || command?(@i))
144
+ end
145
+ space
146
+ end
147
+ true
148
+ end
149
+ end
150
+ end
151
+ end