Konstrukt::File - Comfortable handling of files, file names and paths
#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');
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();
Constructor of this class
Sets the root directory of this object and resets the current-dir-stack.
Parameters:
$Konstrukt::File-
read('/path/file')>. Usually your document root. Should always be an absolute path, otherwise you may get really weird results.Returns the root directory (with a trailing slash) of this object.
Parameters: none
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:
Returns the absolute path to the current virtual directory
Returns the absolute path to the last file that has been read and tracked
Returns to the directory and the file that has been current before we read and tracked a new file.
Returns the stack of the absolute path to the currently tracked files as an array.
Returns the stack of the absolute paths to the currently tracked dirs as an array.
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:
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:
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:
Writes a given scalars in the passed filename.
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:
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:
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:
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.
Extracts the path from a filename
Extracts the filename from a full path to a file
Creates non existing directories in a given path
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.