[inseparable changes from match from perl-5.003_97b to perl-5.003_97c]
[perl.git] / lib / File / stat.pm
1 package File::stat;
2 use strict;
3
4 BEGIN { 
5     use Exporter   ();
6     use vars       qw(@EXPORT @EXPORT_OK %EXPORT_TAGS);
7     @EXPORT      = qw(stat lstat);
8     @EXPORT_OK   = qw( $st_dev     $st_ino    $st_mode 
9                        $st_nlink   $st_uid    $st_gid 
10                        $st_rdev    $st_size 
11                        $st_atime   $st_mtime  $st_ctime 
12                        $st_blksize $st_blocks
13                     );
14     %EXPORT_TAGS = ( FIELDS => [ @EXPORT_OK, @EXPORT ] );
15 }
16 use vars      @EXPORT_OK;
17
18 # Class::Struct forbids use of @ISA
19 sub import { goto &Exporter::import }
20
21 use Class::Struct qw(struct);
22 struct 'File::stat' => [
23      map { $_ => '$' } qw{
24          dev ino mode nlink uid gid rdev size
25          atime mtime ctime blksize blocks
26      }
27 ];
28
29 sub populate (@) {
30     return unless @_;
31     my $stob = new();
32     @$stob = (
33         $st_dev, $st_ino, $st_mode, $st_nlink, $st_uid, $st_gid, $st_rdev,
34         $st_size, $st_atime, $st_mtime, $st_ctime, $st_blksize, $st_blocks ) 
35             = @_;
36     return $stob;
37
38
39 sub lstat ($)  { populate(CORE::lstat(shift)) }
40
41 sub stat ($) {
42     my $arg = shift;
43     my $st = populate(CORE::stat $arg);
44     return $st if $st;
45     no strict 'refs';
46     require Symbol;
47     return populate(CORE::stat \*{Symbol::qualify($arg)});
48 }
49
50 1;
51 __END__
52
53 =head1 NAME
54
55 File::stat - by-name interface to Perl's built-in stat() functions
56
57 =head1 SYNOPSIS
58
59  use File::stat;
60  $st = stat($file) or die "No $file: $!";
61  if ( ($st->mode & 0111) && $st->nlink > 1) ) {
62      print "$file is executable with lotsa links\n";
63  } 
64
65  use File::stat qw(:FIELDS);
66  stat($file) or die "No $file: $!";
67  if ( ($st_mode & 0111) && $st_nlink > 1) ) {
68      print "$file is executable with lotsa links\n";
69  } 
70
71 =head1 DESCRIPTION
72
73 This module's default exports override the core stat() 
74 and lstat() functions, replacing them with versions that return 
75 "File::stat" objects.  This object has methods that
76 return the similarly named structure field name from the
77 stat(2) function; namely,
78 dev,
79 ino,
80 mode,
81 nlink,
82 uid,
83 gid,
84 rdev,
85 size,
86 atime,
87 mtime,
88 ctime,
89 blksize,
90 and
91 blocks.  
92
93 You may also import all the structure fields directly into your namespace
94 as regular variables using the :FIELDS import tag.  (Note that this still
95 overrides your stat() and lstat() functions.)  Access these fields as
96 variables named with a preceding C<st_> in front their method names.
97 Thus, C<$stat_obj-E<gt>dev()> corresponds to $st_dev if you import
98 the fields.
99
100 To access this functionality without the core overrides,
101 pass the C<use> an empty import list, and then access
102 function functions with their full qualified names.
103 On the other hand, the built-ins are still available
104 via the C<CORE::> pseudo-package.
105
106 =head1 NOTE
107
108 While this class is currently implemented using the Class::Struct
109 module to build a struct-like class, you shouldn't rely upon this.
110
111 =head1 AUTHOR
112
113 Tom Christiansen