Help language development. Donate to The Perl Foundation

path-utils zef:lizmat last updated on 2022-11-14

NAME

path-utils - low-level path introspection utility functions

SYNOPSIS

use path-utils;  # export all subs

use path-utils <path-exists>;  # only export sub path-exists

say path-exists($filename);  0 or 1

DESCRIPTION

path-utils provides a number of low-level path introspection utility functions for those cases where you're interested in performance, rather than functionality.

All subroutines take a (native) string as the only argument.

Note that these functions only return native int and native num values, which can be used in conditions without any problems, just don't expect them to be upgraded to Bool values.

Also note that all functions (except path-exists) expect the path to exist. An exception will be thrown if the path does not exist. The reason for this is that in situations where you are already sure a path exists, there is no point checking for its existence again if you e.g. would like to know its size.

SELECTIVE IMPORTING

use path-utils <path-exists>;  # only export sub path-exists

By default all utility functions are exported. But you can limit this to the functions you actually need by specifying the names in the use statement.

To prevent name collisions and/or import any subroutine with a more memorable name, one can use the "original-name:known-as" syntax. A semi-colon in a specified string indicates the name by which the subroutine is known in this distribution, followed by the name with which it will be known in the lexical context in which the use command is executed.

use path-utils <path-exists:alive>;  # export "path-exists" as "alive"

say alive "/etc/passwd";  # 1 if on Unixy, 0 on Windows

EXPORTED SUBROUTINES

In alphabetical order:

path-accessed

Returns number of seconds since epoch as a num when path was last accessed.

path-blocks

Returns the number of filesystem blocks allocated for this path.

path-block-size

Returns the preferred I/O size in bytes for interacting wuth the path.

path-created

Returns number of seconds since epoch as a num when path was created.

path-device-number

Returns the device number of the filesystem on which the path resides.

path-exists

Returns 1 if paths exists, 0 if not.

path-filesize

Returns the size of the path in bytes.

path-gid

Returns the numeric group id of the path.

path-hard-links

Returns the number of hard links to the path.

path-has-setgid

The path has the SETGID bit set in its attributes.

path-inode

Returns the inode of the path.

path-is-device

Returns 1 if path is a device, 0 if not.

path-is-directory

Returns 1 if path is a directory, 0 if not.

path-is-empty

Returns 1 if the path has a filesize of 0.

path-is-executable

Returns a non-zero integer value if path is executable by the current user.

path-is-github-repo

Returns 1 if path appears to be the top directory in a GitHub repository (as recognized by having a .github directory in it).

path-is-git-repo

Returns 1 if path appears to be the top directory in a Git repository (as recognized by having a <.git> directory in it).

path-is-group-executable

Returns a non-zero integer value if path is executable by members of the group of the path.

path-is-group-readable

Returns a non-zero integer value if path is readable by members of the group of the path.

path-is-group-writable

Returns a non-zero integer value if path is writable by members of the group of the path.

path-is-owned-by-user

Returns a non-zero integer value if path is owned by the current user.

path-is-owned-by-group

Returns a non-zero integer value if path is owned by the group of the current user.

path-is-owner-executable

Returns a non-zero integer value if path is executable by the owner of the path.

path-is-owner-readable

Returns a non-zero integer value if path is readable by the owner of the path.

path-is-owner-writable

Returns a non-zero integer value if path is writable by the owner of the path.

path-is-readable

Returns a non-zero integer value if path is readable by the current user.

path-is-regular-file

Returns 1 if path is a regular file, 0 if not.

path-is-sticky

The path has the STICKY bit set in its attributes.

path-is-symbolic-link

Returns 1 if path is a symbolic link, 0 if not.

path-is-text

Returns 1 if path is looks like it containes text, 0 if not.

path-is-world-executable

Returns a non-zero integer value if path is executable by anybody.

path-is-world-readable

Returns a non-zero integer value if path is readable by anybody.

path-is-world-writable

Returns a non-zero integer value if path is writable by any body.

path-is-writable

Returns a non-zero integer value if path is writable by the current user.

path-meta-modified

Returns number of seconds since epoch as a num when the meta information of the path was last modified.

path-mode

Returns the numeric unix-style mode.

path-modified

Returns number of seconds since epoch as a num when path was last modified.

path-uid

Returns the numeric user id of the path.

AUTHOR

Elizabeth Mattijsen [email protected]

Source can be located at: https://github.com/lizmat/path-utils . Comments and Pull Requests are welcome.

If you like this module, or what I’m doing more generally, committing to a small sponsorship would mean a great deal to me!

COPYRIGHT AND LICENSE

Copyright 2022 Elizabeth Mattijsen

This library is free software; you can redistribute it and/or modify it under the Artistic License 2.0.