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.

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.

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 {rw}

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

follow : Bool {rw}

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

sloppy : Bool {rw}

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.

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.

nlink : Maybe[Int] {ro}

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;
  $st->file( '/etc/passwd' );
  @st = @$st;

CONSTRUCTORS

new( args : Hash ) : Self

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

METHODS

stat() : Self

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

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

lstat() : Self

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 : 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 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

cpanm File::Stat::Moose

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