<<

NAME

Konstrukt::File - Comfortable handling of files, file names and paths

SYNOPSIS

        #read a file with a path relative to the current path and set the current
        #path to the path of the read file and save the read file as current file
        $Konstrukt::File->read_and_track('realative/path/file');
        
        #change to the previous dir and file
        $Konstrukt::File->pop();
        
        #read a file with an absolute path with the document_root the root dir without
        #updating the current path and file
        $Konstrukt::File->read('/absolute/path/from/doc_root/file');
        
        #read a file without the built-in path mangling
        $Konstrukt::File->raw_read('/really/absolute/path/file');

        #write a file without the built-in path mangling
        $Konstrukt::File->raw_write('/really/absolute/path/file', 'some content');

DESCRIPTION

This module allows to easily read files relatively to a your document root respectively to an imaginary current directory. So you don't have to care about generating the real path of a file.

Let's say you have this statement inside your webpage:

        <& template src="/templates/layout.template" / &>

In fact this file isn't located in /templates on your system, it's located in /.../your/document_root/templates. So using

        $Konstrukt::File->read_and_track('/templates/main.template');

will just return the file located at /.../your/document_root/templates and update the current dir to the path of the read file. Within this template you may want to load another file:

        <& template src="navigation/top.template" / &>

Actually this file is located at /.../your/document_root/templates/navigation as it is called from within the parent file, to which the path relates. This module will do this nasty path management for you.

To let the module know, when a file has been processed and you want to go back to the previous path, you must state:

        $Konstrukt::File->pop();

METHODS

new

Constructor of this class

set_root

Sets the root directory of this object and resets the current-dir-stack.

Parameters:

get_root

Returns the root directory (with a trailing slash) of this object.

Parameters: none

push

Saves the current file and its path. The paths will be the current "working directory".

Usually only used internally. A plugin developer should rather use "read_and_track" or "read".

Parameters:

current_dir

Returns the absolute path to the current virtual directory

current_file

Returns the absolute path to the last file that has been read and tracked

pop

Returns to the directory and the file that has been current before we read and tracked a new file.

get_files

Returns the stack of the absolute path to the currently tracked files as an array.

get_dirs

Returns the stack of the absolute paths to the currently tracked dirs as an array.

absolute_path

Returns the full path to a partially given filename.

If the path begins with a / this / will be substituted with our root. Otherwise it is relative to our current_dir.

Parameters:

relative_path

Returns the path from a given absolute filename relatively to the document root.

Example:

        #assume that the document root is '/foo/bar/'
        /foo/bar/baz => baz
        /foo/bar/baz/bim/bam => baz/bim/bam
        /foo/baz => ../baz

Parameters:

raw_read

Returns the content of a given filename as a scalar. Returns undef on error.

Will not care about the path management within this module.

Parameters:

raw_write

Writes a given scalars in the passed filename.

read_and_track

Will read a file relatively to the current directory and will change the current directory to the one of the file that shall be read if no errors occured. Will also save the read file as the current file, which can be obtained with the "current_file" method.

The root directory will be the one specified on construction of this object (usually your document root).

This method won't allow reading files outside the specified root. So $Konstrukt::File->read_and_track('/test.txt') will read the file test.txt located in the specified root, not in the system root.

A file read with this method will be put on a stack of "open" files. So all files read will be tracked as "opened"/"currently used". If you're done with a file, you should call $Konstrukt::File->"pop" to remove it from the stack of currently used files. The </current_file> method will then return the last filename.

This method will also add a (file date) cache condition (with the file and date of the read file) to each tracked (currently used) file. So if any of the files, which have been read after a file during a process, has changed until a next request the cache for this will be invalid as it is supposed that the file depends on the files which have been read as the file was tracked.

Parameters:

read

Will read a file relatively to the current directory.

The root directory will be the one specified on construction of this object (usually your document root).

This method won't allow reading files outside the specified root. So $Konstrukt::File->read('/test.txt') will read the file test.txt located in the specified root, not in the system root.

Parameters:

write

Will write a file relatively to the current directory.

The root directory will be the one specified on construction of this object (usually your document root).

This method won't allow writing files outside the specified root. So $Konstrukt::File->write('/test.txt', 'some data') will (over)write the file test.txt located in the specified root, not in the system root.

Parameters:

clean_path

Returns a clean path.

Converts "\" to "/", replaces everything to a "//" with "/", removes everything to a "Drive:\" (MS paths), removes "path/../", removes ./ and converts the path to lowercase on MS OSes.

extract_path

Extracts the path from a filename

extract_file

Extracts the filename from a full path to a file

create_dirs

Creates non existing directories in a given path

AUTHOR

Copyright 2006 Thomas Wittek (mail at gedankenkonstrukt dot de). All rights reserved.

This document is free software. It is distributed under the same terms as Perl itself.

SEE ALSO

Konstrukt

<<