/ 
XML-Directory-0.51
River stage zero No dependents
/ XML::Directory

NAME

XML::Directory - Perl extension allowing to get a content of directory including sub-directories as an XML file. You can generate either array/string or SAX events. The current version is 0.51.

SYNOPSIS

use XML::Directory;

$dir = new XML::Directory('/home/petr');

$dir->set_details(3);
$dir->set_maxdepth(10);

---

$h = new MyHandler;
$e = new MyErrorHandler;

$dir->set_content_handler($h);
$dir->set_error_handler($e);

$rc = $dir->parse_SAX;

or

$rc = $dir->parse;

$res = $dir->get_arrayref;
@res = $dir->get_array;
$res = $dir->get_string;

or

@xml = XML::Directory::get_dir('/home/petr',2,5);

DESCRIPTION

This utility extension provides XML::Directory class and its methods plus the original public function (get_dir) because of backward compatibility. The class methods make it possible to set parameters such as level of details or maximal number of nested sub-directories and generate either string containing the resulting XML or SAX events.

The SAX generator supports both SAX1 and SAX2 handlers. There are two SAX interfaces available: basic ContentHandler and optional ErrorHandler.

XML::DIRECTORY CLASS

new
$dir = new XML::Directory('/home/petr',2,5);
$dir = new XML::Directory('/home/petr',2);
$dir = new XML::Directory('/home/petr');

The constructor accepts up to 3 parameters: path, details (1-3, brief or verbose XML) and depth (number of nested sub-directories). The last two parameters are optional (defaulted to 2 and 1000).

Methods to control parameters

set_path
$dir->set_path('/home/petr');

Resets path. An initial path is set using the constructor.

set_details
$dir->set_details(3);

Sets or resets level of details to be returned. Can be also set using the constructor. Valid values are 1, 2 or 3.

1 = brief

Example:

<?xml version="1.0" encoding="utf-8"?>
<dirtree>
  <directory name="test">
    <file name="dir2xml.pl"/>
  </directory>
</dirtree>

2 = normal

Example:

<?xml version="1.0" encoding="utf-8"?>
<dirtree>
  <directory name="test" depth="0">
    <path>/home/petr/test</path>
    <modify-time epoch="998300843">Mon Aug 20 11:47:23 2001</modify-time>
    <file name="dir2xml.pl">
      <mode code="33261">rwx</mode>
      <size unit="bytes">225</size>
      <modify-time epoch="998300843">Mon Aug 20 11:47:23 2001</modify-time>
    </file>
  </directory>
</dirtree>

3 = verbose

Example:

<?xml version="1.0" encoding="utf-8"?>
<dirtree>
  <directory name="test" depth="0" uid="500" gid="100">
    <path>/home/petr/test</path>
    <access-time epoch="998300915">Mon Aug 20 11:48:35 2001</access-time>
    <modify-time epoch="998300843">Mon Aug 20 11:47:23 2001</modify-time>
    <file name="dir2xml.pl" uid="500" gid="100">
      <mode code="33261">rwx</mode>
      <size unit="bytes">225</size>
      <access-time epoch="998300843">Mon Aug 20 11:47:23 2001</access-time>
      <modify-time epoch="998300843">Mon Aug 20 11:47:23 2001</modify-time>
    </file>
  </directory>
</dirtree>
set_maxdepth
$dir->set_maxdepth(5);

Sets or resets number of nested sub-directories to be parsed. Can also be set using the constructor. 0 means that only a directory specified by path is parsed (no sub-directories).

get_path
$path = $dir->get_path;

Returns current path.

get_details
$details = $dir->get_details;

Returns current level of details.

get_maxdepth
$maxdepth = $dir->get_maxdepth;

Returns current number of nested sub-directories.

Methods to generate strings

parse
$rc  = $dir->parse;

Scans directory tree specified by path and stores its XML representation in memory. Returns a number of lines of the XML file.

This method checks a validity of details and depth. In the event a parameter is out of valid range, an XML file containing error message is returned. The same is true if the path specified can't be found.

Example:

<?xml version="1.0" encoding="utf-8"?>
<dirtree>
<error number="3">Path /home/petr/work/done not found!</error>
</dirtree>
get_arrayref
$res = $dir->get_arrayref;

Returns a parsed XML directory image as a reference to array (each field contains one line of the XML file).

get_array
@res = $dir->get_array;

Returns a parsed XML directory image as an array (each field contains one line of the XML file).

get_string
$res = $dir->get_string;

Returns a parsed XML directory image as a string.

Methods to generate SAX events

set_content_handler
$h = new MyHandler;
$dir->set_content_handler($h);

Sets SAX content handler.

set_error_handler
$e = new MyErrorHandler;
$dir->set_error_handler($e);

Sets SAX error handler.

$dir->parse_SAX
$rc = $dir->parse_SAX($h,$e);
$rc = $dir->parse_SAX($h);
$rc = $dir->parse_SAX;

Generates SAX events for both SAX1 and SAX2 handlers. A content handler is mandatory while an error handler is optional. If there is no error handler registered a SAX exception is thrown. If there is an error handler available an exception is thrown and an appropriate method of the error handler is called.

parse_SAX can either use handlers set by set_content_handler and set_error_handler methods or set/reset one or both handlers itself. If there is no content handler registered in neither way, an exception is thrown.

This method returns a return value of the end_document function or undef in tha case of error.

ORIGINAL INTERFACE

get_dir();
@xml = get_dir('/home/petr',2,5);

This functions takes a path as a mandatory parameter and details and depth as optional ones. It returns an array containing an XML representation of directory specified by the path. Each field of the array represents one line of the XML.

Optional arguments are defaults to 3 and 1000. The default value for detail level is different from the same default for the object interface; the reason is to keep the get_dir function backward compatible with the version 0.30.

LICENSING

Copyright (c) 2001 Ginger Alliance. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

AUTHOR

Petr Cimprich, petr@gingerall.cz

SEE ALSO

perl(1).