NAME
    Sah::Schemas::Perl - Sah schemas related to Perl

VERSION
    This document describes version 0.047 of Sah::Schemas::Perl (from Perl
    distribution Sah-Schemas-Perl), released on 2023-01-14.

SAH SCHEMAS
    The following schemas are included in this distribution:

    *   perl::distname

        Perl distribution name, e.g. Foo-Bar.

        This is a schema you can use when you want to accept a Perl
        distribution name, e.g. "WWW-Mechanize". It offers basic checking of
        syntax as well as a couple of conveniences. First, it offers
        completion from list of locally installed Perl distribution. Second,
        it contains coercion rule so you can also input "Foo::Bar",
        "Foo/Bar", "Foo/Bar.pm", or even 'Foo.Bar' and it will be normalized
        into "Foo-Bar".

        To see this schema in action on the CLI, you can try e.g. the
        "dist-has-deb" script from App::DistUtils and activate its tab
        completion (see its manpage for more details). Then on the CLI try
        typing:

         % dist-has-deb WWW-<tab>
         % dist-has-deb dzp/<tab>

        Note that this schema does not check that the Perl disribution
        exists on CPAN or is installed locally. To check that, use the
        "perl::distname::installed" schema. And there's also a
        "perl::distname::not_installed" schema.

    *   perl::distname::default_this_dist

        Perl distribution name, defaults to "this distribution".

        See App::ThisDist's "this_dist()" for more details on how "this
        distribution" is determined. Note that "App::ThisDist" is not added
        as dependency automatically; you will have to add it manually.

    *   perl::distname_with_optional_ver

        Perl distribution name (e.g. Foo-Bar) with optional version number
        suffix (e.g. Foo-Bar@0.001).

        For convenience (particularly in CLI with tab completion), you can
        input one of:

         Foo::Bar
         Foo/Bar
         Foo/Bar.pm
         Foo.Bar

        and it will be coerced into Foo-Bar form.

    *   perl::distname_with_ver

        Perl distribution name with version number suffix, e.g.
        Foo-Bar@0.001.

        For convenience (particularly in CLI with tab completion), you can
        input one of:

         Foo::Bar@1.23
         Foo/Bar@1.23
         Foo/Bar.pm@1.23
         Foo.Bar@1.23

        and it will be coerced into Foo-Bar form.

    *   perl::filename

        Filename of Perl script/module/POD, e.g. /path/Foo/Bar.pm.

        Use this schema if you want to accept a filesystem path containing
        Perl script, module, or POD. The value of this schema is in the
        convenience of CLI completion, as well as coercion from script or
        module name.

        String containing filename of a Perl script or module or POD. For
        convenience, when value is in the form of:

         Foo
         Foo.pm
         Foo.pod
         Foo::Bar
         Foo/Bar
         Foo/Bar.pm
         Foo/Bar.pod

        and a matching .pod or .pm file is found in @INC, then it will be
        coerced (converted) into the path of that .pod/.pm file, e.g.:

         /home/ujang/perl5/perlbrew/perls/perl-5.24.0/lib/site_perl/5.24.0/Foo/Bar.pm
         lib/Foo/Bar.pod

        To prevent such coercion, you can use prefixing path, e.g.:

         ./Foo::Bar
         ../Foo/Bar
         /path/to/Foo/Bar

        This schema comes with convenience completion too.

    *   perl::funcname

        Perl function name, either qualified with package name (e.g.
        Foo::subname) or unqualified (e.g. subname).

        Currently function name is restricted to this regex:

         \A[A-Za-z_][A-Za-z_0-9]*\z

        Function name can be qualified (prefixed) by a package name, which
        is restricted to this regex:

         [A-Za-z_][A-Za-z_0-9]*(::[A-Za-z_0-9]+)*

    *   perl::identifier::qualified_ascii

        Qualified identifier in Perl, without "use utf8" in effect.

    *   perl::identifier::qualified_unicode

        Unqualified identifier in Perl, with "use utf8" in effect.

    *   perl::identifier::unqualified_ascii

        Unqualified identifier in Perl, without "use utf8" in effect.

    *   perl::identifier::unqualified_unicode

        Unqualified identifier in Perl, with "use utf8" in effect.

    *   perl::modargs

        Shorter alias for perl::modname_with_optional_args.

    *   perl::modname

        Perl module name, e.g. Foo::Bar.

        This is a schema you can use when you want to accept a Perl module
        name. It offers basic checking of syntax as well as a couple of
        conveniences. First, it offers completion from list of locally
        installed Perl modules. Second, it contains coercion rule so you can
        also input "Foo-Bar", "Foo/Bar", "Foo/Bar.pm" or even 'Foo.Bar' and
        it will be normalized into "Foo::Bar".

        To see this schema in action on the CLI, you can try e.g. the
        "pmless" script from App::PMUtils and activate its tab completion
        (see its manpage for more details). Then on the CLI try typing:

         % pmless M/<tab>
         % pmless dzp/<tab>
         % pmless Module/List/Wildcard
         % pmless Module::List::Wildcard

        Note that this schema does not check that the Perl module exists or
        is installed locally. To check that, use the
        "perl::modname::installed" schema. And there's also a
        "perl::modname::not_installed" schema.

    *   perl::modname::default_this_mod

        Perl module, defaults to "this module".

        See App::ThisDist's "this_mod()" for more details on how "this
        module" is determined. Note that "App::ThisDist" is not added as
        dependency automatically; you will have to add it manually.

    *   perl::modname::installed

        Name of a Perl module that is installed locally.

        This schema is based on the "perl::modname" schema with an
        additional check that the perl module is installed locally. Checking
        is done using Module::Installed::Tiny. This check fetches the source
        code of the module from filesystem or %INC hooks, but does not
        actually load/execute the code.

    *   perl::modname::not_installed

        Name of a Perl module that is not installed locally.

        This schema is based on the "perl::modname" schema with an
        additional check that the perl module is not installed locally.
        Checking is done using Module::Installed::Tiny. This check fetches
        the source code of the module from filesystem or %INC hooks, but
        does not actually load/execute the code.

    *   perl::modname_or_prefix

        Perl module name (e.g. Foo::Bar) or prefix (e.g. Foo::Bar::).

        Contains coercion rule so inputing "Foo-Bar" or "Foo/Bar" will be
        normalized to "Foo::Bar" while inputing "Foo-Bar-" or "Foo/Bar/"
        will be normalized to "Foo::Bar::"

        See also: "perl::modname" and "perl::modprefix".

    *   perl::modname_pm

        Perl module name in Foo/Bar.pm form.

        This is just like the "perl::modname" schema except that instead of
        to "Foo::Bar", it normalizes to "Foo/Bar.pm".

    *   perl::modname_with_optional_args

        Perl module name (e.g. Foo::Bar) with optional arguments (e.g.
        Foo::Bar=arg1,arg2).

        Perl module name with optional arguments which will be used as
        import arguments, just like the "-MMODULE=ARGS" shortcut that "perl"
        provides. Examples:

         Foo
         Foo::Bar
         Foo::Bar=arg1,arg2

        See also: "perl::modname". A two-element array from (coercible from
        JSON string) is also allowed:

         ["Foo::Bar", \@args]

    *   perl::modname_with_optional_ver

        Perl module name (e.g. Foo::Bar) with optional version number suffix
        (e.g. Foo::Bar@0.001).

    *   perl::modname_with_ver

        Perl module name with version number suffix, e.g. Foo::Bar@0.001.

    *   perl::modnames

        Array of Perl module names, e.g. ["Foo::Bar", "Baz"].

        Array of Perl module names, where each element is of "perl::modname"
        schema, e.g. "Foo", "Foo::Bar".

        Contains coercion rule that expands wildcard, so you can specify:

         Module::P*

        and it will be expanded to e.g.:

         ["Module::Patch", "Module::Path", "Module::Pluggable"]

        The wildcard syntax supports jokers ("?", "*", "**"), brackets
        ("[abc]"), and braces ("{one,two}"). See Module::List::Wildcard for
        more details.

    *   perl::modprefix

        Perl module prefix, e.g. Foo::Bar::.

        Perl module prefix, e.g. "Foo::Bar::". An empty prefix ('') is also
        allowed.

        Contains coercion rule so you can also input:

         Foo-Bar
         Foo-Bar-
         Foo-Bar
         Foo/Bar
         Foo/Bar/
         Foo::Bar

        and it will be normalized into "Foo::Bar::".

    *   perl::modprefixes

        Perl module prefixes, e.g. ["", "Foo::", "Foo::Bar::"].

        Array of Perl module prefixes, where each element is of
        "perl::modprefix" schema, e.g. "Foo::", "Foo::Bar::".

        Contains coercion rule that expands wildcard, so you can specify:

         Module::C*

        and it will be expanded to e.g.:

         ["Module::CPANTS::", "Module::CPANfile::", "Module::CheckVersion::", "Module::CoreList::"]

        The wildcard syntax supports jokers ("?", '*") and brackets
        ("[abc]"). See the "unix` type of wildcard in Regexp::Wildcards,
        which this coercion rule uses.

    *   perl::module::release::version

        Expression to select module release.

    *   perl::module::release::versions

    *   perl::pm_filename

        A .pm filename, e.g. /path/Foo.pm.

        Use this schema if you want to accept a filesystem path containing
        Perl module. The value of this schema is in the convenience of CLI
        completion, as well as coercion from module name.

        String containing filename of a Perl module. For convenience, when
        value is in the form of:

         Foo
         Foo.pm
         Foo::Bar
         Foo/Bar
         Foo/Bar.pm

        and a matching .pm file is found in @INC, then it will be coerced
        (converted) into the path of that .pm file, e.g.:

         /home/ujang/perl5/perlbrew/perls/perl-5.24.0/lib/site_perl/5.24.0/Foo/Bar.pm

        To prevent such coercion, you can use prefixing path, e.g.:

         ./Foo::Bar
         ../Foo/Bar
         /path/to/Foo/Bar

        This schema comes with convenience completion too.

    *   perl::pod_filename

        A .pod filename, e.g. /path/Foo.pod.

        Use this schema if you want to accept a filesystem path containing
        Perl POD. The value of this schema is in the convenience of CLI
        completion, as well as coercion from POD name.

        String containing filename of a Perl .pod file. For convenience,
        when value is in the form of:

         Foo
         Foo.pod
         Foo::Bar
         Foo/Bar
         Foo/Bar.pod

        and a matching .pod file is found in @INC, then it will be coerced
        (converted) into the filesystem path of that .pod file, e.g.:

         /home/ujang/perl5/perlbrew/perls/perl-5.24.0/lib/site_perl/5.24.0/Foo/Bar.pod

        To prevent such coercion, you can use prefixing path, e.g.:

         ./Foo::Bar
         ../Foo/Bar
         /path/to/Foo/Bar

        This schema comes with convenience completion too.

    *   perl::pod_or_pm_filename

        A .pod or .pm filename, e.g. /path/Foo.pm or /path/Bar/Baz.pod.

        String containing filename of a Perl POD or module. For convenience,
        when value is in the form of:

         Foo
         Foo.pod
         Foo.pm
         Foo::Bar
         Foo/Bar
         Foo/Bar.pod
         Foo/Bar.pm

        and a matching .pod or .pm file is found in @INC, then it will be
        coerced (converted) into the path of that .pod/.pm file, e.g.:

         /home/ujang/perl5/perlbrew/perls/perl-5.24.0/lib/site_perl/5.24.0/Foo/Bar.pm
         lib/Foo/Bar.pod

        To prevent such coercion, you can use prefixing path, e.g.:

         ./Foo::Bar
         ../Foo/Bar
         /path/to/Foo/Bar

        This schema comes with convenience completion too.

        This schema is like another schema "perl::filename" except that .pod
        is prioritized over .pm. If both "Foo.pm" and "Foo.pod" are found in
        @INC, the path to "Foo.pod" will be returned.

    *   perl::podname

        Perl POD name, e.g. Moose::Cookbook.

        Perl POD name, e.g. "Config", "Some::Other::POD".

        Basically the same as "perl::modname", but with a different
        completion.

    *   perl::qualified_funcname

        Perl function name qualified with a package name, e.g. Foo::subname.

        Currently function name is restricted to this regex:

         \A[A-Za-z_][A-Za-z_0-9]*\z

        and package name is restricted to this regex:

         [A-Za-z_][A-Za-z_0-9]*(::[A-Za-z_0-9]+)*

        This schema includes syntax validity check only; it does not check
        whether the function actually exists.

    *   perl::release::version

        One of known released versions of perl (e.g. 5.010 or 5.10.0).

        Use this schema if you want to accept one of the known released
        versions of perl.

        The list of releases of perl is retrieved from the installed core
        module Module::CoreList during runtime as well as the one used
        during build. One of both those Module::CoreList instances might not
        be the latest, so this list might not be up-to-date. To ensure that
        the list is complete, you will need to keep your copy of
        Module::CoreList up-to-date.

        The list of version numbers include numified version (which,
        unfortunately, collapses trailing zeros, e.g. 5.010000 into 5.010)
        as well as the x.y.z version (e.g. 5.10.0).

    *   perl::unqualified_funcname

        Perl function name which must not be qualified with a package name,
        e.g. subname.

        Currently function name is restricted to this regex:

         \A[A-Za-z_][A-Za-z_0-9]*\z

        This schema includes syntax validity check only; it does not check
        whether the function actually exists.

        This schema includes syntax validity check only; it does not check
        whether the function actually exists.

    *   perl::version

        Perl version object.

        Use this schema if you want to accept a version object (see
        version). Coercion from string is provided.

HOMEPAGE
    Please visit the project's homepage at
    <https://metacpan.org/release/Sah-Schemas-Perl>.

SOURCE
    Source repository is at
    <https://github.com/perlancar/perl-Sah-Schemas-Perl>.

SEE ALSO
    Sah - schema specification

    Data::Sah - Perl implementation of Sah

AUTHOR
    perlancar <perlancar@cpan.org>

CONTRIBUTING
    To contribute, you can send patches by email/via RT, or send pull
    requests on GitHub.

    Most of the time, you don't need to build the distribution yourself. You
    can simply modify the code, then test via:

     % prove -l

    If you want to build the distribution (e.g. to try to install it locally
    on your system), you can install Dist::Zilla,
    Dist::Zilla::PluginBundle::Author::PERLANCAR,
    Pod::Weaver::PluginBundle::Author::PERLANCAR, and sometimes one or two
    other Dist::Zilla- and/or Pod::Weaver plugins. Any additional steps
    required beyond that are considered a bug and can be reported to me.

COPYRIGHT AND LICENSE
    This software is copyright (c) 2023, 2022, 2021, 2020, 2019, 2018, 2017,
    2016 by perlancar <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.

BUGS
    Please report any bugs or feature requests on the bugtracker website
    <https://rt.cpan.org/Public/Dist/Display.html?Name=Sah-Schemas-Perl>

    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.

