strling 3.0.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,445 @@
1
+ # frozen_string_literal: true
2
+
3
+ # STRling AST Node Definitions
4
+ #
5
+ # This module defines the complete set of Abstract Syntax Tree (AST) node classes
6
+ # that represent the parsed structure of STRling patterns. The AST is the direct
7
+ # output of the parser and represents the syntactic structure of the pattern before
8
+ # optimization and lowering to IR.
9
+ #
10
+ # AST nodes are designed to:
11
+ # - Closely mirror the source pattern syntax
12
+ # - Be easily serializable to the Base TargetArtifact schema
13
+ # - Provide a clean separation between parsing and compilation
14
+ # - Support multiple target regex flavors through the compilation pipeline
15
+ #
16
+ # Each AST node type corresponds to a syntactic construct in the STRling DSL
17
+ # (alternation, sequencing, character classes, anchors, etc.) and can be
18
+ # serialized to a hash representation for debugging or storage.
19
+
20
+ module Strling
21
+ module Core
22
+ # Container for regex flags/modifiers.
23
+ #
24
+ # Flags control the behavior of pattern matching (case sensitivity, multiline
25
+ # mode, etc.). This class encapsulates all standard regex flags.
26
+ class Flags
27
+ # @return [Boolean] Case-insensitive matching
28
+ attr_accessor :ignore_case
29
+
30
+ # @return [Boolean] Multiline mode (^ and $ match line boundaries)
31
+ attr_accessor :multiline
32
+
33
+ # @return [Boolean] Dot matches all characters including newlines
34
+ attr_accessor :dot_all
35
+
36
+ # @return [Boolean] Unicode mode
37
+ attr_accessor :unicode
38
+
39
+ # @return [Boolean] Extended/free-spacing mode (ignore whitespace)
40
+ attr_accessor :extended
41
+
42
+ def initialize(ignore_case: false, multiline: false, dot_all: false, unicode: false, extended: false)
43
+ @ignore_case = ignore_case
44
+ @multiline = multiline
45
+ @dot_all = dot_all
46
+ @unicode = unicode
47
+ @extended = extended
48
+ end
49
+
50
+ # Convert flags to hash representation.
51
+ #
52
+ # @return [Hash] Hash representation of flags
53
+ def to_dict
54
+ {
55
+ 'ignoreCase' => ignore_case,
56
+ 'multiline' => multiline,
57
+ 'dotAll' => dot_all,
58
+ 'unicode' => unicode,
59
+ 'extended' => extended
60
+ }
61
+ end
62
+
63
+ # Create Flags from flag letters.
64
+ #
65
+ # @param letters [String] Flag letters (i, m, s, u, x)
66
+ # @return [Flags] New Flags instance
67
+ def self.from_letters(letters)
68
+ flags = new
69
+ letters.gsub(/[,\s]/, '').each_char do |ch|
70
+ case ch
71
+ when 'i'
72
+ flags.ignore_case = true
73
+ when 'm'
74
+ flags.multiline = true
75
+ when 's'
76
+ flags.dot_all = true
77
+ when 'u'
78
+ flags.unicode = true
79
+ when 'x'
80
+ flags.extended = true
81
+ when ''
82
+ # Empty character, skip
83
+ else
84
+ # Unknown flags are ignored at parser stage; may be warned later
85
+ end
86
+ end
87
+ flags
88
+ end
89
+ end
90
+
91
+ # Base class for all AST nodes.
92
+ class Node
93
+ # Serialize the node to hash representation.
94
+ #
95
+ # @return [Hash] Hash representation of the node
96
+ # @raise [NotImplementedError] Must be implemented by subclasses
97
+ def to_dict
98
+ raise NotImplementedError, 'Subclasses must implement to_dict'
99
+ end
100
+ end
101
+
102
+ # Represents an alternation (OR) operation in the AST.
103
+ #
104
+ # Matches any one of the provided branches. Equivalent to the | operator
105
+ # in traditional regex syntax.
106
+ class Alt < Node
107
+ # @return [Array<Node>] The alternative branches
108
+ attr_accessor :branches
109
+
110
+ # @param branches [Array<Node>] The alternative branches
111
+ def initialize(branches)
112
+ @branches = branches
113
+ end
114
+
115
+ def to_dict
116
+ { 'kind' => 'Alt', 'branches' => branches.map(&:to_dict) }
117
+ end
118
+ end
119
+
120
+ # Represents a sequence of pattern elements.
121
+ #
122
+ # Matches each part in order. Equivalent to simple concatenation in
123
+ # traditional regex syntax.
124
+ class Seq < Node
125
+ # @return [Array<Node>] The sequence parts
126
+ attr_accessor :parts
127
+
128
+ # @param parts [Array<Node>] The sequence parts
129
+ def initialize(parts)
130
+ @parts = parts
131
+ end
132
+
133
+ def to_dict
134
+ { 'kind' => 'Seq', 'parts' => parts.map(&:to_dict) }
135
+ end
136
+ end
137
+
138
+ # Represents a literal string match.
139
+ #
140
+ # Matches the exact string value provided.
141
+ class Lit < Node
142
+ # @return [String] The literal string value
143
+ attr_accessor :value
144
+
145
+ # @param value [String] The literal string value
146
+ def initialize(value)
147
+ @value = value
148
+ end
149
+
150
+ def to_dict
151
+ { 'kind' => 'Lit', 'value' => value }
152
+ end
153
+ end
154
+
155
+ # Represents the dot metacharacter.
156
+ #
157
+ # Matches any single character (behavior depends on flags).
158
+ class Dot < Node
159
+ def to_dict
160
+ { 'kind' => 'Dot' }
161
+ end
162
+ end
163
+
164
+ # Represents an anchor position assertion.
165
+ #
166
+ # Anchors match positions rather than characters (start/end of string,
167
+ # word boundaries, etc.).
168
+ class Anchor < Node
169
+ # @return [String] The anchor type: "Start", "End", "WordBoundary",
170
+ # "NotWordBoundary", or Absolute* variants
171
+ attr_accessor :at
172
+
173
+ # @param at [String] The anchor type
174
+ def initialize(at)
175
+ @at = at
176
+ end
177
+
178
+ def to_dict
179
+ { 'kind' => 'Anchor', 'at' => at }
180
+ end
181
+ end
182
+
183
+ # Represents a standalone escape sequence (e.g. \d, \w, \s).
184
+ class Esc < Node
185
+ # @return [String] The escape type (d, D, w, W, s, S, p, P)
186
+ attr_accessor :type
187
+
188
+ # @return [String, nil] The Unicode property name (for \p and \P)
189
+ attr_accessor :property
190
+
191
+ # @param type [String] The escape type
192
+ # @param property [String, nil] The Unicode property name
193
+ def initialize(type, property: nil)
194
+ @type = type
195
+ @property = property
196
+ end
197
+
198
+ def to_dict
199
+ data = { 'kind' => 'Esc', 'type' => type }
200
+ data['property'] = property if %w[p P].include?(type) && property
201
+ data
202
+ end
203
+ end
204
+
205
+ # Base class for character class items.
206
+ class ClassItem
207
+ # Serialize the item to hash representation.
208
+ #
209
+ # @return [Hash] Hash representation of the item
210
+ # @raise [NotImplementedError] Must be implemented by subclasses
211
+ def to_dict
212
+ raise NotImplementedError, 'Subclasses must implement to_dict'
213
+ end
214
+ end
215
+
216
+ # Represents a character range in a character class.
217
+ #
218
+ # Matches characters from from_ch to to_ch (inclusive).
219
+ class ClassRange < ClassItem
220
+ # @return [String] The starting character
221
+ attr_accessor :from_ch
222
+
223
+ # @return [String] The ending character
224
+ attr_accessor :to_ch
225
+
226
+ # @param from_ch [String] The starting character
227
+ # @param to_ch [String] The ending character
228
+ def initialize(from_ch, to_ch)
229
+ @from_ch = from_ch
230
+ @to_ch = to_ch
231
+ end
232
+
233
+ def to_dict
234
+ { 'kind' => 'Range', 'from' => from_ch, 'to' => to_ch }
235
+ end
236
+ end
237
+
238
+ # Represents a literal character in a character class.
239
+ #
240
+ # Matches the exact character.
241
+ class ClassLiteral < ClassItem
242
+ # @return [String] The character
243
+ attr_accessor :ch
244
+
245
+ # @param ch [String] The character
246
+ def initialize(ch)
247
+ @ch = ch
248
+ end
249
+
250
+ def to_dict
251
+ { 'kind' => 'Char', 'char' => ch }
252
+ end
253
+ end
254
+
255
+ # Represents an escape sequence in a character class.
256
+ #
257
+ # Matches predefined character classes (\d, \w, \s, etc.) or Unicode
258
+ # property escapes (\p{...}, \P{...}).
259
+ class ClassEscape < ClassItem
260
+ # @return [String] The escape type (d, D, w, W, s, S, p, P)
261
+ attr_accessor :type
262
+
263
+ # @return [String, nil] The Unicode property name (for \p and \P)
264
+ attr_accessor :property
265
+
266
+ # @param type [String] The escape type
267
+ # @param property [String, nil] The Unicode property name
268
+ def initialize(type, property: nil)
269
+ @type = type
270
+ @property = property
271
+ end
272
+
273
+ def to_dict
274
+ data = { 'kind' => 'Esc', 'type' => type }
275
+ data['property'] = property if %w[p P].include?(type) && property
276
+ data
277
+ end
278
+ end
279
+
280
+ # Represents a character class.
281
+ #
282
+ # Matches any character from the set defined by items. Can be negated
283
+ # to match any character NOT in the set.
284
+ class CharClass < Node
285
+ # @return [Boolean] Whether the class is negated
286
+ attr_accessor :negated
287
+
288
+ # @return [Array<ClassItem>] The items in the character class
289
+ attr_accessor :items
290
+
291
+ # @param negated [Boolean] Whether the class is negated
292
+ # @param items [Array<ClassItem>] The items in the character class
293
+ def initialize(negated, items)
294
+ @negated = negated
295
+ @items = items
296
+ end
297
+
298
+ def to_dict
299
+ {
300
+ 'kind' => 'CharClass',
301
+ 'negated' => negated,
302
+ 'items' => items.map(&:to_dict)
303
+ }
304
+ end
305
+ end
306
+
307
+ # Represents a quantifier (repetition operator).
308
+ #
309
+ # Specifies how many times a pattern element should match (min to max times).
310
+ # Supports greedy, lazy, and possessive modes.
311
+ class Quant < Node
312
+ # @return [Node] The child node being quantified
313
+ attr_accessor :child
314
+
315
+ # @return [Integer] The minimum number of matches
316
+ attr_accessor :min
317
+
318
+ # @return [Integer, String] The maximum number of matches ("Inf" for unbounded)
319
+ attr_accessor :max
320
+
321
+ # @return [String] The quantifier mode: "Greedy", "Lazy", or "Possessive"
322
+ attr_accessor :mode
323
+
324
+ # @param child [Node] The child node being quantified
325
+ # @param min [Integer] The minimum number of matches
326
+ # @param max [Integer, String] The maximum number of matches
327
+ # @param mode [String] The quantifier mode
328
+ def initialize(child, min, max, mode)
329
+ @child = child
330
+ @min = min
331
+ @max = max
332
+ @mode = mode
333
+ end
334
+
335
+ def to_dict
336
+ {
337
+ 'kind' => 'Quant',
338
+ 'child' => child.to_dict,
339
+ 'min' => min,
340
+ 'max' => max,
341
+ 'mode' => mode
342
+ }
343
+ end
344
+ end
345
+
346
+ # Represents a capturing or non-capturing group.
347
+ #
348
+ # Groups pattern elements together and optionally captures the matched text
349
+ # for later reference.
350
+ class Group < Node
351
+ # @return [Boolean] Whether the group is capturing
352
+ attr_accessor :capturing
353
+
354
+ # @return [Node] The body of the group
355
+ attr_accessor :body
356
+
357
+ # @return [String, nil] The name of the group (for named captures)
358
+ attr_accessor :name
359
+
360
+ # @return [Boolean, nil] Whether the group is atomic (extension)
361
+ attr_accessor :atomic
362
+
363
+ # @param capturing [Boolean] Whether the group is capturing
364
+ # @param body [Node] The body of the group
365
+ # @param name [String, nil] The name of the group
366
+ # @param atomic [Boolean, nil] Whether the group is atomic
367
+ def initialize(capturing, body, name: nil, atomic: nil)
368
+ @capturing = capturing
369
+ @body = body
370
+ @name = name
371
+ @atomic = atomic
372
+ end
373
+
374
+ def to_dict
375
+ data = {
376
+ 'kind' => 'Group',
377
+ 'capturing' => capturing,
378
+ 'body' => body.to_dict
379
+ }
380
+ data['name'] = name unless name.nil?
381
+ data['atomic'] = atomic unless atomic.nil?
382
+ data
383
+ end
384
+ end
385
+
386
+ # Represents a backreference.
387
+ #
388
+ # Matches the same text as previously captured by a group, referenced
389
+ # either by index or by name.
390
+ class Backref < Node
391
+ # @return [Integer, nil] The group index to reference
392
+ attr_accessor :by_index
393
+
394
+ # @return [String, nil] The group name to reference
395
+ attr_accessor :by_name
396
+
397
+ # @param by_index [Integer, nil] The group index to reference
398
+ # @param by_name [String, nil] The group name to reference
399
+ def initialize(by_index: nil, by_name: nil)
400
+ @by_index = by_index
401
+ @by_name = by_name
402
+ end
403
+
404
+ def to_dict
405
+ data = { 'kind' => 'Backref' }
406
+ data['byIndex'] = by_index unless by_index.nil?
407
+ data['byName'] = by_name unless by_name.nil?
408
+ data
409
+ end
410
+ end
411
+
412
+ # Represents a lookaround assertion.
413
+ #
414
+ # Asserts that a pattern does (or does not) match ahead of or behind
415
+ # the current position, without consuming characters.
416
+ class Look < Node
417
+ # @return [String] The direction: "Ahead" or "Behind"
418
+ attr_accessor :dir
419
+
420
+ # @return [Boolean] Whether the assertion is negative
421
+ attr_accessor :neg
422
+
423
+ # @return [Node] The body of the assertion
424
+ attr_accessor :body
425
+
426
+ # @param dir [String] The direction
427
+ # @param neg [Boolean] Whether the assertion is negative
428
+ # @param body [Node] The body of the assertion
429
+ def initialize(dir, neg, body)
430
+ @dir = dir
431
+ @neg = neg
432
+ @body = body
433
+ end
434
+
435
+ def to_dict
436
+ {
437
+ 'kind' => 'Look',
438
+ 'dir' => dir,
439
+ 'neg' => neg,
440
+ 'body' => body.to_dict
441
+ }
442
+ end
443
+ end
444
+ end
445
+ end