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

VERSION
    This document describes version 0.031 of Sah::SchemaBundle::Path (from
    Perl distribution Sah-SchemaBundle-Path), released on 2024-02-16.

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. in a "delete-files-in" script). It is safer to use
        this schema when performing a non-destructive action (e.g. "ls")
        and/or operate in dry-run mode by default.

    *   dirname::default_curdir_abs

        Directory name, default to current directory (absolutified).

        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. in a "delete-files-in" script). It is safer to use
        this schema when performing a non-destructive action (e.g. "ls")
        and/or operate in dry-run mode by default.

    *   dirname::default_only_subdir_in_curdir

        Directory name, defaults to only subdirectory in current directory
        (if there is one).

        This is like the "dirname" schema but with a default value of "only
        subdirectory in the current directory". That is, if the current
        directory has a single subdirectory and nothing else.

        Difference with "dirname::default_only_subdir_not_file_in_subdir"
        schema: the other schema ignores plain files. Thus, if a directory
        only contains "file1" and "subdir1", then that other schema will
        return "subdir1" but this schema will not return a default value.

        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. in a "delete-files-in" script). It is safer to use
        this schema when performing a non-destructive action (e.g. "ls")
        and/or operate in dry-run mode by default.

    *   dirname::default_only_subdir_not_file_in_curdir

        Directory name, defaults to only subdirectory in current directory
        (if there is one) (files ignored).

        This is like the "dirname" schema but with a default value of "only
        subdirectory in the current directory". That is, if the current
        directory has a single subdirectory and nothing else (plain files
        are ignored).

        Difference with "dirname::default_only_subdir_in_subdir" schema: the
        other schema does not ignore plain files. Thus, if a directory only
        contains "file1" and "subdir1", then that other schema will not
        return "subdir1" but this schema will.

        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. in a "delete-files-in" script). It is safer to use
        this schema when performing 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::exists::default_only_subdir_in_curdir

        Directory name, must exist on the filesystem, defaults to only
        subdirectory in current directory (if there is one).

        This is like the "dirname::exists" schema but with a default value
        of "only subdirectory in the current directory". That is, if the
        current directory has a single subdirectory and nothing else.

        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. in a "delete-files-in" script). It is safer to use
        this schema when performing a non-destructive action (e.g. "ls")
        and/or operate in dry-run mode by default.

    *   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::basename

        Filesystem base directory name on a Unix system.

        This is like the "dirname::unix" schema but not allowing parent
        directory parts. Difference with "filename::unix::basename" and
        "pathname::unix::basename": the completion rule.

    *   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::default_newest_file_in_curdir

        File name, defaults to newest file in current directory (if there is
        one).

        This is like the "filename" schema but with a default value of
        newest plain file in the current directory. If current directory
        does not contain any file, no default will be given.

        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. in a "delete-file" script). It is safer to use
        this schema when performing a non-destructive action (e.g.
        "checksum") and/or operate in dry-run mode by default.

    *   filename::default_only_file_in_curdir

        File name, defaults to only file in current directory (if there is
        one).

        This is like the "filename" schema but with a default value of "only
        file in the current directory". That is, if the current directory
        has a single plain file and nothing else.

        Difference with "filename::default_only_file_not_subdir_in_subdir"
        schema: the other schema ignores subdirectories. Thus, if a
        directory only contains "file1" and "subdir1", then that other
        schema will return "file1" but this schema will not return a default
        value.

        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. in a "delete-file" script). It is safer to use
        this schema when performing a non-destructive action (e.g.
        "checksum") and/or operate in dry-run mode by default.

    *   filename::default_only_file_not_dir_in_curdir

        File name, defaults to only file in current directory (if there is
        one) (subdirectories ignored).

        This is like the "filename" schema but with a default value of "only
        file in the current directory". That is, if the current directory
        has a single plain file and nothing else (subdirectories are
        ignored).

        Difference with "filename::default_only_file_in_subdir" schema: the
        other schema does not ignore subdirectories. Thus, if a directory
        only contains "file1" and "subdir1", then that other schema will not
        return "file1" but this schema will.

        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. in a "delete-file" script). It is safer to use
        this schema when performing a non-destructive action (e.g.
        "checksum") and/or operate in dry-run mode by default.

    *   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::exists::default_only_file_in_curdir

        File name, must exist on the filesystem, defaults to only file in
        current directory (if there is one).

        This is like the "filename::exists" schema but with a default value
        of "only file in the current directory". That is, if the current
        directory has a single plain file and nothing else.

        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. in a "delete-file" script). It is safer to use
        this schema when performing a non-destructive action (e.g.
        "checksum") and/or operate in dry-run mode by default.

    *   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::basename

        Filesystem base file name on a Unix system.

        This is like the "filename::unix" schema but not allowing directory
        parts. Difference with "dirname::unix::basename" and
        "pathname::unix::basename": the completion rule.

    *   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::basename

        Filesystem base path name on a Unix system.

        This is like the "filename::unix" schema but not allowing directory
        parts. Difference with "dirname::unix::basename" and
        "filename::unix::basename": the completion rule.

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

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.

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

SOURCE
    Source repository is at
    <https://github.com/perlancar/perl-Sah-SchemaBundle-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) 2024, 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-SchemaBundle-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.