NAME
    Regexp::Pattern - Collection of regexp patterns

SPECIFICATION VERSION
    0.2.0

VERSION
    This document describes version 0.2.1 of Regexp::Pattern (from Perl
    distribution Regexp-Pattern), released on 2018-03-24.

SYNOPSIS
    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
         ),
     );

DESCRIPTION
    Regexp::Pattern is a convention for organizing reusable regexp patterns
    in modules, as well as framework for some convenience in using those
    patterns in your program.

  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/.../,
             tags => ['A','B'],
         },
 
         # 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'],
         },
     );

    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).

    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".

    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 => <<_,

    I'm not sure whether PAUSE allows digit for the first letter. For safety
    I'm assuming no.

    _ }

  Using a Regexp::Pattern::* module
   Standalone
    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/;

   Via Regexp::Pattern, sub interface
    Regexp::Pattern (this module) also provides "re()" function to help
    retrieve the regexp pattern. See "re" for more details.

   Via Regexp::Pattern, hash interface
    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.

    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).

FUNCTIONS
  re
    Exported by default. Get a regexp pattern by name from a
    "Regexp::Pattern::*" module.

    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()".

    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::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.

    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.

AUTHOR
    perlancar <perlancar@cpan.org>

COPYRIGHT AND LICENSE
    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.