STRling 2.0.0__tar.gz → 2.1.0__tar.gz

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,13 +1,13 @@
1
1
  Metadata-Version: 2.1
2
2
  Name: STRling
3
- Version: 2.0.0
3
+ Version: 2.1.0
4
4
  Description-Content-Type: text/markdown
5
5
 
6
6
  # STRling
7
7
 
8
8
  ## The Next Generation of Regular Expressions
9
9
 
10
- STRling is a next-generation production-grade syntax designed as a user interface for writing powerful regular expressions (RegEx) with an object-oriented approach and instructional error handling. STRling recognizes the cryptic nature of raw regular expression can be challenging and susceptibility to errors, which is why STRling looks and feels nothing like RegEx while maintaining the same power and flexibility. String validation should be simple and enjoyable, not a hassle. Best of all, STRling syntax is built upon the RegEx engine, making it fully compatible with all libraries that accept RegEx along with the traditional RegEx methods built in to Python.
10
+ STRling is a next-generation production-grade syntax designed as a user interface for writing powerful regular expressions (RegEx) with an object-oriented approach and instructional error handling. STRling recognizes the cryptic nature of raw regular expression can be challenging and susceptibility to errors, which is why STRling looks and feels nothing like RegEx while maintaining the same power and flexibility. String validation should be simple and enjoyable, not a hassle. Best of all, STRling syntax is built upon the RegEx engine, making it fully compatible with all libraries that accept RegEx along with the traditional RegEx methods built-in to Python.
11
11
 
12
12
  ### Why STRling?
13
13
 
@@ -45,20 +45,20 @@ import re
45
45
  # - 1234567890
46
46
 
47
47
  # Separator: either space or hyphen
48
- separator = s.in_(s.lit(' -'))
48
+ separator = s.in_(' -')
49
49
 
50
50
  # Optional area code part: 123 even if in parenthesis like (123)
51
51
  area_code = s.merge( # notice we use merge since we don't want to name the group with parenthesis
52
- s.may(s.lit('(')), # Optional opening parenthesis
52
+ s.may('('), # Optional opening parenthesis
53
53
  s.group('area_code', s.digit(3)), # Exactly 3 digits and named for later reference
54
- s.may(s.lit(')')) # Optional closing parenthesis
54
+ s.may(')') # Optional closing parenthesis
55
55
  )
56
56
 
57
57
  # Central part: 456
58
- central_part = s.group('central_part', s.digit(3)) # Exactly 3 digits and named for later reference
58
+ central_part = s.group('central_part', s.digit(3)) # Exactly 3 digits and named for later reference
59
59
 
60
60
  # Last part: 7890
61
- last_part = s.group("last_part", s.digit(4)) # Exactly 4 digits and named for later reference
61
+ last_part = s.group("last_part", s.digit(4)) # Exactly 4 digits and named for later reference
62
62
 
63
63
  # Combine all parts into the final phone number pattern
64
64
  # Notice we don't name the whole pattern since we can already reference it
@@ -73,7 +73,7 @@ phone_number_pattern = s.merge(
73
73
  # Example usage
74
74
  # Note: To make a pattern a RegEx string compatible with other engines use `str(pattern)`.
75
75
  example_text = "(123) 456-7890 and 123-456-7890"
76
- pattern = re.compile(str(phone_number_pattern)) # Notice str(pattern)
76
+ pattern = re.compile(str(phone_number_pattern)) # Notice str(pattern)
77
77
  matches = pattern.finditer(example_text)
78
78
 
79
79
  for match in matches:
@@ -113,13 +113,13 @@ import re
113
113
  # For example, simply.letter(1, 3) will match 1 to 3 letters.
114
114
 
115
115
  # But some methods take an unknown number of parameters and can't distinguish the range.
116
- # For example, s.merge(simply.letter(), simply.digit(), 1, 2). <==== THIS IS INVALID
116
+ # For example, s.merge(simply.letter(), simply.digit(), 1, 2). <==== INVALID
117
117
 
118
- # However, all methods allow setting the range by reinvoking if a range hasn't already been set.
118
+ # However, all methods allow setting the range by externally invoking unless otherwise specified.
119
119
  # For example, simply.letter()(1, 2) is the same as simply.letter(1, 2).
120
120
 
121
121
  # This external invocation may seem useless, but it can solve our earlier issue.
122
- # For example, s.merge(simply.letter(), simply.digit())(1, 2). <==== THIS IS VALID
122
+ # For example, s.merge(simply.letter(), simply.digit())(1, 2). <==== VALID
123
123
 
124
124
  # Notice for all functions (where repetition is valid) we can invoke the range outside the parameters,
125
125
  # but it is primarily useful for functions with an unknown number of parameters.
@@ -148,6 +148,18 @@ s.tab() # Matches a tab character.
148
148
  s.carriage() # Matches a carriage return character.
149
149
  s.bound() # Matches a boundary character.
150
150
 
151
+ ####################
152
+ # Anchors
153
+ ####################
154
+
155
+ s.start() # Matches the start of a line.
156
+ # There is no `simply.not_start()` function.
157
+ # Instead, use `simply.not_behind(simply.start())`.
158
+
159
+ s.end() # Matches the end of a line.
160
+ # There is no `simply.not_end()` function.
161
+ # Instead, use `simply.not_ahead(simply.end())`.
162
+
151
163
  ####################
152
164
  # Custom Sets
153
165
  ####################
@@ -160,43 +172,26 @@ s.between(0, 9) # Matches any digit from 0 to 9.
160
172
  s.between('a', 'z') # Matches any lowercase letter from 'a' to 'z'.
161
173
  s.between('A', 'Z') # Matches any uppercase letter from 'A' to 'Z'.
162
174
 
163
- # Matches any characters in the provided set.
164
- s.in_(s.letter(), s.digit(), s.lit(',.')) # Matches letters, digits, commas, and periods.
165
- # You may notice a resemblance between simply.in_() and simply.any_of().
166
- # Key distinctions:
167
- # - simply.in_() typically processes faster than simply.any_of().
168
- # - simply.any_of() can process composite patterns while simply.in_() cannot.
169
- # A composite pattern is one consisting of smaller combined patterns.
170
-
171
- ####################
172
- # Anchors
173
- ####################
174
-
175
- s.start() # Matches the start of a line.
176
- # There is no `simply.not_start()` function.
177
- # Instead, use `simply.not_behind(simply.start())`.
178
-
179
- s.end() # Matches the end of a line.
180
- # There is no `simply.not_end()` function.
181
- # Instead, use `simply.not_ahead(simply.end())`.
175
+ # Matches any provided patterns, but they can't include subpatterns.
176
+ s.in_(s.letter(), s.digit(), ',.') # Matches any letter, digit, comma, and period.
177
+ # A composite pattern is one consisting of subpatterns (created by constructors and lookarounds).
182
178
 
183
179
  ####################
184
180
  # Constructors
185
181
  ####################
186
182
 
187
- s.any_of() # Matches any one of the provided patterns.
188
- # You may notice a resemblance between simply.in_() and simply.any_of().
189
- # Key distinctions:
190
- # - simply.in_() typically processes faster than simply.any_of().
191
- # - simply.any_of() can process composite patterns while simply.in_() cannot.
192
- # A composite pattern is one consisting of smaller combined patterns.
193
- s.any_of(pattern1, pattern2) # Matches only if one of the patterns listed is present.
183
+ s.any_of() # Matches any pattern, including patterns consisting of subpatterns.
184
+ # A composite pattern is one consisting of subpatterns (created by constructors and lookarounds).
185
+ pattern1 = s.merge(s.digit(3), s.letter(3)) # Matches 3 digits followed by 3 letters.
186
+ pattern2 = s.merge(s.letter(3), s.digit(3)) # Matches 3 letters followed by 3 digits.
187
+ s.any_of(pattern1, pattern2) # Matches either pattern1 or pattern2
194
188
 
195
189
 
196
190
  s.may() # Optionally matches the provided patterns.
197
191
  # If a `may` pattern isn't there, it still will match the rest of the patterns.
198
- # In the text, "ABC2" the patter below matches ['A', 'B', 'C2']
199
192
  s.merge(s.letter(), s.may(s.digit()))
193
+ # Matches any letter, and includes any digit following the letter.
194
+ # In the text, "AB2" the pattern above matches 'A' and 'B2'.
200
195
 
201
196
 
202
197
  s.merge() # Combines multiple patterns into one larger pattern.
@@ -207,12 +202,53 @@ s.capture() # Creates a numbered group that can be indexed for extracting part
207
202
  # Capture is used the same as merge.
208
203
  s.capture(s.letter(), s.digit())
209
204
 
205
+ # Captures CANNOT be invoked with a range: s.capture(s.digit(), s.letter())(1, 2) <== INVALID
206
+ # Captures CAN be invoked with a number of copies: s.capture(s.digit(), s.letter())(3) <== VALID
207
+
208
+ three_digit_group = s.capture(s.digit(3))
209
+ four_groups_of_three = three_digit_groups(4)
210
+
211
+ example_text = "Here is a number: 111222333444"
212
+ match = re.search(str(four_groups_of_three), example_text) # Notice str(pattern)
213
+
214
+ print("Full Match:", match.group())
215
+ print("First:", match.group(1))
216
+ print("Second:", match.group(2))
217
+ print("Third:", match.group(3))
218
+ print("Fourth:", match.group(4))
219
+
220
+ # Output:
221
+ # Full Match: 111222333444
222
+ # First: 111
223
+ # Second: 222
224
+ # Third: 333
225
+ # Fourth: 444
226
+
210
227
 
211
228
  s.group() # Creates a named group that can be referenced for extracting part of a match.
212
229
  # group is used the same as merge and capture but it takes a string name as the first argument.
213
230
  s.group('my_group', s.letter(), s.digit())
214
- # Unlike merge and capture, merge cannot be repeated.
231
+
232
+ # Unlike merge and capture, groups CANNOT be invoked with a range.
215
233
  # This is because group names must be unique in a pattern.
234
+ # s.group('unique_name', s.digit())(1, 2) <== INVALID
235
+
236
+ # Groups can easily be referenced from the match by name
237
+ # assuming the numbers have been grouped and named properly.
238
+ example_text = "Here is a phone number: 123-456-7890."
239
+ match = re.search(str(phone_number_pattern), example_text) # Notice str(pattern)
240
+
241
+ print("Full Match:", match.group())
242
+ print("Area Code:", match.group("area_code"))
243
+ print("Central Part:", match.group("central_part"))
244
+ print("Last Part:", match.group("last_part"))
245
+
246
+ # Output:
247
+ # Full Match: 123-456-7890
248
+ # Area Code: 123
249
+ # Central Part: 456
250
+ # Last Part: 7890
251
+
216
252
 
217
253
  ####################
218
254
  # Lookarounds
@@ -2,7 +2,7 @@
2
2
 
3
3
  ## The Next Generation of Regular Expressions
4
4
 
5
- STRling is a next-generation production-grade syntax designed as a user interface for writing powerful regular expressions (RegEx) with an object-oriented approach and instructional error handling. STRling recognizes the cryptic nature of raw regular expression can be challenging and susceptibility to errors, which is why STRling looks and feels nothing like RegEx while maintaining the same power and flexibility. String validation should be simple and enjoyable, not a hassle. Best of all, STRling syntax is built upon the RegEx engine, making it fully compatible with all libraries that accept RegEx along with the traditional RegEx methods built in to Python.
5
+ STRling is a next-generation production-grade syntax designed as a user interface for writing powerful regular expressions (RegEx) with an object-oriented approach and instructional error handling. STRling recognizes the cryptic nature of raw regular expression can be challenging and susceptibility to errors, which is why STRling looks and feels nothing like RegEx while maintaining the same power and flexibility. String validation should be simple and enjoyable, not a hassle. Best of all, STRling syntax is built upon the RegEx engine, making it fully compatible with all libraries that accept RegEx along with the traditional RegEx methods built-in to Python.
6
6
 
7
7
  ### Why STRling?
8
8
 
@@ -40,20 +40,20 @@ import re
40
40
  # - 1234567890
41
41
 
42
42
  # Separator: either space or hyphen
43
- separator = s.in_(s.lit(' -'))
43
+ separator = s.in_(' -')
44
44
 
45
45
  # Optional area code part: 123 even if in parenthesis like (123)
46
46
  area_code = s.merge( # notice we use merge since we don't want to name the group with parenthesis
47
- s.may(s.lit('(')), # Optional opening parenthesis
47
+ s.may('('), # Optional opening parenthesis
48
48
  s.group('area_code', s.digit(3)), # Exactly 3 digits and named for later reference
49
- s.may(s.lit(')')) # Optional closing parenthesis
49
+ s.may(')') # Optional closing parenthesis
50
50
  )
51
51
 
52
52
  # Central part: 456
53
- central_part = s.group('central_part', s.digit(3)) # Exactly 3 digits and named for later reference
53
+ central_part = s.group('central_part', s.digit(3)) # Exactly 3 digits and named for later reference
54
54
 
55
55
  # Last part: 7890
56
- last_part = s.group("last_part", s.digit(4)) # Exactly 4 digits and named for later reference
56
+ last_part = s.group("last_part", s.digit(4)) # Exactly 4 digits and named for later reference
57
57
 
58
58
  # Combine all parts into the final phone number pattern
59
59
  # Notice we don't name the whole pattern since we can already reference it
@@ -68,7 +68,7 @@ phone_number_pattern = s.merge(
68
68
  # Example usage
69
69
  # Note: To make a pattern a RegEx string compatible with other engines use `str(pattern)`.
70
70
  example_text = "(123) 456-7890 and 123-456-7890"
71
- pattern = re.compile(str(phone_number_pattern)) # Notice str(pattern)
71
+ pattern = re.compile(str(phone_number_pattern)) # Notice str(pattern)
72
72
  matches = pattern.finditer(example_text)
73
73
 
74
74
  for match in matches:
@@ -108,13 +108,13 @@ import re
108
108
  # For example, simply.letter(1, 3) will match 1 to 3 letters.
109
109
 
110
110
  # But some methods take an unknown number of parameters and can't distinguish the range.
111
- # For example, s.merge(simply.letter(), simply.digit(), 1, 2). <==== THIS IS INVALID
111
+ # For example, s.merge(simply.letter(), simply.digit(), 1, 2). <==== INVALID
112
112
 
113
- # However, all methods allow setting the range by reinvoking if a range hasn't already been set.
113
+ # However, all methods allow setting the range by externally invoking unless otherwise specified.
114
114
  # For example, simply.letter()(1, 2) is the same as simply.letter(1, 2).
115
115
 
116
116
  # This external invocation may seem useless, but it can solve our earlier issue.
117
- # For example, s.merge(simply.letter(), simply.digit())(1, 2). <==== THIS IS VALID
117
+ # For example, s.merge(simply.letter(), simply.digit())(1, 2). <==== VALID
118
118
 
119
119
  # Notice for all functions (where repetition is valid) we can invoke the range outside the parameters,
120
120
  # but it is primarily useful for functions with an unknown number of parameters.
@@ -143,6 +143,18 @@ s.tab() # Matches a tab character.
143
143
  s.carriage() # Matches a carriage return character.
144
144
  s.bound() # Matches a boundary character.
145
145
 
146
+ ####################
147
+ # Anchors
148
+ ####################
149
+
150
+ s.start() # Matches the start of a line.
151
+ # There is no `simply.not_start()` function.
152
+ # Instead, use `simply.not_behind(simply.start())`.
153
+
154
+ s.end() # Matches the end of a line.
155
+ # There is no `simply.not_end()` function.
156
+ # Instead, use `simply.not_ahead(simply.end())`.
157
+
146
158
  ####################
147
159
  # Custom Sets
148
160
  ####################
@@ -155,43 +167,26 @@ s.between(0, 9) # Matches any digit from 0 to 9.
155
167
  s.between('a', 'z') # Matches any lowercase letter from 'a' to 'z'.
156
168
  s.between('A', 'Z') # Matches any uppercase letter from 'A' to 'Z'.
157
169
 
158
- # Matches any characters in the provided set.
159
- s.in_(s.letter(), s.digit(), s.lit(',.')) # Matches letters, digits, commas, and periods.
160
- # You may notice a resemblance between simply.in_() and simply.any_of().
161
- # Key distinctions:
162
- # - simply.in_() typically processes faster than simply.any_of().
163
- # - simply.any_of() can process composite patterns while simply.in_() cannot.
164
- # A composite pattern is one consisting of smaller combined patterns.
165
-
166
- ####################
167
- # Anchors
168
- ####################
169
-
170
- s.start() # Matches the start of a line.
171
- # There is no `simply.not_start()` function.
172
- # Instead, use `simply.not_behind(simply.start())`.
173
-
174
- s.end() # Matches the end of a line.
175
- # There is no `simply.not_end()` function.
176
- # Instead, use `simply.not_ahead(simply.end())`.
170
+ # Matches any provided patterns, but they can't include subpatterns.
171
+ s.in_(s.letter(), s.digit(), ',.') # Matches any letter, digit, comma, and period.
172
+ # A composite pattern is one consisting of subpatterns (created by constructors and lookarounds).
177
173
 
178
174
  ####################
179
175
  # Constructors
180
176
  ####################
181
177
 
182
- s.any_of() # Matches any one of the provided patterns.
183
- # You may notice a resemblance between simply.in_() and simply.any_of().
184
- # Key distinctions:
185
- # - simply.in_() typically processes faster than simply.any_of().
186
- # - simply.any_of() can process composite patterns while simply.in_() cannot.
187
- # A composite pattern is one consisting of smaller combined patterns.
188
- s.any_of(pattern1, pattern2) # Matches only if one of the patterns listed is present.
178
+ s.any_of() # Matches any pattern, including patterns consisting of subpatterns.
179
+ # A composite pattern is one consisting of subpatterns (created by constructors and lookarounds).
180
+ pattern1 = s.merge(s.digit(3), s.letter(3)) # Matches 3 digits followed by 3 letters.
181
+ pattern2 = s.merge(s.letter(3), s.digit(3)) # Matches 3 letters followed by 3 digits.
182
+ s.any_of(pattern1, pattern2) # Matches either pattern1 or pattern2
189
183
 
190
184
 
191
185
  s.may() # Optionally matches the provided patterns.
192
186
  # If a `may` pattern isn't there, it still will match the rest of the patterns.
193
- # In the text, "ABC2" the patter below matches ['A', 'B', 'C2']
194
187
  s.merge(s.letter(), s.may(s.digit()))
188
+ # Matches any letter, and includes any digit following the letter.
189
+ # In the text, "AB2" the pattern above matches 'A' and 'B2'.
195
190
 
196
191
 
197
192
  s.merge() # Combines multiple patterns into one larger pattern.
@@ -202,12 +197,53 @@ s.capture() # Creates a numbered group that can be indexed for extracting part
202
197
  # Capture is used the same as merge.
203
198
  s.capture(s.letter(), s.digit())
204
199
 
200
+ # Captures CANNOT be invoked with a range: s.capture(s.digit(), s.letter())(1, 2) <== INVALID
201
+ # Captures CAN be invoked with a number of copies: s.capture(s.digit(), s.letter())(3) <== VALID
202
+
203
+ three_digit_group = s.capture(s.digit(3))
204
+ four_groups_of_three = three_digit_groups(4)
205
+
206
+ example_text = "Here is a number: 111222333444"
207
+ match = re.search(str(four_groups_of_three), example_text) # Notice str(pattern)
208
+
209
+ print("Full Match:", match.group())
210
+ print("First:", match.group(1))
211
+ print("Second:", match.group(2))
212
+ print("Third:", match.group(3))
213
+ print("Fourth:", match.group(4))
214
+
215
+ # Output:
216
+ # Full Match: 111222333444
217
+ # First: 111
218
+ # Second: 222
219
+ # Third: 333
220
+ # Fourth: 444
221
+
205
222
 
206
223
  s.group() # Creates a named group that can be referenced for extracting part of a match.
207
224
  # group is used the same as merge and capture but it takes a string name as the first argument.
208
225
  s.group('my_group', s.letter(), s.digit())
209
- # Unlike merge and capture, merge cannot be repeated.
226
+
227
+ # Unlike merge and capture, groups CANNOT be invoked with a range.
210
228
  # This is because group names must be unique in a pattern.
229
+ # s.group('unique_name', s.digit())(1, 2) <== INVALID
230
+
231
+ # Groups can easily be referenced from the match by name
232
+ # assuming the numbers have been grouped and named properly.
233
+ example_text = "Here is a phone number: 123-456-7890."
234
+ match = re.search(str(phone_number_pattern), example_text) # Notice str(pattern)
235
+
236
+ print("Full Match:", match.group())
237
+ print("Area Code:", match.group("area_code"))
238
+ print("Central Part:", match.group("central_part"))
239
+ print("Last Part:", match.group("last_part"))
240
+
241
+ # Output:
242
+ # Full Match: 123-456-7890
243
+ # Area Code: 123
244
+ # Central Part: 456
245
+ # Last Part: 7890
246
+
211
247
 
212
248
  ####################
213
249
  # Lookarounds
@@ -0,0 +1,211 @@
1
+
2
+ from .pattern import Pattern, clean_params
3
+
4
+
5
+
6
+ ############################
7
+ # Constructor Methods
8
+ ########
9
+
10
+
11
+ def any_of(*patterns):
12
+ """
13
+ Matches any provided pattern, including patterns consisting of subpatterns.
14
+
15
+ Example: simply as s
16
+ pattern1 = s.merge(s.digit(3), s.letter(3)) # Matches 3 digits followed by 3 letters.
17
+
18
+ pattern2 = s.merge(s.letter(3), s.digit(3)) # Matches 3 letters followed by 3 digits.
19
+
20
+ either_pattern = s.any_of(pattern1, pattern2) # Matches either pattern1 or pattern2
21
+
22
+ Parameters:
23
+ - *patterns (Pattern/str): One or more patterns to be matched.
24
+
25
+ Returns:
26
+ - Pattern: A Pattern object representing the OR combination of the given patterns.
27
+
28
+ Raises:
29
+ - ValueError: If any of the parameters are not an instance of Pattern or str.
30
+ """
31
+
32
+ clean_patterns = clean_params(*patterns)
33
+
34
+ joined = '|'.join(f'(?:{str(p)})' for p in clean_patterns)
35
+ new_pattern = f'(?:{joined})'
36
+
37
+ return Pattern(new_pattern, composite=True)
38
+
39
+ def may(*patterns):
40
+ """
41
+ Optionally matches the provided patterns. If this pattern is absent, surrounding patterns can still match.
42
+
43
+ Example: simply as s
44
+ my_pattern = s.merge(s.letter(), s.may(s.digit()))
45
+
46
+ # Matches any letter, and includes any digit following the letter.
47
+
48
+ # In the text, "AB2" the pattern above matches 'A' and 'B2'.
49
+
50
+ Parameters:
51
+ - *patterns (Pattern/str): One or more patterns to be optionally matched.
52
+
53
+ Returns:
54
+ - Pattern: A Pattern object representing the optional match of the given patterns.
55
+
56
+ Raises:
57
+ - ValueError: If any of the parameters are not an instance of Pattern or str.
58
+ """
59
+
60
+ clean_patterns = clean_params(*patterns)
61
+
62
+ joined = merge(*clean_patterns)
63
+ new_pattern = f'{joined}?'
64
+
65
+ return Pattern(new_pattern, composite=True)
66
+
67
+
68
+
69
+ def merge(*patterns):
70
+ """
71
+ Combines the provided patterns into one larger pattern.
72
+
73
+ Example: simply as s
74
+
75
+ # Below matches any digit, comma, or period.
76
+
77
+ my_merged_pattern = s.merge(s.digit(), ',.')
78
+
79
+ Parameters:
80
+ - *patterns (Pattern/str): One or more patterns to be concatenated.
81
+
82
+ Returns:
83
+ - Pattern: A Pattern object representing the concatenation of the given patterns.
84
+
85
+ Raises:
86
+ - ValueError: If any of the parameters are not an instance of Pattern or str.
87
+ """
88
+
89
+ clean_patterns = clean_params(*patterns)
90
+
91
+ joined = ''.join(str(p) for p in clean_patterns)
92
+ new_pattern = f'(?:{joined})'
93
+
94
+ return Pattern(new_pattern, composite=True)
95
+
96
+ def capture(*patterns):
97
+ """
98
+ Creates a numbered group that can be indexed for extracting this part of the match.
99
+
100
+ Captures CANNOT be invoked with a range.
101
+
102
+ s.capture(s.digit(), s.letter())(1, 2) <== INVALID
103
+
104
+ Captures CAN be invoked with a number of copies.
105
+
106
+ s.capture(s.digit(), s.letter())(3) <== VALID
107
+
108
+ Example: simply as s
109
+
110
+ # Below matches any digit, comma, or period.
111
+
112
+ my_captured_pattern = s.capture(s.digit(), ',.')
113
+
114
+
115
+ Parameters:
116
+ - *patterns (Pattern/str): One or more patterns to be captured.
117
+
118
+ Returns:
119
+ - Pattern: A Pattern object representing the capturing group of the given patterns.
120
+
121
+ Raises:
122
+ - ValueError: If any of the parameters are not an instance of Pattern or str.
123
+
124
+ Referencing: simply as s
125
+ three_digit_group = s.capture(s.digit(3))
126
+
127
+ four_groups_of_three = three_digit_groups(4)
128
+
129
+ example_text = "Here is a number: 111222333444"
130
+
131
+ match = re.search(str(four_groups_of_three), example_text) # Notice str(pattern)
132
+
133
+ print("Full Match:", match.group())
134
+ print("First:", match.group(1))
135
+ print("Second:", match.group(2))
136
+ print("Third:", match.group(3))
137
+ print("Fourth:", match.group(4))
138
+
139
+ # Output:
140
+ # Full Match: 111222333444
141
+ # First: 111
142
+ # Second: 222
143
+ # Third: 333
144
+ # Fourth: 444
145
+ """
146
+
147
+ clean_patterns = clean_params(*patterns)
148
+
149
+ joined = ''.join(str(p) for p in clean_patterns)
150
+ new_pattern = f'({joined})'
151
+
152
+ return Pattern(new_pattern, composite=True, numbered_group=True)
153
+
154
+ def group(name, *patterns):
155
+ """
156
+ Creates a unique named group that can be referenced for extracting this part of the match.
157
+
158
+ Groups CANNOT be invoked with a range.
159
+
160
+ s.group('name', s.digit())(1, 2) <== INVALID
161
+
162
+ Example: simply as s
163
+
164
+ # Below matches any digit, comma, or period.
165
+
166
+ my_named_pattern = s.group('my_group', s.digit(), ',.')
167
+
168
+ Parameters:
169
+ - name (str): The name of the capturing group.
170
+ - *patterns (Pattern/str): One or more patterns to be captured.
171
+
172
+ Returns:
173
+ - Pattern: A Pattern object representing the named capturing group of the given patterns.
174
+
175
+ Raises:
176
+ - ValueError: If any of the parameters are not an instance of Pattern or str.
177
+
178
+ Referencing: simply as s
179
+ first = s.group("first", s.digit(3))
180
+
181
+ second = s.group("second", s.digit(3))
182
+
183
+ third = s.group("third", s.digit(4))
184
+
185
+ phone_number_pattern = s.merge(first, "-", second, "-", third)
186
+
187
+ example_text = "Here is a phone number: 123-456-7890."
188
+
189
+ match = re.search(str(phone_number_pattern), example_text) # Notice str(pattern)
190
+
191
+ print("Full Match:", match.group())
192
+ print("First:", match.group("first"))
193
+ print("Second:", match.group("second"))
194
+ print("Third:", match.group("third"))
195
+
196
+ # Output:
197
+ # Full Match: 123-456-7890
198
+ # First: 123
199
+ # Second: 456
200
+ # Third: 7890
201
+ """
202
+
203
+ if not isinstance(name, str):
204
+ raise ValueError("The `name` parameter must be a string like 'my_group_name'.")
205
+
206
+ clean_patterns = clean_params(*patterns)
207
+
208
+ joined = ''.join(str(p) for p in clean_patterns)
209
+ new_pattern = f'(?P<{name}>{joined})'
210
+
211
+ return Pattern(new_pattern, composite=True, named_group=True)