This is Info file pm.info, produced by Makeinfo version 1.68 from the input file bigpm.texi.  File: pm.info, Node: XML/Grove/PerlSAX, Next: XML/Grove/Sub, Prev: XML/Grove/Path, Up: Module List an PerlSAX event interface for XML objects ****************************************** NAME ==== XML::Grove::PerlSAX - an PerlSAX event interface for XML objects SYNOPSIS ======== use XML::Grove::PerlSAX; $parser = XML::Grove::PerlSAX->new( [OPTIONS] ); $result = $parser->parse( [OPTIONS] ); # or $result = $xml_object->parse( [OPTIONS] ); DESCRIPTION =========== `XML::Grove::PerlSAX' is a PerlSAX parser that generates PerlSAX events from XML::Grove objects. This man page summarizes the specific options, handlers, and properties supported by `XML::Grove::PerlSAX'; please refer to the PerlSAX standard in ``PerlSAX.pod'' for general usage information. METHODS ======= new Creates a new parser object. Default options for parsing, described below, are passed as key-value pairs or as a single hash. Options may be changed directly in the parser object unless stated otherwise. Options passed to `parse()' override the default options in the parser object for the duration of the parse. parse Parses a document. Options, described below, are passed as key-value pairs or as a single hash. Options passed to `parse()' override default options in the parser object. OPTIONS ======= The following options are supported by `XML::Grove::PerlSAX': Handler default handler to receive events DocumentHandler handler to receive document events Source hash containing the input source for parsing If no handlers are provided then all events will be silently ignored. If a single grove argument is passed to the `parse()' method, it is treated as if a `Source' option was given with a ``Grove'' parameter. The `Source' hash may contain the following parameters: Grove The grove object used to generate parse events.. HANDLERS ======== The following events are generated by `XML::Grove::PerlSAX'. XML::Grove::PerlSAX passes the corresponding grove object as it's parameter so the properties passed to the handler are those that were used to create or were assigned to the grove. Please see the docs for the parser used to create the grove for a list of properties that were provided. DocumentHandler methods ----------------------- start_document Receive notification of the beginning of a document. This is called from the XML::Grove::Document object before processing any document content. end_document Receive notification of the end of a document. This is called from the XML::Grove::Document object after processing all document content. start_element Receive notification of the beginning of an element. This is called from the XML::Grove::Element object before processing any element content. end_element Receive notification of the end of an element. This is called from the XML::Grove::Element object after processing all element content. characters Receive notification of character data. This is called from the XML::Grove::Characters object. processing_instruction Receive notification of a processing instruction. This is called from the XML::Grove::PI object. comment Receive notification of a comment. This is called from the XML::Grove::Comment object. AUTHOR ====== Ken MacLeod, ken@bitsko.slc.ut.us SEE ALSO ======== perl(1), XML::Grove(3) Extensible Markup Language (XML)  File: pm.info, Node: XML/Grove/Sub, Next: XML/Grove/Subst, Prev: XML/Grove/PerlSAX, Up: Module List run a filter sub over a grove ***************************** NAME ==== XML::Grove::Sub - run a filter sub over a grove SYNOPSIS ======== use XML::Grove::Sub; # Using filter method on XML::Grove::Document or XML::Grove::Element: @results = $grove_object->filter(\&sub [, ...]); # Using an XML::Grove::Sub instance: $filterer = XML::Grove::Sub->new(); @results = $grove_object->accept($filterer, \&sub [, ...]); DESCRIPTION =========== `XML::Grove::Sub' executes a sub, the filter, over all objects in a grove and returns a list of all the return values from the sub. The sub is called with the grove object as it's first parameter and passing the rest of the arguments to the call to ``filter()'' or `accept()'. EXAMPLE ======= The following filter will return a list of all `foo' or `bar' elements with an attribute ``widget-no'' beginning with `A' or `B'. @results = $grove_obj->filter(sub { my $obj = shift; if ($obj->isa('XML::Grove::Element') && (($obj->{Name} eq 'foo') || ($obj->{Name} eq 'bar')) && ($obj->{Attributes}{'widget-no'} =~ /^[AB]/)) { return ($obj); } return (); }); AUTHOR ====== Ken MacLeod, ken@bitsko.slc.ut.us SEE ALSO ======== perl(1), XML::Grove(3), Data::Grove::Visitor(3) Extensible Markup Language (XML)  File: pm.info, Node: XML/Grove/Subst, Next: XML/Grove/Visitor, Prev: XML/Grove/Sub, Up: Module List substitute values into a template ********************************* NAME ==== XML::Grove::Subst - substitute values into a template SYNOPSIS ======== use XML::Grove::Subst; # Using subst method on XML::Grove::Document or XML::Grove::Element: $new_grove = $source_grove->subst( ARGS ); $new_grove = $source_grove->subst_hash( ARG ); # Using an XML::Grove::Subst instance: $subster = XML::Grove::Subst->new(); $new_grove = $subster->subst( $source_grove, ARGS ); $new_grove = $subster->subst_hash( $source_grove, ARG ); DESCRIPTION =========== `XML::Grove::Subst' implements XML templates. `XML::Grove::Subst' traverses through a source grove replacing all elements with names ``SUB:XXX'' or ``SUB:key'' with their corresponding values from ARGS (a list) or ARG (a hash), repsectively. METHODS ======= $grove_obj->subst( ARGS ) =item $subster->subst( $grove_obj, ARGS ) Search for ``SUB:*XXX*'' elements, where XXX is an array index, and replace the element with the value from ARGS, a list of values. The return value is a new grove with the substitutions applied. $grove_obj->subst_hash( ARG ) =item $subster->subst_hash( $grove_obj, ARG ) Search for ``SUB:key'' elements and replace the element with the value from ARG, a hash of values. The hash key is taken from the `key' attribute of the ``SUB:key'' element, for example, ``''. The return value is a new grove with the substitutions applied. EXAMPLE ======= The following template, in a file ``template.xml'', could be used for a simple parts database conversion to HTML: <SUB:key key='Name'>

Information for part number :

To use this template you would first parse it and convert it to a grove, and then use ``subst_hash()'' every time you needed a new page: use XML::Parser::PerlSAX; use XML::Grove; use XML::Grove::Builder; use XML::Grove::Subst; use XML::Grove::PerlSAX; use XML::Handler::XMLWriter; # Load the template $b = XML::Grove::Builder->new(); $p = XML::Parser::PerlSAX->new( Handler = $b ); $source_grove = $p->parse( Source => { SystemId => 'template.xml' } ); # Apply the substitutions $new_grove = $source_grove->subst_hash( { Name => 'Acme DCX-2000 Filter', Number => 'N4728', Description => 'The Best' } ); # Write the new grove to standard output $w = XML::Handler::XMLWriter->new(); $wp = XML::Grove::PerlSAX->new( Handler => $w ); $wp->parse( Source => { Grove => $new_grove } ); AUTHOR ====== Ken MacLeod, ken@bitsko.slc.ut.us SEE ALSO ======== perl(1), XML::Grove(3) Extensible Markup Language (XML)  File: pm.info, Node: XML/Grove/Visitor, Next: XML/Grove/XPointer, Prev: XML/Grove/Subst, Up: Module List add visitor/callback methods to XML objects ******************************************* NAME ==== XML::Grove::Visitor - add visitor/callback methods to XML objects SYNOPSIS ======== use XML::Grove::Visitor; @results = $xml_object->accept ($visitor, ...); @results = $xml_object->accept_name ($visitor, ...); @results = $xml_object->children_accept ($visitor, ...); @results = $xml_object->children_accept_name ($visitor, ...); @results = $element->attr_accept ($attr, $visitor, ...); DESCRIPTION =========== XML::Grove::Visitor adds visitor methods (callbacks) to XML objects and their iterators. A "visitor" is a class (a package) that has methods (subs) corresponding to the objects in the classes being visited. You use the visitor methods by creating an instance of your visitor class, and then calling ``accept($my_visitor)'' on the top-most object you want to visit, that object will in turn call your visitor back with ``visit_*OBJECT*'', where OBJECT is the type of object. There are several forms of `accept'. Simply calling `accept' calls your package back using the object type of the object you are visiting. Calling ``accept_name'' on an element object calls you back with ``visit_name_*NAME*'' where NAME is the tag name of the element, on all other objects it's as if you called `accept'. All of the forms of `accept' return a concatenated list of the result of all `visit' methods. ``children_accept'' calls `accept' on each of the children of the element. This is generally used in element callbacks to recurse down into the element's children, you don't need to get the element's contents and call `accept' on each item. ``children_accept_name'' does the same but calling ``accept_name'' on each of the children. ``attr_accept'' calls `accept' on each of the objects in the named attribute. If the child object you are visiting is a Perl scalar, you will be called back with ``visit_scalar''. The complete list of callbacks defined by XML::Grove::Visitor are: visit_grove visit_element visit_entity visit_pi visit_comment visit_scalar When using `accept' methods with an iterator, the child objects you get called back with will also be iterators, including ``visit_scalar''. See also the examples ``visitor.pl'' and ``my-html.pl''. HMM === These are random ideas that haven't been implemented yet: * Some people like their subs a little simpler, i.e. drop the ``visit_''. In SGML::Grove, tag names were called back with the SGML equivalent, ``visit_gi_*NAME*'' (generic identifier). Both of these could possibly be made into options. * Several objects fall into subclasses, or you may want to be able to subclass a visited object and still be able to tell the difference. In SGML::Grove I had used the package name in the callback (``visit_SGML_Element'') instead of a generic name (``visit_element''). The idea here would be to try calling ``visit_*PACKAGE*'' with the most specific class first, then try superclasses, and lastly to try the generic. AUTHOR ====== Ken MacLeod, ken@bitsko.slc.ut.us SEE ALSO ======== perl(1), XML::Parser(3), XML::Parser::Grove(3). Extensible Markup Language (XML)  File: pm.info, Node: XML/Grove/XPointer, Next: XML/Handler/BuildDOM, Prev: XML/Grove/Visitor, Up: Module List deprecated module once intended for XPointer ******************************************** NAME ==== XML::Grove::XPointer - deprecated module once intended for XPointer SYNOPSIS ======== THIS MODULE IS USED BY XML::Grove::Path, it does not implement any current version of XPointer DESCRIPTION =========== This module implements a very tiny portion of an old draft of XPointer. XML::Grove::Path still uses this module, but both modules will be obsolete when a real XPath and XPointer module become available. AUTHOR ====== Ken MacLeod, ken@bitsko.slc.ut.us SEE ALSO ======== perl(1), XML::Grove(3), XML::Grove::Path(3) Extensible Markup Language (XML)  File: pm.info, Node: XML/Handler/BuildDOM, Next: XML/Handler/CanonXMLWriter, Prev: XML/Grove/XPointer, Up: Module List PerlSAX handler that creates XML::DOM document structures ********************************************************* NAME ==== XML::Handler::BuildDOM - PerlSAX handler that creates XML::DOM document structures SYNOPSIS ======== use XML::Handler::BuildDOM; use XML::Parser::PerlSAX; my $handler = new XML::Handler::BuildDOM (KeepCDATA => 1); my $parser = new XML::Parser::PerlSAX (Handler => $handler); my $doc = $parser->parsefile ("file.xml"); DESCRIPTION =========== XML::Handler::BuildDOM creates *Note XML/DOM: XML/DOM, document structures (i.e. *Note XML/DOM/Document: XML/DOM/Document,) from PerlSAX events. This class used to be called `XML::PerlSAX::DOM' in this node prior to libxml-enno 1.0.1. CONSTRUCTOR OPTIONS ------------------- The XML::Handler::BuildDOM constructor supports the following options: * KeepCDATA => 1 If set to 0 (default), CDATASections will be converted to regular text. * Document => $doc If undefined, start_document will extract it from Element or DocType (if set), otherwise it will create a new XML::DOM::Document. * Element => $elem If undefined, it is set to Document. This will be the insertion point (or parent) for the nodes defined by the following callbacks. * DocType => $doctype If undefined, start_document will extract it from Document (if possible). Otherwise it adds a new XML::DOM::DocumentType to the Document.  File: pm.info, Node: XML/Handler/CanonXMLWriter, Next: XML/Handler/Composer, Prev: XML/Handler/BuildDOM, Up: Module List output XML in canonical XML format ********************************** NAME ==== XML::Handler::CanonXMLWriter - output XML in canonical XML format SYNOPSIS ======== use XML::Handler::CanonXMLWriter; $writer = XML::Handler::CanonXMLWriter OPTIONS; $parser->parse(Handler => $writer); DESCRIPTION =========== `XML::Handler::CanonXMLWriter' is a PerlSAX handler that will return a string or write a stream of canonical XML for an XML instance and it's content. `XML::Handler::CanonXMLWriter' objects hold the options used for writing the XML objects. Options can be supplied when the the object is created, $writer = new XML::Handler::CanonXMLWriter PrintComments => 1; or modified at any time before calling the parser's `parse()' method: $writer->{PrintComments} = 0; OPTIONS ======= IOHandle IOHandle contains a handle for writing the canonical XML to. If an IOHandle is not provided, the canonical XML string will be returned from `parse()'. PrintComments By default comments are not written to the output. Setting comment to a true value will include comments in the output. AUTHOR ====== Ken MacLeod, ken@bitsko.slc.ut.us SEE ALSO ======== perl(1), PerlSAX James Clark's Canonical XML definition  File: pm.info, Node: XML/Handler/Composer, Next: XML/Handler/PrintEvents, Prev: XML/Handler/CanonXMLWriter, Up: Module List Another XML printer/writer/generator ************************************ NAME ==== XML::Handler::Composer - Another XML printer/writer/generator SYNOPSIS ======== use XML::Handler::Composer; my $composer = new XML::Handler::Composer ( [OPTIONS] ); DESCRIPTION =========== XML::Handler::Composer is similar to XML::Writer, XML::Handler::XMLWriter, XML::Handler::YAWriter etc. in that it generates XML output. This implementation may not be fast and it may not be the best solution for your particular problem, but it has some features that may be missing in the other implementations: * Supports every output encoding that *Note XML/UM: XML/UM, supports *Note XML/UM: XML/UM, supports every encoding for which there is a mapping file in the *Note XML/Encoding: XML/Encoding, distribution. * Pretty printing When used with *Note XML/Filter/Reindent: XML/Filter/Reindent,. * Fine control over which kind of quotes are used See options below. * Supports PerlSAX interface Constructor Options =================== * EndWithNewline (Default: 1) Whether to print a newline at the end of the file (i.e. after the root element) * Newline (Default: undef) If defined, which newline to use for printing. (Note that XML::Parser etc. convert newlines into "\x0A".) If undef, newlines will not be converted and XML::Handler::Composer will use "\x0A" when printing. A value of "\n" will convert the internal newlines into the platform specific line separator. See the PreserveWS option in the characters event (below) for finer control over when newline conversion is active. * DocTypeIndent (Default: a Newline and 2 spaces) Newline plus indent that is used to separate lines inside the DTD. * IndentAttList (Default: 8 spaces) Indent used when printing an declaration that has more than one attribute definition, e.g. * Quote (Default: { XMLDecl => '"', Attr => '"', Entity => '"', SystemLiteral => '"' }) Quote contains a reference to a hash that defines which quoting characters to use when printing XML declarations (XMLDecl), attribute values (Attr), values (Entity) and system/public literals (SystemLiteral) as found in , declarations etc. * PrintDefaultAttr (Default: 0) If 1, prints attribute values regardless of whether they are default attribute values (as defined in declarations.) Normally, default attributes are not printed. * Encoding (Default: undef) Defines the output encoding (if specified.) Note that future calls to the xml_decl() handler may override this setting (if they contain an Encoding definition.) * EncodeUnmapped (Default: \&XML::UM::encode_unmapped_dec) Defines how Unicode characters not found in the mapping file (of the specified encoding) are printed. By default, they are converted to decimal entity references, like '{' Use \&XML::UM::encode_unmapped_hex for hexadecimal constants, like '«' * Print (Default: sub { print @_ }, which prints to stdout) The subroutine that is used to print the encoded XML output. The default prints the string to stdout. Method: get_compressed_element_suffix ($event) ============================================== Override this method to support the different styles for printing empty elements in compressed notation, e.g.

,

,

,

. The default returns "/>", which results in

. Use " />" for XHTML style elements or ">" for certain HTML style elements. The $event parameter is the hash reference that was received from the start_element() handler. Extra PerlSAX event information =============================== XML::Handler::Composer relies on hints from previous SAX filters to format certain parts of the XML. These SAX filters (e.g. XML::Filter::Reindent) pass extra information by adding name/value pairs to the appropriate PerlSAX events (the events themselves are hash references.) * entity_reference: Parameter => 1 If Parameter is 1, it means that it is a parameter entity reference. A parameter entity is referenced with %ent; instead of &ent; and the entity declaration starts with instead of NOTE: This should be added to the PerlSAX interface! * start_element/end_element: Compress => 1 If Compress is 1 in both the start_element and end_element event, the element will be printed in compressed form, e.g. instead of . * start_element: PreserveWS => 1 If newline conversion is active (i.e. Newline was defined in the constructor), then newlines will *NOT* be converted in text (character events) within this element. * attlist_decl: First, MoreFollow The First and MoreFollow options can be used to force successive declarations for the same element to be merged, e.g. In this example, the attlist_decl event for foo should contain (First => 1, MoreFollow => 1) and the event for bar should contain (MoreFollow => 1). The quux event should have no extra info. 'First' indicates that the event is the first of a sequence. 'MoreFollow' indicates that more events will follow in this sequence. If neither option is set by the preceding PerlSAX filter, each attribute definition will be printed as a separate line. CAVEATS ======= This code is highly experimental! It has not been tested well and the API may change. AUTHOR ====== Send bug reports, hints, tips, suggestions to Enno Derksen at <`enno@att.com'>.  File: pm.info, Node: XML/Handler/PrintEvents, Next: XML/Handler/PyxWriter, Prev: XML/Handler/Composer, Up: Module List Prints PerlSAX events (for debugging) ************************************* NAME ==== XML::Handler::PrintEvents - Prints PerlSAX events (for debugging) SYNOPSIS ======== use XML::Handler::PrintEvents; my $pr = new XML::Handler::PrintEvents; DESCRIPTION =========== This PerlSAX handler prints the PerlSAX events it receives to STDOUT. It can be useful when debugging PerlSAX filters. It supports all PerlSAX handler including ignorable_whitespace. AUTHOR ====== Send bug reports, hints, tips, suggestions to Enno Derksen at <`enno@att.com'>.  File: pm.info, Node: XML/Handler/PyxWriter, Next: XML/Handler/Sample, Prev: XML/Handler/PrintEvents, Up: Module List convert Perl SAX events to ESIS of Nsgmls or Pyxie. *************************************************** NAME ==== XML::Handler::PyxWriter - convert Perl SAX events to ESIS of Nsgmls or Pyxie. SYNOPSIS ======== use XML::Handler::PyxWriter; $writer = new XML::Handler::PyxWriter OPTIONS; $handler->parse(Handler => $writer); DESCRIPTION =========== XML::Handler::PyxWriter is a Perl SAX module. It generates ESIS of Nsgmls or Pyxie. Behaviour of object is specified when the object is created. OPTIONS ======= ByteStream Output stream object with method "print" (for example, IO::File). SystemId Name of file passed to method "open" of IO::File. If "ByteStream" is defined then "SystemId" is ignored. Default value of "SystemId" is "-". AttrBeforeElement Attributes are before element (1) or after element (0). Default is 1 (before). CompactAttrString Attribute type is absent (1) or present (0). Default is 0 (present). RECOMMENDED VALUES ================== Probably you like to be compatible with Nsgmls or Pyxie. The main difference is that Nsgmls has attributes before element and attribute types. Pyxie has attributes after element and does not have attribute types. By default XML::Parser::PyxWriter uses Nsgmls mode. Recommended values for Nsgmls mode: * AttrBeforeElement = 1 * CompactAttrString = 0 Recommended values for Pyxie mode: * AttrBeforeElement = 0 * CompactAttrString = 1 OUTPUT STREAM ============= XML::Handler::PyxWriter produces these escape sequences: \ \\ [TAB] \011 [LF] \012 [CR] \015 AUTHOR ====== Oleg A. Paraschenko, prof@beta.math.spbu.ru SEE ALSO ======== XML::Parser::PyxParser Home Page, http://beta.math.spbu.ru/~prof/xc/ Nsgmls Pyxie, http://www.pyxie.org/ PerlSAX XML::PYX XML::ESISParser SGMLS  File: pm.info, Node: XML/Handler/Sample, Next: XML/Handler/Subs, Prev: XML/Handler/PyxWriter, Up: Module List a trivial PerlSAX handler ************************* NAME ==== XML::Handler::Sample - a trivial PerlSAX handler SYNOPSIS ======== use XML::Parser::PerlSAX; use XML::Handler::Sample; $my_handler = XML::Handler::Sample->new; XML::Parser::PerlSAX->new->parse(Source => { SystemId => 'REC-xml-19980210.xml' }, Handler => $my_handler); DESCRIPTION =========== `XML::Handler::Sample' is a trivial PerlSAX handler that prints out the name of each event it receives. The source for `XML::Handler::Sample' lists all the currently known PerlSAX handler methods. `XML::Handler::Sample' is intended for Perl module authors who wish to look at example PerlSAX handler modules. `XML::Handler::Sample' can be used as a template for writing your own PerlSAX handler modules. `XML::Handler::Sample' is in the Public Domain and can be used for any purpose without restriction. AUTHOR ====== Ken MacLeod, ken@bitsko.slc.ut.us SEE ALSO ======== perl(1), PerlSAX.pod(3)  File: pm.info, Node: XML/Handler/Subs, Next: XML/Handler/XMLWriter, Prev: XML/Handler/Sample, Up: Module List a PerlSAX handler base class for calling user-defined subs ********************************************************** NAME ==== XML::Handler::Subs - a PerlSAX handler base class for calling user-defined subs SYNOPSIS ======== use XML::Handler::Subs; package MyHandlers; use vars qw{ @ISA }; sub s_NAME { my ($self, $element) = @_ }; sub e_NAME { my ($self, $element) = @_ }; $self->{Names}; # an array of names $self->{Nodes}; # an array of $element nodes $handler = MyHandlers->new(); $self->in_element($name); $self->within_element($name); DESCRIPTION =========== `XML::Handler::Subs' is a base class for PerlSAX handlers. `XML::Handler::Subs' is subclassed to implement complete behavior and to add element-specific handling. Each time an element starts, a method by that name prefixed with `s_' is called with the element to be processed. Each time an element ends, a method with that name prefixed with `e_' is called. Any special characters in the element name are replaced by underscores. Subclassing XML::Handler::Subs in this way is similar to XML::Parser's Subs style. XML::Handler::Subs maintains a stack of element names, ``$self-'{Names}', and a stack of element nodes, ``$self-'{Nodes}>' that can be used by subclasses. The current element is pushed on the stacks before calling an element-name start method and popped off the stacks after calling the element-name end method. The ``in_element()'' and ``within_element()'' calls use these stacks. If the subclass implements ``start_document()'', ``end_document()'', ``start_element()'', and ``end_element()'', be sure to use ``SUPER::'' to call the the superclass methods also. See perlobj(1) for details on SUPER::. ``SUPER::start_element()'' and ``SUPER::end_element()'' return 1 if an element-name method is called, they return 0 if no method was called. XML::Handler::Subs does not implement any other PerlSAX handlers. XML::Handler::Subs supports the following methods: new( OPTIONS ) A basic `new()' method. `new()' takes a list of key, value pairs or a hash and creates and returns a hash with those options; the hash is blessed into the subclass. in_element($name) Returns true if `$name' is equal to the name of the innermost currently opened element. within_element($name) Returns the number of times the `$name' appears in Names. AUTHOR ====== Ken MacLeod, ken@bitsko.slc.ut.us SEE ALSO ======== perl(1), PerlSAX.pod(3)  File: pm.info, Node: XML/Handler/XMLWriter, Next: XML/Handler/YAWriter, Prev: XML/Handler/Subs, Up: Module List a PerlSAX handler for writing readable XML ****************************************** NAME ==== XML::Handler::XMLWriter - a PerlSAX handler for writing readable XML SYNOPSIS ======== use XML::Parser::PerlSAX; use XML::Handler::XMLWriter; $my_handler = XML::Handler::XMLWriter->new( I ); XML::Parser::PerlSAX->new->parse(Source => { SystemId => 'REC-xml-19980210.xml' }, Handler => $my_handler); DESCRIPTION =========== `XML::Handler::XMLWriter' is a PerlSAX handler for writing readable XML (in contrast to Canonical XML, for example). XML::Handler::XMLWriter can be used with a parser to reformat XML, with XML::DOM or XML::Grove to write out XML, or with other PerlSAX modules that generate events. `XML::Handler::XMLWriter' is intended to be used with PerlSAX event generators and does not perform any checking itself (for example, matching start and end element events). If you want to generate XML directly from your Perl code, use the XML::Writer module. XML::Writer has an easy to use interface and performs many checks to make sure that the XML you generate is well-formed. `XML::Handler::XMLWriter' is a subclass of `XML::Handler::Subs'. `XML::Handler::XMLWriter' can be further subclassed to alter it's behavior or to add element-specific handling. In the subclass, each time an element starts, a method by that name prefixed with `s_' is called with the element to be processed. Each time an element ends, a method with that name prefixed with `e_' is called. Any special characters in the element name are replaced by underscores. If there isn't a start or end method for an element, the default action is to write the start or end tag. Start and end methods can use the ``print_start_element()'' and ``print_end_element()'' methods to print start or end tags. Subclasses can call the `print()' method to write additional output. Subclassing XML::Handler::XMLWriter in this way is similar to XML::Parser's Stream style. XML::Handler::Subs maintains a stack of element names, ``$self-'{Names}', and a stack of element nodes, ``$self-'{Nodes}>' that can be used by subclasses. The current element is pushed on the stacks before calling an element-name start method and popped off the stacks after calling the element-name end method. See XML::Handler::Subs for additional methods. In addition to the standard PerlSAX handler methods (see PerlSAX for descriptions), XML::Handler::XMLWriter supports the following methods: new( OPTIONS ) Creates and returns a new instance of XML::Handler::XMLWriter with the given OPTIONS. Options may be changed at any time by modifying them directly in the hash returned. OPTIONS can be a list of key, value pairs or a hash. The following OPTIONS are supported: Output An IO::Handle or one of it's subclasses (such as IO::File), if this parameter is not present and the AsString option is not used, the module will write to standard output. AsString Return the generated XML as a string from the `parse()' method of the PerlSAX event generator. Newlines A true or false value; if this parameter is present and its value is true, then the module will insert an extra newline before the closing delimiter of start, end, and empty tags to guarantee that the document does not end up as a single, long line. If the paramter is not present, the module will not insert the newlines. IsSGML A true or false value; if this parameter is present and its value is true, then the module will generate SGML rather than XML. print_start_element($element) Print a start tag for ``$element''. This is the default action for the PerlSAX ``start_element()'' handler, but subclasses may use this if they define a start method for an element. print_end_element($element) Prints an end tag for ``$element''. This is the default action for the PerlSAX ``end_element()'' handler, but subclasses may use this if they define a start method for an element. print($output) Write ``$output'' to Output and/or append it to the string to be returned. Subclasses may use this to write additional output. TODO ==== * An Elements option that provides finer control over newlines than the Newlines option, where you can choose before and after newline for element start and end tags. Inspired by the Python XMLWriter. * Support Doctype and XML declarations. AUTHOR ====== Ken MacLeod, ken@bitsko.slc.ut.us This module is partially derived from XML::Writer by David Megginson. SEE ALSO ======== perl(1), PerlSAX.pod(3)  File: pm.info, Node: XML/Handler/YAWriter, Next: XML/MetaGenerator, Prev: XML/Handler/XMLWriter, Up: Module List Yet another Perl SAX XML Writer ******************************* NAME ==== XML::Handler::YAWriter - Yet another Perl SAX XML Writer SYNOPSIS ======== use XML::Handler::YAWriter; my $ya = new XML::Handler::YAWriter( %options ); my $perlsax = new XML::Parser::PerlSAX( 'Handler' => $ya ); DESCRIPTION =========== YAWriter implements Yet Another XML::Handler::Writer. The reasons for this one are that I needed a flexible escaping technique, and want some kind of pretty printing. If an instance of YAWriter is created without any options, the default behavior is to produce an array of strings containing the XML in : @{$ya->{Strings}} Options ------- Options are given in the usual 'key' => 'value' idiom. Output IO::File This option tells YAWriter to use an already open file for output, instead of using $ya->{Strings} to store the array of strings. It should be noted that the only thing the object needs to implement is the print method. So anything can be used to receive a stream of strings from YAWriter. AsFile string This option will cause start_document to open named file and end_document to close it. Use the literal dash "-" if you want to print on standard output. AsArray boolean This option will force storage of the XML in $ya->{Strings}, even if the Output option is given. AsString boolean This option will cause end_document to return the complete XML document in a single string. Most SAX drivers return the value of end_document as a result of their parse method. As this may not work with some combinations of SAX drivers and filters, a join of $ya->{Strings} in the controlling method is preferred. Encoding string This will change the default encoding from UTF-8 to anything you like. You should ensure that given data are already in this encoding or provide an Escape hash, to tell YAWriter about the recoding. Escape hash The Escape hash defines substitutions that have to be done to any string, with the exception of the processing_instruction and doctype_decl methods, where I think that escaping of target and data would cause more trouble than necessary. The default value for Escape is $XML::Handler::YAWriter::escape = { '&' => '&', '<' => '<', '>' => '>', '"' => '"', '--' => '--' }; YAWriter will use an evaluated sub to make the recoding based on a given Escape hash reasonably fast. Future versions may use XS to improve this performance bottleneck. Pretty hash Hash of string => boolean tuples, to define kind of prettyprinting. Default to undef. Possible string values: AddHiddenNewline boolean Add hidden newline before ">" AddHiddenAttrTab boolean Add hidden tabulation for attributes CatchEmptyElement boolean Catch empty Elements, apply "/>" compression CatchWhiteSpace boolean Catch whitespace with comments IsSGML boolean This option will cause start_document, processing_instruction and doctype_decl to appear as SGML. The SGML is still well-formed of course, if your SAX events are well-formed. NoComments boolean Supress Comments NoDTD boolean Supress DTD NoPI boolean Supress Processing Instructions NoProlog boolean Supress Prolog NoWhiteSpace boolean Supress WhiteSpace to clean documents from prior pretty printing. PrettyWhiteIndent boolean Add visible indent before any eventstring PrettyWhiteNewline boolean Add visible newlines before any eventstring SAX1 boolean (not yet implemented) Output only SAX1 compliant eventstrings Notes: ------ Correct handling of start_document and end_document is required! The YAWriter Object initialises its structures during start_document and does its cleanup during end_document. If you forget to call start_document, any other method will break during the run. Most likely place is the encode method, trying to eval undef as a subroutine. If you forget to call end_document, you should not use a single instance of YAWriter more than once. For small documents AsArray may be the fastest method and AsString the easiest one to receive the output of YAWriter. But AsString and AsArray may run out of memory with infinite SAX streams. The only method XML::Handler::Writer calls on a given Output object is the print method. So it's easy to use a self written Output object to improve streaming. A single instance of XML::Handler::YAWriter is able to produce more than one file in a single run. Be sure to provide a fresh IO::File as Output before you call start_document and close this File after calling end_document. Or provide a filename in AsFile, so start_document and end_document can open and close its own filehandle. Automatic recoding between 8bit and 16bit does not yet work correctly ! I have Perl-5.00563 at home and here I can specify "use utf8;" in the right places to make recoding work. But I dislike saying "use 5.00555;" because many systems run 5.00503. If you use some 8bit character set internally and want use national characters, either state your character as Encoding to be ISO-8859-1, or provide an Escape hash similar to the following : $ya->{'Escape'} = { '&' => '&', '<' => '<', '>' => '>', '"' => '"', '--' => '--' 'ö' => 'ö' 'ä' => 'ä' 'ü' => 'ü' 'Ö' => 'Ö' 'Ä' => 'Ä' 'Ü' => 'Ü' 'ß' => 'ß' }; You may abuse YAWriter to clean whitespace from XML documents. Take a look at test.pl, doing just that with an XML::Edifact message, without querying the DTD. This may work in 99% of the cases where you want to get rid of ignorable whitespace caused by the various forms of pretty printing. my $ya = new XML::Handler::YAWriter( 'Output' => new IO::File ( ">-" ); 'Pretty' => { 'NoWhiteSpace'=>1, 'NoComments'=>1, 'AddHiddenNewline'=>1, 'AddHiddenAttrTab'=>1, } ); XML::Handler::Writer implements any method XML::Parser::PerlSAX wants. This extends the Java SAX1.0 specification. I have in mind using Pretty=>SAX1=>1 to disable this feature, if abusing YAWriter for a SAX proxy. =head1 AUTHOR Michael Koehne, Kraehe@Copyleft.De Thanks ====== "Derksen, Eduard (Enno), CSCIO" helped me with the Escape hash and gave quite a lot of useful comments. SEE ALSO ======== *Note Perl: (perl.info)perl, and *Note XML/Parser/PerlSAX: XML/Parser/PerlSAX,  File: pm.info, Node: XML/MetaGenerator, Next: XML/Node, Prev: XML/Handler/YAWriter, Up: Module List Collects user input, validates input and generates output in a number of ways based on the defined grammar. *********************************************************************************************************** NAME ==== XML::MetaGenerator - Collects user input, validates input and generates output in a number of ways based on the defined grammar. SYNOPSIS ======== use XML::MetaGenerator; use XML::MetaGenerator::Language::Formula; use XML::MetaGenerator::Language::Formula::Collector::ReadLine; use XML::MetaGenerator::Language::Formula::Generator::HTML; my $wow = XML::MetaGenerator->get_instance(); $wow->setObject('user'); $wow->setLanguage(XML::MetaGenerator::Language::Formula->new()); my $input = XML::MetaGenerator::Language::Formula::Collector::ReadLine->new(); $wow->setCollector($input); my $generator = XML::MetaGenerator::Language::Formula::Generator::HTML->new(); $wow->setGenerator($generator); # now collect the data $wow->collect(); # validate it my ($valids, $missings, $invalids)= $wow->validate(); # generate a document from the collected data; my $page = $wow->generate(); DESCRIPTION =========== This object will work with many kinds of XML specification languages (RELAX, xml-scheme, Formula and so on), using them to catch ('collect') input data from different sources (cgi, command line, files ...), 'validate' it and eventually transforming it into the desired format (e.g. HTML, XML). I use this in order to have a common API for applications that require multiple media access (e.g. WWW and console). Object methods ============== These are the public methods available from MetaGenerator objects get_instance returns the singleton MetaGenerator object setCollector This let the user choose what kind of collector will be used. The only parameter is a XML::MetaGenerator::Collector object. XML::MetaGenerator comes with three prepackaged collectors: Apache - read data from $r params Environment - read data from %ENV ReadLine - read data from terminal using Term::ReadLine setGenerator This let the user choose what kind of output to generate. The parameter is a XML::MetaGenerator::Generator object. The package comes with two prepackaged generator: SimpleHTML - generate a html document consisting of a table with one row for every element in the formula; Also, if the data was validated before calling the generator, invalid elements will be highlighted. XML - generate a basic xml document with XML::Writer. setLanguage This method lets the user choose what kind of grammar to use for validation. Currently XML::MetaGenerator supports just the formula language, for more information on it, refer to XML::MetaGenerator::Formula(3). I hope to be able to add more languages soon (e.g. RELAX and xml-schema). setObject This set the type of objects that MetaGenerator is going to manipulate. The formulae directory holds some sample objects defined through the formula markup language. collect This is the input method for MetaGenerator. It uses the Collector object to get the data from the right input source template This method outputs a dummy object. It's useful for testing or when you have to show how that object will look like. generate This method is used to parse the collected input and to output the desired object in the desired format. validate This method validates the input and returns an hash containing valids, invalids and missing elements. AUTHOR ====== Riccardo Cambiassi SEE ALSO ========  File: pm.info, Node: XML/Node, Next: XML/PPD, Prev: XML/MetaGenerator, Up: Module List Node-based XML parsing: an simplified interface to XML::Parser ************************************************************** NAME ==== XML::Node - Node-based XML parsing: an simplified interface to XML::Parser SYNOPSIS ======== use XML::Node; $xml_node = new XML::Node; $xml_node->register( $nodetype, $callback_type => \&callback_function ); $xml_node->register( $nodetype, $callback_type => \$variable ); open(FOO, 'xmlgenerator |'); $p3->parse(*FOO); close(FOO); $xml_node->parsefile( $xml_filename ); DESCRIPTION =========== If you are only interested in processing certain nodes in an XML file, this module can help you simplify your Perl scripts significantly. The XML::Node module allows you to register callback functions or variables for any XML node. If you register a call back function, it will be called when the node of the type you specified are encountered. If you register a variable, the content of a XML node will be appended to that variable automatically. Subroutine register accepts both absolute and relative node registrations. Here is an example of absolute path registration: 1. register(">TestCase>Name", "start" => \&handle_TestCase_Name_start); Here are examples of single node name registration: 2. register( "Name", "start" => \&handle_Name_start); 3. register( "Name", "end" => \&handle_Name_end); 4. register( "Name", "char" => \&handle_Name_char); Here is an example of attribute registration: 5. register(">TestCase:Author", "attr" => \$testcase_author); Abosolute path trigger condition is recommended because a "Name" tage could appear in different places and stands for differe names. Example: 1 2 Something 3 4 Something 5 6 Statement 1 causes &handle_TestCase_Name_start to be called when parsing Line 2. Statements 2,3,4 cause the three handler subroutines to be called when parsing both Line 2 and Line 4. This module uses XML::Parser. EXAMPLE ======= Examples "test.pl" and "parse_orders.pl" come with this perl module. BUG REPORT ========== Please report bugs to http://belmont-shores.ics.uci.edu/bugzilla SEE ALSO ======== XML::Parser NOTE ==== When you register a variable, XML::Node appends strings found to that variable. So please be sure to clear that variable when needed. AUTHORS ======= Chang Liu LAST MODIFIED ============= $Date: 2000/03/13 11:38:28 $  File: pm.info, Node: XML/PPD, Next: XML/PPMConfig, Prev: XML/Node, Up: Module List PPD file format and XML parsing elements **************************************** NAME ==== XML::PPD - PPD file format and XML parsing elements SYNOPSIS ======== use XML::Parser; use XML::PPD; $p = new XML::Parser( Style => 'Objects', Pkg => 'XML::PPD' ); ... DESCRIPTION =========== This module provides a set of classes for parsing PPD files using the XML::Parser module. Each of the classes is derived from `XML::ValidatingElement', with optional/required attributes/children enforced. MAJOR ELEMENTS ============== SOFTPKG ------- Defines a Perl Package. The root of a PPD document is always a SOFTPKG element. The SOFTPKG element allows for the following attributes: NAME Required attribute. Name of the package (e.g. "Foobar"). VERSION Version number of the package, in comma-delimited format (e.g. "1,0,0,0"). IMPLEMENTATION -------------- Child of SOFTPKG, used to describe a particular implementation of the Perl Package. Multiple instances are valid, and should be used to describe different implementations/ports for different operating systems or architectures. DEPENDENCY ---------- Child of SOFTPKG or IMPLEMENTATION, used to indicate a dependency this Perl Package has on another Perl Package. Multiple instances are valid. The DEPENDENCY element allows for the following attributes: NAME Name of the package that this implementation is dependant upon. VERSION Version number of the dependency, in comma-delimited format (e.g. "1,0,0,0"). MINOR ELEMENTS ============== TITLE ----- Child of SOFTPKG, used to state the title of the Perl Package. Only one instance should be present. ABSTRACT -------- Child of SOFTPKG, used to provide a short description outlining the nature and purpose of the Perl Package. Only one instance should be present. AUTHOR ------ Child of SOFTPKG, used to provide information about the author(s) of the Perl Package. Multiple instances are valid. LANGUAGE -------- Child of IMPLEMENTATION, used to specify the language used within the given implementation of the Perl Package. Only one instance should be present. LICENSE ------- Child of SOFTPKG, indicating the location of the appropriate license agreement or copyright notice for the Perl Package. Only one instance should be present. The LICENSE element allows for the following attributes: HREF Required attribute. A reference to the location of the license agreement or copyright notice for this package. OS -- Child of IMPLEMENTATION, used to outline the operating system required for this implementation of the Perl Package. Multiple instances are valid. Valid values can be taken from the OSD Specification and it's OS element. The OS element allows for the following attributes: VALUE The name of the operating system required for this implementation of the Perl Package. This value should be obtained from Config.pm as 'osname'. Note that previous versions of the PPD format used a 'NAME' attribute. It's use has been deprecated in preference of the 'VALUE' attribute. Also note that during validation, this element will automatically convert any existing 'NAME' attribute to be a 'VALUE' attribute. OSVERSION --------- Child of IMPLEMENTATION, used to outline the required version of the operating system required for this implementation of the Perl Package. Only one instance should be present. The OSVERSION element allows for the following attributes: VALUE The version of the operating system required for installation of this implementation of the package, in a comma-delimited format (e.g. "3,1,0,0"). Note that previous versions of the PPD format used a 'NAME' attribute. It's use has been deprecated in preference of the 'VALUE' attribute. Also note that during validation, this element will automatically convert any existing 'NAME' attribute to be a 'VALUE' attribute. PERLCORE -------- Child of IMPLEMENTATION, used to specify the minimum version of the Perl core distribution that this Perl Package is to be used with. Only one instance should be present. The PERLCORE element allows for the following attributes: VERSION Version of the Perl core that is required for this implementation of the Perl Package. PROCESSOR --------- Child of IMPLEMENTATION, outlining the cpu required for this implementation of the Perl Package. Only one instance should be present. The PROCESSOR element allows for the following attributes: VALUE CPU required for the installation of this implementation of the Perl Package. The following values are all valid according to the OSD Specification: x86 alpha mips sparc 680x0 Note that previous versions of the PPD format used a 'NAME' attribute. It's use has been deprecated in preference of the 'VALUE' attribute. Also note that during validation, this element will automatically convert any existing 'NAME' attribute to be a 'VALUE' attribute. CODEBASE -------- Child of IMPLEMENTATION, indicating a location where an archive of the Perl Package can be retrieved. Multiple instances are valid, and can be used to indicate multiple possible locations where the same version of the Perl Package can be retrieved. The CODEBASE element allows for the following attributes: FILENAME ??? HREF Required attribute. A reference to the location of the Perl Package distribution. INSTALL ------- Child of IMPLEMENTATION, used to provide either a reference to an installation script or a series of commands which can be used to install the Perl Package once it has been retrieved. If the EXEC attribute is not specified, the value is assumed to be one or more commands, separated by `;;'. Each such command will be executed by the Perl `system()' function. Only one instance should be present. The INSTALL element allows for the following attributes: HREF Reference to an external script which should be retrieved and run as part of the installation process. Both filenames and URLs should be considered valid. EXEC Name of interpreter/shell used to execute the installation script. If the value of EXEC is `PPM_PERL', the copy of Perl that is executing PPM itself ($^X) is used to execute the install script. UNINSTALL --------- Child of IMPLEMENTATION, used to provide either a reference to an uninstallation script or a raw Perl script which can be used to uninstall the Perl Package at a later point. Only one instance should be present. The UNINSTALL element allows for the following attributs: HREF Reference to an external script which should be retrieved and run as part of the removal process. Both filenames and URLs should be considered valid. EXEC Name of interpreter/shell used to execute the uninstallation script. If the value of EXEC is `PPM_PERL', the copy of Perl that is executing PPM itself ($^X) is used to execute the install script. DOCUMENT TYPE DEFINITION ======================== The DTD for PPD documents is available from the ActiveState website and the latest version can be found at http://www.ActiveState.com/PPM/DTD/ppd.dtd This revision of the `XML::PPD' module implements the following DTD: SAMPLE PPD FILE =============== The following is a sample PPD file describing the `Math-MatrixBool' module. Note that this may not be a current/proper description of this module and is for sample purposes only. Math-MatrixBool Easy manipulation of matrices of booleans (Boolean Algebra) Steffen Beyer (sb@sdm.de) system("make"); ;; system("make test"); ;; system("make install"); ;; KNOWN BUGS/ISSUES ================= Elements which are required to be empty (e.g. LICENSE) are not enforced as such. Notations above about elements for which "only one instance" or "multiple instances" are valid are not enforced; this primarily a guideline for generating your own PPD files. AUTHORS ======= Graham TerMarsch Murray Nesbitt Dick Hardt HISTORY ======= v0.1 - Initial release SEE ALSO ======== `XML::ValidatingElement' in this node, *Note XML/Element: XML/Element,, *Note XML/Parser: XML/Parser,, OSD Specification (http://www.microsoft.com/standards/osd/)