View on
MetaCPAN
Aaron Straup Cope > XML-Filter-XML_Directory_2-Base-1.4.4 > XML::Filter::XML_Directory_2::Base

Download:
XML-Filter-XML_Directory_2-Base-1.4.4.tar.gz

Dependencies

Annotate this POD

View/Report Bugs
Module Version: 1.4.4   Source  

NAME ^

XML::Filter::XML_Directory_2::Base - base class for creating XML::Directory to something else SAX filters.

SYNOPSIS ^

 package XML::Filter::XML_Directory_2Foo;
 use base qw (XML::Filter::XML_Directory_2::Base);

DESCRIPTION ^

Base class for creating XML::Directory to something else SAX filters.

This class inherits from XML::Filter::XML_Directory_Pruner.

PACKAGE METHODS ^

__PACKAGE__->attributes(\%args)

This is a simple helper method designed to save typing.

Value arguments are

Returns a hash with a single key named Attributes whose value is a hash ref for passing to the XML::SAX::Base::start_element method.

This method does not support namespaces (yet.)

OBJECT METHODS ^

$pkg->encoding($type)

$pkg->set_encoding($type)

Alias for encoding

$pkg->exclude_root($bool)

By default, XML::Directory will include the directory you pass to the XML::Directory(::SAX)::parse_dir method.

You can use this method to instruct your filter to only include the contents of the root directory and not the directory itself.

$pkg->start_level()

Read-only.

$pkg->cwd()

Read-only.

$pkg->current_directory()

Short-cut (ahem) for $pkg->cwd()

$pkg->current_location()

Returns the current location relative to the directory root

$pkg->set_handlers(\%args)

Define one or more valid SAX2 thingies to be called when your package encounters a specific event. Thingies are like any other SAX2 thingy with a few requirements :

 # If this...

 my $writer = XML::SAX::Writer->new();
 my $rss = XML::Filter::XML_Directory_2RSS->new(Handler=>$writer);
 $rss->set_handlers({title=>MySAX::TitleHandler->new(Handler=>$writer)});

 # Called this...

 package MySAX::TitleHandler;
 use base qw (XML::SAX::Base);
 
 sub parse_uri {
    my ($pkg,$path,$title) = @_;

    $pkg->SUPER::start_prefix_mapping({Prefix=>"me",NamespaceURI=>"..."});
    $pkg->SUPER::start_element({Name=>"me:woot"});
    $pkg->SUPER::characters({Data=>&get_title_from_file($path)});
    $pkg->SUPER::end_element({Name=>"me:woot"});
    $pkg->SUPER::end_prefix_mapping({Prefix=>"me"});
 }

 # Then the output would look like this...

 <item>
  <title>
   <me:woot xmlns:me="...">I Got My Title From the File</me:woot>
  </title>
  <link>...</link>
  <description />
 </item>

Valid events are defined on a per class basis. Your class needs to define a handler_events package method that returns a list of valid handler events.

Handlers have a higher precedence than callbacks.

$pkg->retrieve_handler($event_name)

Returns the handler (object) associated with $event_name

$pkg->set_callbacks(\%args)

Register one of more callbacks for your document.

Callbacks are like handlers except that they are code references instead of SAX2 thingies.

A code reference might be used to munge the link value of an item into a URI suitable for viewing in a web browser.

Valid events are defined on a per class basis. Your class needs to define a callback_events package method that returns a list of valid callback events.

Callbacks have a lower precedence than handlers.

$pkg->retrieve_callback($event_name)

Return the callback (code reference) associated with $event_name.

$pkg->generate_id()

Returns an MD5 hash of the path, relative to the root, for the current file

$pkg->build_uri(\%data)

Returns the absolute path for the current document.

$pkg->make_link(\%data)

Returns the output of $pkg->build_uri.

If your program has defined a link callback (see above) then the output will be filtered through the callback before being returned your program.

$pkg->on_enter_start_element(\%data)

This method should be called as the first action in your class' start_element method. It will perform a number of helper actions, like keeping track of the current node level and the absolute path of the current document.

Additionalllly it will check to see if the current node should be included or excluded based on rules defined by XML::Filter::XML_Directory_Pruner.

Returns true if everything is honky-dorry.

Returns false if the current node is to be excluded or if the document has not "started" (see docs for the start_level method.)

$pkg->on_enter_end_element(\%data)

$pkg->on_exit_end_element(\%data)

This method should be called as the first action in your class' end_element method.

$pkg->on_characters(\%data)

This method should be called as the first action in your class' characters method.

VERSION ^

1.4.4

DATE ^

July 22, 2002

AUTHOR ^

Aaron Straup Cope

TO DO ^

SEE ALSO ^

XML::Directory::SAX

XML::Filter::XML_Directory_Pruner

LICENSE ^

Copright (c) 2002, Aaron Straup Cope. All Rights Reserved.

This is free software, you may use it and distribute it under the same terms as Perl itself.

syntax highlighting: