NAME

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

VERSION

This document describes version 0.037 of Sah::Schemas::Perl (from Perl distribution Sah-Schemas-Perl), released on 2021-07-19.

SAH SCHEMAS

perl::distname

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

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

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

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.

AUTHOR

perlancar <perlancar@cpan.org>

COPYRIGHT AND LICENSE

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 Sah::Schemas::Perl, copy and paste the appropriate command in to your terminal.

cpanm

cpanm Sah::Schemas::Perl

CPAN shell

perl -MCPAN -e shell
install Sah::Schemas::Perl

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)