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

• The name of an attribute

• The value of an attribute

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 :

• Must inherit from XML::SAX::Base.

• It must define a parse_uri method.

 # 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

• Investigate mucking with the symbol table to hide having to call the various on_foo_bar methods.

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.

cpanm XML::Filter::XML_Directory_2::Base

perl -MCPAN -e shell
install XML::Filter::XML_Directory_2::Base