The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.
 / 
XML-Directory-0.60
River stage zero No dependents
/ XML::Directory

NAME

XML::Directory - returns a content of directory as XML

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>
   <head version="0.60">
     <path>/home/petr/test</path>
     <details>2</details>
     <depth>5</depth>
   </head>
   <directory name="test" depth="0">
     <path></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>
   <head version="0.60">
     <path>/home/petr/test</path>
     <details>3</details>
     <depth>5</depth>
   </head>
   <directory name="test" depth="0" uid="500" gid="100">
     <path></path>
     <access-time epoch="999857485">Fri Sep  7 12:11:25 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 xmlns="http://gingerall.org/directory">
 <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.

Methods to deal with namespaces

Generated XML (or SAX events) doesn't contain namespace declarations by default (for the sake of simplicity). This feature can enabled manually if you want to merge this data with some other XML data, for example.

enable_ns;
 $dir->enable_ns;

Enables the support for namespaces.

disable_ns;
 $dir->disable_ns;

Disables the support for namespaces.

get_ns_data;
 $ns  = $dir->get_ns_data;

Returns a hash reference with the following keys:

enabled

either 1 or 0

uri

namespace URI, 'http://gingerall.org/directory' by default

prefix

namespace prefix, 'xd' by default

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.

XML::DIRECTORY::APACHE

This is a mod_perl module that serves as an Apache interface to XML::Directory. It allows to send parameters in http request and receive a result (XML representation of a directory tree) in http response.

Parameters include:

path

absolute path to a directory to be parsed, mandatory

The path is not send in query but as an extra path instead. This seems to be more appropriate for this kind of parameter.

dets

level of details, optional

depth

maximal number of nested sub-directories, optional

ns

if set to 1, namespaces are used, optional

To use this module, add a similar section to your Apache config file

 <Location /xdir>
     SetHandler perl-script
     PerlHandler XML::Directory::Apache
     PerlSendHeader On
 </Location>

and send a request to:

 http://hostname/xdir/home/petr/work[?dets=1&depth=1&ns=1]

The path portion following 'xdir' is taken as path; other parameters can be send in query.

VERSION

Current version is 0.60.

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).