File::Name

The File::Name class provides file pathname objects and related operations. File::Name::Temp is a subclass that ensures the file pointed to by the filename is deleted if it exists at the time the File::Name::Temp object is destroyed.

Synopsis

    use File::Name;
    
    $passwd = File::Name->new( '/etc/passwd' );
    
    $etc = $fn->parent;
    $shadow = $etc->child( '/etc/shadow' );
    $passwd = $shadow if ( ! $passwd->exists and $shadow->exists );
    
    $passwd->must_exist;
    $text = $passwd->get_contents;
    
    foreach $file ( $etc->children ) {
      next if $file->isdir;
      print $file->name . ': ' . $file->size . "\n";
    }

Description

File::Name objects are blessed filename strings. This is an OOP wrapper around functionality from FileHandle, Basename, and Cwd.

Interface

Interface

These functions create new File::Name objects, returning a reference to a blessed string value.

File::Name->new( @path_name_elements ) : $fn

Pass a full file path or a a series of relative elements to create a filename object.

filename( $path ) : $fn

Same as File::Name->new. This function is exported when you use File::Name.

File::Name->current : $fn

Creates a filename object for the current working directory.

current_directory : $fn

Same as File::Name->current. This function is exported when you use File::Name.

Path and Name Methods

$fn->path : $pathname

Return the full pathname.

$fn->name : $filename

Return the filename without the parent directory path

$fn->base_name : $shortname

Return the filename with extention stripped off.

$fn->extension : $extension

Return the outermost dot-separated extension of the filename.

$fn->hasextension( $extn ) : flag

Return a flag indicating if the file has the provided extention.

Directory Methods

$fn->parent : $parent_fn

Return a filename object representing the directory the current file is in.

$fn->children : @child_fns

$fn->children( $pattern ) : @child_fns

Directories only. If no argument is passed, returns a list of filename objects represeting each of the items in the directory. Simple filename expressions can be passed to limit which children you get back, using ? for a single character and * for multiple characters.

$fn->child( $name ) : $child_fn

Returns a filename object for a file in the current directory with the specified name. You'll need to check _$child_fn_ -exists> to see if such a file actually exists.

Attribute Methods

$fn->exists : flag

Returns a flag indicating whether there actually exists a file with this name.

$fn->must_exist

Dies unless the file exists.

$fn->isdir : flag

Returns a flag indicating whether the file exists and is a directory.

$fn->must_be_dir

Dies unless the file is a directory

$fn->size : bytecount

Return the length of the file in bytes.

$fn->age_since_change : num_days

Return the age in days since the file was modified, measured from when the current process started.

$fn->media_type : mime_type

Attempts to determine the content type based on the filename extention.

$fn->delete

Delete the file.

Read and Write Methods

$fn->open_reader : filehandle

Returns a FileHandle object set to read from this filename.

$fn->reader : filehandle

Returns a FileHandle object, as above. Dies unless it is successfully opened

$fn->open_writer : filehandle

Returns a FileHandle object set to write to this filename.

$fn->writer : filehandle

Returns a FileHandle object, as above. Dies unless it is successfully opened

$fn->open_appender : filehandle

Returns a FileHandle object set to append to this filename.

$fn->appender : filehandle

Returns a FileHandle object, as above. Dies unless it is successfully opened

$fn->get_contents : $content_bytes

Reads and returns the contents of the file at this filename.

$fn->set_contents( $content_bytes )

Sets the contents of the file at this filename to the value passed in.

$fn->sys_get_contents : $content_bytes

$fn->sys_set_contents( $content_bytes )

These methods perform the same actions as get_contents and set_contents, but use sysread and syswrite instead of read and print.

$fn->open_text_reader : filehandle

$fn->text_reader : filehandle

$fn->open_text_writer : filehandle

$fn->text_writer : filehandle

$fn->open_text_appender : $fh

$fn->text_appender : $fh

$fn->get_text_contents : $content_text

$fn->set_text_contents( $content_text )

$fn->append_text( $text )

Each of these methods performs the actions of its equivalent non-text method, but does not activate binmode. Although identical on Unix, these methods should be used for Mac, DOS, and Win32 portability.

$fn->get_text_lines : @lines

$fn->set_text_lines( @lines )

$fn->append_text_lines( @lines )

As above, except that contents are handled as a list of text lines. Lines are ended with \n, which will be translated to \r\n under Windows by the non-binmoded filehandle.

Temp Files

File::Name->temp_dir : $tmp_dir_fn

Return a File::Name containing the path to a directory that may be used for temporary file storage. To discover this path, we check several possible paths (stored in @TempDirCandidates), then store the result in $TempDirectory.

File::Name->new_temp( $filename ) : $tmp_fn

Returns a File::Name in the temporary directory using a unique variation of the provided filename string.

Path Manipulation Functions

simple_wildcard_to_regex( $partial_filename_with_stars ) : $regex

Returns a Perl regular expression equivalent to the simple filename expression provided, where ? matches one character and * matches many.

DRef Interface

These methods use Data::DRef and provide special access methods for file information.

$fn->get($dref) : $value

You can retrieve any of the following file attributes via dref: path, name, extension, contents, lastmod, size, media_type.

$fn->set($dref, $value)

You can set the following file attributes via dref: contents.

Debugging

$fn->check_state($context_name)

Writes some potentially interesting information about this filename to STDERR via warn. Include a unique string in $context_name to differentiate your debugging cases.

See Also

Data::DRef, Cwd, FileHandle, File::Basename

This is Free Software

Copyright 1997, 1998 Evolution Online Systems, Inc. (http://www.evolution.com)

You can use this software under the same terms as Perl itself.

Part of the EvoScript Web Application Framework (http://www.evoscript.com)