NAME
Regexp::Pattern - Collection of regexp patterns
SPECIFICATION VERSION
0.1.0
VERSION
This document describes version 0.1.4 of Regexp::Pattern (from Perl distribution Regexp-Pattern), released on 2016-12-31.
SYNOPSIS
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"});DESCRIPTION
Regexp::Pattern is a convention for organizing reusable regexp patterns in modules.
Structure of an example Regexp::Pattern::* module
package Regexp::Pattern::Example;
our %RE = (
# the minimum spec
re1 => { pat => qr/\d{3}-\d{4}/ },
# more complete spec
re2 => {
summary => 'This is regexp for blah',
description => <<'_',
A longer description.
_
pat => qr/.../,
},
# 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,
},
},
},
);A Regexp::Pattern::* module must declare a package global hash variable named %RE. Hash keys are pattern names, hash values are defhashes (see DefHash). At the minimum, it should be:
{ pat => qr/.../ },Regexp pattern should be written as qr// literal, or (less desirable) as a string literal. Regexp should not be anchored (qr/^...$/) unless necessary. Regexp should not contain capture groups unless necessary.
Using a Regexp::Pattern::* module
A Regexp::Pattern::* module can be used manually by itself, as it contains simply 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.
FUNCTIONS
re
Exported by default. Get a regexp pattern by name from a Regexp::Pattern::* module.
Syntax:
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().
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).
HOMEPAGE
Please visit the project's homepage at https://metacpan.org/release/Regexp-Pattern.
SOURCE
Source repository is at https://github.com/perlancar/perl-Regexp-Pattern.
BUGS
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.
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 re() function.
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.
AUTHOR
perlancar <perlancar@cpan.org>
COPYRIGHT AND LICENSE
This software is copyright (c) 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.