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.
- checksums.yaml +7 -0
- data/README.md +88 -0
- data/lib/strling/core/compiler.rb +96 -0
- data/lib/strling/core/errors.rb +174 -0
- data/lib/strling/core/hint_engine.rb +43 -0
- data/lib/strling/core/ir.rb +348 -0
- data/lib/strling/core/nodes.rb +445 -0
- data/lib/strling/core/parser.rb +579 -0
- data/lib/strling/core/validator.rb +101 -0
- data/lib/strling/emitters/pcre2.rb +246 -0
- data/lib/strling/ir.rb +201 -0
- data/lib/strling/nodes.rb +102 -0
- data/lib/strling/simply.rb +90 -0
- data/lib/strling.rb +25 -0
- metadata +55 -0
checksums.yaml
ADDED
|
@@ -0,0 +1,7 @@
|
|
|
1
|
+
---
|
|
2
|
+
SHA256:
|
|
3
|
+
metadata.gz: ab1d693aae49028d066f48a6fb4501dbfef9c71fc9d8294fb8d9dbd991397e42
|
|
4
|
+
data.tar.gz: 87c88486adf55484d2facaf14c4638179c528a5dab29ea1304792dfdfe6a27cc
|
|
5
|
+
SHA512:
|
|
6
|
+
metadata.gz: a4cc2c940db9c72b4655369c2fa82e768fd7ad51ad6741635f08a71dff2c50c3fcf6855cea175f828ed5e8332131bbe596ebaf79913542a356ff1c1e279d9249
|
|
7
|
+
data.tar.gz: 2453ac0fa5ad735916a603a70fc32b26a6f35d94af880a6a4642cc3172a7b49232bd49d8ae7fe74d0cbf94ed4c338033d1e1bd84834c242c70bc276c062e1277
|
data/README.md
ADDED
|
@@ -0,0 +1,88 @@
|
|
|
1
|
+
# STRling - Ruby Binding
|
|
2
|
+
|
|
3
|
+
> Part of the [STRling Project](https://github.com/strling-lang/strling/blob/main/README.md)
|
|
4
|
+
|
|
5
|
+
<table>
|
|
6
|
+
<tr>
|
|
7
|
+
<td style="padding: 10px;"><img src="https://raw.githubusercontent.com/strling-lang/.github/refs/heads/main/strling_silver_bell.png" alt="STRling Logo" width="100" /></td>
|
|
8
|
+
<td style="padding: 10px;">
|
|
9
|
+
<strong>The Universal Regular Expression Compiler.</strong><br><br>
|
|
10
|
+
STRling is a next-generation production-grade syntax designed to make Regex readable, maintainable, and robust. It abstracts the cryptic nature of raw regex strings into a clean, object-oriented, and strictly typed interface that compiles to standard PCRE2 (or native) patterns.
|
|
11
|
+
</td>
|
|
12
|
+
</tr>
|
|
13
|
+
</table>
|
|
14
|
+
|
|
15
|
+
## 💿 Installation
|
|
16
|
+
|
|
17
|
+
```bash
|
|
18
|
+
gem install strling
|
|
19
|
+
```
|
|
20
|
+
|
|
21
|
+
Or add to your Gemfile:
|
|
22
|
+
|
|
23
|
+
```ruby
|
|
24
|
+
gem 'strling'
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
## 📦 Usage
|
|
28
|
+
|
|
29
|
+
Here is how to match a US Phone number (e.g., `555-0199`) using STRling in **Ruby**:
|
|
30
|
+
|
|
31
|
+
```ruby
|
|
32
|
+
require 'strling'
|
|
33
|
+
|
|
34
|
+
# Build the phone pattern using the Simply fluent API
|
|
35
|
+
# Match: ^(\d{3})[-. ]?(\d{3})[-. ]?(\d{4})$
|
|
36
|
+
s = Strling::Simply
|
|
37
|
+
|
|
38
|
+
phone_pattern = s.merge(
|
|
39
|
+
s.start, # Start of line
|
|
40
|
+
s.capture(s.digit.times(3)), # 3 digits (area code)
|
|
41
|
+
s.may(s.any_of('-', '.', ' ')), # Optional separator
|
|
42
|
+
s.capture(s.digit.times(3)), # 3 digits (exchange)
|
|
43
|
+
s.may(s.any_of('-', '.', ' ')), # Optional separator
|
|
44
|
+
s.capture(s.digit.times(4)), # 4 digits (line number)
|
|
45
|
+
s.end # End of line
|
|
46
|
+
)
|
|
47
|
+
|
|
48
|
+
# Compile to regex string and test
|
|
49
|
+
regex = Regexp.new(phone_pattern.to_s)
|
|
50
|
+
puts regex.match?('555-123-4567') # true
|
|
51
|
+
```
|
|
52
|
+
|
|
53
|
+
> **Note:** This compiles to the optimized regex: `^(\d{3})[-. ]?(\d{3})[-. ]?(\d{4})$`
|
|
54
|
+
|
|
55
|
+
## 🚀 Why STRling?
|
|
56
|
+
|
|
57
|
+
Regular Expressions are powerful but notorious for being "write-only" code. STRling solves this by treating Regex as **Software**, not a string.
|
|
58
|
+
|
|
59
|
+
- **🧩 Composability:** Regex strings are hard to merge. STRling lets you build reusable components (e.g., `ip_address`, `email`) and safely compose them into larger patterns without breaking operator precedence or capturing groups.
|
|
60
|
+
- **🛡️ Type Safety:** Catch syntax errors, invalid ranges, and incompatible flags at **compile time** inside your IDE, not at runtime when your app crashes.
|
|
61
|
+
- **🧠 IntelliSense & Autocomplete:** Stop memorizing cryptic codes like `(?<=...)`. Use fluent, self-documenting methods like `Simply.look_behind(...)` with full IDE discovery.
|
|
62
|
+
- **📖 Readability First:** Code is read far more often than it is written. STRling patterns describe _intent_, making them understandable to junior developers and future maintainers instantly.
|
|
63
|
+
- **🌍 Polyglot Engine:** One mental model, 17 languages. Whether you are writing Rust, Python, or TypeScript, the syntax and behavior remain identical.
|
|
64
|
+
|
|
65
|
+
## 🏗️ Architecture
|
|
66
|
+
|
|
67
|
+
STRling follows a strict compiler pipeline architecture to ensure consistency across all ecosystems:
|
|
68
|
+
|
|
69
|
+
1. **Parse**: `DSL -> AST` (Abstract Syntax Tree)
|
|
70
|
+
- Converts the human-readable STRling syntax into a structured tree.
|
|
71
|
+
2. **Compile**: `AST -> IR` (Intermediate Representation)
|
|
72
|
+
- Transforms the AST into a target-agnostic intermediate representation, optimizing structures like literal sequences.
|
|
73
|
+
3. **Emit**: `IR -> Target Regex`
|
|
74
|
+
- Generates the final, optimized regex string for the specific target engine (e.g., PCRE2, JS, Python `re`).
|
|
75
|
+
|
|
76
|
+
## 📚 Documentation
|
|
77
|
+
|
|
78
|
+
- [**API Reference**](./docs/api_reference.md): Detailed documentation for this binding.
|
|
79
|
+
- [**Project Hub**](https://github.com/strling-lang/strling/blob/main/README.md): The main STRling repository.
|
|
80
|
+
- [**Specification**](https://github.com/strling-lang/strling/tree/main/spec): The core grammar and semantic specifications.
|
|
81
|
+
|
|
82
|
+
## 🌐 Connect
|
|
83
|
+
|
|
84
|
+
[](https://github.com/strling-lang)
|
|
85
|
+
|
|
86
|
+
## 💖 Support
|
|
87
|
+
|
|
88
|
+
If you find STRling useful, consider starring the repository and contributing!
|
|
@@ -0,0 +1,96 @@
|
|
|
1
|
+
# frozen_string_literal: true
|
|
2
|
+
|
|
3
|
+
# STRling Compiler - AST to IR Transformation
|
|
4
|
+
#
|
|
5
|
+
# This module transforms Abstract Syntax Tree (AST) nodes from the parser
|
|
6
|
+
# into Intermediate Representation (IR) nodes. The IR is a simplified,
|
|
7
|
+
# language-agnostic representation that can be easily emitted to various
|
|
8
|
+
# target regex flavors.
|
|
9
|
+
#
|
|
10
|
+
# The compiler performs:
|
|
11
|
+
# - AST node type transformation (Node → IROp)
|
|
12
|
+
# - Semantic validation
|
|
13
|
+
# - Optimization opportunities (future)
|
|
14
|
+
|
|
15
|
+
require_relative 'nodes'
|
|
16
|
+
require_relative 'ir'
|
|
17
|
+
|
|
18
|
+
module Strling
|
|
19
|
+
module Core
|
|
20
|
+
# Compiler class for transforming AST to IR
|
|
21
|
+
class Compiler
|
|
22
|
+
# Compile an AST node tree to IR
|
|
23
|
+
#
|
|
24
|
+
# @param node [Node] The root AST node to compile
|
|
25
|
+
# @return [IROp] The compiled IR root node
|
|
26
|
+
def self.compile(node)
|
|
27
|
+
new.compile_node(node)
|
|
28
|
+
end
|
|
29
|
+
|
|
30
|
+
# Compile a single AST node to its IR equivalent
|
|
31
|
+
#
|
|
32
|
+
# @param node [Node] The AST node to compile
|
|
33
|
+
# @return [IROp] The corresponding IR node
|
|
34
|
+
def compile_node(node)
|
|
35
|
+
case node
|
|
36
|
+
when Alt
|
|
37
|
+
IRAlt.new(node.branches.map { |b| compile_node(b) })
|
|
38
|
+
when Seq
|
|
39
|
+
IRSeq.new(node.parts.map { |p| compile_node(p) })
|
|
40
|
+
when Lit
|
|
41
|
+
IRLit.new(node.value)
|
|
42
|
+
when Dot
|
|
43
|
+
IRDot.new
|
|
44
|
+
when Anchor
|
|
45
|
+
IRAnchor.new(node.at)
|
|
46
|
+
when CharClass
|
|
47
|
+
IRCharClass.new(
|
|
48
|
+
node.negated,
|
|
49
|
+
node.items.map { |item| compile_class_item(item) }
|
|
50
|
+
)
|
|
51
|
+
when Quant
|
|
52
|
+
IRQuant.new(
|
|
53
|
+
compile_node(node.child),
|
|
54
|
+
node.min,
|
|
55
|
+
node.max,
|
|
56
|
+
node.mode
|
|
57
|
+
)
|
|
58
|
+
when Group
|
|
59
|
+
IRGroup.new(
|
|
60
|
+
node.capturing,
|
|
61
|
+
compile_node(node.body),
|
|
62
|
+
name: node.name,
|
|
63
|
+
atomic: node.atomic
|
|
64
|
+
)
|
|
65
|
+
when Backref
|
|
66
|
+
IRBackref.new(by_index: node.by_index, by_name: node.by_name)
|
|
67
|
+
when Look
|
|
68
|
+
IRLook.new(node.dir, node.neg, compile_node(node.body))
|
|
69
|
+
else
|
|
70
|
+
raise "Unknown AST node type: #{node.class}"
|
|
71
|
+
end
|
|
72
|
+
end
|
|
73
|
+
|
|
74
|
+
private
|
|
75
|
+
|
|
76
|
+
# Compile a character class item
|
|
77
|
+
def compile_class_item(item)
|
|
78
|
+
case item
|
|
79
|
+
when ClassRange
|
|
80
|
+
IRClassRange.new(item.from_ch, item.to_ch)
|
|
81
|
+
when ClassLiteral
|
|
82
|
+
IRClassLiteral.new(item.ch)
|
|
83
|
+
when ClassEscape
|
|
84
|
+
IRClassEscape.new(item.type, property: item.property)
|
|
85
|
+
else
|
|
86
|
+
raise "Unknown class item type: #{item.class}"
|
|
87
|
+
end
|
|
88
|
+
end
|
|
89
|
+
end
|
|
90
|
+
|
|
91
|
+
# Module-level compile function for convenience
|
|
92
|
+
def self.compile(node)
|
|
93
|
+
Compiler.compile(node)
|
|
94
|
+
end
|
|
95
|
+
end
|
|
96
|
+
end
|
|
@@ -0,0 +1,174 @@
|
|
|
1
|
+
# frozen_string_literal: true
|
|
2
|
+
|
|
3
|
+
# STRling Error Classes - Rich Error Handling for Instructional Diagnostics
|
|
4
|
+
#
|
|
5
|
+
# This module provides enhanced error classes that deliver context-aware,
|
|
6
|
+
# instructional error messages. The STRlingParseError class stores detailed
|
|
7
|
+
# information about syntax errors including position, context, and beginner-friendly
|
|
8
|
+
# hints for resolution.
|
|
9
|
+
|
|
10
|
+
module Strling
|
|
11
|
+
module Core
|
|
12
|
+
# Rich parse error with position tracking and instructional hints.
|
|
13
|
+
#
|
|
14
|
+
# This error class transforms parse failures into learning opportunities by
|
|
15
|
+
# providing:
|
|
16
|
+
# - The specific error message
|
|
17
|
+
# - The exact position where the error occurred
|
|
18
|
+
# - The full line of text containing the error
|
|
19
|
+
# - A beginner-friendly hint explaining how to fix the issue
|
|
20
|
+
class STRlingParseError < StandardError
|
|
21
|
+
# @return [String] A concise description of what went wrong
|
|
22
|
+
attr_reader :message
|
|
23
|
+
|
|
24
|
+
# @return [Integer] The character position (0-indexed) where the error occurred
|
|
25
|
+
attr_reader :pos
|
|
26
|
+
|
|
27
|
+
# @return [String] The full input text being parsed
|
|
28
|
+
attr_reader :text
|
|
29
|
+
|
|
30
|
+
# @return [String, nil] An instructional hint explaining how to fix the error
|
|
31
|
+
attr_reader :hint
|
|
32
|
+
|
|
33
|
+
# Initialize a STRlingParseError.
|
|
34
|
+
#
|
|
35
|
+
# @param message [String] A concise description of what went wrong
|
|
36
|
+
# @param pos [Integer] The character position (0-indexed) where the error occurred
|
|
37
|
+
# @param text [String] The full input text being parsed (default: "")
|
|
38
|
+
# @param hint [String, nil] An instructional hint explaining how to fix the error (default: nil)
|
|
39
|
+
def initialize(message, pos, text: '', hint: nil)
|
|
40
|
+
@message = message
|
|
41
|
+
@pos = pos
|
|
42
|
+
@text = text
|
|
43
|
+
@hint = hint
|
|
44
|
+
|
|
45
|
+
# Call parent constructor with formatted message
|
|
46
|
+
super(format_error)
|
|
47
|
+
end
|
|
48
|
+
|
|
49
|
+
# Format the error in the visionary state format.
|
|
50
|
+
#
|
|
51
|
+
# @return [String] A formatted error message with context and hints
|
|
52
|
+
def format_error
|
|
53
|
+
if text.empty?
|
|
54
|
+
# Fallback to simple format if no text provided
|
|
55
|
+
return "#{message} at position #{pos}"
|
|
56
|
+
end
|
|
57
|
+
|
|
58
|
+
# Find the line containing the error
|
|
59
|
+
lines = text.lines(chomp: true)
|
|
60
|
+
current_pos = 0
|
|
61
|
+
line_num = 1
|
|
62
|
+
line_text = ''
|
|
63
|
+
col = pos
|
|
64
|
+
|
|
65
|
+
lines.each_with_index do |line, i|
|
|
66
|
+
line_len = line.length + 1 # +1 for newline
|
|
67
|
+
if current_pos + line_len > pos
|
|
68
|
+
line_num = i + 1
|
|
69
|
+
line_text = line
|
|
70
|
+
col = pos - current_pos
|
|
71
|
+
break
|
|
72
|
+
end
|
|
73
|
+
current_pos += line_len
|
|
74
|
+
end
|
|
75
|
+
|
|
76
|
+
# Error is beyond the last line
|
|
77
|
+
if line_text.empty?
|
|
78
|
+
if !lines.empty?
|
|
79
|
+
line_num = lines.length
|
|
80
|
+
line_text = lines[-1]
|
|
81
|
+
col = line_text.length
|
|
82
|
+
else
|
|
83
|
+
line_text = text
|
|
84
|
+
col = pos
|
|
85
|
+
end
|
|
86
|
+
end
|
|
87
|
+
|
|
88
|
+
# Build the formatted error message
|
|
89
|
+
parts = ["STRling Parse Error: #{message}", '']
|
|
90
|
+
parts << "> #{line_num} | #{line_text}"
|
|
91
|
+
parts << "> | #{' ' * col}^"
|
|
92
|
+
|
|
93
|
+
if hint
|
|
94
|
+
parts << ''
|
|
95
|
+
parts << "Hint: #{hint}"
|
|
96
|
+
end
|
|
97
|
+
|
|
98
|
+
parts.join("\n")
|
|
99
|
+
end
|
|
100
|
+
|
|
101
|
+
# Return the formatted error message.
|
|
102
|
+
#
|
|
103
|
+
# @return [String] The formatted error message
|
|
104
|
+
def to_s
|
|
105
|
+
format_error
|
|
106
|
+
end
|
|
107
|
+
|
|
108
|
+
# Backwards/JS-friendly alias for getting the formatted error string.
|
|
109
|
+
#
|
|
110
|
+
# @return [String] The formatted error message (same as `to_s`)
|
|
111
|
+
def to_formatted_string
|
|
112
|
+
format_error
|
|
113
|
+
end
|
|
114
|
+
|
|
115
|
+
# Convert the error to LSP Diagnostic format.
|
|
116
|
+
#
|
|
117
|
+
# Returns a hash compatible with the Language Server Protocol
|
|
118
|
+
# Diagnostic specification, which can be serialized to JSON for
|
|
119
|
+
# communication with LSP clients.
|
|
120
|
+
#
|
|
121
|
+
# @return [Hash] A hash containing:
|
|
122
|
+
# - range: The line/column range where the error occurred
|
|
123
|
+
# - severity: Error severity (1 = Error)
|
|
124
|
+
# - message: The error message with hint if available
|
|
125
|
+
# - source: "STRling"
|
|
126
|
+
# - code: A normalized error code derived from the message
|
|
127
|
+
def to_lsp_diagnostic
|
|
128
|
+
# Find the line and column containing the error
|
|
129
|
+
lines = text.empty? ? [] : text.lines(chomp: true)
|
|
130
|
+
current_pos = 0
|
|
131
|
+
line_num = 0 # 0-indexed for LSP
|
|
132
|
+
col = pos
|
|
133
|
+
|
|
134
|
+
lines.each_with_index do |line, i|
|
|
135
|
+
line_len = line.length + 1 # +1 for newline
|
|
136
|
+
if current_pos + line_len > pos
|
|
137
|
+
line_num = i
|
|
138
|
+
col = pos - current_pos
|
|
139
|
+
break
|
|
140
|
+
end
|
|
141
|
+
current_pos += line_len
|
|
142
|
+
end
|
|
143
|
+
|
|
144
|
+
# Error is beyond the last line
|
|
145
|
+
if col == pos && !lines.empty?
|
|
146
|
+
line_num = lines.length - 1
|
|
147
|
+
col = lines[-1].length
|
|
148
|
+
end
|
|
149
|
+
|
|
150
|
+
# Build the diagnostic message
|
|
151
|
+
diagnostic_message = message
|
|
152
|
+
diagnostic_message += "\n\nHint: #{hint}" if hint
|
|
153
|
+
|
|
154
|
+
# Create error code from message (normalize to snake_case)
|
|
155
|
+
error_code = message.downcase
|
|
156
|
+
[' ', "'", '"', '(', ')', '[', ']', '{', '}', '\\', '/'].each do |char|
|
|
157
|
+
error_code = error_code.gsub(char, '_')
|
|
158
|
+
end
|
|
159
|
+
error_code = error_code.split('_').reject(&:empty?).join('_')
|
|
160
|
+
|
|
161
|
+
{
|
|
162
|
+
range: {
|
|
163
|
+
start: { line: line_num, character: col },
|
|
164
|
+
end: { line: line_num, character: col + 1 }
|
|
165
|
+
},
|
|
166
|
+
severity: 1, # 1 = Error, 2 = Warning, 3 = Information, 4 = Hint
|
|
167
|
+
message: diagnostic_message,
|
|
168
|
+
source: 'STRling',
|
|
169
|
+
code: error_code
|
|
170
|
+
}
|
|
171
|
+
end
|
|
172
|
+
end
|
|
173
|
+
end
|
|
174
|
+
end
|
|
@@ -0,0 +1,43 @@
|
|
|
1
|
+
# frozen_string_literal: true
|
|
2
|
+
|
|
3
|
+
# STRling Hint Engine - Context-Aware Error Hints
|
|
4
|
+
#
|
|
5
|
+
# This module provides intelligent, beginner-friendly hints for parse errors.
|
|
6
|
+
# It analyzes error messages and context to suggest likely fixes and
|
|
7
|
+
# explanations for common mistakes.
|
|
8
|
+
|
|
9
|
+
module Strling
|
|
10
|
+
module Core
|
|
11
|
+
# Generate a helpful hint for a parse error
|
|
12
|
+
#
|
|
13
|
+
# @param message [String] The error message
|
|
14
|
+
# @param text [String] The full input text being parsed
|
|
15
|
+
# @param pos [Integer] The position where the error occurred
|
|
16
|
+
# @return [String, nil] A helpful hint, or nil if no specific hint applies
|
|
17
|
+
def self.get_hint(message, text, pos)
|
|
18
|
+
# Extract key parts of the error message
|
|
19
|
+
case message
|
|
20
|
+
when /Invalid quantifier/
|
|
21
|
+
"Quantifiers (*, +, ?, {m,n}) must follow something to repeat. They can't appear at the start of a pattern or immediately after another quantifier."
|
|
22
|
+
when /Cannot quantify anchor/
|
|
23
|
+
"Anchors (^, $, \\b, \\B, etc.) match positions, not characters, so they can't be repeated with quantifiers like * or +."
|
|
24
|
+
when /Unclosed/
|
|
25
|
+
"Make sure every opening bracket has a matching closing bracket. Check for: ( ), [ ], { }"
|
|
26
|
+
when /Unmatched/
|
|
27
|
+
"This closing bracket doesn't have a matching opening bracket. Did you mean to escape it?"
|
|
28
|
+
when /Unknown escape sequence/
|
|
29
|
+
"This escape sequence isn't recognized. Common escapes include: \\n (newline), \\t (tab), \\d (digit), \\w (word character), \\s (whitespace)."
|
|
30
|
+
when /Invalid flag/
|
|
31
|
+
"Valid flags are: i (case-insensitive), m (multiline), s (dotall), u (unicode), x (extended/free-spacing)."
|
|
32
|
+
when /Alternation lacks/
|
|
33
|
+
"Alternation (|) requires a pattern on both sides. Example: 'cat|dog', not 'cat|' or '|dog'."
|
|
34
|
+
when /Unexpected trailing input/
|
|
35
|
+
"The pattern ended but there's still input remaining. Check for extra characters or unmatched brackets."
|
|
36
|
+
when /Directive after pattern content/
|
|
37
|
+
"Directives like %flags must appear before the pattern content, not after."
|
|
38
|
+
else
|
|
39
|
+
nil
|
|
40
|
+
end
|
|
41
|
+
end
|
|
42
|
+
end
|
|
43
|
+
end
|