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.

       App::RegexpPatternUtils

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.