NAME
    Sah::Schemas::Path - Schemas related to filesystem path

VERSION
    This document describes version 0.021 of Sah::Schemas::Path (from Perl
    distribution Sah-Schemas-Path), released on 2023-10-29.

DESCRIPTION
    This distribution includes several schemas you can use if you want to
    accept filename/dirname/pathname.

    Some general guidelines:

    "pathname" should be your first choice. But if you only want to accept
    directory name, you can use "dirname" instead. And if you only want to
    accept file name and not directory, you can use "filename".

    "filename", "dirname", "pathname" are basically the same; they differ in
    the completion they provide, i.e. "dirname" offers completion of only
    directory names.

    Use "filename::unix", "dirname::unix", "pathname::unix" only if you want
    to accept Unix-style path. These schemas contain additional checks that
    are specific to Unix filesystem.

    Use "filename::exists", "dirname::exists", "pathname::exists" if you
    want to accept an existing path. For example in a utility/routine to
    rename or process files. On the contrary, there are
    "filename::not_exists", "dirhname::not_exists", and
    "pathname::not_exists" if you want to accept non-existing path, e.g. in
    a utility/routine to create a new file.

SAH SCHEMAS
    The following schemas are included in this distribution:

    *   dirname

        Filesystem directory name.

        This schema is basically string with some checks and prefilters. Why
        use this schema instead of plain ol' str? Mainly to give you the
        ability to change tilde to user's home directory, e.g. "~/foo" into
        "/home/someuser/foo". Normally this expansion is done by a Unix
        shell, but sometimes your program receives an unexpanded path, e.g.
        when you get it from some config file.

        See also more OS-specific schemas like "dirname::unix", which adds
        some more checks (e.g. filename cannot contain forward slash and
        each component cannot be longer than 255 characters) and
        preprocessing (e.g. stripping extraneous slashes like "foo//bar"
        into "foo/bar".

        What's the difference between this schema and "filename"? The
        default completion rule. This schema's completion by default only
        includes directories.

    *   dirname::default_curdir

        Directory name, default to current directory.

        Note: be careful when using this schema for actions that are
        destructive, because a user can perform those actions without giving
        an argument (e.g. a "delete-files-in" script). It is safer to use
        this schema to perform a non=destructive action (e.g. "ls") and/or
        operate in dry-run mode by default.

    *   dirname::exists

        Directory name, must exist on filesystem.

        This is like the "dirname" schema but with an extra check that the
        path must already exist.

    *   dirname::not_exists

        Directory name, must not exist on filesystem.

        This is like the "dirname" schema but with an extra check that the
        path must not already exist.

    *   dirname::unix

        Filesystem directory name on a Unix system.

        This is like the "dirname" schema but with extra checks relevant to
        the Unix, (e.g. a path element cannot be longer than 255 characters)
        and prefilters (e.g. multipile consecutive slashes "//" will be
        normalized into a single one "/").

    *   dirname::unix::exists

        Unix directory name, must exist on filesystem.

        This is like the "dirname::unix" schema but with an extra check that
        the path must already exist.

    *   dirname::unix::not_exists

        Unix directory name, must exist on filesystem.

        This is like the "dirname::unix" schema but with an extra check that
        the path must not already exist.

    *   dirnames::exist

        List of directory names, all must exist on filesystem.

    *   filename

        Filesystem file name.

        This schema is basically string with some checks and prefilters. Why
        use this schema instead of plain ol' str? Mainly to give you the
        ability to change tilde to user's home directory, e.g. "~/foo.txt"
        into "/home/someuser/foo.txt". Normally this expansion is done by a
        Unix shell, but sometimes your program receives an unexpanded path,
        e.g. when you get it from some config file.

        See also more OS-specific schemas like "filename::unix", which adds
        some more checks (e.g. filename cannot contain forward slash and
        each component cannot be longer than 255 characters) and
        preprocessing (e.g. stripping extraneous slashes like "foo//bar"
        into "foo/bar".

        What's the difference between this schema and "dirname"? The default
        completion rule. "dirname"'s completion only includes directories
        and not files.

    *   filename::exists

        File name, must exist on filesystem.

        This is like the "filename" schema but with an extra check that the
        path must already exist.

    *   filename::not_exists

        File name, must not already exist on filesystem.

        This is like the "filename" schema but with an extra check that the
        path must not already exist.

    *   filename::unix

        Filesystem file name on a Unix system.

        This is like the "filename" schema but with extra checks relevant to
        the Unix, (e.g. a path element cannot be longer than 255 characters)
        and prefilters (e.g. multipile consecutive slashes "//" will be
        normalized into a single one "/").

    *   filename::unix::exists

        Unix file name, must exist on filesystem.

        This is like the "filename::unix" schema but with an extra check
        that the path must already exist.

    *   filename::unix::not_exists

        Unix file name, must not already exist on filesystem.

        This is like the "filename::unix" schema but with an extra check
        that the path must not already exist.

    *   filenames

        List of filesystem file names.

        Coerces from string by expanding the glob pattern in the string.

    *   filenames::exist

        List of file names, all must exist on filesystem.

    *   pathname

        Filesystem path name.

        This schema is basically string with some checks and prefilters. Why
        use this schema instead of plain ol' str? Mainly to give you the
        ability to change tilde to user's home directory, e.g. "~/foo" into
        "/home/someuser/foo". Normally this expansion is done by a Unix
        shell, but sometimes your program receives an unexpanded path, e.g.
        when you get it from some config file.

        See also more OS-specific schemas like "pathname::unix", which adds
        some more checks (e.g. pathname cannot contain forward slash and
        each component cannot be longer than 255 characters) and
        preprocessing (e.g. stripping extraneous slashes like "foo//bar"
        into "foo/bar".

        What's the difference between this schema and "filename" and
        "dirname"? The default completion rule. This schema's completion by
        default includes files as well as directories, while "dirname"'s
        only include directories.

    *   pathname::exists

        Path name, must exist on filesystem.

        This is like the "pathname" schema but with an extra check that the
        path must already exist.

    *   pathname::not_exists

        Path name, must not already exist on filesystem.

        This is like the "pathname" schema but with an extra check that the
        path must not already exist.

    *   pathname::unix

        Filesystem path name on a Unix system.

        This is like the "pathname" schema but with extra checks relevant to
        the Unix, (e.g. a path element cannot be longer than 255 characters)
        and prefilters (e.g. multipile consecutive slashes "//" will be
        normalized into a single one "/").

    *   pathname::unix::exists

        Unix path name, must exist on filesystem.

        This is like the "pathname::unix" schema but with an extra check
        that the path must already exist.

    *   pathname::unix::not_exists

        Unix path name, must not already exist on filesystem.

        This is like the "pathname::unix" schema but with an extra check
        that the path must not already exist.

    *   pathnames

        List of filesystem path names.

        Coerces from string by expanding the glob pattern in the string.

    *   pathnames::exist

        List of path names, all must exist on filesystem.

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

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

SEE ALSO
    Sah - schema specification

    Data::Sah - Perl implementation of Sah

AUTHOR
    perlancar <perlancar@cpan.org>

CONTRIBUTOR
    Gabor Szabo <gabor@szabgab.com>

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, 2020, 2019, 2018, 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-Path>

    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.

