/ 
Konstrukt-0.5-beta1
River stage zero No dependents
/ Konstrukt::File

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:

  • $root - The pseudo-root dir. Will be the root of a $Konstrukt::File-read('/path/file')>. Usually your document root. Should always be an absolute path, otherwise you may get really weird results.

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:

  • $file - The absolute path to the filename

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:

  • $path - The path

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:

  • $path - The absolute path

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:

  • $filename - The name of the file to read

  • $asref - Boolean value. If true, the result will be returned by reference to avoid copying of large data within the memory.

raw_write

Writes a given scalars in the passed filename.

  • $filename - The name of the file to write to

  • @scalars - The scalars which should be written to disk. May be references (which will be dereferenced).

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:

  • $filename - The name of the file to read relative to the current directory

  • $asref - Boolean value. If true, the result will be returned by reference to avoid copying of large data within the memory.

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:

  • $filename - The name of the file to read

  • $asref - Boolean value. If true, the result will be returned by reference to avoid copying of large data within the memory.

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:

  • $filename - The name of the file to write

  • @scalars - The scalars which should be written to disk. May be references (which will be dereferenced).

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.

  • $path - The path

extract_path

Extracts the path from a filename

  • $filename - The filename

extract_file

Extracts the filename from a full path to a file

  • $filename - The filename

create_dirs

Creates non existing directories in a given path

  • $path - The (absolute) 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