NAME

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

SYNOPSIS

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

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

BASE CLASSES

• Moose::Base

TYPE CONSTRAINTS

OpenHandle

Represents opened file handle (glob reference or object).

CacheFileHandle

Represents normal file handle or special cached file handle: underscore (_) which is used for stat tests.

EXCEPTIONS

Exception::Argument

Thrown whether a methods is called with wrong arguments.

Exception::IO

Thrown whether an IO error is occurred.

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.

ATTRIBUTES

file (ro, new, weak_ref)

Contains the file for check. The attribute can hold file name or file handler or IO object.

follow (ro, new)

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 attribute is defined and follow attribute is a true value or calls lstat method if the file attribute is defined and follow attribute 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 = File::Stat::Moose->new( 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 = File::Stat::Moose->new( file=>'/etc/passwd' );
  print "Size: $st->size\n";  # object's attribute
  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 = File::Stat::Moose->new;
  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 = File::Stat::Moose->new;
  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 1.7 times slower than File::stat module and 10 times slower than CORE::stat function. The function interface is 1.5 times slower than OO interface.

SEE ALSO

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

AUTHOR

Piotr Roszatycki <dexter@debian.org>

COPYRIGHT

Copyright (C) 2007, 2008 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

cpanm File::Stat::Moose

perl -MCPAN -e shell
install File::Stat::Moose