/ 
Sah-Schemas-Path-0.030
River stage one • 1 direct dependent • 1 total dependent
/ Sah::Schemas::Path

NAME

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

VERSION

This document describes version 0.030 of Sah::Schemas::Path (from Perl distribution Sah-Schemas-Path), released on 2024-01-08.

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