Regexp::Pattern(3pm)

1Regexp::Pattern(3)    User Contributed Perl Documentation   Regexp::Pattern(3)
2
3
4

NAME

6       Regexp::Pattern - Convention/framework for modules that contain
7       collection of regexes
8

SPECIFICATION VERSION

10       0.2.0
11

VERSION

13       This document describes version 0.2.3 of Regexp::Pattern (from Perl
14       distribution Regexp-Pattern), released on 2018-04-03.
15

SYNOPSIS

17       Subroutine interface:
18
19        use Regexp::Pattern; # exports re()
20
21        my $re = re('YouTube::video_id');
22        say "ID does not look like a YouTube video ID" unless $id =~ /\A$re\z/;
23
24        # a dynamic pattern (generated on-demand) with generator arguments
25        my $re2 = re('Example::re3', {variant=>"B"});
26
27       Hash interface (a la Regexp::Common but simpler with
28       regular/non-magical hash that is only 1-level deep):
29
30        use Regexp::Pattern 'YouTube::video_id';
31        say "ID does not look like a YouTube video ID"
32            unless $id =~ /\A$RE{video_id}\z/;
33
34        # more complex example
35
36        use Regexp::Pattern (
37            're',                                # we still want the re() function
38            'Foo::bar' => (-as => 'qux'),        # the pattern will be in your $RE{qux}
39            'YouTube::*',                        # wildcard import
40            'Example::re3' => (variant => 'B'),  # supply generator arguments
41            'JSON::*' => (-prefix => 'json_'),   # add prefix
42            'License::*' => (
43              -has_tag    => 'family:cc',        # select by tag
44              -lacks_tag  => 'type:unversioned', #   also select by lack of tag
45              -suffix     => '_license',         #   also add suffix
46            ),
47        );
48

DESCRIPTION

50       Regexp::Pattern is a convention for organizing reusable regexp patterns
51       in modules, as well as framework to provide convenience in using those
52       patterns in your program.
53
54   Structure of an example Regexp::Pattern::* module
55        package Regexp::Pattern::Example;
56
57
58        our %RE = (
59            # the minimum spec
60            re1 => { pat => qr/\d{3}-\d{4}/ },
61
62            # more complete spec
63            re2 => {
64                summary => 'This is regexp for blah',
65                description => <<'_',
66
67        A longer description.
68
69        _
70                pat => qr/.../,
71                tags => ['A','B'],
72            },
73
74            # dynamic (regexp generator)
75            re3 => {
76                summary => 'This is a regexp for blah blah',
77                description => <<'_',
78
79        ...
80
81        _
82                gen => sub {
83                    my %args = @_;
84                    my $variant = $args{variant} || 'A';
85                    if ($variant eq 'A') {
86                        return qr/\d{3}-\d{3}/;
87                    } else { # B
88                        return qr/\d{3}-\d{2}-\d{5}/;
89                    }
90                },
91                gen_args => {
92                    variant => {
93                        summary => 'Choose variant',
94                        schema => ['str*', in=>['A','B']],
95                        default => 'A',
96                        req => 1,
97                    },
98                },
99                tags => ['B','C'],
100            },
101        );
102
103       A Regexp::Pattern::* module must declare a package global hash variable
104       named %RE. Hash keys are pattern names, hash values are pattern
105       definitions in the form of defhashes (see DefHash).
106
107       Pattern name should be a simple identifier that matches this regexp:
108       "/\A[A-Za-z_][A-Za-z_0-9]*\z/". The definition for the qualified
109       pattern name "Foo::Bar::baz" can then be located in
110       %Regexp::Pattern::Foo::Bar::RE under the hash key "baz".
111
112       Pattern definition hash should at the minimum be:
113
114        { pat => qr/.../ }
115
116       You can add more stuffs from the defhash specification, e.g. summary,
117       description, tags, and so on, for example (taken from
118       Regexp::Pattern::CPAN):
119
120        {
121            summary     => 'PAUSE author ID, or PAUSE ID for short',
122            pat         => qr/[A-Z][A-Z0-9]{1,8}/,
123            description => <<~HERE,
124            I'm not sure whether PAUSE allows digit for the first letter. For safety
125            I'm assuming no.
126            HERE
127        }
128
129   Using a Regexp::Pattern::* module
130       Standalone
131
132       A Regexp::Pattern::* module can be used in a standalone way (i.e. no
133       need to use via the Regexp::Pattern framework), as it simply contains
134       data that can be grabbed using a normal means, e.g.:
135
136        use Regexp::Pattern::Example;
137
138        say "Input does not match blah"
139            unless $input =~ /\A$Regexp::Pattern::Example::RE{re1}{pat}\z/;
140
141       Via Regexp::Pattern, sub interface
142
143       Regexp::Pattern (this module) also provides "re()" function to help
144       retrieve the regexp pattern. See "re" for more details.
145
146       Via Regexp::Pattern, hash interface
147
148       Additionally, Regexp::Pattern (since v0.2.0) lets you import regexp
149       patterns into your %RE package hash variable, a la Regexp::Common (but
150       simpler because the hash is just a regular hash, only 1-level deep, and
151       not magical).
152
153       To import, you specify qualified pattern names as the import arguments:
154
155        use Regexp::Pattern 'Q::pat1', 'Q::pat2', ...;
156
157       Each qualified pattern name can optionally be followed by a list of
158       name-value pairs. A pair name can be an option name (which is dash
159       followed by a word, e.g.  "-as", "-prefix") or a generator argument
160       name for dynamic pattern.
161
162       Wildcard import. Instead of a qualified pattern name, you can use
163       'Module::SubModule::*' wildcard syntax to import all patterns from a
164       pattern module.
165
166       Importing into a different name. You can add the import option "-as" to
167       import into a different name, for example:
168
169        use Regexp::Pattern 'YouTube::video_id' => (-as => 'yt_id');
170
171       Prefix and suffix. You can also add a prefix and/or suffix to the
172       imported name:
173
174        use Regexp::Pattern 'Example::*' => (-prefix => 'example_');
175        use Regexp::Pattern 'Example::*' => (-suffix => '_sample');
176
177       Filtering. When wildcard-importing, you can select the patterns you
178       want using a combination of these options: "-has_tag" (only select
179       patterns that have a specified tag), "-lacks_tag" (only select patterns
180       that do not have a specified tag).
181
182   Recommendations for writing the regex patterns
183       ·   Regexp pattern should be written as a "qr//" literal
184
185           Using a string literal is less desirable. That is:
186
187            pat => qr/foo[abc]+/,
188
189           is preferred over:
190
191            pat => 'foo[abc]+',
192
193       ·   Regexp pattern should not be anchored (unless really necessary)
194
195           That is:
196
197            pat => qr/foo/,
198
199           is preferred over:
200
201            pat => qr/^foo/, # or qr/foo$/, or qr/\Afoo\z/
202
203           Adding anchors limits the reusability of the pattern. When
204           composing pattern, user can add anchors herself if needed.
205
206           When you define an anchored pattern, adding tag "anchored" is
207           recommended:
208
209            tags => ['anchored'],
210
211       ·   Regexp pattern should not contain capture groups (unless really
212           necessary)
213
214           Adding capture groups limits the reusability of the pattern because
215           it can affect the groups of the composed pattern. When composing
216           pattern, user can add captures herself if needed.
217
218           When you define an anchored pattern, adding tag "capturing" is
219           recommended:
220
221            tags => ['capturing'],
222

FUNCTIONS

224   re
225       Exported by default. Get a regexp pattern by name from a
226       "Regexp::Pattern::*" module.
227
228       Usage:
229
230        re($name[, \%args ]) => $re
231
232       $name is MODULE_NAME::PATTERN_NAME where MODULE_NAME is name of a
233       "Regexp::Pattern::*" module without the "Regexp::Pattern::" prefix and
234       PATTERN_NAME is a key to the %RE package global hash in the module. A
235       dynamic pattern can accept arguments for its generator, and you can
236       pass it as hashref in the second argument of "re()".
237
238       Die when pattern by name $name cannot be found (either the module
239       cannot be loaded or the pattern with that name is not found in the
240       module).
241

HOMEPAGE

243       Please visit the project's homepage at
244       <https://metacpan.org/release/Regexp-Pattern>.
245

SOURCE

247       Source repository is at
248       <https://github.com/perlancar/perl-Regexp-Pattern>.
249

BUGS

251       Please report any bugs or feature requests on the bugtracker website
252       <https://rt.cpan.org/Public/Dist/Display.html?Name=Regexp-Pattern>
253
254       When submitting a bug or request, please include a test-file or a patch
255       to an existing test-file that illustrates the bug or desired feature.
256

AUTHOR

278       perlancar <perlancar@cpan.org>
279

COPYRIGHT AND LICENSE

281       This software is copyright (c) 2018, 2016 by perlancar@cpan.org.
282
283       This is free software; you can redistribute it and/or modify it under
284       the same terms as the Perl 5 programming language system itself.
285
286
287
288perl v5.28.0                      2018-04-03                Regexp::Pattern(3)