strling 3.0.0 → 4.0.1

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.
@@ -1,579 +0,0 @@
1
- # frozen_string_literal: true
2
-
3
- # STRling Parser - Recursive Descent Parser for STRling DSL
4
- #
5
- # This module implements a hand-rolled recursive-descent parser that transforms
6
- # STRling pattern syntax into Abstract Syntax Tree (AST) nodes. The parser handles:
7
- # - Alternation and sequencing
8
- # - Character classes and ranges
9
- # - Quantifiers (greedy, lazy, possessive)
10
- # - Groups (capturing, non-capturing, named, atomic)
11
- # - Lookarounds (lookahead and lookbehind, positive and negative)
12
- # - Anchors and special escapes
13
- # - Extended/free-spacing mode with comments
14
- #
15
- # The parser produces AST nodes (defined in nodes.rb) that can be compiled
16
- # to IR and ultimately emitted as target-specific regex patterns. It includes
17
- # comprehensive error handling with position tracking for helpful diagnostics.
18
-
19
- require_relative 'nodes'
20
- require_relative 'errors'
21
- require_relative 'hint_engine'
22
-
23
- module Strling
24
- module Core
25
- # Alias for backward compatibility
26
- ParseError = STRlingParseError
27
-
28
- # Cursor for tracking parser position and state
29
- class Cursor
30
- attr_accessor :text, :i, :extended_mode, :in_class
31
-
32
- def initialize(text, i = 0, extended_mode = false, in_class = 0)
33
- @text = text
34
- @i = i
35
- @extended_mode = extended_mode
36
- @in_class = in_class
37
- end
38
-
39
- def eof?
40
- @i >= @text.length
41
- end
42
-
43
- def peek(n = 0)
44
- j = @i + n
45
- j >= @text.length ? '' : @text[j]
46
- end
47
-
48
- def take
49
- return '' if eof?
50
-
51
- ch = @text[@i]
52
- @i += 1
53
- ch
54
- end
55
-
56
- def match(s)
57
- if @text[@i...(@i + s.length)] == s
58
- @i += s.length
59
- true
60
- else
61
- false
62
- end
63
- end
64
-
65
- def skip_ws_and_comments
66
- return if !@extended_mode || @in_class > 0
67
-
68
- # In free-spacing mode, ignore spaces/tabs/newlines and #-to-EOL comments
69
- until eof?
70
- ch = peek
71
- if " \t\r\n".include?(ch)
72
- @i += 1
73
- next
74
- end
75
- if ch == '#'
76
- # skip comment to end of line
77
- @i += 1 until eof? || "\r\n".include?(peek)
78
- next
79
- end
80
- break
81
- end
82
- end
83
- end
84
-
85
- # Main parser class
86
- class Parser
87
- attr_reader :flags, :src, :cur
88
-
89
- # Control character escapes mapping
90
- CONTROL_ESCAPES = {
91
- 'n' => "\n",
92
- 'r' => "\r",
93
- 't' => "\t",
94
- 'f' => "\f",
95
- 'v' => "\v"
96
- }.freeze
97
-
98
- def initialize(text)
99
- # Store original text for error reporting
100
- @original_text = text
101
- # Extract directives first
102
- @flags, @src = parse_directives(text)
103
- @cur = Cursor.new(@src, 0, @flags.extended, 0)
104
- @cap_count = 0
105
- @cap_names = Set.new
106
- end
107
-
108
- # Main parsing entry point
109
- # Returns the root AST node
110
- def parse
111
- node = parse_alt
112
- @cur.skip_ws_and_comments
113
- unless @cur.eof?
114
- if @cur.peek == ')'
115
- raise STRlingParseError.new(
116
- "Unmatched ')'",
117
- @cur.i,
118
- text: @src,
119
- hint: "This ')' character does not have a matching opening '('. Did you mean to escape it with '\\)'?"
120
- )
121
- end
122
- if @cur.peek == '|'
123
- raise_error('Alternation lacks right-hand side', @cur.i)
124
- else
125
- raise_error('Unexpected trailing input', @cur.i)
126
- end
127
- end
128
- [@flags, node]
129
- end
130
-
131
- private
132
-
133
- def raise_error(message, pos)
134
- hint = Strling::Core.get_hint(message, @src, pos)
135
- raise STRlingParseError.new(message, pos, text: @src, hint: hint)
136
- end
137
-
138
- # Parse directives (%flags, etc.) from the start of the text
139
- def parse_directives(text)
140
- flags = Flags.new
141
- lines = text.lines
142
- pattern_lines = []
143
- in_pattern = false
144
- line_num = 0
145
-
146
- lines.each do |line|
147
- line_num += 1
148
- stripped = line.strip
149
-
150
- # Skip leading blank lines or comments
151
- if !in_pattern && (stripped.empty? || stripped.start_with?('#'))
152
- next
153
- end
154
-
155
- # Process %flags directive
156
- if !in_pattern && stripped.start_with?('%flags')
157
- idx = line.index('%flags')
158
- after = line[(idx + 7)..]
159
- # Extract flags
160
- letters = after.gsub(/[,\[\]\s]+/, ' ').strip.downcase
161
- valid_flags = Set.new(%w[i m s u x])
162
-
163
- letters.delete(' ').each_char do |ch|
164
- next if ch.empty?
165
-
166
- unless valid_flags.include?(ch)
167
- pos = lines[0...line_num - 1].join.length + idx
168
- raise STRlingParseError.new(
169
- "Invalid flag '#{ch}'",
170
- pos,
171
- text: @original_text,
172
- hint: nil
173
- )
174
- end
175
- end
176
-
177
- flags = Flags.from_letters(letters)
178
- # Check for pattern content on same line
179
- remainder = after.gsub(/[imsux,\[\]\s]+/, '')
180
- if !remainder.empty?
181
- in_pattern = true
182
- pattern_lines << line[(idx + 7 + after.index(remainder))..] if after.index(remainder)
183
- end
184
- next
185
- end
186
-
187
- # Skip other directives
188
- next if !in_pattern && stripped.start_with?('%')
189
-
190
- # Check for misplaced %flags
191
- if line.include?('%flags')
192
- pos = lines[0...line_num - 1].join.length + line.index('%flags')
193
- raise STRlingParseError.new(
194
- 'Directive after pattern content',
195
- pos,
196
- text: @original_text,
197
- hint: nil
198
- )
199
- end
200
-
201
- # All other lines are pattern content
202
- in_pattern = true
203
- pattern_lines << line
204
- end
205
-
206
- pattern = pattern_lines.join
207
- [flags, pattern]
208
- end
209
-
210
- # Parse alternation: alt := seq ('|' seq)+ | seq
211
- def parse_alt
212
- @cur.skip_ws_and_comments
213
- raise_error('Alternation lacks left-hand side', @cur.i) if @cur.peek == '|'
214
-
215
- branches = [parse_seq]
216
- @cur.skip_ws_and_comments
217
-
218
- while @cur.peek == '|'
219
- pipe_pos = @cur.i
220
- @cur.take
221
- @cur.skip_ws_and_comments
222
-
223
- raise_error('Alternation lacks right-hand side', pipe_pos) if @cur.peek.empty?
224
- raise_error('Empty alternation branch', pipe_pos) if @cur.peek == '|'
225
-
226
- branches << parse_seq
227
- @cur.skip_ws_and_comments
228
- end
229
-
230
- branches.length == 1 ? branches[0] : Alt.new(branches)
231
- end
232
-
233
- # Parse sequence: seq := { term }
234
- def parse_seq
235
- parts = []
236
- prev_had_failed_quant = false
237
-
238
- loop do
239
- @cur.skip_ws_and_comments
240
- ch = @cur.peek
241
-
242
- # Invalid quantifier at start
243
- if !ch.empty? && '*+?{'.include?(ch) && parts.empty?
244
- raise_error("Invalid quantifier '#{ch}'", @cur.i)
245
- end
246
-
247
- # Stop parsing sequence
248
- break if ch.empty? || ')|'.include?(ch)
249
-
250
- # Parse atom
251
- atom = parse_atom
252
-
253
- # Parse quantifier if present
254
- quantified_atom, had_failed_quant = parse_quant_if_any(atom)
255
-
256
- # Coalesce adjacent literals (simplified logic)
257
- should_coalesce = quantified_atom.is_a?(Lit) &&
258
- !parts.empty? &&
259
- parts.last.is_a?(Lit) &&
260
- !@cur.extended_mode &&
261
- !prev_had_failed_quant
262
-
263
- if should_coalesce
264
- parts[-1] = Lit.new(parts.last.value + quantified_atom.value)
265
- else
266
- parts << quantified_atom
267
- end
268
-
269
- prev_had_failed_quant = had_failed_quant
270
- end
271
-
272
- parts.length == 1 ? parts[0] : Seq.new(parts)
273
- end
274
-
275
- # Parse individual atom (literal, group, class, anchor, etc.)
276
- def parse_atom
277
- ch = @cur.peek
278
-
279
- case ch
280
- when '('
281
- parse_group
282
- when '['
283
- parse_char_class
284
- when '\\'
285
- parse_escape
286
- when '.'
287
- @cur.take
288
- Dot.new
289
- when '^'
290
- @cur.take
291
- Anchor.new('Start')
292
- when '$'
293
- @cur.take
294
- Anchor.new('End')
295
- when '*', '+', '?', '{', ')', '|'
296
- raise_error("Unexpected '#{ch}'", @cur.i)
297
- else
298
- parse_literal
299
- end
300
- end
301
-
302
- # Parse group: (pattern) or (?:pattern) or (?<name>pattern) etc.
303
- def parse_group
304
- raise_error("Expected '('", @cur.i) unless @cur.take == '('
305
-
306
- # Simplified group parsing
307
- # TODO: Handle all group types (?:...), (?<name>...), (?=...), etc.
308
-
309
- # Check for special group syntax
310
- if @cur.peek == '?'
311
- @cur.take
312
- case @cur.peek
313
- when ':'
314
- @cur.take
315
- body = parse_alt
316
- raise_error("Unclosed group", @cur.i) unless @cur.take == ')'
317
- return Group.new(false, body)
318
- when '='
319
- @cur.take
320
- body = parse_alt
321
- raise_error("Unclosed lookahead", @cur.i) unless @cur.take == ')'
322
- return Look.new('Ahead', false, body)
323
- when '!'
324
- @cur.take
325
- body = parse_alt
326
- raise_error("Unclosed lookahead", @cur.i) unless @cur.take == ')'
327
- return Look.new('Ahead', true, body)
328
- when '<'
329
- @cur.take
330
- if @cur.peek == '='
331
- @cur.take
332
- body = parse_alt
333
- raise_error("Unclosed lookbehind", @cur.i) unless @cur.take == ')'
334
- return Look.new('Behind', false, body)
335
- elsif @cur.peek == '!'
336
- @cur.take
337
- body = parse_alt
338
- raise_error("Unclosed lookbehind", @cur.i) unless @cur.take == ')'
339
- return Look.new('Behind', true, body)
340
- else
341
- # Named capture: (?<name>...)
342
- name = ''
343
- until @cur.peek == '>' || @cur.eof?
344
- name += @cur.take
345
- end
346
- raise_error("Unclosed named group", @cur.i) if @cur.eof?
347
- @cur.take # consume '>'
348
- @cap_count += 1
349
- @cap_names.add(name)
350
- body = parse_alt
351
- raise_error("Unclosed group", @cur.i) unless @cur.take == ')'
352
- return Group.new(true, body, name: name)
353
- end
354
- when '>'
355
- # Atomic group
356
- @cur.take
357
- body = parse_alt
358
- raise_error("Unclosed atomic group", @cur.i) unless @cur.take == ')'
359
- return Group.new(false, body, atomic: true)
360
- else
361
- raise_error("Unknown group syntax", @cur.i - 1)
362
- end
363
- end
364
-
365
- # Capturing group
366
- @cap_count += 1
367
- body = parse_alt
368
- raise_error("Unclosed group", @cur.i) unless @cur.take == ')'
369
- Group.new(true, body)
370
- end
371
-
372
- # Parse character class: [abc] or [^abc] or [a-z]
373
- def parse_char_class
374
- raise_error("Expected '['", @cur.i) unless @cur.take == '['
375
-
376
- @cur.in_class += 1
377
- negated = false
378
-
379
- if @cur.peek == '^'
380
- negated = true
381
- @cur.take
382
- end
383
-
384
- items = []
385
-
386
- # Simplified character class parsing
387
- # TODO: Handle ranges, escapes, nested classes
388
- until @cur.peek == ']' || @cur.eof?
389
- if @cur.peek == '\\'
390
- @cur.take
391
- type_ch = @cur.take
392
- case type_ch
393
- when 'd', 'D', 'w', 'W', 's', 'S'
394
- items << ClassEscape.new(type_ch)
395
- when 'b'
396
- # \b in class means backspace
397
- items << ClassLiteral.new("\b")
398
- else
399
- # Escaped literal
400
- items << ClassLiteral.new(type_ch)
401
- end
402
- elsif @cur.peek(1) == '-' && @cur.peek(2) != ']' && !@cur.eof?
403
- # Range
404
- from_ch = @cur.take
405
- @cur.take # consume '-'
406
- to_ch = @cur.take
407
- items << ClassRange.new(from_ch, to_ch)
408
- else
409
- items << ClassLiteral.new(@cur.take)
410
- end
411
- end
412
-
413
- raise_error("Unclosed character class", @cur.i) if @cur.eof?
414
-
415
- @cur.take # consume ']'
416
- @cur.in_class -= 1
417
-
418
- CharClass.new(negated, items)
419
- end
420
-
421
- # Parse escape sequence: \d, \w, \b, \123, \x41, etc.
422
- def parse_escape
423
- raise_error("Expected '\\'", @cur.i) unless @cur.take == '\\'
424
-
425
- ch = @cur.take
426
- raise_error("Unexpected end after '\\'", @cur.i) if ch.empty?
427
-
428
- case ch
429
- when 'd', 'D', 'w', 'W', 's', 'S'
430
- # Shorthand character classes
431
- CharClass.new(
432
- ch == ch.upcase,
433
- [ClassEscape.new(ch.downcase)]
434
- )
435
- when 'b'
436
- Anchor.new('WordBoundary')
437
- when 'B'
438
- Anchor.new('NotWordBoundary')
439
- when 'A'
440
- Anchor.new('AbsoluteStart')
441
- when 'Z'
442
- Anchor.new('EndBeforeFinalNewline')
443
- when 'n', 'r', 't', 'f', 'v'
444
- # Control escapes
445
- Lit.new(CONTROL_ESCAPES[ch])
446
- when '0'..'9'
447
- # Backreference
448
- num = ch
449
- while @cur.peek =~ /[0-9]/ && !@cur.eof?
450
- num += @cur.take
451
- end
452
- Backref.new(by_index: num.to_i)
453
- else
454
- # Handle other escapes or literal
455
- if 'nrtfv'.include?(ch)
456
- Lit.new(CONTROL_ESCAPES[ch])
457
- elsif '^$.*+?{}[]()|\\/'.include?(ch)
458
- # Escaped metacharacter
459
- Lit.new(ch)
460
- else
461
- # Unknown escape - raise error
462
- raise_error("Unknown escape sequence \\#{ch}", @cur.i - 2)
463
- end
464
- end
465
- end
466
-
467
- # Parse literal character(s)
468
- def parse_literal
469
- value = ''
470
- loop do
471
- ch = @cur.peek
472
- # Stop at metacharacters or end
473
- break if ch.empty? || '\\[](){}.*+?|^$'.include?(ch)
474
-
475
- value += @cur.take
476
- # Only take one character at a time in normal mode
477
- break unless @cur.extended_mode
478
- end
479
-
480
- value.empty? ? raise_error('Empty literal', @cur.i) : Lit.new(value)
481
- end
482
-
483
- # Parse quantifier if present
484
- def parse_quant_if_any(child)
485
- @cur.skip_ws_and_comments
486
- ch = @cur.peek
487
- had_failed_quant = false
488
-
489
- # Check if child can be quantified
490
- # Note: Must check ch is not empty first, as ''.include?('') is true in Ruby
491
- if !ch.empty? && '*+?{'.include?(ch)
492
- if child.is_a?(Anchor)
493
- raise_error('Cannot quantify anchor', @cur.i)
494
- end
495
-
496
- min = 0
497
- max = 'Inf'
498
-
499
- case ch
500
- when '*'
501
- @cur.take
502
- min = 0
503
- max = 'Inf'
504
- when '+'
505
- @cur.take
506
- min = 1
507
- max = 'Inf'
508
- when '?'
509
- @cur.take
510
- min = 0
511
- max = 1
512
- when '{'
513
- # Parse {m,n} quantifier
514
- brace_start = @cur.i
515
- @cur.take # consume '{'
516
-
517
- # Parse min
518
- min_str = ''
519
- while @cur.peek =~ /\d/
520
- min_str += @cur.take
521
- end
522
-
523
- if min_str.empty?
524
- raise_error('Expected digit in brace quantifier', @cur.i)
525
- end
526
- min = min_str.to_i
527
-
528
- # Check for comma
529
- if @cur.peek == ','
530
- @cur.take # consume ','
531
-
532
- # Parse optional max
533
- max_str = ''
534
- while @cur.peek =~ /\d/
535
- max_str += @cur.take
536
- end
537
-
538
- max = max_str.empty? ? 'Inf' : max_str.to_i
539
- else
540
- # Exact quantifier {n}
541
- max = min
542
- end
543
-
544
- # Expect closing brace
545
- if @cur.peek != '}'
546
- raise_error('Expected } in brace quantifier', @cur.i)
547
- end
548
- @cur.take # consume '}'
549
-
550
- # Validate min <= max
551
- if max != 'Inf' && min > max
552
- raise_error("Invalid quantifier: min (#{min}) > max (#{max})", brace_start)
553
- end
554
- end
555
-
556
- # Check for lazy (?) or possessive (+) modifier
557
- mode = 'Greedy'
558
- if @cur.peek == '?'
559
- @cur.take
560
- mode = 'Lazy'
561
- elsif @cur.peek == '+'
562
- @cur.take
563
- mode = 'Possessive'
564
- end
565
-
566
- return [Quant.new(child, min, max, mode), had_failed_quant]
567
- end
568
-
569
- [child, had_failed_quant]
570
- end
571
- end
572
-
573
- # Module-level parse function for convenience
574
- def self.parse(text)
575
- parser = Parser.new(text)
576
- [parser.flags, parser.parse]
577
- end
578
- end
579
- end
@@ -1,101 +0,0 @@
1
- # frozen_string_literal: true
2
-
3
- # STRling Validator - Semantic Validation of AST
4
- #
5
- # This module performs semantic validation of parsed AST nodes to catch
6
- # errors that are syntactically valid but semantically problematic, such as:
7
- # - Invalid backreference numbers
8
- # - Duplicate named capture groups
9
- # - Invalid character class ranges
10
- # - Lookbehind assertions with variable-length patterns (flavor-specific)
11
-
12
- require_relative 'nodes'
13
- require_relative 'errors'
14
-
15
- module Strling
16
- module Core
17
- # Validator class for semantic AST validation
18
- class Validator
19
- # Validate an AST node tree
20
- #
21
- # @param node [Node] The root AST node to validate
22
- # @param flags [Flags] The flags for this pattern
23
- # @return [Boolean] True if valid
24
- # @raise [STRlingParseError] If validation fails
25
- def self.validate(node, flags)
26
- new(flags).validate_node(node)
27
- true
28
- end
29
-
30
- def initialize(flags)
31
- @flags = flags
32
- @capture_count = 0
33
- @capture_names = Set.new
34
- end
35
-
36
- # Validate a single node and its children
37
- #
38
- # @param node [Node] The AST node to validate
39
- # @return [void]
40
- def validate_node(node)
41
- case node
42
- when Alt
43
- node.branches.each { |b| validate_node(b) }
44
- when Seq
45
- node.parts.each { |p| validate_node(p) }
46
- when CharClass
47
- node.items.each { |item| validate_class_item(item) }
48
- when Quant
49
- validate_node(node.child)
50
- when Group
51
- if node.capturing
52
- @capture_count += 1
53
- if node.name
54
- if @capture_names.include?(node.name)
55
- raise STRlingParseError.new(
56
- "Duplicate capture group name: #{node.name}",
57
- 0,
58
- text: '',
59
- hint: 'Each named capture group must have a unique name'
60
- )
61
- end
62
- @capture_names.add(node.name)
63
- end
64
- end
65
- validate_node(node.body)
66
- when Backref
67
- # TODO: Validate backreference numbers and names
68
- when Look
69
- validate_node(node.body)
70
- when Lit, Dot, Anchor
71
- # No validation needed for these leaf nodes
72
- end
73
- end
74
-
75
- private
76
-
77
- # Validate a character class item
78
- def validate_class_item(item)
79
- case item
80
- when ClassRange
81
- # Validate range is valid (from <= to)
82
- if item.from_ch.ord > item.to_ch.ord
83
- raise STRlingParseError.new(
84
- "Invalid character class range: #{item.from_ch}-#{item.to_ch}",
85
- 0,
86
- text: '',
87
- hint: 'Character class ranges must be in ascending order'
88
- )
89
- end
90
- when ClassLiteral, ClassEscape
91
- # No validation needed
92
- end
93
- end
94
- end
95
-
96
- # Module-level validate function for convenience
97
- def self.validate(node, flags)
98
- Validator.validate(node, flags)
99
- end
100
- end
101
- end