Debian Codegraph @

README

raw
1 NAME
2 Regexp::Pattern - Convention/framework for modules that contain
3 collection of regexes
4
5 SPECIFICATION VERSION
6 0.2
7
8 VERSION
9 This document describes version 0.2.14 of Regexp::Pattern (from Perl
10 distribution Regexp-Pattern), released on 2020-04-01.
11
12 SYNOPSIS
13 Subroutine interface:
14
15 use Regexp::Pattern; # exports re()
16
17 my $re = re('YouTube::video_id');
18 say "ID does not look like a YouTube video ID" unless $id =~ /\A$re\z/;
19
20 # a dynamic pattern (generated on-demand) with generator arguments
21 my $re2 = re('Example::re3', {variant=>"B"});
22
23 Hash interface (a la Regexp::Common but simpler with regular/non-magical
24 hash that is only 1-level deep):
25
26 use Regexp::Pattern 'YouTube::video_id';
27 say "ID does not look like a YouTube video ID"
28 unless $id =~ /\A$RE{video_id}\z/;
29
30 # more complex example
31
32 use Regexp::Pattern (
33 're', # we still want the re() function
34 'Foo::bar' => (-as => 'qux'), # the pattern will be in your $RE{qux}
35 'YouTube::*', # wildcard import
36 'Example::re3' => (variant => 'B'), # supply generator arguments
37 'JSON::*' => (-prefix => 'json_'), # add prefix
38 'License::*' => (
39 # filtering options
40 -has_tag => 'family:cc', # only select patterns that have this tag
41 -lacks_tag => 'type:unversioned', # only select patterns that do not have this tag
42 -has_tag_matching => qr/^type:/, # only select patterns that have at least a tag matching this regex
43 -lacks_tag_matching => qr/^type:/, # only select patterns that do not have any tags matching this regex
44
45 # other options
46 -prefix => 'pat_', # add prefix
47 -suffix => '_license', # add suffix
48 ),
49 );
50
51 DESCRIPTION
52 Regexp::Pattern is a convention for organizing reusable regexp patterns
53 in modules, as well as framework to provide convenience in using those
54 patterns in your program.
55
56 Structure of an example Regexp::Pattern::* module
57 package Regexp::Pattern::Example;
58
59
60 our %RE = (
61 # the minimum spec
62 re1 => { pat => qr/\d{3}-\d{3}/ },
63
64 # more complete spec
65 re2 => {
66 summary => 'This is regexp for blah', # plaintext
67 description => <<'_',
68
69 A longer description in *Markdown* format.
70
71 _
72 pat => qr/\d{3}-\d{3}(?:-\d{5})?/,
73 tags => ['A','B'],
74 examples => [
75 # examples can be tested using 'test-regexp-pattern' script
76 # (distributed in Test-Regexp-Pattern distribution). examples can
77 # also be rendered in your POD using
78 # Pod::Weaver::Plugin::Regexp::Pattern.
79 {
80 str => '123-456',
81 matches => 1,
82 },
83 {
84 summary => 'Another example that matches',
85 str => '123-456-78901',
86 matches => 1,
87 },
88 {
89 summary => 'An example that does not match',
90 str => '123456',
91 matches => 0,
92 },
93 {
94 summary => 'An example that does not get tested',
95 str => '123456',
96 },
97 {
98 summary => 'Another example that does not get tested nor rendered to POD',
99 str => '234567',
100 matches => 0,
101 test => 0,
102 doc => 0,
103 },
104 ],
105 },
106
107 # dynamic (regexp generator)
108 re3 => {
109 summary => 'This is a regexp for blah blah',
110 description => <<'_',
111
112 ...
113
114 _
115 gen => sub {
116 my %args = @_;
117 my $variant = $args{variant} || 'A';
118 if ($variant eq 'A') {
119 return qr/\d{3}-\d{3}/;
120 } else { # B
121 return qr/\d{3}-\d{2}-\d{5}/;
122 }
123 },
124 gen_args => {
125 variant => {
126 summary => 'Choose variant',
127 schema => ['str*', in=>['A','B']],
128 default => 'A',
129 req => 1,
130 },
131 },
132 tags => ['B','C'],
133 examples => [
134 {
135 summary => 'An example that matches',
136 gen_args => {variant=>'A'},
137 str => '123-456',
138 matches => 1,
139 },
140 {
141 summary => "An example that doesn't match",
142 gen_args => {variant=>'B'},
143 str => '123-456',
144 matches => 0,
145 },
146 ],
147 },
148
149 re4 => {
150 summary => 'This is a regexp that does capturing',
151 # it is recommended that your pattern does not capture, unless
152 # necessary. capturing pattern should tag with 'capturing' to let
153 # users/tools know.
154 tags => ['capturing'],
155 pat => qr/(\d{3})-(\d{3})/,
156 examples => [
157 {str=>'123-456', matches=>[123, 456]},
158 {str=>'foo-bar', matches=>[]},
159 ],
160 },
161
162 re5 => {
163 summary => 'This is another regexp that is anchored and does (named) capturing',
164 # it is recommended that your pattern is not anchored for more
165 # reusability, unless necessary. anchored pattern should tag with
166 # 'anchored' to let users/tools know.
167 tags => ['capturing', 'anchored'],
168 pat => qr/^(?<cap1>\d{3})-(?<cap2>\d{3})/,
169 examples => [
170 {str=>'123-456', matches=>{cap1=>123, cap2=>456}},
171 {str=>'something 123-456', matches=>{}},
172 ],
173 },
174 );
175
176 A Regexp::Pattern::* module must declare a package global hash variable
177 named %RE. Hash keys are pattern names, hash values are pattern
178 definitions in the form of defhashes (see DefHash).
179
180 Pattern name should be a simple identifier that matches this regexp:
181 "/\A[A-Za-z_][A-Za-z_0-9]*\z/". The definition for the qualified pattern
182 name "Foo::Bar::baz" can then be located in
183 %Regexp::Pattern::Foo::Bar::RE under the hash key "baz".
184
185 Pattern definition hash should at the minimum be:
186
187 { pat => qr/.../ }
188
189 You can add more stuffs from the defhash specification, e.g. summary,
190 description, tags, and so on, for example (taken from
191 Regexp::Pattern::CPAN):
192
193 {
194 summary => 'PAUSE author ID, or PAUSE ID for short',
195 pat => qr/[A-Z][A-Z0-9]{1,8}/,
196 description => <<~HERE,
197 I'm not sure whether PAUSE allows digit for the first letter. For safety
198 I'm assuming no.
199 HERE
200 examples => [
201 {str=>'PERLANCAR', matches=>1},
202 {str=>'BAD ID', anchor=>1, matches=>0},
203 ],
204 }
205
206 Examples. Your regexp specification can include an "examples" property
207 (see above for example). The value of the "examples" property is an
208 array, each of which should be a defhash. For each example, at the
209 minimum you should specify "str" (string to be matched by the regexp),
210 "gen_args" (hash, arguments to use when generating dynamic regexp
211 pattern), and "matches" (a boolean value that specifies whether the
212 regexp should match the string or not, or an array/hash that specifies
213 the captures). You can of course specify other defhash properties (e.g.
214 "summary", "description", etc). Other example properties might be
215 introduced in the future.
216
217 If you use Dist::Zilla to build your distribution, you can use the
218 plugin [Regexp::Pattern] to test the examples during building, and the
219 Pod::Weaver plugin [-Regexp::Pattern] to render the examples in your
220 POD.
221
222 Using a Regexp::Pattern::* module
223 Standalone
224 A Regexp::Pattern::* module can be used in a standalone way (i.e. no
225 need to use via the Regexp::Pattern framework), as it simply contains
226 data that can be grabbed using a normal means, e.g.:
227
228 use Regexp::Pattern::Example;
229
230 say "Input does not match blah"
231 unless $input =~ /\A$Regexp::Pattern::Example::RE{re1}{pat}\z/;
232
233 Via Regexp::Pattern, sub interface
234 Regexp::Pattern (this module) also provides "re()" function to help
235 retrieve the regexp pattern. See "re" for more details.
236
237 Via Regexp::Pattern, hash interface
238 Additionally, Regexp::Pattern (since v0.2.0) lets you import regexp
239 patterns into your %RE package hash variable, a la Regexp::Common (but
240 simpler because the hash is just a regular hash, only 1-level deep, and
241 not magical).
242
243 To import, you specify qualified pattern names as the import arguments:
244
245 use Regexp::Pattern 'Q::pat1', 'Q::pat2', ...;
246
247 Each qualified pattern name can optionally be followed by a list of
248 name-value pairs. A pair name can be an option name (which is dash
249 followed by a word, e.g. "-as", "-prefix") or a generator argument name
250 for dynamic pattern.
251
252 Wildcard import. Instead of a qualified pattern name, you can use
253 'Module::SubModule::*' wildcard syntax to import all patterns from a
254 pattern module.
255
256 Importing into a different name. You can add the import option "-as" to
257 import into a different name, for example:
258
259 use Regexp::Pattern 'YouTube::video_id' => (-as => 'yt_id');
260
261 Prefix and suffix. You can also add a prefix and/or suffix to the
262 imported name:
263
264 use Regexp::Pattern 'Example::*' => (-prefix => 'example_');
265 use Regexp::Pattern 'Example::*' => (-suffix => '_sample');
266
267 Filtering. When wildcard-importing, you can select the patterns you want
268 using a combination of these options: "-has_tag" (only select patterns
269 that have a specified tag), "-lacks_tag" (only select patterns that do
270 not have a specified tag), "-has_tag_matching" (only select patterns
271 that have at least one tag matching specified regex pattern),
272 "-lacks_tag_matching" (only select patterns that do not have any tags
273 matching specified regex pattern).
274
275 Recommendations for writing the regex patterns
276 * Regexp pattern should in general be written as a "qr//" literal
277 instead of string
278
279 That is:
280
281 pat => qr/foo[abc]+/,
282
283 is preferred over:
284
285 pat => 'foo[abc]+',
286
287 Using a string literal is less desirable because of lack of
288 compile-time checking. An exception to this rule is when you want to
289 delay regex compilation for some reason, e.g. you want your user to
290 compile the patterns themselves using different regex engine (see
291 "re::engine::*" modules on CPAN).
292
293 * Regexp pattern should not be anchored (unless really necessary)
294
295 That is:
296
297 pat => qr/foo/,
298
299 is preferred over:
300
301 pat => qr/^foo/, # or qr/foo$/, or qr/\Afoo\z/
302
303 Adding anchors limits the reusability of the pattern. When composing
304 pattern, user can add anchors herself if needed.
305
306 When you define an anchored pattern, adding tag "anchored" is
307 recommended:
308
309 tags => ['anchored'],
310
311 * Regexp pattern should not contain capture groups (unless really
312 necessary)
313
314 Adding capture groups limits the reusability of the pattern because
315 it can affect the groups of the composed pattern. When composing
316 pattern, user can add captures herself if needed.
317
318 When you define a capturing pattern, adding tag "capturing" is
319 recommended:
320
321 tags => ['capturing'],
322
323 FUNCTIONS
324 re
325 Exported by default. Get a regexp pattern by name from a
326 "Regexp::Pattern::*" module.
327
328 Usage:
329
330 re($name[, \%args ]) => $re
331
332 $name is *MODULE_NAME::PATTERN_NAME* where *MODULE_NAME* is name of a
333 "Regexp::Pattern::*" module without the "Regexp::Pattern::" prefix and
334 *PATTERN_NAME* is a key to the %RE package global hash in the module. A
335 dynamic pattern can accept arguments for its generator, and you can pass
336 it as hashref in the second argument of "re()".
337
338 Anchoring. You can also put "-anchor => 1" in %args. This will
339 conveniently wraps the regex inside "qr/\A(?:...)\z/". To only add left
340 anchoring, specify "-anchor => 'left'" ("qr/\A(?:...)/". To only add
341 right anchoring, specify "-anchor => 'right'" ("qr/(?:...)\z/".
342
343 Die when pattern by name $name cannot be found (either the module cannot
344 be loaded or the pattern with that name is not found in the module).
345
346 FAQ
347 My pattern is not anchored, but what if I want to test the anchored version?
348 You can add "anchor=>1" or "gen_args=>{-anchor=>1}" in the example, for
349 example:
350
351 {
352 summary => 'PAUSE author ID, or PAUSE ID for short',
353 pat => qr/[A-Z][A-Z0-9]{1,8}/,
354 description => <<~HERE,
355 I'm not sure whether PAUSE allows digit for the first letter. For safety
356 I'm assuming no.
357 HERE
358 examples => [
359 {str=>'PERLANCAR', matches=>1},
360 {str=>'BAD ID', anchor=>1, matches=>0, summary=>"Contains whitespace"},
361 {str=>'NAMETOOLONG', gen_args=>{-anchor=>1}, matches=>0, summary=>"Too long"},
362 ],
363 }
364
365 HOMEPAGE
366 Please visit the project's homepage at
367 <https://metacpan.org/release/Regexp-Pattern>.
368
369 SOURCE
370 Source repository is at
371 <https://github.com/perlancar/perl-Regexp-Pattern>.
372
373 BUGS
374 Please report any bugs or feature requests on the bugtracker website
375 <https://rt.cpan.org/Public/Dist/Display.html?Name=Regexp-Pattern>
376
377 When submitting a bug or request, please include a test-file or a patch
378 to an existing test-file that illustrates the bug or desired feature.
379
380 SEE ALSO
381 Regexp::Common. Regexp::Pattern is an alternative to Regexp::Common.
382 Regexp::Pattern offers simplicity and lower startup overhead. Instead of
383 a magic hash, you retrieve available regexes from normal data structure
384 or via the provided "re()" function. Regexp::Pattern also provides a
385 hash interface, albeit the hash is not magic.
386
387 Regexp::Common::RegexpPattern, a bridge module to use patterns in
388 "Regexp::Pattern::*" modules via Regexp::Common.
389
390 Regexp::Pattern::RegexpCommon, a bridge module to use patterns in
391 "Regexp::Common::*" modules via Regexp::Pattern.
392
393 App::RegexpPatternUtils
394
395 If you use Dist::Zilla: Dist::Zilla::Plugin::Regexp::Pattern,
396 Pod::Weaver::Plugin::Regexp::Pattern,
397 Dist::Zilla::Plugin::AddModule::RegexpCommon::FromRegexpPattern,
398 Dist::Zilla::Plugin::AddModule::RegexpPattern::FromRegexpCommon.
399
400 Test::Regexp::Pattern and test-regexp-pattern.
401
402 AUTHOR
403 perlancar <[email protected]>
404
405 COPYRIGHT AND LICENSE
406 This software is copyright (c) 2020, 2019, 2018, 2016 by
407 [email protected].
408
409 This is free software; you can redistribute it and/or modify it under
410 the same terms as the Perl 5 programming language system itself.
411