Linux Certif

Toute la documentation sur la certification Linux LPI

Zim::FS.3pm

NAME

Zim::FS - OO wrapper for Files and Directories

SYNOPSIS

         $dir = Zim::FS::Dir->new('.');
         print "Dir contents:\n", map "- $_\n", $dir->list;
 
         $file = Zim::FS::File->new('./Changes');
         $text = $file->read;
         $file->write("New item\n", $text);
 
 

DESCRIPTION

This package provides various objects for handling files and directories.

OVERLOAD

These classes overload the '""' operator, so the string version of an object is the path of the file or directory in question.

METHODS

Zim::FS;

The main "Zim::FS" class contains non-OO routines for handling paths. These are used by the File and Dir objects and should in general be avoided in other modules.

"localize(FILE)"

Returns platform dependend version of FILE. Can also localize uris produced by "uri2path()" in some corner cases.

"is_abs_path(PATH)"

Returns boolean whether a path is absolute or not. Urls are considered absolute paths.

"abs_path(PATH, REFERENCE)"

Turn a relative filename or a file uri into a local path name and cleans up this path to a logical form. It also does tilde expansion.

If REFERENCE is omitted the current dir is used.

Calls "uri2path()" first when needed.

"clean_path(PATH)"

Removes ``.'' and ``..'' from the path. Returned path can only contain ``..'' at the begin.

"rel_path(FILE, REFERENCE, UPWARD)"

Returns a path for FILE relative to REFERENCE or undef when this is not possible.

When UPWARD is true the returned path can contain ``../'', else it will only go below REFERENCE.

"uri2path(URI)"

Method for parsing file uris, returns either a normal path or a (modified) uri. No url decoding is done here.

"path2uri(FILE)"

Turns a path into an uri. Does no checks.

"cache_file(NAME)"

Returns a file in the cache. If NAME is a path directory separators are stripped.

"tmp_file(NAME)"

Returns a file in the tmp directory. Basides NAME both the user name and the process id are included in the file name to avoid collisions between separate instances of zim.

"devnull"

Returns the path for the /dev/null device.

"tmpdir"

Returns the path for /tmp or equivalent.

Zim::FS::Node

Base class for directory and file objects.

"path"

Returns the full path.

"uri"

Returns the path as a "file://" uri.

"name"

Returns the last part of the path.

"basename"

Returns basename part of the path.

"dir()"

Returns a Dir object for the directory containing this file or dir.

"parent()"

Returns Dir object to which this file or dir belongs. Not necessarily the direct parent dir, use "dir()" to find that.

"rel_path()"

Return the path relative to "parent" if any.

"writable()"

Returns boolean.

Zim::FS::Dir

Object for a single directory.

"new(@PATH)"

Simple constructor, takes path as a list. If the first argument is a Dir object it regards this as its parent object.

"exists"

Returns whether dir exists or not.

"list()"

Returns a list of items for DIR. Ignores hidden files.

"touch()"

Create this dir and parents if it doesn't exist already. Returns list of created dirs.

"touch(DIR)"

Create a sub dir if it doesn't exist alread. Returns list of created dirs.

"file(@PATH)"

Returns a file in this directory.

"subdir(@PATH)"

Returns a sub dir in this directory.

"resolve_file(EXT, @PARTS)"

Look for a file below this directory that kind of looks like @PARTS.

EXT is the file extension to add to the last part when resolving a file. This can be "undef". The extension is also used to keep case the same between like-named dirs and files.

"resolve_dir(EXT, @PARTS)"

Like "resolve_file()" but returns a Dir object.

"cleanup()"

Remove this directory and clean up its parent directories if they are empty. Only works if this dir has an parent Dir object.

"cleanup(FILE)"

"cleanup(DIR)"

Removes a file or directory and cleans up it's parents when they are empty up to the directory of the current object. Returns list of deleted parents.

"remove_file(FILE)"

Remove a file under this dir. FILE is an object.

"remove_dir(DIR)"

Remove a subdir under this dir. DIR is an object.

"copy_file(SOURCE =" DEST)>

Copy content from one file object to another.

"move_file(SOURCE =" DEST)>

Move content from one file object to another.

"commit_file(FILE)"

"discard_file(FILE)"

"on_write_file(FILE)"

Callbacks to be overloaded in sub classes.

Zim::FS::File

Object for a single file.

"new(FILENAME)"

Simple constructor, uses File::Spec's "catfile" when multiple arguments are given. Attaches to Dir object when first argument is an object reference.

"read()"

Returns the contents of the file. Takes list context in account. Returns empty when the file does not exist.

"write(CONTENT, ..)"

Write CONTENT to file. Creates file and parent directories when needed.

"append(CONTENT, ..)"

Append content to file. Creates file and parent directories when needed.

"cleanup()" Delete the file and empty parent directories.

"remove()"

Delete the file.

"exists()"

Returns boolean.

"mtime()"

Return the modification time for this file.

"set_mtime()"

Set the current mtime of the file as an object attribute.

"check_mtime()"

Get the mtime for the file and compare to stored mtime atribute. Dies when timestamps do not match. Used by subclasses to detect when files changed on disk.

"open(MODE)"

Returns an "IO" object that can be used as a file handle.

Make sure to close this handle using OO syntax, using "$fh->close" instead of "close $fh".

FILE is an optional argument allowing this function to be used without an object.

MODE can be 'r', 'w' or 'a' for read, write and append respectivly.

"grep(REGEXP, MODE)"

Line based grep function. MODE can be undefined, 'lines' or 'count'; In normal mode matches are returned, for 'lines' complete lines that match are returns, and for 'count' a number of matches is returned.

"touch()"

Create empty file if file does not exist.

"on_write()"

Called by the file handle object when it is closed after writing to this file. Used by subclasses, not intended for external use.

"resolve_link()"

If the file is a symlink this will return the final destination of that link.

"copy(DESTINATION)"

Copy content from one file to another. Creates parent directories if needed.

"move(DESTINATION)"

Move file contents from one place to another. Takes care of creating and cleaning up parent directories.

Zim::FS::File::Config

This subclass is used for reading and writing config files

"read(\%CONFIG, GROUP)"

Returns a hash with config data.

Arguments CONFIG and GROUP are optional. If CONFIG is given it will be used to store the config. Existing keys found in the file will be overwritten with the value from the file If GROUP is given this is the default group in the config. Keys from the group will be placed in the top level hash, all other groups will be sub-hashes.

"write(\%CONFIG, GROUP)"

Writes a hash with config data.

GROUP is optional and will be used as the name for the default group. All keys in the top level hash go in this group. Sub-hashes will be separate groups.

Zim::FS::File::CheckOnWrite

This subclass is used for the text files containing pages to prevent data loss.

Be aware that checking and locking done in this class are only intended to prevent a single user to overwrite data by accident. It will not suffice for a multi-user system.

This class checks the modification time of the file when reading and writing. It will not allow you to overwrite a file if it changed since you read it.

Also this class implements ``atomic'' writing. This means that when you write to a file you write to a temporary file first. When the file handle is closed the temporary file is moved to replace the original file. This way the original file is not purged when an error occurs while writing.

Zim::FS::File::CacheOnWrite

This subclass is used when the original file is located on a slow file system. It implements a ``copy on write'' that uses a cache file after the first write. You need to call "commit_change()" in order to overwrite the original file.

It does check the modification time like CheckOnWrite.

"commit_change()"

Copy the cached data back to the original file.

"discard_change()"

Throw away the cached version.

Zim::FS::URI

Subclass of Zim::FS::Node that just contains an URI or something that looks like a path, but does not exist on the file system. Can be used with certain interfaces that require a dir object for resolving paths.

"new(@URI)"

Simple constructor.

"uri()"

Returns URI.

"path()"

Same as "uri()".

"dir()"

Returns an URI object for parent ``dir''.

"subdir(@PATH)"

Returns a URI object for the URI after appending @PATH.

"file()"

Like "subdir()" but without trailing ``/''.

Zim::FS::Buffer

This object implements part of the API of Zim::FS::File but keeps all data in memory. Can be used with certain interfaces that require a file object to read/write data.

Does not inherit from Zim::FS::Node.

"new(\$STRING)"

"new(@STRING)"

Simple constructor, takes a scalar ref or a list of scalars as argument.

"read()"

Returns contents.

"write(TEXT)"

Sets contents.

"append(TEXT)"

Appends contents.

"open(MODE)"

Returns a file handle.

"exists()"

True if content defined.

"remove()"

Delete content.

"copy(FILE)"

Write content of buffer to FILE.

"move(FILE)"

Write content of buffer to FILE and delete buffer.

AUTHOR

Jaap Karssenberg (Pardus) <pardus@cpan.org>

Copyright (c) 2006, 2007 Jaap G Karssenberg. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

SEE ALSO

Zim