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 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
+ [![GitHub](https://img.shields.io/badge/GitHub-black?logo=github&logoColor=white)](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