# NAME

File::stat::Extra - An extension of the File::stat module, provides additional methods.

# VERSION

version 0.002

# SYNOPSIS

    use File::stat::Extra;

    $st = lstat($file) or die "No $file: $!";

    if ($st->isLink) {
        print "$file is a symbolic link";
    }

    if (-x $st) {
        print "$file is executable";
    }

    use Fcntl 'S_IRUSR';
    if ( $st->cando(S_IRUSR, 1) ) {
        print "My effective uid can read $file";
    }

    if ($st == stat($file)) {
        printf "%s and $file are the same", $st->file;
    }

# DESCRIPTION

This module's default exports override the core stat() and lstat()
functions, replacing them with versions that return
`File::stat::Extra` objects when called in scalar context. In list
context the same 13 item list is returned as with the original `stat`
and `lstat` functions.

`File::stat::Extra` is an extension of the [File::stat](https://metacpan.org/pod/File::stat)
module.

- Returns non-object result in list context.
- You can now pass in bare file handles to `stat` and `lstat` under `use strict`.
- File tests `-t` `-T`, and `-B` have been implemented too.
- Convenience functions `filetype` and `permissions` for direct access to filetype and permission parts of the mode field.
- Named access to common file tests (`isRegular` / `isFile`, `isDir`, `isLink`, `isBlock`, `isChar`, `isFIFO` / `isPipe`, `isSocket`).
- Access to the name of the file / file handle used for the stat (`file`, `abs_file` / `target`).

# FUNCTIONS

## stat( _FILEHANDLE_ )

## stat( _DIRHANDLE_ )

## stat( _EXPR_ )

## lstat( _FILEHANDLE_ )

## lstat( _DIRHANDLE_ )

## lstat( _EXPR_ )

When called in list context, these functions behave as the original
`stat` and `lstat` functions, returning the 13 element `stat` list.
When called in scalar context, a `File::stat::Extra` object is
returned with the methods as outlined below.

# METHODS

## dev

## ino

## mode

## nlink

## uid

## gid

## rdev

## size

## atime

## mtime

## ctime

## blksize

## blocks

These methods provide named acced to the same fields in the original
`stat` result. Just like the original [File::stat](https://metacpan.org/pod/File::stat).

## cando( _ACCESS_, _EFFECTIVE_ )

Interprets the `mode`, `uid` and `gid` fields, and returns whether
or not the current process would be allowed the specified access.

_ACCESS_ is one of `S_IRUSR`, `S_IWUSR` or `S_IXUSR` from the
[Fcntl](https://metacpan.org/pod/Fcntl) module, and _EFFECTIVE_ indicates whether to use
effective (true) or real (false) ids.

## file

Returns the full path to the original file (or the filehandle) on which
`stat` or `lstat` was called.

Note: Symlinks are not resolved. And, like `rel2abs`, neither are
`x/../y` constructs. Use the `abs_file` / `target` methods to
resolve these too.

## abs\_file

## target

Returns the absolute path of the file. In case of a file handle, this is returned unaltered.

## permissions

Returns just the permissions (including setuid/setgid/sticky bits) of the `mode` stat field.

## filetype

Returns just the filetype of the `mode` stat field.

## isFile

## isRegular

Returns true if the file is a regular file (same as -f file test).

## isDir

Returns true if the file is a directory (same as -d file test).

## isLink

Returns true if the file is a symbolic link (same as -l file test).

Note: Only relevant when `lstat` was used!

## isBlock

Returns true if the file is a block special file (same as -b file test).

## isChar

Returns true if the file is a character special file (same as -c file test).

## isFIFO

## isPipe

Returns true if the file is a FIFO file or, in case of a file handle, a pipe  (same as -p file test).

## isSocket

Returns true if the file is a socket file (same as -S file test).

## -X operator

You can use the file test operators on the `File::stat::Extra` object
just as you would on a file (handle). However, instead of querying the
file system, these operators will use the information from the
object itself.

Note: in case of the special file tests `-t`, `-T`, and `-B`, the
file (handle) _is_ tested the _first_ time the operator is
used. After the first time, the initial result is re-used.

## Unary "" (stringification) and other operators

The unary "" operator is overloaded to return the the device and inode
numbers separated by a `.` (`_dev_._ino_`). This yields a uniqe file identifier.

All other operators are automagically generated based on this
representation, meaning you can easily compare two
`File::stat::Extra` objects to see if they are the same (hardlinked)
file.

# WARNINGS

When a file (handle) can not be (l)stat-ed, a warning `Unable to
stat: %s`. To disable this warning, specify

    no warnings "File::stat::Extra";

The following warnings are inhereted from `File::stat`, these can all
be disabled with

    no warnings "File::stat";

- File::stat ignores use filetest 'access'

    You have tried to use one of the `-rwxRWX` filetests with `use
    filetest 'access'` in effect. `File::stat` will ignore the pragma, and
    just use the information in the `mode` member as usual.

- File::stat ignores VMS ACLs

    VMS systems have a permissions structure that cannot be completely
    represented in a stat buffer, and unlike on other systems the builtin
    filetest operators respect this. The `File::stat` overloads, however,
    do not, since the information required is not available.

# BUGS

Please report any bugs or feature requests on the bugtracker website
https://github.com/HayoBaan/File-stat-Extra/issues

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.

# COMPATIBILITY

As with [File::stat](https://metacpan.org/pod/File::stat), you can no longer use the implicit `$_` or the
special filehandle `_` with this module's versions of `stat` and
`lstat`.

Currently `File::stat::Extra` only provides an object interface, the
[File::stat](https://metacpan.org/pod/File::stat) `$st_*` variables and `st_cando` funtion are not
available. This may change in a future version of this module.

# SEE ALSO

- [File::stat](https://metacpan.org/pod/File::stat) for the module for which `File::stat::Extra` is the extension.
- [stat](https://metacpan.org/pod/stat) and [lstat](https://metacpan.org/pod/lstat) for the original `stat` and `lstat` functions.

# AUTHOR

Hayo Baan <info@hayobaan.nl>

# COPYRIGHT AND LICENSE

This software is copyright (c) 2015 by Hayo Baan.

This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.
