=begin pod

=head1 NAME

path-utils - low-level path introspection utility functions

=head1 SYNOPSIS

=begin code :lang<raku>
use path-utils;  # export all subs

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

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

=head1 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 C<int> and native C<num>
values, which can be used in conditions without any problems, just
don't expect them to be upgraded to C<Bool> values.

Also note that all functions (except C<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.

=head1 SELECTIVE IMPORTING

=begin code :lang<raku>
use path-utils <path-exists>;  # only export sub path-exists
=end code

By default all utility functions are exported.  But you can limit this to
the functions you actually need by specifying the names in the C<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 C<use> command is executed.

=begin code :lang<raku>
use path-utils <path-exists:alive>;  # export "path-exists" as "alive"

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

=head1 EXPORTED SUBROUTINES

In alphabetical order:

=head2 path-accessed

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

=head2 path-blocks

Returns the number of filesystem blocks allocated for this path.

=head2 path-block-size

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

=head2 path-created

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

=head2 path-device-number

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

=head2 path-exists

Returns 1 if paths exists, 0 if not.

=head2 path-filesize

Returns the size of the path in bytes.

=head2 path-gid

Returns the numeric group id of the path.

=head2 path-git-repo

Returns the path of the Git repository associated with the B<absolute> path
given, or returns the empty string if the path is not part inside a Git
repository.  Note that this not mean that the file is actually part of that
Git repository: it merely indicates that the returned path returned C<True>
with C<path-is-git-repo>.

=head2  path-hard-links

Returns the number of hard links to the path.

=head2 path-has-setgid

The path has the SETGID bit set in its attributes.

=head2 path-inode

Returns the inode of the path.

=head2 path-is-device

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

=head2 path-is-directory

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

=head2 path-is-empty

Returns 1 if the path has a filesize of 0.

=head2 path-is-executable

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

=head2 path-is-github-repo

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

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

=head2 path-is-group-executable

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

=head2 path-is-group-readable

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

=head2 path-is-group-writable

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

=head2 path-is-moarvm

Returns 1 if path is a C<MoarVM> bytecode file (either from core, or
from a precompiled module file), 0 if not.

=head2 path-is-owned-by-user

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

=head2 path-is-owned-by-group

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

=head2 path-is-owner-executable

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

=head2 path-is-owner-readable

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

=head2 path-is-owner-writable

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

=head2 path-is-pdf

Returns 1 if path looks a C<PDF> file, judging by its magic number,
0 if not.

=head2 path-is-readable

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

=head2 path-is-regular-file

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

=head2 path-is-sticky

The path has the STICKY bit set in its attributes.

=head2 path-is-sqlite

Returns 1 if path is a C<SQLite> database file.

=head2 path-is-symbolic-link

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

=head2 path-is-text

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

=head2 path-is-world-executable

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

=head2 path-is-world-readable

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

=head2 path-is-world-writable

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

=head2 path-is-writable

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

=head2 path-meta-modified

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

=head2 path-mode

Returns the numeric unix-style mode.

=head2 path-modified

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

=head2 path-uid

Returns the numeric user id of the path.

=head1 AUTHOR

Elizabeth Mattijsen <liz@raku.rocks>

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
L<small sponsorship|https://github.com/sponsors/lizmat/>  would mean a great
deal to me!

=head1 COPYRIGHT AND LICENSE

Copyright 2022, 2023, 2024, 2025, 2026 Elizabeth Mattijsen

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

=end pod

# vim: expandtab shiftwidth=4
