.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Regexp::Pattern 3pm" .TH Regexp::Pattern 3pm "2022-11-29" "perl v5.36.0" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Regexp::Pattern \- Convention/framework for modules that contain collection of regexes .SH "SPECIFICATION VERSION" .IX Header "SPECIFICATION VERSION" 0.2 .SH "VERSION" .IX Header "VERSION" This document describes version 0.2.14 of Regexp::Pattern (from Perl distribution Regexp-Pattern), released on 2020\-04\-01. .SH "SYNOPSIS" .IX Header "SYNOPSIS" Subroutine interface: .PP .Vb 1 \& use Regexp::Pattern; # exports re() \& \& my $re = re(\*(AqYouTube::video_id\*(Aq); \& say "ID does not look like a YouTube video ID" unless $id =~ /\eA$re\ez/; \& \& # a dynamic pattern (generated on\-demand) with generator arguments \& my $re2 = re(\*(AqExample::re3\*(Aq, {variant=>"B"}); .Ve .PP Hash interface (a la Regexp::Common but simpler with regular/non\-magical hash that is only 1\-level deep): .PP .Vb 3 \& use Regexp::Pattern \*(AqYouTube::video_id\*(Aq; \& say "ID does not look like a YouTube video ID" \& unless $id =~ /\eA$RE{video_id}\ez/; \& \& # more complex example \& \& use Regexp::Pattern ( \& \*(Aqre\*(Aq, # we still want the re() function \& \*(AqFoo::bar\*(Aq => (\-as => \*(Aqqux\*(Aq), # the pattern will be in your $RE{qux} \& \*(AqYouTube::*\*(Aq, # wildcard import \& \*(AqExample::re3\*(Aq => (variant => \*(AqB\*(Aq), # supply generator arguments \& \*(AqJSON::*\*(Aq => (\-prefix => \*(Aqjson_\*(Aq), # add prefix \& \*(AqLicense::*\*(Aq => ( \& # filtering options \& \-has_tag => \*(Aqfamily:cc\*(Aq, # only select patterns that have this tag \& \-lacks_tag => \*(Aqtype:unversioned\*(Aq, # only select patterns that do not have this tag \& \-has_tag_matching => qr/^type:/, # only select patterns that have at least a tag matching this regex \& \-lacks_tag_matching => qr/^type:/, # only select patterns that do not have any tags matching this regex \& \& # other options \& \-prefix => \*(Aqpat_\*(Aq, # add prefix \& \-suffix => \*(Aq_license\*(Aq, # add suffix \& ), \& ); .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" Regexp::Pattern is a convention for organizing reusable regexp patterns in modules, as well as framework to provide convenience in using those patterns in your program. .SS "Structure of an example Regexp::Pattern::* module" .IX Subsection "Structure of an example Regexp::Pattern::* module" .Vb 1 \& package Regexp::Pattern::Example; \& \& \& our %RE = ( \& # the minimum spec \& re1 => { pat => qr/\ed{3}\-\ed{3}/ }, \& \& # more complete spec \& re2 => { \& summary => \*(AqThis is regexp for blah\*(Aq, # plaintext \& description => <<\*(Aq_\*(Aq, \& \& A longer description in *Markdown* format. \& \& _ \& pat => qr/\ed{3}\-\ed{3}(?:\-\ed{5})?/, \& tags => [\*(AqA\*(Aq,\*(AqB\*(Aq], \& examples => [ \& # examples can be tested using \*(Aqtest\-regexp\-pattern\*(Aq script \& # (distributed in Test\-Regexp\-Pattern distribution). examples can \& # also be rendered in your POD using \& # Pod::Weaver::Plugin::Regexp::Pattern. \& { \& str => \*(Aq123\-456\*(Aq, \& matches => 1, \& }, \& { \& summary => \*(AqAnother example that matches\*(Aq, \& str => \*(Aq123\-456\-78901\*(Aq, \& matches => 1, \& }, \& { \& summary => \*(AqAn example that does not match\*(Aq, \& str => \*(Aq123456\*(Aq, \& matches => 0, \& }, \& { \& summary => \*(AqAn example that does not get tested\*(Aq, \& str => \*(Aq123456\*(Aq, \& }, \& { \& summary => \*(AqAnother example that does not get tested nor rendered to POD\*(Aq, \& str => \*(Aq234567\*(Aq, \& matches => 0, \& test => 0, \& doc => 0, \& }, \& ], \& }, \& \& # dynamic (regexp generator) \& re3 => { \& summary => \*(AqThis is a regexp for blah blah\*(Aq, \& description => <<\*(Aq_\*(Aq, \& \& ... \& \& _ \& gen => sub { \& my %args = @_; \& my $variant = $args{variant} || \*(AqA\*(Aq; \& if ($variant eq \*(AqA\*(Aq) { \& return qr/\ed{3}\-\ed{3}/; \& } else { # B \& return qr/\ed{3}\-\ed{2}\-\ed{5}/; \& } \& }, \& gen_args => { \& variant => { \& summary => \*(AqChoose variant\*(Aq, \& schema => [\*(Aqstr*\*(Aq, in=>[\*(AqA\*(Aq,\*(AqB\*(Aq]], \& default => \*(AqA\*(Aq, \& req => 1, \& }, \& }, \& tags => [\*(AqB\*(Aq,\*(AqC\*(Aq], \& examples => [ \& { \& summary => \*(AqAn example that matches\*(Aq, \& gen_args => {variant=>\*(AqA\*(Aq}, \& str => \*(Aq123\-456\*(Aq, \& matches => 1, \& }, \& { \& summary => "An example that doesn\*(Aqt match", \& gen_args => {variant=>\*(AqB\*(Aq}, \& str => \*(Aq123\-456\*(Aq, \& matches => 0, \& }, \& ], \& }, \& \& re4 => { \& summary => \*(AqThis is a regexp that does capturing\*(Aq, \& # it is recommended that your pattern does not capture, unless \& # necessary. capturing pattern should tag with \*(Aqcapturing\*(Aq to let \& # users/tools know. \& tags => [\*(Aqcapturing\*(Aq], \& pat => qr/(\ed{3})\-(\ed{3})/, \& examples => [ \& {str=>\*(Aq123\-456\*(Aq, matches=>[123, 456]}, \& {str=>\*(Aqfoo\-bar\*(Aq, matches=>[]}, \& ], \& }, \& \& re5 => { \& summary => \*(AqThis is another regexp that is anchored and does (named) capturing\*(Aq, \& # it is recommended that your pattern is not anchored for more \& # reusability, unless necessary. anchored pattern should tag with \& # \*(Aqanchored\*(Aq to let users/tools know. \& tags => [\*(Aqcapturing\*(Aq, \*(Aqanchored\*(Aq], \& pat => qr/^(?\ed{3})\-(?\ed{3})/, \& examples => [ \& {str=>\*(Aq123\-456\*(Aq, matches=>{cap1=>123, cap2=>456}}, \& {str=>\*(Aqsomething 123\-456\*(Aq, matches=>{}}, \& ], \& }, \& ); .Ve .PP A Regexp::Pattern::* module must declare a package global hash variable named \&\f(CW%RE\fR. Hash keys are pattern names, hash values are pattern definitions in the form of defhashes (see DefHash). .PP Pattern name should be a simple identifier that matches this regexp: \f(CW\*(C`/\eA[A\-Za\-z_][A\-Za\-z_0\-9]*\ez/\*(C'\fR. The definition for the qualified pattern name \&\f(CW\*(C`Foo::Bar::baz\*(C'\fR can then be located in \f(CW%Regexp::Pattern::Foo::Bar::RE\fR under the hash key \f(CW\*(C`baz\*(C'\fR. .PP Pattern definition hash should at the minimum be: .PP .Vb 1 \& { pat => qr/.../ } .Ve .PP You can add more stuffs from the defhash specification, e.g. summary, description, tags, and so on, for example (taken from Regexp::Pattern::CPAN): .PP .Vb 12 \& { \& summary => \*(AqPAUSE author ID, or PAUSE ID for short\*(Aq, \& pat => qr/[A\-Z][A\-Z0\-9]{1,8}/, \& description => <<~HERE, \& I\*(Aqm not sure whether PAUSE allows digit for the first letter. For safety \& I\*(Aqm assuming no. \& HERE \& examples => [ \& {str=>\*(AqPERLANCAR\*(Aq, matches=>1}, \& {str=>\*(AqBAD ID\*(Aq, anchor=>1, matches=>0}, \& ], \& } .Ve .PP \&\fBExamples\fR. Your regexp specification can include an \f(CW\*(C`examples\*(C'\fR property (see above for example). The value of the \f(CW\*(C`examples\*(C'\fR property is an array, each of which should be a defhash. For each example, at the minimum you should specify \&\f(CW\*(C`str\*(C'\fR (string to be matched by the regexp), \f(CW\*(C`gen_args\*(C'\fR (hash, arguments to use when generating dynamic regexp pattern), and \f(CW\*(C`matches\*(C'\fR (a boolean value that specifies whether the regexp should match the string or not, or an array/hash that specifies the captures). You can of course specify other defhash properties (e.g. \f(CW\*(C`summary\*(C'\fR, \f(CW\*(C`description\*(C'\fR, etc). Other example properties might be introduced in the future. .PP If you use Dist::Zilla to build your distribution, you can use the plugin [Regexp::Pattern] to test the examples during building, and the Pod::Weaver plugin [\-Regexp::Pattern] to render the examples in your \s-1POD.\s0 .SS "Using a Regexp::Pattern::* module" .IX Subsection "Using a Regexp::Pattern::* module" \fIStandalone\fR .IX Subsection "Standalone" .PP A Regexp::Pattern::* module can be used in a standalone way (i.e. no need to use via the Regexp::Pattern framework), as it simply contains data that can be grabbed using a normal means, e.g.: .PP .Vb 1 \& use Regexp::Pattern::Example; \& \& say "Input does not match blah" \& unless $input =~ /\eA$Regexp::Pattern::Example::RE{re1}{pat}\ez/; .Ve .PP \fIVia Regexp::Pattern, sub interface\fR .IX Subsection "Via Regexp::Pattern, sub interface" .PP Regexp::Pattern (this module) also provides \f(CW\*(C`re()\*(C'\fR function to help retrieve the regexp pattern. See \*(L"re\*(R" for more details. .PP \fIVia Regexp::Pattern, hash interface\fR .IX Subsection "Via Regexp::Pattern, hash interface" .PP Additionally, Regexp::Pattern (since v0.2.0) lets you import regexp patterns into your \f(CW%RE\fR package hash variable, a la Regexp::Common (but simpler because the hash is just a regular hash, only 1\-level deep, and not magical). .PP To import, you specify qualified pattern names as the import arguments: .PP .Vb 1 \& use Regexp::Pattern \*(AqQ::pat1\*(Aq, \*(AqQ::pat2\*(Aq, ...; .Ve .PP Each qualified pattern name can optionally be followed by a list of name-value pairs. A pair name can be an option name (which is dash followed by a word, e.g. \&\f(CW\*(C`\-as\*(C'\fR, \f(CW\*(C`\-prefix\*(C'\fR) or a generator argument name for dynamic pattern. .PP \&\fBWildcard import.\fR Instead of a qualified pattern name, you can use \&'Module::SubModule::*' wildcard syntax to import all patterns from a pattern module. .PP \&\fBImporting into a different name.\fR You can add the import option \f(CW\*(C`\-as\*(C'\fR to import into a different name, for example: .PP .Vb 1 \& use Regexp::Pattern \*(AqYouTube::video_id\*(Aq => (\-as => \*(Aqyt_id\*(Aq); .Ve .PP \&\fBPrefix and suffix.\fR You can also add a prefix and/or suffix to the imported name: .PP .Vb 2 \& use Regexp::Pattern \*(AqExample::*\*(Aq => (\-prefix => \*(Aqexample_\*(Aq); \& use Regexp::Pattern \*(AqExample::*\*(Aq => (\-suffix => \*(Aq_sample\*(Aq); .Ve .PP \&\fBFiltering.\fR When wildcard-importing, you can select the patterns you want using a combination of these options: \f(CW\*(C`\-has_tag\*(C'\fR (only select patterns that have a specified tag), \f(CW\*(C`\-lacks_tag\*(C'\fR (only select patterns that do not have a specified tag), \f(CW\*(C`\-has_tag_matching\*(C'\fR (only select patterns that have at least one tag matching specified regex pattern), \f(CW\*(C`\-lacks_tag_matching\*(C'\fR (only select patterns that do not have any tags matching specified regex pattern). .SS "Recommendations for writing the regex patterns" .IX Subsection "Recommendations for writing the regex patterns" .IP "\(bu" 4 Regexp pattern should in general be written as a \f(CW\*(C`qr//\*(C'\fR literal instead of string .Sp That is: .Sp .Vb 1 \& pat => qr/foo[abc]+/, .Ve .Sp is preferred over: .Sp .Vb 1 \& pat => \*(Aqfoo[abc]+\*(Aq, .Ve .Sp Using a string literal is less desirable because of lack of compile-time checking. An exception to this rule is when you want to delay regex compilation for some reason, e.g. you want your user to compile the patterns themselves using different regex engine (see \f(CW\*(C`re::engine::*\*(C'\fR modules on \s-1CPAN\s0). .IP "\(bu" 4 Regexp pattern should not be anchored (unless really necessary) .Sp That is: .Sp .Vb 1 \& pat => qr/foo/, .Ve .Sp is preferred over: .Sp .Vb 1 \& pat => qr/^foo/, # or qr/foo$/, or qr/\eAfoo\ez/ .Ve .Sp Adding anchors limits the reusability of the pattern. When composing pattern, user can add anchors herself if needed. .Sp When you define an anchored pattern, adding tag \f(CW\*(C`anchored\*(C'\fR is recommended: .Sp .Vb 1 \& tags => [\*(Aqanchored\*(Aq], .Ve .IP "\(bu" 4 Regexp pattern should not contain capture groups (unless really necessary) .Sp Adding capture groups limits the reusability of the pattern because it can affect the groups of the composed pattern. When composing pattern, user can add captures herself if needed. .Sp When you define a capturing pattern, adding tag \f(CW\*(C`capturing\*(C'\fR is recommended: .Sp .Vb 1 \& tags => [\*(Aqcapturing\*(Aq], .Ve .SH "FUNCTIONS" .IX Header "FUNCTIONS" .SS "re" .IX Subsection "re" Exported by default. Get a regexp pattern by name from a \f(CW\*(C`Regexp::Pattern::*\*(C'\fR module. .PP Usage: .PP .Vb 1 \& re($name[, \e%args ]) => $re .Ve .PP \&\f(CW$name\fR is \fI\s-1MODULE_NAME::PATTERN_NAME\s0\fR where \fI\s-1MODULE_NAME\s0\fR is name of a \&\f(CW\*(C`Regexp::Pattern::*\*(C'\fR module without the \f(CW\*(C`Regexp::Pattern::\*(C'\fR prefix and \&\fI\s-1PATTERN_NAME\s0\fR is a key to the \f(CW%RE\fR package global hash in the module. A dynamic pattern can accept arguments for its generator, and you can pass it as hashref in the second argument of \f(CW\*(C`re()\*(C'\fR. .PP \&\fBAnchoring.\fR You can also put \f(CW\*(C`\-anchor => 1\*(C'\fR in \f(CW%args\fR. This will conveniently wraps the regex inside \f(CW\*(C`qr/\eA(?:...)\ez/\*(C'\fR. To only add left anchoring, specify \f(CW\*(C`\-anchor => \*(Aqleft\*(Aq\*(C'\fR (\f(CW\*(C`qr/\eA(?:...)/\*(C'\fR. To only add right anchoring, specify \f(CW\*(C`\-anchor => \*(Aqright\*(Aq\*(C'\fR (\f(CW\*(C`qr/(?:...)\ez/\*(C'\fR. .PP Die when pattern by name \f(CW$name\fR cannot be found (either the module cannot be loaded or the pattern with that name is not found in the module). .SH "FAQ" .IX Header "FAQ" .SS "My pattern is not anchored, but what if I want to test the anchored version?" .IX Subsection "My pattern is not anchored, but what if I want to test the anchored version?" You can add \f(CW\*(C`anchor=>1\*(C'\fR or \f(CW\*(C`gen_args=>{\-anchor=>1}\*(C'\fR in the example, for example: .PP .Vb 10 \& { \& summary => \*(AqPAUSE author ID, or PAUSE ID for short\*(Aq, \& pat => qr/[A\-Z][A\-Z0\-9]{1,8}/, \& description => <<~HERE, \& I\*(Aqm not sure whether PAUSE allows digit for the first letter. For safety \& I\*(Aqm assuming no. \& HERE \& examples => [ \& {str=>\*(AqPERLANCAR\*(Aq, matches=>1}, \& {str=>\*(AqBAD ID\*(Aq, anchor=>1, matches=>0, summary=>"Contains whitespace"}, \& {str=>\*(AqNAMETOOLONG\*(Aq, gen_args=>{\-anchor=>1}, matches=>0, summary=>"Too long"}, \& ], \& } .Ve .SH "HOMEPAGE" .IX Header "HOMEPAGE" Please visit the project's homepage at . .SH "SOURCE" .IX Header "SOURCE" Source repository is at . .SH "BUGS" .IX Header "BUGS" Please report any bugs or feature requests on the bugtracker website .PP When submitting a bug or request, please include a test-file or a patch to an existing test-file that illustrates the bug or desired feature. .SH "SEE ALSO" .IX Header "SEE ALSO" Regexp::Common. Regexp::Pattern is an alternative to Regexp::Common. Regexp::Pattern offers simplicity and lower startup overhead. Instead of a magic hash, you retrieve available regexes from normal data structure or via the provided \f(CW\*(C`re()\*(C'\fR function. Regexp::Pattern also provides a hash interface, albeit the hash is not magic. .PP Regexp::Common::RegexpPattern, a bridge module to use patterns in \&\f(CW\*(C`Regexp::Pattern::*\*(C'\fR modules via Regexp::Common. .PP Regexp::Pattern::RegexpCommon, a bridge module to use patterns in \&\f(CW\*(C`Regexp::Common::*\*(C'\fR modules via Regexp::Pattern. .PP App::RegexpPatternUtils .PP If you use Dist::Zilla: Dist::Zilla::Plugin::Regexp::Pattern, Pod::Weaver::Plugin::Regexp::Pattern, Dist::Zilla::Plugin::AddModule::RegexpCommon::FromRegexpPattern, Dist::Zilla::Plugin::AddModule::RegexpPattern::FromRegexpCommon. .PP Test::Regexp::Pattern and test-regexp-pattern. .SH "AUTHOR" .IX Header "AUTHOR" perlancar .SH "COPYRIGHT AND LICENSE" .IX Header "COPYRIGHT AND LICENSE" This software is copyright (c) 2020, 2019, 2018, 2016 by perlancar@cpan.org. .PP This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.