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,63 @@
1
+ # SPDX-License-Identifier: Apache-2.0
2
+ # Copyright 2026 Naomi Persephone Amethyst <naomi@amethyst.name>
3
+
4
+ module Vexyl
5
+ # How to render a flag, as section 3 of the SDK describes. Every option is optional, and
6
+ # rendering with none gives the flag as it is. A value that can't be used is refused when the
7
+ # flag is rendered, so that no option is ever silently ignored.
8
+ #
9
+ # opts = Vexyl::RenderOptions.new(height: 300, variant: "vertical")
10
+ # flag.svg(height: 300, variant: "vertical") # the same, as keywords
11
+ class RenderOptions
12
+ # The height an image has without the +height+ option.
13
+ DEFAULT_HEIGHT = 600.0
14
+
15
+ KEYS = %i[height ratio variant side fit align fold fold_step id_prefix tags].freeze
16
+
17
+ # +height+ and +ratio+ are numbers, or nil for the default; +ratio+ is fly divided by hoist.
18
+ # +fold_step+ is a whole number, or nil for all of a fold's steps. The others are strings,
19
+ # where nil or "" is the default, apart from +tags+, which is true or false.
20
+ attr_reader(*KEYS)
21
+
22
+ def initialize(height: nil, ratio: nil, variant: nil, side: nil, fit: nil, align: nil, fold: nil,
23
+ fold_step: nil, id_prefix: nil, tags: false)
24
+ @height = height.nil? ? nil : Float(height)
25
+ @ratio = ratio.nil? ? nil : Float(ratio)
26
+ @variant = variant.to_s.dup.freeze
27
+ @side = side.to_s.dup.freeze
28
+ @fit = fit.to_s.dup.freeze
29
+ @align = align.to_s.dup.freeze
30
+ @fold = fold.to_s.dup.freeze
31
+ @fold_step = fold_step.nil? ? nil : Integer(fold_step)
32
+ @id_prefix = id_prefix.to_s.dup.freeze
33
+ @tags = tags ? true : false
34
+ freeze
35
+ end
36
+
37
+ # No options: the flag as it is, at the default height.
38
+ def self.defaults
39
+ @defaults ||= new
40
+ end
41
+
42
+ # These options with some of them changed.
43
+ def with(**changes)
44
+ self.class.new(**to_h, **changes)
45
+ end
46
+
47
+ def to_h
48
+ KEYS.to_h { |k| [k, public_send(k)] }
49
+ end
50
+
51
+ # Options from a RenderOptions, a hash of them, or nil for none.
52
+ # Options from a RenderOptions, a hash of them or nil, with any keywords changing them.
53
+ def self.from(value = nil, **keywords)
54
+ base = case value
55
+ when nil then defaults
56
+ when RenderOptions then value
57
+ when Hash then new(**value.transform_keys(&:to_sym))
58
+ else raise ArgumentError, "options have to be a Vexyl::RenderOptions or a hash"
59
+ end
60
+ keywords.empty? ? base : base.with(**keywords)
61
+ end
62
+ end
63
+ end
@@ -0,0 +1,401 @@
1
+ # SPDX-License-Identifier: Apache-2.0
2
+ # Copyright 2026 Naomi Persephone Amethyst <naomi@amethyst.name>
3
+
4
+ module Vexyl
5
+ # Checks inline SVG against the format's allowlist, as SPEC section 8.3 says, and writes what
6
+ # passes in the canonical form of SDK section 4.2.
7
+ module Sanitizer
8
+ SVG_NAMESPACE = "http://www.w3.org/2000/svg"
9
+ XLINK_NAMESPACE = "http://www.w3.org/1999/xlink"
10
+ MAX_DEPTH = 64
11
+
12
+ # Stands in for an ID's prefix in sanitized markup until it's drawn. It can't appear in XML, so
13
+ # it can't be confused with anything in the artwork.
14
+ ID_MARK = "\0"
15
+
16
+ # What counts as whitespace inside strings and inline SVG.
17
+ SPACE = " \t\n\f\r"
18
+
19
+ # The one way to write a number inside a string, as SPEC section 4 gives it. (Regexp source, so
20
+ # that other patterns can be built from it.)
21
+ DECIMAL = "[-+]?(?:[0-9]+\\.?[0-9]*|\\.[0-9]+)(?:[eE][-+]?[0-9]+)?"
22
+ # Separates numbers in a string, as SVG's comma-wsp does. (Regexp source.)
23
+ COMMA_SPACE = "(?:[ \\t\\n\\f\\r]*,[ \\t\\n\\f\\r]*|[ \\t\\n\\f\\r]+)"
24
+
25
+ COLOR_PROPS = %w[fill stroke stop-color flood-color lighting-color color].freeze
26
+ ALLOWED_ELEMENTS = %w[defs g path rect circle ellipse line polyline polygon linearGradient
27
+ radialGradient stop clipPath mask].freeze
28
+ # These describe a file rather than draw it.
29
+ DROPPED_ELEMENTS = %w[title desc metadata].freeze
30
+ # Allowed as attributes and in style attributes.
31
+ PRESENTATION = %w[fill fill-opacity fill-rule stroke stroke-width stroke-opacity stroke-linecap
32
+ stroke-linejoin stroke-miterlimit stroke-dasharray stroke-dashoffset opacity
33
+ clip-path clip-rule mask stop-color stop-opacity color display visibility
34
+ paint-order vector-effect shape-rendering mix-blend-mode isolation].freeze
35
+ ALLOWED_ATTRS = %w[id transform d x y width height cx cy r rx ry x1 y1 x2 y2 points offset fx fy
36
+ fr gradientUnits gradientTransform spreadMethod clipPathUnits maskUnits
37
+ maskContentUnits style href].freeze
38
+ # Consumed in working out the root's viewBox, or replaced when it's placed on the flag.
39
+ ROOT_ONLY = %w[id x y width height viewBox preserveAspectRatio version baseProfile].freeze
40
+
41
+ CSS_WORD = /[A-Za-z0-9_-]+/
42
+ LOCAL_ID = /\A[A-Za-z_][A-Za-z0-9_.:-]*\z/
43
+ # These spell their cases out, since matching case-insensitively could take other letters.
44
+ COLOR_FUNC = /(?<![A-Za-z0-9_])(?:[rR][gG][bB][aA]?|[hH][sS][lL][aA]?)\(/
45
+ LOCAL_URL = /[uU][rR][lL]\([ \t\n\f\r]*["']?#([A-Za-z_][A-Za-z0-9_.:-]*)["']?[ \t\n\f\r]*\)/
46
+ VIEW_BOX = Regexp.new("\\A[ \\t\\n\\f\\r]*(#{DECIMAL})#{COMMA_SPACE}(#{DECIMAL})#{COMMA_SPACE}" \
47
+ "(#{DECIMAL})#{COMMA_SPACE}(#{DECIMAL})[ \\t\\n\\f\\r]*\\z")
48
+ LENGTH = Regexp.new("\\A[ \\t\\n\\f\\r]*(#{DECIMAL})(?:px)?[ \\t\\n\\f\\r]*\\z")
49
+ DECIMAL_WHOLE = Regexp.new("\\A(?:#{DECIMAL})\\z")
50
+ # SVG's default preserveAspectRatio, the only way artwork is ever fitted.
51
+ DEFAULT_FIT = /\A[ \t\n\f\r]*xMidYMid(?:[ \t\n\f\r]+meet)?[ \t\n\f\r]*\z/
52
+ LEADING_SPACE = /\A[ \t\n\f\r]+/
53
+ TRAILING_SPACE = /[ \t\n\f\r]+\z/
54
+ private_constant :ID_MARK, :SPACE, :COLOR_PROPS, :ALLOWED_ELEMENTS, :DROPPED_ELEMENTS,
55
+ :PRESENTATION, :ALLOWED_ATTRS, :ROOT_ONLY, :CSS_WORD, :LOCAL_ID, :COLOR_FUNC,
56
+ :LOCAL_URL, :VIEW_BOX, :LENGTH, :DECIMAL_WHOLE, :DEFAULT_FIT, :LEADING_SPACE,
57
+ :TRAILING_SPACE
58
+
59
+ # Inline SVG that has passed the sanitizer.
60
+ class Artwork
61
+ # Set by the sanitizer only.
62
+ attr_writer :view_box, :current_color, :attrs, :body
63
+
64
+ def initialize
65
+ @view_box = ""
66
+ @current_color = false
67
+ # The root element's attributes, each with a leading space.
68
+ @attrs = ""
69
+ @body = ""
70
+ end
71
+
72
+ # The root's viewBox, its four numbers joined by single spaces as they were written.
73
+ def view_box
74
+ @view_box
75
+ end
76
+
77
+ # Whether the artwork paints in currentColor anywhere.
78
+ def uses_current_color?
79
+ @current_color
80
+ end
81
+
82
+ # The root's attributes, each with a leading space, with every ID given a prefix.
83
+ def attrs(id_prefix)
84
+ @attrs.gsub("\0") { id_prefix }
85
+ end
86
+
87
+ # What's inside the root, with every ID and reference given a prefix.
88
+ def body(id_prefix)
89
+ @body.gsub("\0") { id_prefix }
90
+ end
91
+
92
+ # The sanitized artwork as one document, with its IDs as they were written.
93
+ def canonical
94
+ ("<svg xmlns=\"#{SVG_NAMESPACE}\" viewBox=\"#{Xml.escape(@view_box)}\"#{@attrs}>#{@body}</svg>")
95
+ .delete("\0")
96
+ end
97
+ end
98
+
99
+ module_function
100
+
101
+ # A number written as SPEC section 4 says, within the format's limits, or nil.
102
+ def decimal_value(text)
103
+ return nil unless DECIMAL_WHOLE.match?(text)
104
+
105
+ # A number such as "1." is valid, and one out of a Float's range is Infinity or 0, but
106
+ # Float() refuses the one and warns about the other, so the magnitude is worked out from
107
+ # the digits first, and anything far outside the limits is refused without parsing it.
108
+ mantissa, exponent = text.split(/[eE]/, 2)
109
+ exp = exponent.nil? ? 0 : exponent.to_i
110
+ digits = mantissa.sub(/\A[-+]/, "")
111
+ int_part, frac_part = digits.split(".", 2)
112
+ int_part ||= ""
113
+ frac_part ||= ""
114
+ int_nz = int_part.sub(/\A0+/, "")
115
+ if !int_nz.empty?
116
+ magnitude = exp + int_nz.length - 1
117
+ elsif frac_part =~ /[1-9]/
118
+ magnitude = exp - (frac_part.index(/[1-9]/) + 1)
119
+ else
120
+ magnitude = 0 # Zero as written.
121
+ end
122
+ return nil if magnitude > 12 || magnitude < -13
123
+
124
+ sign = mantissa.start_with?("-") ? "-" : ""
125
+ v = Float("#{sign}#{int_part.empty? ? "0" : int_part}.#{frac_part.empty? ? "0" : frac_part}e#{exp}")
126
+ a = v.abs
127
+ return nil if v.nan? || a > 1e12 || (a != 0 && a < 1 / 1e12)
128
+ # One too small for a double comes out as 0, though it isn't zero as written.
129
+ return nil if v.zero? && written_nonzero(text)
130
+
131
+ v
132
+ end
133
+
134
+ # Whether a number, as written, has a digit other than 0 before any exponent.
135
+ def written_nonzero(text)
136
+ mantissa = text.downcase.split("e", 2)[0] || ""
137
+ mantissa.match?(/[1-9]/)
138
+ end
139
+
140
+ def trim(s)
141
+ s.sub(LEADING_SPACE, "").sub(TRAILING_SPACE, "")
142
+ end
143
+
144
+ def ascii_lower(s)
145
+ s.downcase(:ascii)
146
+ end
147
+
148
+ # Splits at each +sep+, keeping empty parts, so that "" gives [""].
149
+ def split(s, sep)
150
+ s.split(sep, -1).tap { |a| a << "" if a.empty? }
151
+ end
152
+
153
+ # Whether an attribute, or a declaration in a style, paints in currentColor, as its value or as
154
+ # a keyword in it such as a fallback after url(#id). An id or other text containing the word
155
+ # doesn't count.
156
+ def takes_current_color(name, value)
157
+ if name == "style"
158
+ split(value, ";").each do |decl|
159
+ colon = decl.index(":")
160
+ prop = colon.nil? ? decl : decl[0, colon]
161
+ v = colon.nil? ? "" : decl[(colon + 1)..]
162
+ return true if takes_current_color(ascii_lower(trim(prop)), v)
163
+ end
164
+ return false
165
+ end
166
+ return false unless COLOR_PROPS.include?(name)
167
+
168
+ value.gsub(LOCAL_URL, "").scan(CSS_WORD).any? { |w| ascii_lower(w) == "currentcolor" }
169
+ end
170
+
171
+ # Checks inline SVG and gives a copy with marks in place of its IDs' prefixes, so that drawing
172
+ # it can make them unique. Anything drawn must be on the allowlist or the markup is refused;
173
+ # only descriptive and foreign-namespace content is removed quietly.
174
+ def sanitize(markup)
175
+ dec = begin
176
+ Xml.new(markup)
177
+ rescue Xml::XmlException => e
178
+ raise Vexyl::Error, "invalid SVG: #{e.message}"
179
+ end
180
+ result = Artwork.new
181
+ body = +""
182
+ depth = 0
183
+ skip = 0
184
+ saw_root = false
185
+ closed_root = false
186
+ loop do
187
+ t = begin
188
+ dec.token
189
+ rescue Xml::XmlException => e
190
+ raise Vexyl::Error, "invalid SVG: #{e.message}"
191
+ end
192
+ break if t.nil?
193
+
194
+ case t.kind
195
+ when :directive
196
+ raise Vexyl::Error, "SVG can't contain a DOCTYPE or other directive"
197
+ when :text
198
+ if skip.zero? && !trim(t.text).empty?
199
+ raise Vexyl::Error, "SVG can't contain text outside elements; convert any lettering to paths"
200
+ end
201
+ when :start
202
+ if skip.positive?
203
+ skip += 1
204
+ next
205
+ end
206
+ raise Vexyl::Error, "SVG must have a single root element" if closed_root
207
+
208
+ name = t.name
209
+ unless saw_root
210
+ saw_root = true
211
+ if name.space != SVG_NAMESPACE || name.local != "svg"
212
+ raise Vexyl::Error, "root must be <svg xmlns=\"#{SVG_NAMESPACE}\">"
213
+ end
214
+
215
+ read_root(result, t.attrs)
216
+ depth = 1
217
+ next
218
+ end
219
+ if (name.space != SVG_NAMESPACE && !name.space.empty?) ||
220
+ (name.space == SVG_NAMESPACE && DROPPED_ELEMENTS.include?(name.local))
221
+ skip = 1
222
+ next
223
+ end
224
+ if name.space.empty? || !ALLOWED_ELEMENTS.include?(name.local)
225
+ raise Vexyl::Error, "SVG element <#{name.local}> isn't allowed"
226
+ end
227
+
228
+ depth += 1
229
+ raise Vexyl::Error, "SVG is nested more than #{MAX_DEPTH} levels deep" if depth > MAX_DEPTH
230
+
231
+ attrs = begin
232
+ clean_attrs(t.attrs, [].freeze, result)
233
+ rescue Vexyl::Error => e
234
+ raise Vexyl::Error, "SVG element <#{name.local}>: #{e.message}"
235
+ end
236
+ body << "<" << name.local << attrs << ">"
237
+ when :end
238
+ if skip.positive?
239
+ skip -= 1
240
+ next
241
+ end
242
+ depth -= 1
243
+ if depth.zero?
244
+ closed_root = true
245
+ next
246
+ end
247
+ body << "</" << t.name.local << ">"
248
+ end
249
+ end
250
+ raise Vexyl::Error, "SVG has no root element" unless saw_root
251
+
252
+ result.body = body
253
+ result
254
+ end
255
+
256
+ # Works out the root's viewBox and keeps its other styling attributes.
257
+ def read_root(e, attrs)
258
+ view_box = ""
259
+ width = ""
260
+ height = ""
261
+ attrs.each do |a|
262
+ next unless a.name.space.empty?
263
+
264
+ case a.name.local
265
+ when "viewBox"
266
+ view_box = a.value
267
+ when "width"
268
+ width = a.value
269
+ when "height"
270
+ height = a.value
271
+ when "preserveAspectRatio"
272
+ unless DEFAULT_FIT.match?(a.value)
273
+ raise Vexyl::Error, "SVG's preserveAspectRatio \"#{a.value}\" isn't the default, " \
274
+ "which is how artwork is always fitted"
275
+ end
276
+ end
277
+ end
278
+ if !view_box.empty?
279
+ m = VIEW_BOX.match(view_box)
280
+ raise Vexyl::Error, "SVG has an invalid viewBox \"#{view_box}\"" if m.nil?
281
+
282
+ values = (1..4).map { |i| decimal_value(m[i]) }
283
+ raise Vexyl::Error, "SVG has an invalid viewBox \"#{view_box}\"" if values.any?(&:nil?)
284
+ raise Vexyl::Error, "SVG viewBox \"#{view_box}\" has no area" if values[2] <= 0 || values[3] <= 0
285
+
286
+ e.view_box = "#{m[1]} #{m[2]} #{m[3]} #{m[4]}"
287
+ else
288
+ wm = LENGTH.match(width)
289
+ hm = LENGTH.match(height)
290
+ raise Vexyl::Error, "SVG needs a viewBox, or a numeric width and height" if wm.nil? || hm.nil?
291
+
292
+ w = decimal_value(wm[1])
293
+ h = decimal_value(hm[1])
294
+ raise Vexyl::Error, "SVG's width and height must be positive" if w.nil? || h.nil? || w <= 0 || h <= 0
295
+
296
+ e.view_box = "0 0 #{wm[1]} #{hm[1]}"
297
+ end
298
+ begin
299
+ e.attrs = clean_attrs(attrs, ROOT_ONLY, e)
300
+ rescue Vexyl::Error => err
301
+ raise Vexyl::Error, "SVG root: #{err.message}"
302
+ end
303
+ end
304
+
305
+ # Checks attributes against the allowlist and writes them out, noting whether any of them
306
+ # paints in currentColor.
307
+ def clean_attrs(attrs, ignored, e)
308
+ b = +""
309
+ href = false
310
+ attrs.each do |a|
311
+ name = a.name.local
312
+ space = a.name.space
313
+ if space == XLINK_NAMESPACE && name == "href"
314
+ # The same as the plain href it's equivalent to.
315
+ elsif !space.empty?
316
+ # Editor data doesn't affect rendering.
317
+ next
318
+ elsif ignored.include?(name)
319
+ next
320
+ elsif !ALLOWED_ATTRS.include?(name) && !PRESENTATION.include?(name)
321
+ raise Vexyl::Error, "attribute \"#{name}\" isn't allowed"
322
+ end
323
+ if name == "href"
324
+ raise Vexyl::Error, "attribute \"href\" is repeated, since xlink:href means the same" if href
325
+
326
+ href = true
327
+ end
328
+ value = clean_value(name, a.value)
329
+ e.current_color = true if takes_current_color(name, a.value)
330
+ b << " " << name << "=\"" << value << "\""
331
+ end
332
+ b
333
+ end
334
+
335
+ # A value escaped for writing out.
336
+ def clean_value(name, value)
337
+ case name
338
+ when "id"
339
+ raise Vexyl::Error, "invalid id \"#{value}\"" unless LOCAL_ID.match?(value)
340
+
341
+ return ID_MARK + Xml.escape(value)
342
+ when "href"
343
+ unless value.start_with?("#") && LOCAL_ID.match?(value[1..])
344
+ raise Vexyl::Error, "href \"#{value}\" must refer to an id in this SVG"
345
+ end
346
+
347
+ return "#" + ID_MARK + Xml.escape(value[1..])
348
+ when "style"
349
+ return clean_style(value)
350
+ end
351
+ return clean_presentation(value) if PRESENTATION.include?(name)
352
+
353
+ Xml.escape(value)
354
+ end
355
+
356
+ # Marks url(#id) references and refuses every CSS function other than those and plain color
357
+ # functions, since functions can load things.
358
+ def clean_presentation(value)
359
+ remaining = value.gsub(LOCAL_URL, "").gsub(COLOR_FUNC, "")
360
+ if remaining.include?("(")
361
+ raise Vexyl::Error, "\"#{value}\" uses a function other than url(#id) or a color"
362
+ end
363
+
364
+ b = +""
365
+ last = 0
366
+ pos = 0
367
+ while (m = LOCAL_URL.match(value, pos))
368
+ b << Xml.escape(value[last...m.begin(0)]) << "url(#" << ID_MARK << Xml.escape(m[1]) << ")"
369
+ last = m.end(0)
370
+ # A match is never empty, so the search always moves on.
371
+ pos = last
372
+ end
373
+ b << Xml.escape(value[last..])
374
+ b
375
+ end
376
+
377
+ # Keeps a style's declarations in their order, since a later one can win.
378
+ def clean_style(style)
379
+ if style.include?("\\") || style.include?("@") || style.include?("/*")
380
+ raise Vexyl::Error, "style can't contain escapes, at-rules or comments"
381
+ end
382
+
383
+ out = []
384
+ split(style, ";").each do |decl|
385
+ next if trim(decl).empty?
386
+
387
+ colon = decl.index(":")
388
+ prop = ascii_lower(trim(colon.nil? ? decl : decl[0, colon]))
389
+ if colon.nil? || !PRESENTATION.include?(prop)
390
+ raise Vexyl::Error, "style property \"#{prop}\" isn't allowed"
391
+ end
392
+
393
+ out << "#{prop}:#{clean_presentation(trim(decl[(colon + 1)..]))}"
394
+ end
395
+ out.join(";")
396
+ end
397
+
398
+ private_class_method :split, :read_root, :clean_attrs, :clean_value, :clean_presentation,
399
+ :clean_style
400
+ end
401
+ end