Robin Berjon > XML-XPathExt-0.01_01 > XML::XPathExt

Download:
XML-XPathExt-0.01_01.tar.gz

Dependencies

Annotate this POD

Module Version: 0.01_01   Source  

NAME ^

XML::XPathExt - Common XPath extension framework

SYNOPSIS ^

  package XML::XPathExt::MyCoolExtension;
  use base 'XML::XPathExt';

  my $ns = "http://perl-xml-rocks.org/java-xml-sucks/";
  our @EXTENSIONS = ( [ $ns, 'func1', \&my_func1 ],
                      [ $ns, 'func2', \&my_func2 ],
                      [ $ns, 'func3', \&my_func3 ],);

   # your functions...

WARNING, HEY, WARNING, YES YOU ^

THIS IS EVEN BEFORE AN ALPHA, IT IS A PROOF OF CONCEPT THAT HAS NOT BEEN TESTED.

SURGEON GENERAL WARNING: SMOKING PRE-ALPHA MODULES IN PRODUCTION MAY ENSURE JOB SECURITY OF CONSULTANTS.

USING THIS YOU ARE IN THE DARK, YOU MAY BE EATEN BY A GRUE.

DESCRIPTION ^

This is a simple module, the goal of which is to help make XPath extensions consistent in such a way that they work with both XML::LibXSLT and XML::XPathContext.

I would very much like to support other modules, but that will require more work (mostly around having factory methods that do the right thing to convert to the right objects, which is simple enough but long -- patches welcome).

Your modules implementing XPath extensions should inherit from this class. It will do two things for them: if c<XML::LibXSLT> is present, when your class is loaded its extensions will be registered automatically; and you will inherit a registerOnContext method that when called with an XML::XPathContext context object will register all your extensions on it (it can't be done automatically as for XML::LibXSLT because and instance of the class is required).

There's a special variable that should exist and be publically available in your package called @EXTENSIONS. It is an array containing arrayrefs. The synopsis should be pretty clear (hopefully) but in case it is not, each of those arrayrefs contains three items: the namespace URI, the name of the extension function, and a reference to its Perl implementation. Behaviour of extension functions with no defined namespace is not guaranteed and even if it works for you it may very well blow up in other cases. So it is quite a bad idea to not use a namespace.

GRATUITOUS PONTIFICATING ^

It is recommended that your extension modules be under the XML::XPathExt::* hierarchy, though of course if you have good reasons to put them elsewhere you are totally free to do as you wish.

It is also STRONGLY recommended that the namespace you choose for your extensions be an http: URI, and not something much harder to retrieve such as a URN. The reason for this is that in the close future (as of this writing, in August 2003) it is likely that the W3C will publish a Note on RDDL indicating documents to be put at the end of a namespace URI. Interesting things that could be useful for this module could be discovered through such a mechanism, using the XML::RDDL module.

Also, if you wish to make your namespace URIs easy to remember for your users, I suggest you use the form http://xmlns.perl.org/xpath/MyExtension/ where MyExtension matches the one in XML::XPathExt::MyExtension. The xmlns.perl.org has already been registered with the perl.org admin (thanks!) and should RDDL be published then a corresponding server will be made available to the community shortly thereafter to simply RDDL publishing.

AUTHOR ^

Robin Berjon, <robin.berjon@expway.fr>

COPYRIGHT AND LICENSE ^

Copyright 2003 by Robin Berjon

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

syntax highlighting: