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

NAME

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

SYNOPSIS

use File::Stat::Moose;
$st = File::Stat::Moose->new( file => '/etc/passwd' );
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.

IMPORTS

By default, the class does not export its symbols.

stat
lstat

Imports stat and/or lstat functions.

use File::Stat::Moose 'stat', 'lstat';
:all

Imports all available symbols.

use File::Stat::Moose ':all';

INHERITANCE

EXCEPTIONS

Exception::Argument

Thrown whether a methods is called with wrong arguments.

Exception::IO

Thrown whether an IO error is occurred.

ATTRIBUTES

file : Str|FileHandle|CacheFileHandle|OpenHandle {ro, required}

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

follow : Bool = false {ro}

If the value is true and the file for check is symlink, then follows it than checking the symlink itself.

sloppy : Bool = false {ro}

On Win32 "stat" in perlfunc needs to open the file to determine the link count and update attributes that may have been changed through hard links. If the sloppy is set to true value, "stat" in perlfunc speeds up by not performing this operation.

strict_accessors : Bool = false {rw}

By default the accessors might be avoided for performance reason. This optimization can be disabled if the attribute is set to true value.

dev : Maybe[Int] {ro}

ID of device containing file. If this value and following has no meaning on the platform, it will contain undefined value.

ino : Maybe[Int] {ro}

inode number.

mode : Maybe[Int] {ro}

Unix mode for file.

Number of hard links.

uid : Maybe[Int] {ro}

User ID of owner.

gid : Maybe[Int] {ro}

Group ID of owner.

rdev : Maybe[Int] {ro}

Device ID (if special file).

size : Maybe[Int] {ro}

Total size, in bytes.

atime : Maybe[DateTime] {ro}

Time of last access as DateTime object.

mtime : Maybe[DateTime] {ro}

Time of last modification as DateTime object.

ctime : Maybe[DateTime] {ro}

Time of last status change as DateTime object.

blksize : Maybe[Int] {ro}

Block size for filesystem I/O.

blocks : Maybe[Int] {ro}

Number of blocks allocated.

OVERLOADS

Array dereferencing

If File::Stat::Moose object is dereferenced as array it returns an array with the same order of values as in "stat" in perlfunc or "lstat" in perlfunc functions. Attributes atime, ctime and mtime are returned as number values (Unix timestamp).

$st = File::Stat::Moose->new( file => '/etc/passwd' );
@st = @$st;

CONSTRUCTORS

new( args : Hash ) : Self

Creates the File::Stat::Moose object and calls update method.

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

METHODS

stat() : Self

Updates all attributes which represent status of file.

Calls "stat" in perlfunc function if follow method is true value or "lstat" in perlfunc function otherwise.

FUNCTIONS

stat( file : Str|FileHandle|CacheFileHandle|OpenHandle = $_ ) : Self|Array

Calls stat on given file. If the file is undefined, the $_ variable is used instead.

If it is called 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 : Str|FileHandle|CacheFileHandle|OpenHandle = $_ ) : Self|Array

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 30 times slower than "stat" in perlfunc function. The function interface is 1.5 times slower than OO interface. The strict accessors are 2.5 times slower that optimized direct access to hash.

SEE ALSO

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

AUTHOR

Piotr Roszatycki <dexter@cpan.org>

LICENSE

Copyright (C) 2007, 2008, 2009 by Piotr Roszatycki <dexter@cpan.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