/ 
PTools-SDF-0.01
/ PTools::SDF::DIR

NAME

PTools::SDF::DIR - Load dir entries into an 'PTools::SDF::SDF' object

VERSION

This document describes version 0.11, released February, 2006.

DEPENDENCIES

This class depends directly on the PTools::SDF::SDF class.

SYNOPSIS

Load the contentes of a subdirectory into an object of this class.

    use PTools::SDF::DIR;

or  use PTools::SDF::DIR ("stat");

    $dirObj = new PTools::SDF::DIR( "/subdir/path" );

Obtain information about the subdirectory's entries.

     $dirname = $dirObj->ctrl('fileName');

     print " Contents of $dirname:\n";

     foreach my $idx ( 0 .. $dirObj->param() ) {

	 $filename = $dirObj->param( $idx, 'filename' );
	 $fileBase = $dirObj->param( $idx, 'file'     );
	 $fileExt  = $dirObj->param( $idx, 'ext'      );

	 if ( $dirObj->isaFile( $idx ) ) {

             $size  = $dirObj->stat_size( $idx );
             $atime = $dirObj->stat_atime( $idx );

	     print "  $filename is a FILE, size=$size, atime=$atime\n";

	 } elsif ( $dirObj->isaDir( $idx ) ) {

             $uid   = $dirObj->stat_uid( $idx );
             $mode  = $dirObj->stat_mode( $idx );

	     print "  $filename is a DIR, uid=$uid, mode=$mode\n";

	 } else {

             $type  = $dirObj->type( $idx );
             $dev   = $dirObj->stat_dev( $idx );

	     print "  $filename type is $type, on dev=$dev\n";
	 }
     }

DESCRIPTION

Constructor

new

This class relies on a constructor in the parent class. See PTools::SDF::SDF for details.

However, this class is influenced by the use directive. If a "stat" parameter is added, a stat(2) is performed on each entry in a directory as it is loaded into an object of this class.

The default is to skip the 'stat' calls while loading the directory entries. This is for performance reasons. In this case, a 'stat' is not called on a particular entry until a method is invoked that needs to return some or all of the stat data for that entry.

In either case, only one 'stat' call is made per entry during the life of a given object of this class.

Examples:

Delay "stat" calls on dir entries until they are actually needed.

use PTools::SDF::DIR;

$dirObj = new PTools::SDF::DIR( "/subdir/path" );

Alternatively, call "stat" on every dir entry during object creation.

use PTools::SDF::DIR ("stat");

$dirObj = new PTools::SDF::DIR( "/subdir/path" );

General Methods

This class inherits from the PTools::SDF::SDF class which, in turn, inherits from the PTools::SDF::File class. Many other methods exist in these classes for accessing, sorting, locking and manipulating the contents of objects of this class.

In addition, several methods exist in this class to facilitate obtaining information about entries in a given subdirectory.

ext
extension ( RecIdx )

The extension method returns the extension name, if any, of the directory entry specified by the given RecIdx.

save

The save method in the PTools::SDF::SDF class is overridden here. This class provides read-only access to subdirectories.

Type Methods

The following methods provide access to file type information for any directory entries contained in the current object.

type ( RecIdx )

Return a string identifying the type of the directory at the RecIdx location in the current object.

The type returned will be one of the following.

file    - vanilla file
dir     - directory
symlink - symbolic link
socket  - socket
pipe    - named pipe
other   - other / unknown
type_file ( RecIdx )
type_dir ( RecIdx )
type_socket ( RecIdx )
type_pipe ( RecIdx )
type_undef ( RecIdx )
isaFile ( RecIdx )
isaDir ( RecIdx )
isaSocket ( RecIdx )
isaPipe ( RecIdx )
isUnknown ( RecIdx )

Returns a boolean indicating the particular type value for a given subdirectory entry.

Example:

$filename = $dirObj->param( $idx, 'filename' );

if ( $dirObj->isaFile( $idx ) ) {
    print "  $filename is a FILE\n";

} elsif ( $dirObj->isaDir( $idx ) ) {
    print "  $filename is a DIR\n";

} else {
    $type  = $dirObj->type( $idx );
    print "  $filename is a $type\n";
}

Stat Methods

The following methods provide access to status information for any directory entries contained in the current object.

For performance reasons, no 'stat' is performed on a given directory entry until a method is invoked that accesses stat data for that particular entry. Once obtained, the 'stat' data is cached so there is no further performance penalty for requesting additional 'stat' data for that particular directory entry.

To stat every directory entry while the entries are loaded during object creation, see the Constructor section, above.

statFile ( RecIdx, StatIdx )

Return status array elements. In the following example each of the three 'fileSize' variables are equivalent.

The RecIdx is the record index into the current object of directory entries and StatIdx is the offset into the 'stat(2)' array.

Example:

# In this example each of the three 'fileSize' variables are equivalent.

$dirRef = new PTools::SDF::DIR("/tmp");

$statIdx = 7;

foreach $recIdx ( 0 .. $dirRef->param() ) {

     (@statArray)= $dirRef->stat_array( $recIdx );

     $fileSizeA  = $dirRef->statFile( $recIdx, $statIdx );

     $fileSizeB  = $dirRef->stat_size( $recIdx );

     $fileSizeC  = $statArray[ $statIdx ];
}
stat_array ( RecIdx )
stat_dev ( RecIdx )
stat_ino ( RecIdx )
stat_mode ( RecIdx )
stat_uid ( RecIdx )
stat_gid ( RecIdx )
stat_rdev ( RecIdx )
stat_size ( RecIdx )
stat_atime ( RecIdx )
stat_mtime ( RecIdx )
stat_ctime ( RecIdx )
stat_bsize ( RecIdx )
stat_block ( RecIdx )

Return the particular stat value for a given subdirectory entry. The stat_array() method returns the entire status list for the given entry.

Examples:

(@statArray)= $dirRef->stat_array( $recIdx );

$fileSize   = $dirRef->stat_size( $recIdx );

$fileInode  = $dirRef->stat_ino( $recIdx );

INHERITANCE

This PTools::SDF::DIR class inherits from the PTools::SDF::SDF and PTools::SDF::File classes. Additional methods are available via these parent classes.

SEE ALSO

See PTools::SDF::Overview, PTools::SDF::ARRAY, PTools::SDF::CSV, PTools::SDF::DB, PTools::SDF::DSET, PTools::SDF::File, PTools::SDF::IDX, PTools::SDF::INI, PTools::SDF::SDF, PTools::SDF::TAG, PTools::SDF::Lock::Advisory, PTools::SDF::Sort::Bubble, PTools::SDF::Sort::Quick and PTools::SDF::Sort::Shell.

AUTHOR

Chris Cobb, <nospamplease@ccobb.net>

COPYRIGHT

Copyright (c) 1997-2007 by Chris Cobb. All rights reserved. This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.