Regexp::Pattern - Convention/framework for modules that contain collection of regexes
0.2
This document describes version 0.2.8 of Regexp::Pattern (from Perl distribution Regexp-Pattern), released on 2018-09-12.
Subroutine interface:
use Regexp::Pattern; # exports re() my $re = re('YouTube::video_id'); say "ID does not look like a YouTube video ID" unless $id =~ /\A$re\z/; # a dynamic pattern (generated on-demand) with generator arguments my $re2 = re('Example::re3', {variant=>"B"});
Hash interface (a la Regexp::Common but simpler with regular/non-magical hash that is only 1-level deep):
use Regexp::Pattern 'YouTube::video_id'; say "ID does not look like a YouTube video ID" unless $id =~ /\A$RE{video_id}\z/; # more complex example use Regexp::Pattern ( 're', # we still want the re() function 'Foo::bar' => (-as => 'qux'), # the pattern will be in your $RE{qux} 'YouTube::*', # wildcard import 'Example::re3' => (variant => 'B'), # supply generator arguments 'JSON::*' => (-prefix => 'json_'), # add prefix 'License::*' => ( -has_tag => 'family:cc', # select by tag -lacks_tag => 'type:unversioned', # also select by lack of tag -suffix => '_license', # also add suffix ), );
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.
package Regexp::Pattern::Example; our %RE = ( # the minimum spec re1 => { pat => qr/\d{3}-\d{3}/ }, # more complete spec re2 => { summary => 'This is regexp for blah', description => <<'_', A longer description. _ pat => qr/\d{3}-\d{3}(?:-\d{5})?/, tags => ['A','B'], examples => [ { str => '123-456', matches => 1, }, { summary => 'Another example that matches', str => '123-456-78901', matches => 1, }, { summary => 'An example that does not match', str => '123456', matches => 0, }, { summary => 'An example that does not get tested', str => '123456', }, { summary => 'Another example that does not get tested nor rendered to POD', str => '234567', matches => 0, test => 0, doc => 0, }, ], }, # dynamic (regexp generator) re3 => { summary => 'This is a regexp for blah blah', description => <<'_', ... _ gen => sub { my %args = @_; my $variant = $args{variant} || 'A'; if ($variant eq 'A') { return qr/\d{3}-\d{3}/; } else { # B return qr/\d{3}-\d{2}-\d{5}/; } }, gen_args => { variant => { summary => 'Choose variant', schema => ['str*', in=>['A','B']], default => 'A', req => 1, }, }, tags => ['B','C'], examples => [ { summary => 'An example that matches', gen_args => {variant=>'A'}, str => '123-456', matches => 1, }, { summary => "An example that doesn't match", gen_args => {variant=>'B'}, str => '123-456', matches => 0, }, ], }, re4 => { summary => 'This is a regexp that does capturing', tags => ['capturing'], pat => qr/(\d{3})-(\d{3})/, examples => [ {str=>'123-456', matches=>[123, 456]}, {str=>'foo-bar', matches=>[]}, ], }, re5 => { summary => 'This is another regexp that does (named) capturing and anchoring', tags => ['capturing', 'anchored'], pat => qr/^(?<cap1>\d{3})-(?<cap2>\d{3})/, examples => [ {str=>'123-456', matches=>{cap1=>123, cap2=>456}}, {str=>'something 123-456', matches=>{}}, ], }, );
A Regexp::Pattern::* module must declare a package global hash variable named %RE. Hash keys are pattern names, hash values are pattern definitions in the form of defhashes (see DefHash).
%RE
Pattern name should be a simple identifier that matches this regexp: /\A[A-Za-z_][A-Za-z_0-9]*\z/. The definition for the qualified pattern name Foo::Bar::baz can then be located in %Regexp::Pattern::Foo::Bar::RE under the hash key baz.
/\A[A-Za-z_][A-Za-z_0-9]*\z/
Foo::Bar::baz
%Regexp::Pattern::Foo::Bar::RE
baz
Pattern definition hash should at the minimum be:
{ pat => qr/.../ }
You can add more stuffs from the defhash specification, e.g. summary, description, tags, and so on, for example (taken from Regexp::Pattern::CPAN):
{ summary => 'PAUSE author ID, or PAUSE ID for short', pat => qr/[A-Z][A-Z0-9]{1,8}/, description => <<~HERE, I'm not sure whether PAUSE allows digit for the first letter. For safety I'm assuming no. HERE examples => [ {str=>'PERLANCAR', matches=>1}, {str=>'BAD ID', matches=>0}, ], }
Examples. Your regexp specification can include an examples property (see above for example). The value of the examples property is an array, each of which should be a defhash. For each example, at the minimum you should specify str (string to be matched by the regexp), gen_args (hash, arguments to use when generating dynamic regexp pattern), and matches (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. summary, description, etc). Other example properties might be introduced in the future.
examples
str
gen_args
matches
summary
description
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 POD.
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.:
use Regexp::Pattern::Example; say "Input does not match blah" unless $input =~ /\A$Regexp::Pattern::Example::RE{re1}{pat}\z/;
Regexp::Pattern (this module) also provides re() function to help retrieve the regexp pattern. See "re" for more details.
re()
Additionally, Regexp::Pattern (since v0.2.0) lets you import regexp patterns into your %RE package hash variable, a la Regexp::Common (but simpler because the hash is just a regular hash, only 1-level deep, and not magical).
To import, you specify qualified pattern names as the import arguments:
use Regexp::Pattern 'Q::pat1', 'Q::pat2', ...;
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. -as, -prefix) or a generator argument name for dynamic pattern.
-as
-prefix
Wildcard import. Instead of a qualified pattern name, you can use 'Module::SubModule::*' wildcard syntax to import all patterns from a pattern module.
Importing into a different name. You can add the import option -as to import into a different name, for example:
use Regexp::Pattern 'YouTube::video_id' => (-as => 'yt_id');
Prefix and suffix. You can also add a prefix and/or suffix to the imported name:
use Regexp::Pattern 'Example::*' => (-prefix => 'example_'); use Regexp::Pattern 'Example::*' => (-suffix => '_sample');
Filtering. When wildcard-importing, you can select the patterns you want using a combination of these options: -has_tag (only select patterns that have a specified tag), -lacks_tag (only select patterns that do not have a specified tag).
-has_tag
-lacks_tag
Regexp pattern should be written as a qr// literal
qr//
Using a string literal is less desirable. That is:
pat => qr/foo[abc]+/,
is preferred over:
pat => 'foo[abc]+',
Regexp pattern should not be anchored (unless really necessary)
That is:
pat => qr/foo/,
pat => qr/^foo/, # or qr/foo$/, or qr/\Afoo\z/
Adding anchors limits the reusability of the pattern. When composing pattern, user can add anchors herself if needed.
When you define an anchored pattern, adding tag anchored is recommended:
anchored
tags => ['anchored'],
Regexp pattern should not contain capture groups (unless really necessary)
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.
When you define an anchored pattern, adding tag capturing is recommended:
capturing
tags => ['capturing'],
Exported by default. Get a regexp pattern by name from a Regexp::Pattern::* module.
Regexp::Pattern::*
Usage:
re($name[, \%args ]) => $re
$name is MODULE_NAME::PATTERN_NAME where MODULE_NAME is name of a Regexp::Pattern::* module without the Regexp::Pattern:: prefix and PATTERN_NAME is a key to the %RE 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 re().
$name
Regexp::Pattern::
Anchoring. You can also put -anchor => 1 in %args. This will conveniently wraps the regex inside qr/\A(?:...)\z/.
-anchor => 1
%args
qr/\A(?:...)\z/
Die when pattern by name $name cannot be found (either the module cannot be loaded or the pattern with that name is not found in the module).
Please visit the project's homepage at https://metacpan.org/release/Regexp-Pattern.
Source repository is at https://github.com/perlancar/perl-Regexp-Pattern.
Please report any bugs or feature requests on the bugtracker website https://rt.cpan.org/Public/Dist/Display.html?Name=Regexp-Pattern
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.
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 re() function. Regexp::Pattern also provides a hash interface, albeit the hash is not magic.
Regexp::Common::RegexpPattern, a bridge module to use patterns in Regexp::Pattern::* modules via Regexp::Common.
Regexp::Pattern::RegexpCommon, a bridge module to use patterns in Regexp::Common::* modules via Regexp::Pattern.
Regexp::Common::*
App::RegexpPatternUtils
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.
Test::Regexp::Pattern and test-regexp-pattern.
perlancar <perlancar@cpan.org>
This software is copyright (c) 2018, 2016 by perlancar@cpan.org.
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.
To install Regexp::Pattern, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Regexp::Pattern
CPAN shell
perl -MCPAN -e shell install Regexp::Pattern
For more information on module installation, please visit the detailed CPAN module installation guide.