NAME
    File::Stat::Moose - Status info for a file - Moose-based

SYNOPSIS
      use IO::File;
      use File::Stat::Moose;
      $fh = new IO::File '/etc/passwd';
      $st = new File::Stat::Moose file=>$fh;
      print "Size: ", $st->size, "\n";    # named field
      print "Blocks: ". $st->[12], "\n";  # numbered field

DESCRIPTION
    This class provides methods that returns status info for a file. It is
    the OO-style version of stat/lstat functions. It also throws an
    exception immediately after error is occured.

BASE CLASSES
    * Moose::Base

IMPORTS
    By default, the class does not export its symbols.

    use File::Stat::Moose 'stat', 'lstat';
        Imports stat and/or lstat functions.

    use File::Stat::Moose ':all';
        Imports all available symbols.

FIELDS
    file (ro, weak_ref)
        Contains the file for check. The field can hold file name or file
        handler or IO object.

    follow (ro)
        If the value is true and the *file* for check is symlink, then
        follow it than checking the symlink itself.

    dev (ro)
        ID of device containing file.

    ino (ro)
        inode number.

    mode (ro)
        Unix mode for file.

    nlink (ro)
        Number of hard links.

    uid (ro)
        User ID of owner.

    gid (ro)
        Group ID of owner.

    rdev (ro)
        Device ID (if special file).

    size (ro)
        Total size, in bytes.

    atime (ro)
        Time of last access.

    mtime (ro)
        Time of last modification.

    ctime (ro)
        Time of last status change.

    blksize (ro)
        Blocksize for filesystem I/O.

    blocks (ro)
        Number of blocks allocated.

CONSTRUCTORS
    new Creates the File::Stat::Moose object and calls stat method if the
        *file* field is defined and *follow* field is a true value or calls
        lstat method if the *file* field is defined and *follow* field is
        not a true value.

        If the *file* is symlink and the *follow* is true, it will check the
        file that it refers to. If the *follow* is false, it will check the
        symlink itself.

          $st = new File::Stat::Moose file=>'/etc/cdrom', follow=>1;
          print "Device: $st->rdev\n";  # check real device, not symlink itself  

        The object is dereferenced in array context to the array reference
        which contains the same values as core stat function output.

          $st = new File::Stat::Moose file=>'/etc/passwd';
          print "Size: $st->size\n";  # object's field
          print "Size: $st->[7]\n";   # array dereference

    File::Stat::Moose->stat(*file*)
        Creates the File::Stat::Moose object and calls CORE::stat function
        on given *file*. If the *file* is undefined, the <$_> variable is
        used instead. It returns the object reference.

          $st = File::Stat::Moose->stat('/etc/passwd');
          print "Size: ", $st->size, "\n";
          @st = @{ File::Stat::Moose->stat('/etc/passwd') };

    File::Stat::Moose->lstat(*file*)
        Creates the File::Stat::Moose object and calls CORE::lstat function
        on given *file*. If the *file* is undefined, the <$_> variable is
        used instead. It returns the object reference.

          @st = @{ File::Stat::Moose->lstat('/dev/stdin') };

METHODS
    $st->stat([*file*])
        Calls stat on given *file* or the file which has beed set with new
        constructor. If the *file* is undefined, the <$_> variable is used
        instead. It returns the object reference.

          $st = new File::Stat::Moose;
          print "Size: ", $st->stat('/etc/passwd')->{size}, "\n";

    $st->lstat([*file*])
        It is identical to stat, except that if *file* is a symbolic link,
        then the link itself is checked, not the file that it refers to.

          $st = new File::Stat::Moose;
          print "Size: ", $st->lstat('/dev/cdrom')->{mode}, "\n";

FUNCTIONS
    stat([*file*])
        Calls stat on given *file*. If the *file* is undefined, the <$_>
        variable is used instead.

        If it is called as function or static method in array context, it
        returns an array with the same values as for output of core stat
        function.

          use File::Stat::Moose 'stat';
          $_ = '/etc/passwd';
          @st = stat;
          print "Size: $st[7]\n";

        If it is called with scalar context, it returns the
        File::Stat::Moose object.

          use File::Stat::Moose 'stat';
          $st = stat '/etc/passwd';
          @st = @$st;

    lstat([*file*])
        It is identical to stat, except that if *file* is a symbolic link,
        then the link itself is checked, not the file that it refers to.

          use File::Stat::Moose 'lstat';
          @st = lstat '/etc/motd';

BUGS
    stat and lstat functions does not accept special handler _ written as
    bareword. You have to use it as a glob reference \*_.

      use File::Stat::Moose 'stat';
      stat "/etc/passwd";  # set the special filehandle _
      @st = stat _;        # does not work
      @st = stat \*_;      # ok

PERFORMANCE
    The File::Stat::Moose module is 4 times slower than File::stat module
    and 28 times slower than CORE::stat function. The function interface is
    4 times slower than OO interface.

SEE ALSO
    Exception::Base, perlfunc, Moose, File::stat.

AUTHOR
    Piotr Roszatycki <dexter@debian.org>

COPYRIGHT
    Copyright 2007 by Piotr Roszatycki <dexter@debian.org>.

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

    See <http://www.perl.com/perl/misc/Artistic.html>