/ 
File-Stat-Moose-0.03
River stage zero No dependents
/ File::Stat::Moose

NAME

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

SYNOPSIS

use File::Stat::Moose;
open my $fh, '/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.

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 (rw, new)

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

follow (rw, 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.

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 as DateTime object.

mtime (ro)

Time of last modification as DateTime object.

ctime (ro)

Time of last status change as DateTime object.

blksize (ro)

Blocksize for filesystem I/O.

blocks (ro)

Number of blocks allocated.

CONSTRUCTORS

new

Creates the File::Stat::Moose object.

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

The new constructor 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

The object is dereferenced in array context to the array reference which contains the same values as "stat" in perlfunc 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 "stat" in perlfunc 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 "lstat" in perlfunc 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

Calls stat on the file which has beed set with new constructor. It returns the object reference.

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

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;
$st->file( '/dev/cdrom' );
print "Size: ", $st->lstat->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 "stat" in perlfunc function. The function interface is 1.5 times slower than OO interface.

SEE ALSO

Exception::Base, MooseX::Types::OpenHandle, MooseX::Types::CacheFileHandle, Moose, File::stat, DateTime.

AUTHOR

Piotr Roszatycki <dexter@debian.org>

LICENSE

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