xml_pp - xml pretty-printer

XML pretty-print using XML::Twig.

xml_grep - grep XML files looking for specific elements

"xml_grep" does a grep on XML files. Instead of using regular expressions it uses XPath expressions (in fact the subset of XPath supported by XML::Twig).

xml_split - cut a big XML file into smaller chunks

"xml_split" takes a (presumably big) XML file and split it in several smaller files, based on various criteria (level in the tree, size or an XPath expression).

xml_merge - merge back XML files split with xml_split

"xml_merge" takes several xml files that have been split using "xml_split" and recreates a single file.

xml_spellcheck - spellcheck XML files

"xml_spellcheck" lets you spell-check the contents of an XML file. It extracts the text (the content of elements and optionally of attributes), call a spell checker on it, then recreates the XML document.

Loading an XML document and processing it

  my $t= XML::Twig->new();
  $t->parse( '<d><title>title</title><para>p 1</para><para>p 2</para></d>');
  my $root= $t->root;
  $root->set_tag( 'html');              # change doc to html
  $title= $root->first_child( 'title'); # get the title
  $title->set_tag( 'h1');               # turn it into h1
  my @para= $root->children( 'para');   # get the para children
  foreach my $para (@para)
    { $para->set_tag( 'p'); }           # turn them into p
  $t->print;                            # output the document

Other useful methods include:

att: "$elt->att( 'foo')" return the "foo" attribute for an element,

set_att : "$elt->set_att( foo => "bar")" sets the "foo" attribute to the "bar" value,

next_sibling: "$elt->next_sibling" return the next sibling in the document (in the example "$title->next_sibling" is the first "para", you can also (and actually should) use "$elt->next_sibling( 'para')" to get it.

The document can also be transformed through the use of the cut, copy, paste and move methods: "$title->cut; $title->paste( after => $p);" for example.

And much, much more, see XML::Twig::Elt.

Processing an XML document chunk by chunk

One of the strengths of XML::Twig is that it lets you work with files that do not fit in memory. Storing an XML document in memory as a tree is quite memory-expensive; the expansion factor being often around 10x.

To do this, you can define handlers that will be called once a specific element has been completely parsed (closed). In these handlers, you can access the element and process it as you see fit, using the navigation and the cut/copy/paste methods, plus lots of convenient ones like "prefix ". Once the element is completely processed, you can then "flush " it, which outputs the element and frees its memory. You can also "purge " it if you don't need to output it (if you are just extracting some data from the document for example). The handler will be called again once the next relevant element has been parsed.

  my $t= XML::Twig->new( twig_handlers =>
                          { section => \&section,
                            para   => sub { $_->set_tag( 'p'); }
                          },
                       );
  $t->parsefile( 'doc.xml');
  # the handler is called once a section is completely parsed, ie when
  # the end tag for section is found, it receives the twig itself and
  # the element (including all its sub-elements) as arguments
  sub section
    { my( $t, $section)= @_;      # arguments for all twig_handlers
      $section->set_tag( 'div');  # change the tag name
      # let's use the attribute nb as a prefix to the title
      my $title= $section->first_child( 'title'); # find the title
      my $nb= $title->att( 'nb'); # get the attribute
      $title->prefix( "$nb - ");  # easy isn't it?
      $section->flush;            # outputs the section and frees memory
    }

When a handler is called, $_ contains the element matched by the handler.

You can trigger handlers on more elaborate conditions. This handler matches only "title" elements that are in in "section" elements:

  my $t= XML::Twig->new( twig_handlers =>
                           { 'section/title' => sub { $_->print } }
                       )
                  ->parsefile( 'doc.xml');

Here "sub { $_->print }" simply prints the current element.

Handlers can also test for the presence or content of attributes:

  my $t= XML::Twig->new( twig_handlers =>
                      { 'section[@level="1" or @force]' => sub { $_->print } }
                       );
                  ->parsefile( 'doc.xml');

You can also use "start_tag_handlers " to process an element as soon as the start tag is found.

Processing just parts of an XML document

The twig_roots mode builds only the required sub-trees from the document. Anything outside of the twig roots is ignored:

  my $t= XML::Twig->new(
       # the twig will include just the root and selected titles
           twig_roots   => { 'section/title' => \&print_n_purge,
                             'annex/title'   => \&print_n_purge
           }
                      );
  $t->parsefile( 'doc.xml');
  sub print_n_purge
    { my( $t, $elt)= @_;
      print $elt->text;    # print the text (including sub-element texts)
      $t->purge;           # frees the memory
    }

You can use that mode when you want to process parts of a documents but are not interested in the rest and you don't want to pay the price, either in time or memory, to build the tree for the it.

Building an XML filter

You can combine the "twig_roots" and the "twig_print_outside_roots" options to build filters, which let you modify selected elements and output the rest of the document as-is.

This would convert prices in $ to prices in Euro in a document:

  my $t= XML::Twig->new(
           twig_roots   => { 'price' => \&convert, },   # process prices
           twig_print_outside_roots => 1,               # print the rest
                      );
  $t->parsefile( 'doc.xml');
  sub convert
    { my( $t, $price)= @_;
      my $currency=  $price->att( 'currency');          # get the currency
      if( $currency eq 'USD')
        { $usd_price= $price->text;                     # get the price
          # %rate is just a conversion table
          my $euro_price= $usd_price * $rate{usd2euro};
          $price->set_text( $euro_price);               # set the new price
          $price->set_att( currency => 'EUR');          # don't forget this!
        }
      $price->print;                                    # output the price
    }

XML::Twig and various versions of Perl, XML::Parser and expat:

XML::Twig is a lot more sensitive to variations in versions of perl, XML::Parser and expat than to the OS, so this should cover some reasonable configurations.

The "recommended configuration" is perl 5.10.0+ (for good Unicode support), XML::Parser 2.31+, and expat 1.95.5+.

See <http://testers.cpan.org/search?request=dist&dist=XML-Twig> for the CPAN testers reports on XML::Twig, which list all tested configurations.

An Atom feed of the CPAN Testers results is available at <http://xmltwig.org/rss/twig_testers.rss>.

Finally:

XML::Twig does NOT work with expat 1.95.4.

XML::Twig only works with XML::Parser 2.27 in perl 5.10.0+.

Note that I can't compile XML::Parser 2.27 anymore, so I can't guarantee that it still works.

XML::Parser 2.28 does not really work.

When in doubt, upgrade expat, XML::Parser, and Scalar::Util.

Finally, for some optional features, XML::Twig depends on some additional modules. The complete list, which depends somewhat on the version of Perl that you are running, is given by running "t/zz_dump_config.t".

XML::Twig

A twig is a subclass of XML::Parser, so all XML::Parser methods can be called on a twig object, including parse and parsefile. "setHandlers" on the other hand cannot be used, see "BUGS ".

new

This is a class method, the constructor for XML::Twig. Options are passed as keyword-value pairs. Recognized options are the same as XML::Parser, plus some (in fact a lot!) XML::Twig specifics.

New Options:

  para => sub { $_->set_tag( 'p'); }

parse ( $source)

The $source parameter should either be a string containing the whole XML document, or it should be an open "IO::Handle" (aka a filehandle).

A "die" call is thrown if a parse error occurs. Otherwise, it returns the twig built by the parse. Use "safe_parse" if you want the parsing to return even when an error occurs.

If this method is called as a class method ("XML::Twig->parse( $some_xml_or_html)") then an XML::Twig object is created, using the parameters except the last one (eg "XML::Twig->parse( pretty_print => 'indented', $some_xml_or_html)") and "xparse " is called on it.

Note that when parsing a filehandle, the handle should NOT be open with an encoding (ie open with "open( my $in, '<', $filename)". The file will be parsed by "expat", so specifying the encoding actually causes problems for the parser (as in: it can crash it, see https://rt.cpan.org/Ticket/Display.html?id=78877). For parsing a file it is actually recommended to use "parsefile" on the file name, instead of <parse> on the open file.

parsestring

Same as "parse" (for backwards compatibility).

parsefile (FILE [, OPT => OPT_VALUE [...]])

Opens "FILE" for reading, then calls "parse" with the open handle. The file is closed no matter how "parse" returns.

A "die" call is thrown if a parse error occurs. Otherwise it returns the twig built by the parse. Use "safe_parsefile" if you want the parsing to return even when an error occurs.

parsefile_inplace ( $file, $optional_extension)

Parses and updates a file "in place". It does this by creating a temporary file, selecting it as the default for print() statements (and methods), then parsing the input file. If the parsing is successful, then the temporary file is moved to replace the input file.

If an extension is given, then the original file is backed-up (the rules for the extension are the same as the rule for the -i option in perl).

parsefile_html_inplace ( $file, $optional_extension)

Same as parsefile_inplace, except that it parses HTML instead of XML.

parseurl ($url $optional_user_agent)

Gets the data from $url and parses it. The data is piped to the parser in chunks the size of the XML::Parser::Expat buffer, so memory consumption and hopefully speed are optimal.

For most (read "small") XML it is probably as efficient (and easier to debug) to just "get" the XML file and then parse it as a string:

  use XML::Twig;
  use LWP::Simple;
  my $twig= XML::Twig->new();
  $twig->parse( LWP::Simple::get( $URL ));
    

or:

  use XML::Twig;
  my $twig= XML::Twig->nparse( $URL);
    

If the $optional_user_agent argument is given, then it is used, otherwise a new one is created.

safe_parse ( SOURCE [, OPT => OPT_VALUE [...]])

This method is similar to "parse" except that it wraps the parsing in an "eval" block. It returns the twig on success and 0 on failure (the twig object also contains the parsed twig). $@ contains the error message on failure.

Note that the parsing still stops as soon as an error is detected, there is no way to keep going after an error.

safe_parsefile (FILE [, OPT => OPT_VALUE [...]])

This method is similar to "parsefile" except that it wraps the parsing in an "eval" block. It returns the twig on success and 0 on failure (the twig object also contains the parsed twig) . $@ contains the error message on failure.

Note that the parsing still stops as soon as an error is detected; there is no way to keep going after an error.

safe_parseurl ($url $optional_user_agent)

Same as "parseurl" except that it wraps the parsing in an "eval" block. It returns the twig on success and 0 on failure (the twig object also contains the parsed twig) . $@ contains the error message on failure.

parse_html ($string_or_fh)

Parse an HTML string or file handle (by converting it to XML using HTML::TreeBuilder, which needs to be available).

This works nicely, but some information gets lost in the process: newlines are removed, and (at least on the version I use) comments get an extra CDATA section inside ( <!-- foo --> becomes <!-- <![CDATA[ foo ]]> -->.

parsefile_html ($file)

Parse an HTML file (by converting it to XML using HTML::TreeBuilder, which needs to be available, or HTML::Tidy if the "use_tidy" option was used). The file is loaded completely in memory and converted to XML before being parsed.

This method should be used with caution though, as it doesn't know about the file encoding. It is usually better to use "parse_html ", which gives you a chance to open the file with the proper encoding layer.

parseurl_html ($url $optional_user_agent)

Parses an URL as HTML the same way "parse_html " does.

safe_parseurl_html ($url $optional_user_agent)

Same as "parseurl_html "> except that it wraps the parsing in an "eval" block. It returns the twig on success and 0 on failure (the twig object also contains the parsed twig). $@ contains the error message on failure.

safe_parsefile_html ($file $optional_user_agent)

Same as "parsefile_html "> except that it wraps the parsing in an "eval" block. It returns the twig on success and 0 on failure (the twig object also contains the parsed twig). $@ contains the error message on failure.

safe_parse_html ($string_or_fh)

Same as "parse_html " except that it wraps the parsing in an "eval" block. It returns the twig on success and 0 on failure (the twig object also contains the parsed twig). $@ contains the error message on failure.

xparse ($thing_to_parse)

Parses the $thing_to_parse, whether it is a filehandle, a string, an HTML file, an HTML URL, a URL, or a file.

Note that this is mostly a convenience method for one-off scripts. For example, files that end in '.htm' or '.html' are parsed first as XML, and if this fails as HTML. This is certainly not the most efficient way to do this in general.

nparse ($optional_twig_options, $thing_to_parse)

Creates a twig with the $optional_options, and parses the $thing_to_parse, whether it is a filehandle, a string, an HTML file, an HTML URL, a URL, or a file.

Examples:

   XML::Twig->nparse( "file.xml");
   XML::Twig->nparse( error_context => 1, "file://file.xml");
    

nparse_pp ($optional_twig_options, $thing_to_parse)

Same as "nparse " but also sets the "pretty_print" option to "indented".

nparse_e ($optional_twig_options, $thing_to_parse)

Same as "nparse " but also sets the "error_context" option to 1.

nparse_ppe ($optional_twig_options, $thing_to_parse)

Same as "nparse " but also sets the "pretty_print" option to "indented" and the "error_context" option to 1.

parser

This method returns the "expat" object (actually the XML::Parser::Expat object) used during parsing. It is useful for example to call XML::Parser::Expat methods on it. To get the line of a tag for example, use "$t->parser->current_line".

setTwigHandlers ($handlers)

Sets the twig_handlers. $handlers is a reference to a hash similar to the one in the "twig_handlers" option of "new". All previous handlers are unset. This method returns the reference to the previous handlers.

setTwigHandler ($exp $handler)

Sets a single twig_handler for elements matching $exp. $handler is a reference to a subroutine. If the handler was previously set, then the reference to the previous handler is returned.

setStartTagHandlers ($handlers)

Sets the start_tag handlers. $handlers is a reference to a hash similar to the one in the "start_tag_handlers" option of new. All previous handlers are unset. This method returns the reference to the previous handlers.

setStartTagHandler ($exp $handler)

Sets a single start_tag handlers for elements matching $exp. $handler is a reference to a subroutine. If the handler was previously set, then the reference to the previous handler is returned.

setEndTagHandlers ($handlers)

Sets the end_tag handlers. $handlers is a reference to a hash similar to the one in the "end_tag_handlers" option of new. All previous handlers are unset. This method returns the reference to the previous handlers.

setEndTagHandler ($exp $handler)

Sets a single end_tag handlers for elements matching $exp. $handler is a reference to a subroutine. If the handler was previously set, then this reference to the previous handler is returned.

setTwigRoots ($handlers)

Same as using the "twig_roots " option when creating the twig.

setCharHandler ($exp $handler)

Sets a "char_handler".

setIgnoreEltsHandler ($exp)

Sets a "ignore_elt" handler (elements that match $exp will be ignored.

setIgnoreEltsHandlers ($exp)

Sets all "ignore_elt" handlers (previous handlers are replaced).

dtd

Returns the dtd (an XML::Twig::DTD object) of a twig.

xmldecl

Returns the XML declaration for the document, or a default one if it doesn't have one.

doctype

Returns the doctype for the document.

doctype_name

Returns the doctype of the document from the doctype declaration.

system_id

Returns the system value of the DTD of the document from the doctype declaration.

public_id

Returns the public doctype of the document from the doctype declaration.

internal_subset

Returns the internal subset of the DTD.

dtd_text

Returns the DTD text.

dtd_print

Prints the DTD.

model ($tag)

Returns the model (in the DTD) for the element $tag.

root

Returns the root element of a twig.

set_root ($elt)

Sets the root element of a twig.

first_elt ($optional_condition)

Returns the first element matching $optional_condition of a twig, if no condition is given then the root is returned.

last_elt ($optional_condition)

Returns the last element matching $optional_condition of a twig, if no condition is given then the last element of the twig is returned.

elt_id ($id)

Returns the element whose "id" attribute is $id.

getEltById

Same as "elt_id ".

index ($index_name, $optional_index)

If the $optional_index argument is present, returns the corresponding element in the index (created using the "index" option for "XML::Twig-"new>).

If the argument is not present, returns an arrayref to the index.

normalize

Merge together all consecutive "#PCDATA" elements in the document. For example, if you have turned some elements into "#PCDATA" using "erase ", this will give you a "clean" element in which there all text fragments are as long as possible).

encoding

Returns the encoding of the XML document, as defined by the "encoding" attribute in the XML declaration (ie it is "undef" if the attribute is not defined).

set_encoding

Sets the value of the "encoding" attribute in the XML declaration. Note that if the document did not have a declaration it is generated (with an XML version of 1.0).

xml_version

Returns the XML version, as defined by the "version" attribute in the XML declaration (ie it is "undef" if the attribute is not defined).

set_xml_version

Sets the value of the "version" attribute in the XML declaration. If the declaration did not exist it is created.

standalone

Returns the value of the "standalone" declaration for the document.

set_standalone

Sets the value of the "standalone" attribute in the XML declaration. Note that if the document did not have a declaration it is generated (with an XML version of 1.0).

set_output_encoding

Sets the "encoding" "attribute" in the XML declaration.

set_doctype ($name, $system, $public, $internal)

Sets the doctype of the element. If an argument is "undef" (or not present) then its former value is retained, if a false ('' or 0) value is passed then the former value is deleted.

entity_list

Returns the entity list of a twig.

entity_names

Returns the list of all defined entities.

entity ($entity_name)

Returns the entity.

notation_list

Returns the notation list of a twig.

notation_names

Returns the list of all defined notations.

notation ($notation_name)

Returns the notation.

change_gi ($old_gi, $new_gi)

Performs a (very fast) global change. All elements $old_gi are now $new_gi. This is a bit dangerous though and should be avoided if possible, as the new tag might be ignored in subsequent processing.

See "BUGS ".

flush ($optional_filehandle, %options)

Flushes a twig up to (and including) the current element, then deletes all unnecessary elements from the tree that are in memory. "flush" keeps track of which elements need to be open/closed, so if you flush from handlers you don't have to worry about anything. Just keep flushing the twig every time you're done with a sub-tree and it will come out well-formed. After parsing completes, don't forget to "flush" one more time to print the end of the document. The doctype and entity declarations are also printed.

"flush" take an optional filehandle as an argument.

If you use "flush" at any point during parsing, the document will be flushed one last time at the end of the parsing, to the proper filehandle.

Options: use the "update_DTD" option if you have updated the (internal) DTD and/or the entity list and you want the updated DTD to be output.

The "pretty_print" option sets the pretty printing of the document.

   Example: $t->flush( Update_DTD => 1);
            $t->flush( $filehandle, pretty_print => 'indented');
            $t->flush( \*FILE);
    

flush_up_to ($elt, $optional_filehandle, %options)

Flushes up to the $elt element. This allows you to keep part of the tree in memory when you "flush".

Options: see "flush".

purge

Does the same as a "flush" except it does not print the twig. It just deletes all elements that have been completely parsed so far.

purge_up_to ($elt)

Purges up to the $elt element. This allows you to keep part of the tree in memory when you "purge".

print ($optional_filehandle, %options)

Prints the whole document associated with the twig. To be used only AFTER the parse.

Options: see "flush".

print_to_file ($filename, %options)

Prints the whole document associated with the twig to file $filename. To be used only AFTER the parse.

Options: see "flush".

safe_print_to_file ($filename, %options)

Prints the whole document associated with the twig to file $filename. This variant, which probably only works on *nix, prints to a temporary file then moves the temporary file to overwrite the original file.

This is a bit safer when two processes can potentially write the same file: only the last one will succeed, but the file won't be corrupted. I often use this for cron jobs, so testing the code doesn't interfere with the cron job running at the same time.

Options: see "flush".

sprint

Returns the text of the whole document associated with the twig. To be used only AFTER the parse.

Options: see "flush".

trim

Trims the document: gets rid of initial and trailing spaces, and replaces multiple spaces by a single one.

toSAX1 ($handler)

Sends SAX events for the twig to the SAX1 handler $handler.

toSAX2 ($handler)

Sends SAX events for the twig to the SAX2 handler $handler.

flush_toSAX1 ($handler)

Same as "flush", except that SAX events are sent to the SAX1 handler $handler instead of the twig being printed.

flush_toSAX2 ($handler)

Same as "flush", except that SAX events are sent to the SAX2 handler $handler instead of the twig being printed.

ignore

This method should be called during parsing, usually in "start_tag_handlers". It causes the element to be skipped during the parsing: the twig is not built for this element; it will not be accessible during parsing or after it. The element does not take up any memory and parsing will be faster.

Note that this method can also be called on an element. If the element is a parent of the current element then this element will be ignored (the twig will not be built anymore for it and what has already been built will be deleted).

set_pretty_print ($style)

Set the pretty print method, amongst '"none"' (default), '"nsgmls"', '"nice"', '"indented"', "indented_c", '"wrapped"', '"record"' and '"record_c"'.

WARNING: The pretty print style is a GLOBAL variable, so once set it applies to ALL "print"'s (and "sprint"'s). Same goes if you use XML::Twig with "mod_perl". This should not be a problem as the XML that's generated is valid anyway, and XML processors (as well as HTML processors, including browsers) should not care. Let me know if this is a big problem, but at the moment the performance/cleanliness trade-off clearly favors the global approach.

set_empty_tag_style ($style)

Sets the empty tag display style ('"normal"', '"html"' or '"expand"'). As with "set_pretty_print ", this sets a global flag.

"normal" outputs an empty tag '"<tag/>"', "html" adds a space '"<tag />"' for elements that can be empty in XHTML, and "expand" outputs '"<tag></tag>"'.

set_remove_cdata ($flag)

Sets (or unsets) the flag that forces the twig to output "#CDATA" sections as regular (escaped) "#PCDATA".

print_prolog ($optional_filehandle, %options)

Prints the prolog (XML declaration + DTD + entity declarations) of a document.

Options: see "flush ".

prolog ($optional_filehandle, %options)

Returns the prolog (XML declaration + DTD + entity declarations) of a document.

Options: see "flush ".

finish

Calls the Expat "finish" method. Unsets all handlers (including internal ones that set context), but expat continues parsing to the end of the document or until it finds an error. It should finish a lot faster than with the handlers set.

finish_print

Stops twig processing, flush the twig, and proceed to finish printing the document as fast as possible. Use this method when modifying a document and the modification is done.

finish_now

Stops twig processing, does not finish parsing the document (which could actually be not well-formed after the point where "finish_now" is called). Execution resumes after the "Lparse"> or "parsefile " call. The content of the twig is what has been parsed so far (all open elements at the time "finish_now" is called are considered closed).

set_expand_external_entities

Same as using the "expand_external_ents " option when creating the twig.

set_input_filter

Same as using the "input_filter " option when creating the twig.

set_keep_atts_order

Same as using the "keep_atts_order " option when creating the twig.

set_keep_encoding

Same as using the "keep_encoding " option when creating the twig.

escape_gt

Same as using the "escape_gt " option when creating the twig.

do_not_escape_gt

Reverts XML::Twig behavior to its default of not escaping > in its output.

set_output_filter

Same as using the "output_filter " option when creating the twig.

set_output_text_filter

Same as using the "output_text_filter " option when creating the twig.

add_stylesheet ($type, @options)

Adds an external stylesheet to an XML document.

Supported types and options are:

Methods inherited from XML::Parser::Expat

A twig inherits all the relevant methods from XML::Parser::Expat. These methods can only be used during the parsing phase (they will generate a fatal error otherwise).

Inherited methods are:

path ( $optional_tag)

Returns the element context in a form similar to XPath's short form: '"/root/tag1/../tag"'.

get_xpath ( $optional_array_ref, $xpath, $optional_offset)

Performs a "get_xpath" on the document root (see <Elt|"Elt">).

If the $optional_array_ref argument is used, the array must contain elements. The $xpath expression is applied to each element in turn and the result is union of all results. This way a first query can be refined in further steps.

find_nodes ( $optional_array_ref, $xpath, $optional_offset)

Same as "get_xpath".

findnodes ( $optional_array_ref, $xpath, $optional_offset)

Same as "get_xpath" (similar to the XML::LibXML method).

findvalue ( $optional_array_ref, $xpath, $optional_offset)

Returns the "join" of all texts of the results of applying "get_xpath " to the node (similar to the XML::LibXML method).

findvalues ( $optional_array_ref, $xpath, $optional_offset)

Returns an array of all texts of the results of applying "get_xpath " to the node.

subs_text ($regexp, $replace)

Performs text substitution on the whole document, similar to perl's " s///" operator.

dispose

Useful only if you don't have "Scalar::Util" or "WeakRef" installed.

Properly reclaims the memory used by an XML::Twig object. As the object has circular references, it never goes out of scope, so if you want to parse lots of XML documents then the memory leak becomes a problem. Use "$twig->dispose" to clear this problem.

att_accessors (list_of_attribute_names)

A convenience method that creates l-valued accessors for attributes. So "$twig->create_accessors( 'foo')" will create a "foo" method that can be called on elements:

  $elt->foo;         # equivalent to $elt->att( 'foo');
  $elt->foo( 'bar'); # equivalent to $elt->set_att( foo => 'bar');
    

The methods are l-valued only under those perl's that support this feature.

create_accessors (list_of_attribute_names)

Same as att_accessors.

elt_accessors (list_of_attribute_names)

A convenience method that creates accessors for elements. So "$twig->create_accessors( 'foo')" will create a "foo" method that can be called on elements:

  $elt->foo;         # equivalent to $elt->first_child( 'foo');
    

field_accessors (list_of_attribute_names)

A convenience method that creates accessors for element values ("field"). So "$twig->create_accessors( 'foo')" will create a "foo" method that can be called on elements:

  $elt->foo;         # equivalent to $elt->field( 'foo');
    

set_do_not_escape_amp_in_atts

An evil method that I only document because Test::Pod::Coverage complaints otherwise, but really, you don't want to know about it.

XML::Twig::Elt

new ($optional_tag, $optional_atts, @optional_content)

Returns the newly created element.

The "tag" is optional (but then you can't have content!), the $optional_atts argument is a reference to a hash of attributes, the content can be just a string or a list of strings and element. A content of '"#EMPTY"' creates an empty element.

 Examples: my $elt= XML::Twig::Elt->new();
           my $elt= XML::Twig::Elt->new( para => { align => 'center' });
           my $elt= XML::Twig::Elt->new( para => { align => 'center' }, 'foo');
           my $elt= XML::Twig::Elt->new( br   => '#EMPTY');
           my $elt= XML::Twig::Elt->new( 'para');
           my $elt= XML::Twig::Elt->new( para => 'this is a para');
           my $elt= XML::Twig::Elt->new( para => $elt3, 'another para');
    

The strings are not parsed, and the element is not attached to any twig.

WARNING: if you rely on IDs then you will have to set the id yourself. At this point the element does not belong to a twig yet, so the ID attribute is not known and it won't be stored in the ID list.

Note that "#COMMENT", "#PCDATA", and "#CDATA" are valid tag names that will create those element types.

To create an element "foo" containing a "#CDATA" section:

           my $foo= XML::Twig::Elt->new( '#CDATA' => "content of the CDATA section")
                                  ->wrap_in( 'foo');
    

An attribute of '#CDATA', when set, creates the content of the element as CDATA:

  my $elt= XML::Twig::Elt->new( 'p' => { '#CDATA' => 1}, 'foo < bar');
    

creates an element.

  <p><![CDATA[foo < bar]]></>
    

parse ($string, %args)

Creates an element from an XML string. The string is actually parsed as a new twig, then the root of that twig is returned. The arguments in %args are passed to the twig. As always, if the parse fails the parser will die, so use an "eval" if you want to trap syntax errors.

As obviously the element does not exist beforehand, this method must be explicitly called on the class:

  my $elt= parse XML::Twig::Elt( "<a> string to parse, with <sub/>
                                  <elements>, actually tons of </elements>
                  h</a>");
    

Returns the calling element.

set_inner_xml ($string)

Sets the content of the element to be the tree created from the string.

Returns the calling element.

set_inner_html ($string)

Sets the content of the element, after parsing the string with an HTML parser (HTML::Parser).

Returns the calling element.

set_outer_xml ($string)

Replaces the element with the tree created from the string.

Returns the calling element.

print ($optional_filehandle, $optional_pretty_print_style)

Prints an entire element, including the tags, optionally to a $optional_filehandle, optionally with a $pretty_print_style.

The print outputs XML data so base entities are escaped.

No return value.

print_to_file ($filename, %options)

Prints the element to file $filename.

Options: see "flush".

sprint ($elt, $optional_no_enclosing_tag)

Returns the xml string for an entire element, including the tags. If the optional second argument is true then only the string inside the element is returned (the start and end tag for $elt are not). The text is XML-escaped: base entities (& and < in text, & < and " in attribute values) are turned into entities.

gi

Returns the gi of the element (the gi is the "generic identifier", the tag name, in SGML parlance).

"tag" and "name" are synonyms of "gi".

tag

Same as "gi ".

name

Same as "gi ".

set_gi ($tag)

Sets the gi (tag) of an element.

Returns the calling element.

set_tag ($tag)

Same as "set_gi ".

set_name ($name)

Same as "set_gi ".

root

Returns the root of the twig in which the element is contained.

twig

Returns the twig containing the element.

parent ($optional_condition)

Returns the parent of the element, or the first ancestor matching the $optional_condition.

first_child ($optional_condition)

Returns the first child of the element, or the first child matching the $optional_condition.

has_child ($optional_condition)

Same as first_child.

has_children ($optional_condition)

Same as first_child.

first_child_text ($optional_condition)

Returns the text of the first child of the element, or the first child matching the $optional_condition. If there is no first_child, then returns ''. This avoids getting the child, checking for its existence, then getting the text for trivial cases.

Similar methods are available for the other navigation methods:

field ($condition)

Same as "first_child_text".

fields ($condition_list)

Returns the list of fields (text of first child matching each condition). Missing fields are returned as empty strings.

trimmed_field ($optional_condition)

Same as "first_child_trimmed_text".

set_field ($condition, $optional_atts, @list_of_elt_and_strings)

Sets the content of the first child of the element that matches $condition; the rest of the arguments is the same as for "set_content ".

If no child matches $condition _and_ if $condition is a valid XML element name, then a new element by that name is created and inserted as the last child.

Returns the matching or newly created field element.

first_child_matches ($optional_condition)

Returns the element if the first child of the element (if it exists) passes the $optional_condition, "undef" otherwise.

  if( $elt->first_child_matches( 'title')) ...
    

is equivalent to:

  if( $elt->{first_child} && $elt->{first_child}->passes( 'title'))
    

Similar methods are available for the other navigation methods:

first_child_is ($optional_condition) Same as "first_child_matches".

is_first_child ($optional_condition)

Returns true (the calling element) if the element is the first child of its parent (optionally that satisfies the $optional_condition) otherwise returns 0.

is_last_child ($optional_condition)

Returns true (the calling element) if the element is the last child of its parent (optionally that satisfies the $optional_condition) otherwise returns 0.

prev_sibling ($optional_condition)

Returns the previous sibling of the element, or the previous sibling matching $optional_condition, or undefined if none exists.

next_sibling ($optional_condition)

Returns the next sibling of the element, or the first one matching $optional_condition, or undefined if none exists.

next_elt ($optional_elt, $optional_condition)

Returns the next elt (optionally matching $optional_condition) of the element (defined as the next element which opens after the current element opens). This usually returns the first child of the element. Counter-intuitive as it might seem, this allows you to loop through the whole document by starting from the root.

The $optional_elt is the root of a subtree. When the "next_elt" is out of the subtree then the method returns "undef". You can then walk a sub-tree with:

  my $elt= $subtree_root;
  while( $elt= $elt->next_elt( $subtree_root))
    { # insert processing code here
    }
    

prev_elt ($optional_condition)

Returns the previous elt (optionally matching $optional_condition) of the element (defined as the first element which opens before the current element opens). This usually returns the last descendant of the previous sibling or simply the parent.

next_n_elt ($offset, $optional_condition)

Returns the $offset-th element that matches the $optional_condition.

following_elt

Returns the following element (as per the XPath following axis).

preceding_elt

Returns the preceding element (as per the XPath preceding axis).

following_elts

Returns the list of following elements (as per the XPath following axis).

preceding_elts

Returns the list of preceding elements (as per the XPath preceding axis).

children ($optional_condition)

Returns the list of children (optionally which matches $optional_condition) of the element. The list is in document order.

children_count ($optional_condition)

Returns the number of children of the element (optionally which matches $optional_condition).

children_text ($optional_condition)

In array context, returns an array containing the text of children of the element (optionally which matches $optional_condition), or an empty array if none match.

In scalar context, returns the concatenation of the text of children of the element, or an empty string if none match.

This uses the "text " method, which considers text in descendants too.

children_trimmed_text ($optional_condition)

Same as "children_text " except uses the "trimmed_text " method on matching children (and their descendants).

children_copy ($optional_condition)

Returns a list of elements that are copies of the children of the element, optionally only those which match $optional_condition.

descendants ($optional_condition)

Returns the list of all descendants (optionally which match $optional_condition) of the element. This is the equivalent of the "getElementsByTagName" of the DOM. (By the way, if you are really a DOM addict, you can use "getElementsByTagName" instead.)

NOTE: The element itself is not part of the list; to include it, use "descendants_or_self ".

getElementsByTagName ($optional_condition)

Same as "descendants ".

find_by_tag_name ($optional_condition)

Same as "descendants ".

descendants_or_self ($optional_condition)

Same as "descendants " except that the element itself is included in the list if it matches the $optional_condition.

first_descendant ($optional_condition)

Returns the first descendant of the element that matches the condition.

last_descendant ($optional_condition)

Returns the last descendant of the element that matches the condition.

ancestors ($optional_condition)

Returns the list of ancestors (optionally matching $optional_condition) of the element. The list is ordered from the innermost ancestor to the outermost one.

NOTE: The element itself is not part of the list; to include it, use "ancestors_or_self ".

ancestors_or_self ($optional_condition)

Same as "ancestors " except that the element itself is included in the list if it matches the $optional_condition.

passes ($condition)

Returns the calling element if it passes the $condition, else "undef".

att ($att)

Returns the value of attribute $att or "undef".

latt ($att)

Returns the value of attribute $att or "undef".

This method is an lvalue, so you can do "$elt->latt( 'foo') = 'bar'" or "$elt->latt( 'foo')++;".

If you are working with ID values, use "id" or "set_id" instead so that the internal ID hash is updated.

set_att ($att, $att_value)

Sets the attribute of the element to the given value.

You can set several attributes at once:

  $elt->set_att( att1 => "val1", att2 => "val2");
    

Returns the calling element.

del_att (@att)

Deletes one or more attributes for the element.

You can actually delete several attributes at once:

  $elt->del_att( 'att1', 'att2', 'att3');
    

Returns the calling element.

att_exists ($att)

Returns true (1) if the attribute $att exists for the element, false ('') otherwise.

cut

Cuts the element from the tree. The element still exists in memory, and it can be copied or pasted somewhere else; it is just not attached to the tree anymore.

Note that the "old" links to the parent, previous and next siblings can still be accessed using the former_* methods.

former_next_sibling

Returns the former next sibling of a cut node (or "undef" if the node has not been cut).

This makes it easier to write loops where you cut elements:

    my $child= $parent->first_child( 'achild');
    while( $child->{'att'}->{'cut'})
      { $child->cut; $child= ($child->{former} && $child->{former}->{next_sibling}); }
    

former_prev_sibling

Returns the former previous sibling of a cut node (or "undef" if the node has not been cut).

former_parent

Returns the former parent of a cut node (or "undef" if the node has not been cut).

cut_children ($optional_condition)

Cuts all children of the element (or all which satisfy the $optional_condition).

Returns the list of cut children.

cut_descendants ($optional_condition)

Cuts all descendants of the element (or all of those which satisfy the $optional_condition).

Returns the list of descendants.

copy ($elt)

Returns a copy of the element. The copy is a "deep" copy: all sub-elements of the element are duplicated.

paste ($optional_position, $ref)

Pastes a (previously "cut" or newly generated) element; dies if the element already belongs to a tree.

Returns the calling element.

Note that the calling element is pasted, not the reference element:

  $child->paste( first_child => $existing_parent);
  $new_sibling->paste( after => $this_sibling_is_already_in_the_tree);
    

or:

  my $new_elt= XML::Twig::Elt->new( tag => $content);
  $new_elt->paste( $position => $existing_elt);
    

Example:

  my $t= XML::Twig->new->parse( 'doc.xml')
  my $toc= $t->root->new( 'toc');
  $toc->paste( $t->root); # $toc is pasted as first child of the root
  foreach my $title ($t->findnodes( '/doc/section/title'))
    { my $title_toc= $title->copy;
      # paste $title_toc as the last child of toc
      $title_toc->paste( last_child => $toc)
    }
    

Position options:

move ($optional_position, $ref)

Moves an element in the tree. This is just a "cut" then a "paste". The syntax is the same as "paste".

Returns the calling element.

replace ($ref)

Replaces an element in the tree. Sometimes it is just not possible to"cut" an element then "paste" another in its place, so "replace" comes in handy. The calling element replaces $ref.

Returns the provided replacement element.

replace_with (@elts)

Replaces the calling element with one or more elements.

Returns the first element in the provided list.

delete

Cuts the element and frees the memory.

No return value.

prefix ($text, $optional_option)

Adds a prefix to an element. If the element is a "#PCDATA" element, the text is added to its PCDATA; if the element's first child is a "#PCDATA", then the text is added to its PCDATA; otherwise a new "#PCDATA" element is created and pasted as the first child of the element.

Returns the calling element.

If the option is "asis" then the prefix is added as-is: it is created in a separate "#PCDATA" element with the "asis" property. You can then write:

  $elt1->prefix( '<b>', 'asis');
    

to create a "<b>" in the output of "print".

suffix ($text, $optional_option)

Adds a suffix to an element. If the element is a "#PCDATA" element, the text is added to its PCDATA, if the element's last child is a "#PCDATA", then the text is added to its PCDATA, otherwise a new PCDATA element is created and pasted as the last child of the element.

Returns the calling element.

If the option is "asis" then the suffix is added as-is: it is created in a separate "#PCDATA" element with the "asis" property. You can then write:

  $elt2->suffix( '</b>', 'asis');
    

trim

Trims the element in-place: spaces at the beginning and at the end of the element are discarded; multiple spaces within the element (or its descendants) are replaced by a single space.

Returns the calling element.

Note that in some cases you can still end up with multiple spaces, if they are split between several elements:

  <doc>  text <b>  hah! </b>  yep</doc>
    

gets trimmed to:

  <doc>text <b> hah! </b> yep</doc>
    

This is somewhere in between a bug and a feature.

normalize

Merge together all consecutive "#PCDATA" elements in the element. For example, if you have turned some elements into "#PCDATA" using "erase ", this will give you a "clean" element in which there all text fragments are as long as possible).

Returns the calling element.

simplify (%options)

Returns a data structure suspiciously similar to XML::Simple's. Options are identical to XMLin options, see XML::Simple doc for more details (or use DATA::dumper or YAML to dump the data structure).

Note: there is no magic here; if you write "$twig->parsefile( $file )->simplify();" then it will load the entire document in memory. I am afraid you will have to put some work into it to get just the bits you want and discard the rest. Look at the synopsis or the XML::Twig 101 section at the top of the docs for more information.

split_at ($offset)

Splits a text ("#PCDATA" or "#CDATA") element in 2 at $offset, the original element now holds the first part of the string and a new element holds the right part. The new element is returned.

If the element is not a text element then the first text child of the element is split.

split ( $optional_regexp, $tag1, $atts1, $tag2, $atts2...)

Splits the text descendants of an element in place, the text is split using the $regexp, if the regexp includes () then the matched separators will be wrapped in elements. $1 is wrapped in $tag1, with attributes $atts1 if $atts1 is given (as a hashref), $2 is wrapped in $tag2...

if $elt is "<p>tati tata <b>tutu tati titi</b> tata tati tata</p>":

  $elt->split( qr/(ta)ti/, 'foo', {type => 'toto'} )
    

will change $elt to:

  <p><foo type="toto">ta</foo> tata <b>tutu <foo type="toto">ta</foo>
      titi</b> tata <foo type="toto">ta</foo> tata</p>
    

The regexp can be passed either as a string or as "qr//", it defaults to \s+ just as the "split" built-in (but this would be quite a useless behaviour without the $optional_tag parameter).

$optional_tag defaults to PCDATA or CDATA, depending on the initial element type.

Returns the list of descendants (including un-touched original elements and newly created ones).

mark ( $regexp, $optional_tag, $optional_attribute_ref)

This method behaves exactly as split, except only the newly created elements are returned.

wrap_children ( $regexp_string, $tag, $optional_attribute_hashref)

Wrap the children of the element that match the regexp in an element $tag. If $optional_attribute_hashref is passed, then the new element will have these attributes.

Returns the calling element.

The $regexp_string includes tags, within pointy brackets, as in "<title><para>+" and the usual Perl modifiers (+*?...). Inside tag brackets, only "." is treated as a special regex character for matching tag names. Outside tag brackets, the usual modifiers ("+*?"...) work normally for matching tags, including lookaheads.

Note: Currently, lookbehinds do not work because the "<" in the lookbehind expression causes issues with tag recognition.

"^" and "$" are interpreted as the beginning and end of the children in the current twig.

Tags can be further qualified with attributes: "<para type="warning" classif="cosmic_secret">+". The values for attributes should be xml-escaped: "<candy type="M&amp;Ms">*" ("<", "&" ">" and """ should be escaped).

Note that elements might get extra "id" attributes in the process. See add_id. Use strip_att to remove unwanted id's.

For example, if the element $elt has the following content:

  <body>
    <h1>Fruit</h1>
    <p>content</p>
    <h2>Apples</h2>
    <p>content</p>
    <h3>Apple Varieties</h3>
    <p>content</p>
    <h2>Oranges</h2>
    <p>content</p>
    <h1>Vegetables</h1>
    <p>content</p>
    <h2>Leafy Vegetables</h2>
    <p>content</p>
  </body>
    

Then after running the code:

  $elt->wrap_children('<h3>.*?(?=(<h.>)|$)', 'topic');  # <h.> can match h1/h2/h3
  $elt->wrap_children('<h2>.*?(?=(<h.>)|$)', 'topic');  # <h.> can match h1/h2
  $elt->wrap_children('<h1>.*?(?=(<h.>)|$)', topic => {toplevel => 'true'});  # <h.> can match h1
  $elt->strip_att('id');
    

$elt will contain:

  <body>
    <topic toplevel="true">
      <h1>Fruit</h1>
      <p>content</p>
      <topic>
        <h2>Apples</h2>
        <p>content</p>
        <topic>
          <h3>Apple Varieties</h3>
          <p>content</p>
        </topic>
      </topic>
      <topic>
        <h2>Oranges</h2>
        <p>content</p>
      </topic>
    </topic>
    <topic toplevel="true">
      <h1>Vegetables</h1>
      <p>content</p>
      <topic>
        <h2>Leafy Vegetables</h2>
        <p>content</p>
      </topic>
    </topic>
  </body>
    

subs_text ($regexp, $replace)

subs_text does text substitution, similar to perl's " s///" operator.

$regexp must be a perl regexp, created with the "qr" operator.

Returns the calling element.

$replace can include "$1, $2"... from the $regexp. It can also be used to create element and entities, by using "&elt( tag => { att => val }, text)" (similar syntax as "new ") and &ent( name).

Here is a rather complex example:

  $elt->subs_text( qr{(?<!do not )link to (http://([^\s,]*))},
                   'see &elt( a =>{ href => $1 }, $2)'
                 );
    

This replaces text like link to http://www.xmltwig.org by see <a href="www.xmltwig.org">www.xmltwig.org</a>, but not do not link to....

Generating entities (here replacing spaces with &nbsp;):

  $elt->subs_text( qr{ }, '&ent( " ")');
    

or, using a variable:

  my $ent=" ";
  $elt->subs_text( qr{ }, "&ent( '$ent')");
    

Note that the substitution is always global, as in using the "g" modifier in a perl substitution, and that it is performed on all text descendants of the element.

Bug: in the $regexp, you can only use "\1", "\2"... if the replacement expression does not include elements or attributes. eg:

  $t->subs_text( qr/((t[aiou])\2)/, '$2');             # ok, replaces toto, tata, titi, tutu by to, ta, ti, tu
  $t->subs_text( qr/((t[aiou])\2)/, '&elt(p => $1)' ); # NOK, does not find toto...
    

add_id ($optional_coderef)

Adds an id to the element.

If the element already has an id, no new id is generated.

Returns the id value (existing or newly generated).

The id is an attribute, "id" by default, see the "id" option for XML::Twig "new" to change it. Use an id starting with "#" to get an id that's not output by print, flush or sprint, yet that allows you to use the elt_id method to get the element easily.

By default, the method create an id of the form "twig_id_<nnnn>", where "<nnnn>" is a number, incremented each time the method is called successfully.

set_id_seed ($prefix)

By default, the id generated by "add_id " is "twig_id_<nnnn>", "set_id_seed" changes the prefix to $prefix and resets the number to 1.

strip_att (@att_list)

Removes the attributes in @att_list from the calling element and all its descendants.

Returns the calling element.

change_att_name ($old_name, $new_name)

Changes the name of the attribute from $old_name to $new_name. If there is no attribute $old_name, nothing happens.

Returns the calling element.

lc_attnames

Lowercases the name of all the attributes of the element.

Returns the calling element.

sort_children_on_value (%options)

Sorts the children of the element in place according to their text. All children are sorted.

Returns the calling element, with its children sorted.

%options are:

  type  : numeric |  alpha     (default: alpha)
  order : normal  |  reverse   (default: normal)
    

Returns the element, with its children sorted.

sort_children_on_att ($att, %options)

Sorts the children of the element in place according to attribute $att. %options are the same as for "sort_children_on_value".

Returns the calling element, with its children sorted.

sort_children_on_field ($tag, %options)

Sorts the children of the element in place, according to the field $tag (the text of the first child of the child with this tag). %options are the same as for "sort_children_on_value".

Returns the calling element, with its children sorted.

sort_children( $get_key, %options)

Sorts the children of the element in place. The $get_key argument is a reference to a function that returns the sort key when passed an element.

For example:

  $elt->sort_children( sub { $_[0]->att( "nb") + $_[0]->text },
                       type => 'numeric', order => 'reverse'
                     );
    

Returns the calling element.

field_to_att ($cond, $att)

Turns the text of the first sub-element matched by $cond into the value of attribute $att of the element. If $att is omitted then $cond is used as the name of the attribute, which makes sense only if $cond is a valid element (and attribute) name.

The sub-element is then cut.

Returns the calling element.

att_to_field ($att, $tag)

Takes the value of attribute $att and creates a sub-element $tag as first child of the element. If $tag is omitted then $att is used as the name of the sub-element.

Returns the calling element.

get_xpath ($xpath, $optional_offset)

Returns a list of elements satisfying the $xpath. $xpath is an XPATH-like expression.

A subset of the XPATH abbreviated syntax is covered:

  tag
  tag[1]    (or any other positive number)
  tag[last()]
  tag[@att]    (the attribute exists for the element)
  tag[@att="val"]
  tag[@att=~ /regexp/]
  tag[att1="val1" and att2="val2"]    (@ is optional)
  tag[att1="val1" or att2="val2"]
  tag[string()="toto"]   (returns tag elements which text (as per the text method)
                         is toto)
  tag[string()=~/regexp/]   (returns tag elements which text (as per the text
                            method) matches regexp)
  expressions can start with / (search starts at the document root)
  expressions can start with . (search starts at the current element)
  // can be used to get all descendants instead of just direct children
  * matches any tag
    

So the following examples from the XPath recommendation<http://www.w3.org/TR/xpath.html#path-abbrev> work:

  para selects the para element children of the context node
  * selects all element children of the context node
  para[1] selects the first para child of the context node
  para[last()] selects the last para child of the context node
  */para selects all para grandchildren of the context node
  /doc/chapter[5]/section[2] selects the second section of the fifth chapter
     of the doc
  chapter//para selects the para element descendants of the chapter element
     children of the context node
  //para selects all the para descendants of the document root and thus selects
     all para elements in the same document as the context node
  //olist/item selects all the item elements in the same document as the
     context node that have an olist parent
  .//para selects the para element descendants of the context node
  .. selects the parent of the context node
  para[@type="warning"] selects all para children of the context node that have
     a type attribute with value warning
  employee[@secretary and @assistant] selects all the employee children of the
     context node that have both a secretary attribute and an assistant
     attribute
    

The elements are returned in document order.

If $optional_offset is used, then only one element will be returned - the one with the appropriate offset in the list, starting at 0.

Quoting and interpolating variables can be a pain when the Perl syntax and the XPATH syntax collide, so use alternate quoting mechanisms like q or qq (I like q{} and qq{} myself).

Here are some more examples to get you started:

  my $p1= "p1";
  my $p2= "p2";
  my @res= $t->get_xpath( qq{p[string( "$p1") or string( "$p2")]});
  my $a= "a1";
  my @res= $t->get_xpath( qq{//*[@att="$a"]});
  my $val= "a1";
  my $exp= qq{//p[ \@att='$val']}; # you need to use \@ or you will get a warning
  my @res= $t->get_xpath( $exp);
    

Note that the only supported regexps delimiters are / and that you must backslash all / in regexps AND in regular strings.

XML::Twig does not provide full native XPATH support, but you can use "XML::Twig::XPath " to get "findnodes" to use "XML::XPath" as the XPath engine with full coverage of the spec.

find_nodes

Same as "get_xpath".

findnodes

Same as "get_xpath".

text @optional_options

Returns a string consisting of all the "#PCDATA" and "#CDATA" in an element, without any tags. The text is not XML-escaped: base entities such as "&" and "<" are not escaped.

The '"no_recurse"' option will only return the text of the element, not of any included sub-elements (same as "text_only ").

text_only

Same as "text " except that the text returned doesn't include the text of sub-elements.

trimmed_text

Same as "text" except that the text is trimmed: leading and trailing spaces are discarded, consecutive spaces are collapsed.

set_text ($string)

Sets the text for the element.

If the calling element is a "#PCDATA", its text is changed to the provided text.

Otherwise, all children of the element are deleted and replaced by a single "#PCDATA" child which holds the provided text.

Returns the calling element.

merge ($elt2)

Moves the content of $elt2 within the element.

insert ($tag1, [$optional_atts1], $tag2, [$optional_atts2],...)

For each tag in the list, inserts an element $tag as the only child of the element. The element gets the optional attributes in"$optional_atts<n>." All children of the element are set as children of the new element. The upper level element is returned.

  $p->insert( table => { border=> 1}, 'tr', 'td')
    

Put $p in a table with a visible border, a single "tr" and a single "td" and return the "table" element:

  <p><table border="1"><tr><td>original content of p</td></tr></table></p>
    

wrap_in (@tag)

Wraps elements in @tag as the successive ancestors of the element.

Returns the outermost newly created element (last in the list).

"$elt->wrap_in( 'td', 'tr', 'table')" wraps the element as a single cell in a table for example.

Optionally each tag can be followed by a hashref of attributes, that are set on the wrapping element:

  $elt->wrap_in( p => { class => "advisory" }, div => { class => "intro", id => "div_intro" });
    

insert_new_elt ($opt_position, @args)

Combines a "new " and a "paste ": creates a new element and pastes it, using $opt_position or 'first_child', relative to $elt.

@args can be either a string (which must be well-formed XML), or the same arguments as for the "new" method: $tag, $opt_atts_hashref and @opt_content.

Examples:

    $elt->insert_new_elt( first_child => p => { class => 'new_p' }, 'the new element' );
    

or:

    $elt->insert_new_elt( first_child => '<p class="new_p">the new element</p>' );
    

Returns the newly created element.

erase

Erases the element: the element is deleted and all of its children are pasted in its place.

set_content ( $optional_atts, @list_of_elt_and_strings) ( $optional_atts, '#EMPTY')

Sets the content for the element from a list of strings and elements. Cuts all existing element children, then pastes the provided list elements as the new children. This method creates "#PCDATA" elements for any strings in the list.

The $optional_atts argument is the ref of a hash of attributes. If this argument is used then the previous attributes are deleted, otherwise they are left untouched.

WARNING: If you rely on IDs, then you will have to set the ID yourself. At this point the element does not belong to a twig yet, so the ID attribute is not known so it won't be stored in the ID list.

A content of '"#EMPTY"' creates an empty element.

namespace ($optional_prefix)

Returns the URI of the namespace that $optional_prefix or the element name belongs to. If the name doesn't belong to any namespace, "undef" is returned.

local_name

Returns the local name (without the prefix) for the element.

ns_prefix

Returns the namespace prefix for the element.

current_ns_prefixes

Returns a list of namespace prefixes valid for the element. The order of the prefixes in the list has no meaning. If the default namespace is currently bound, then '' appears in the list.

inherit_att ($att, @optional_tag_list)

Returns the value of an attribute inherited from parent tags. The value returned is found by looking for the attribute in the element then in turn in each of its ancestors. If the @optional_tag_list is supplied, then only those ancestors whose tag is in the list will be checked.

all_children_are ($optional_condition)

Returns true (the calling element) if all children of the element pass the $optional_condition, false (0) otherwise.

level ($optional_condition)

Returns the depth of the element in the twig (root is 0). If $optional_condition is given then only ancestors that match the condition are counted.

WARNING: In a tree created using the "twig_roots" option this will not return the level in the document tree, level 0 will be the document root, level 1 will be the "twig_roots" elements. During the parsing (in a "twig_handler") you can use the "depth" method on the twig object to get the real parsing depth.

in ($potential_parent)

Returns true (the potential parent element) if the element is in the potential_parent ($potential_parent is an element), otherwise false (0).

in_context ($cond, $optional_level)

Returns true (the matching including element) if the element is included in an element which passes $cond optionally within $optional_level levels, otherwise false (0).

pcdata

Returns the text of a "#PCDATA" element or "undef" if the element is not "#PCDATA".

pcdata_xml_string

Returns the text of a "#PCDATA" element or "undef" if the element is not "#PCDATA". The text is "XML-escaped" ('&' and '<' are replaced by '&amp;' and '&lt;').

set_pcdata ($text)

Sets the text of a "#PCDATA" element. This method does not check that the element is indeed a "#PCDATA" so usually you should use "set_text " instead.

append_pcdata ($text)

Adds the text at the end of a "#PCDATA" element.

is_cdata

Returns true (1) if the element is a "#CDATA" element, returns false ('') otherwise.

is_text

Returns true (1) if the element is a "#CDATA" or "#PCDATA" element, returns false ('') otherwise.

cdata

Returns the text of a "#CDATA" element or "undef" if the element is not "#CDATA".

cdata_string

Returns the XML string of a "#CDATA" element, including the opening and closing markers.

set_cdata ($text)

Sets the text of a "#CDATA" element.

append_cdata ($text)

Adds the text at the end of a "#CDATA" element.

remove_cdata

Turns all "#CDATA" sections in the element into regular "#PCDATA" elements. This is useful when converting XML to HTML, as browsers do not support CDATA sections.

extra_data

Returns the extra_data (comments and PI's) attached to an element.

set_extra_data ($extra_data)

Sets the extra_data (comments and PI's) attached to an element.

append_extra_data ($extra_data)

Appends extra_data to the existing extra_data before the element (if no previous extra_data exists then it is created).

set_asis

Sets a property of the element that causes it to be output without being XML escaped by the print functions: if it contains "a < b" it will be output as such and not as "a &lt; b". This can be useful to create text elements that will be output as markup.

Note that all "#PCDATA" descendants of the element are also marked as having the property (they are the ones that are actually impacted by the change).

If the element is a "#CDATA" element it will also be output asis, without the "#CDATA" markers. The same goes for any "#CDATA" descendant of the element.

Returns the calling element.

set_not_asis

Unsets the "asis" property for the element and its text descendants.

is_asis

Returns the "asis" property status of the element (1 or "undef").

closed

Returns true if the element has been closed. Might be useful if you are somewhere in the tree, during the parse, and have no idea whether a parent element is completely loaded or not.

get_type

Returns the type of the element: '"#ELT"' for "real" elements, or '"#PCDATA"', '"#CDATA"', '"#COMMENT"', '"#ENT"', '"#PI"'.

is_elt

Returns the calling element if the element is a "real" element, or 0 if it is "#PCDATA", "#CDATA"...

contains_only_text

Returns true (the calling element) if the element does not contain any other "real" element, otherwise false (0).

contains_only ($exp)

Returns true (the list of matching children) if all children of the element match the expression $exp, otherwise returns false (0).

  if( $para->contains_only( 'tt')) { ... }
    

contains_a_single ($exp)

Returns the (the matching child) if the element contains a single child that matches the expression $exp, otherwise returns false (0).

is_field

Same as "contains_only_text".

is_pcdata

Returns true (1) if the element is a "#PCDATA" element, otherwise returns false ('').

is_ent

Returns true (1) if the element is an entity (an unexpanded entity) element, otherwise returns false ('').

is_empty

Returns true (1) if the element is empty, otherwise returns false ('').

set_empty

Flags the element as empty. No further check is made, so if the element is actually not empty the output will be messed. The only effect of this method is that the output will be "<tag att="value""/>".

Returns the calling element.

set_not_empty

Flags the element as not empty. If it is actually empty then the element will be output as "<tag att="value""></tag>".

Returns the calling element.

is_pi

Returns true (1) if the element is a processing instruction ("#PI") element, otherwise returns false ('').

target

Returns the target of a processing instruction.

set_target ($target)

Sets the target of a processing instruction.

Returns the calling element.

data

Returns the data part of a processing instruction.

set_data ($data)

Sets the data of a processing instruction.

Returns the calling element.

set_pi ($target, $data)

Sets the target and data of a processing instruction.

Returns the calling element.

pi_string

Returns the string form of a processing instruction ("<?target data?>").

is_comment

Returns true (1) if the element is a comment ("#COMMENT") element, otherwise returns false ('').

set_comment ($comment_text)

Set the text for a comment.

Returns the calling element.

comment

Returns the content of a comment (just the text, not the "<!--" and "-->"), or "undef".

comment_string

Returns the XML string for a comment ("<!-- comment -->").

Note that an XML comment cannot start or end with a '-', or include '--' (http://www.w3.org/TR/2008/REC-xml-20081126/#sec-comments), if that is the case (because you have created the comment yourself presumably, as it could not be in the input XML), then a space will be inserted before an initial '-', after a trailing one or between two '-' in the comment (which could presumably mangle javascript "hidden" in an XHTML comment).

The element must be a valid comment element.

set_ent ($entity)

Sets an (non-expanded) entity ("#ENT"). $entity) is the entity text ("&ent;").

Returns the calling element.

ent

Returns the entity for an entity ("#ENT") element ("&ent;"), otherwise returns "undef".

ent_name

Returns the entity name for an entity ("#ENT") element ("ent").

The element must be a valid entity element.

ent_string

Returns the entity, either expanded if the expanded version is available, or non-expanded ("&ent;") otherwise.

The element must be a valid entity element.

child ($offset, $optional_condition)

Returns the $offset-th child of the element, optionally the $offset-th child that matches $optional_condition. The children are treated as a list, so "$elt->child( 0)" is the first child, while "$elt->child( -1)" is the last child.

child_text ($offset, $optional_condition)

Returns the text of a child or "undef" if the sibling does not exist. Arguments are the same as child.

last_child ($optional_condition)

Returns the last child of the element, or the last child matching $optional_condition (ie the last of the element children matching the condition), or "undef" if none exist/match.

last_child_text ($optional_condition)

Same as "first_child_text" but for the last child.

sibling ($offset, $optional_condition)

Returns the next or previous $offset-th sibling of the element, or the $offset-th one matching $optional_condition. If $offset is negative then a previous sibling is returned, if $offset is positive then a next sibling is returned. "$offset=0" returns the element if there is no condition or if the element matches the condition>, "undef" otherwise.

sibling_text ($offset, $optional_condition)

Returns the text of a sibling or "undef" if the sibling does not exist. Arguments are the same as "sibling".

prev_siblings ($optional_condition)

Returns the list of previous siblings (optionally matching $optional_condition) for the element. The elements are ordered in document order.

next_siblings ($optional_condition)

Returns the list of siblings (optionally matching $optional_condition) following the element. The elements are ordered in document order.

siblings ($optional_condition)

Returns the list of siblings (optionally matching $optional_condition) of the element (excluding the element itself). The elements are ordered in document order.

pos ($optional_condition)

Returns the position of the element in the children list. The first child has a position of 1 (as in XPath).

If the $optional_condition is given, then only siblings that match the condition are counted. If the element itself does not match the condition, then 0 is returned.

atts

Returns a hash ref containing the element attributes.

set_atts ({ att1=>$att1_val, att2=> $att2_val... })

Set the element attributes with the hash ref supplied as the argument. The previous attributes are lost (ie the attributes set by "set_atts" replace all of the attributes of the element).

You can also pass a list instead of a hashref: "$elt->set_atts( att1 => 'val1',...)".

del_atts

Deletes all attributes of the element.

Returns the calling element.

att_nb

Returns the number of attributes for the element.

has_atts

Returns true if the element has attributes. (In fact, this is an alias for "att_nb ".)

has_no_atts

Returns true if the element has no attributes, false (0) otherwise.

att_names

Returns a list of the attribute names for the element.

att_xml_string ($att, $options)

Returns the attribute value, where '&', '<' and quote (" or the value of the quote option at twig creation) are XML-escaped.

The options are passed as a hashref. Setting "escape_gt" to a true value will also escape '>'.

set_id ($id)

Sets the "id" attribute of the element to the value. See "elt_id " to change the id attribute name.

Returns the calling element.

id

Gets the id attribute value (or "undef" if none).

del_id ($id)

Deletes the "id" attribute of the element and remove it from the id list for the document.

Returns the calling element.

class

Returns the "class" attribute for the element (methods on the "class" attribute are quite convenient when dealing with XHTML, or plain XML that will eventually be displayed using CSS).

lclass

Same as "class ", except that this method is an lvalue, so you can do "$elt->lclass= "foo"".

set_class ($class)

Sets the "class" attribute for the element to $class.

Returns the calling element.

add_class ($class)

Adds $class to the element "class" attribute: the new class is added only if not already present.

Note that classes are then sorted alphabetically, so the "class" attribute can be changed even if the class is already there.

Returns the calling element.

remove_class ($class)

Remove $class from the element "class" attribute.

Note that classes are then sorted alphabetically, so the "class" attribute can be changed even if the class is already there.

Returns the calling element.

add_to_class ($class)

Same as add_class.

att_to_class ($att)

Sets the "class" attribute to the value of attribute $att.

Returns the calling element.

add_att_to_class ($att)

Adds the value of attribute $att to the "class" attribute of the element.

Returns the calling element.

move_att_to_class ($att)

Adds the value of attribute $att to the "class" attribute of the element, then deletes the attribute.

Returns the calling element.

tag_to_class

Sets the "class" attribute of the element to the element tag.

Returns the calling element.

add_tag_to_class

Adds the element tag to its "class" attribute.

Returns the calling element.

set_tag_class ($new_tag)

Adds the element tag to its "class" attribute and sets the tag to $new_tag.

Returns the calling element.

in_class ($class)

Returns true (the calling element) if the element is in the class $class (if $class is one of the tokens in the element "class" attribute), otherwise returns false (0).

tag_to_span

Changes the element tag to "span" and sets its class to the old tag.

Returns the calling element.

tag_to_div

Changes the element tag to "div" and sets its class to the old tag.

DESTROY

Frees the element from memory.

start_tag

Returns the string for the start tag for the element, including the "/>" at the end of an empty element tag.

end_tag

Returns the string for the end tag of an element. For an empty element, returns an empty string ('').

xml_string @optional_options

Equivalent to "$elt->sprint( 1)", returns the string for the entire element, excluding the element's tags (but nested element tags are present).

The '"no_recurse"' option will only return the text of the element, not of any included sub-elements (same as "xml_text_only ").

inner_xml

Same as xml_string.

outer_xml

Same as sprint.

xml_text

Returns the text of the element, encoded (and processed by the current "output_filter " or "output_encoding " options, without any tag.

xml_text_only

Same as "xml_text " except that the text returned doesn't include the text of sub-elements.

set_pretty_print ($style)

Sets the pretty print method, amongst '"none"' (default), '"nsgmls"', '"nice"', '"indented"', '"record"' and '"record_c"'.

pretty_print styles:

set_empty_tag_style ($style)

Sets the method to output empty tags. Values are '"normal"' (default), '"html"', and '"expand"'.

"normal" outputs an empty tag '"<tag/>"', "html" adds a space '"<tag />"' for elements that can be empty in XHTML and "expand" outputs '"<tag></tag>"'.

Returns the previous setting.

set_remove_cdata ($flag)

Sets (or unsets) the flag that forces the twig to output "#CDATA" sections as regular (escaped) "#PCDATA".

Returns the previous setting.

set_indent ($string)

Sets the indentation for the indented pretty print style (default is two spaces).

Returns the previous setting.

set_quote ($quote)

Sets the quotes used for attributes. Valid values are '"double"' (default) or '"single"'.

Returns the previous setting.

cmp ($elt)

  Compare the order of the two elements in a twig.
  C<$a> is the <A>..</A> element, C<$b> is the <B>...</B> element
  document                        $a->cmp( $b)
  <A> ... </A> ... <B>  ... </B>     -1
  <A> ... <B>  ... </B> ... </A>     -1
  <B> ... </B> ... <A>  ... </A>      1
  <B> ... <A>  ... </A> ... </B>      1
   $a == $b                           0
   $a and $b not in the same tree   undef
    

before ($elt)

Returns 1 if $elt starts before the element, 0 otherwise. If the two elements are not in the same twig then return "undef".

    if( $a->cmp( $b) == -1) { return 1; } else { return 0; }
    

after ($elt)

Returns 1 if $elt starts after the element, 0 otherwise. If the two elements are not in the same twig then return "undef".

    if( $a->cmp( $b) == -1) { return 1; } else { return 0; }
    

other comparison methods

path

Returns the element context in a form similar to XPath's short form: '"/root/tag1/../tag"'.

xpath

Returns a unique XPath expression that can be used to find the element again.

It looks like "/doc/sect[3]/title": unique elements do not have an index, the others do.

flush

Flushes the twig up to the current element (strictly equivalent to "$elt->root->flush").

private methods

Low-level methods on the twig:

cond

Most of the navigation functions accept a condition as an optional argument The first element (or all elements for "children " or "ancestors ") that passes the condition is returned.

The condition is a single step of an XPath expression using the XPath subset defined by "get_xpath ". Additional conditions are:

The condition can be:

#ELT

Returns a "real" element (not a "#PCDATA", "#CDATA", "#COMMENT", or "#PI" element).

#TEXT

Returns a "#PCDATA" or "#CDATA" element.

regular expression

Returns an element whose tag matches the regexp. The regexp must be created with "qr//".

code reference

Applies the code, passing the current element as argument. If the code returns true, then the element is returned. If it returns false, then the code is applied to the next candidate.

XML::Twig::XPath

XML::Twig implements a subset of XPath through the "get_xpath " method.

If you want to use the full power of XPath, then you can use "XML::Twig::XPath" instead. In this case, "XML::Twig" uses "XML::XPathEngine" or "XML::XPath" to execute XPath queries. You still need "XML::XPathEngine" or "XML::XPath" installed to be able to use "XML::Twig::XPath".

See XML::XPathEngine or XML::XPath for more information.

The methods you can use are:

findnodes ($path)

Returns a list of nodes found by $path.

findnodes_as_string ($path)

Returns the nodes found reproduced as XML. The result is not guaranteed to be valid XML though.

findvalue ($path)

Returns the concatenation of the text content of the result nodes.

In order for "XML::XPathEngine" to be used as the XPath engine, the following methods are included in "XML::Twig":

in XML::Twig:

getRootNode

getParentNode

getChildNodes

in XML::Twig::Elt:

string_value

toString

getName

getRootNode

getNextSibling

getPreviousSibling

isElementNode

isTextNode

isPI

isPINode

isProcessingInstructionNode

isComment

isCommentNode

getTarget

getChildNodes

getElementById

XML::Twig::XPath::Elt

The methods you can use are the same as on "XML::Twig::XPath" elements:

findnodes ($path)

Returns a list of nodes found by $path.

findnodes_as_string ($path)

Returns the nodes found reproduced as XML. The result is not guaranteed to be valid XML though.

findvalue ($path)

Returns the concatenation of the text content of the result nodes.

XML::Twig::Entity_list

new

Creates an entity list.

add ($ent)

Adds an entity to an entity list.

add_new_ent ($name, $val, $sysid, $pubid, $ndata, $param)

Creates a new entity and adds it to the entity list.

delete ($ent or $tag).

Deletes an entity (defined by its name or by the Entity object) from the list.

print ($optional_filehandle)

Prints the entity list.

list

Returns the list as an array.

XML::Twig::Entity

new ($name, $val, $sysid, $pubid, $ndata, $param)

Same arguments as the Entity handler for XML::Parser.

print ($optional_filehandle)

Prints an entity declaration.

name

Returns the name of the entity.

val

Returns the value of the entity.

sysid

Returns the system id for the entity (for NDATA entities).

pubid

Returns the public id for the entity (for NDATA entities).

ndata

Returns true if the entity is an NDATA entity.

param

Returns true if the entity is a parameter entity.

text

Returns the entity declaration text.

XML::Twig::Notation_list

new

Create a notation list.

add ($notation)

Adds a notation to a notation list.

add_new_notation ($name, $base, $sysid, $pubid)

Creates a new notation and add it to the notation list.

delete ($notation or $tag).

Deletes a notation (defined by its name or by the Notation object) from the list.

sprint

Returns the notation list as a string.

print ($optional_filehandle)

Print the notation list.

list

Returns the list as an array.

XML::Twig::Notation

new ($name, $base, $sysid, $pubid)

Same arguments as the Notation handler for XML::Parser.

print ($optional_filehandle)

Prints a notation declaration.

name

Returns the name of the notation.

base

Returns the base to be used for resolving a relative URI.

sysid

Returns the system id for the notation.

pubid

Returns the public id for the notation.

text

Returns the notation declaration text.

Subclassing XML::Twig

Useful methods:

elt_class

In order to subclass "XML::Twig" you will probably need to subclass also "XML::Twig::Elt ". Use the "elt_class" option when you create the "XML::Twig" object to get the elements created in a different class (which should be a subclass of "XML::Twig::Elt".

add_options

If you inherit "XML::Twig" new method but want to add more options to it you can use this method to prevent XML::Twig from issuing warnings for those additional options.

DTD Handling

There are 3 possibilities here. They are:

No DTD

No doctype, no DTD information, no entity information, the world is simple...

Internal DTD

The XML document includes an internal DTD, and maybe entity declarations.

If you use the load_DTD option when creating the twig the DTD information and the entity declarations can be accessed.

The DTD and the entity declarations will be "flush"'ed (or "print"'ed) either as is (if they have not been modified) or as reconstructed (poorly, comments are lost, order is not kept, due to it's content this DTD should not be viewed by anyone) if they have been modified. You can also modify them directly by changing the "$twig->{twig_doctype}->{internal}" field (straight from XML::Parser, see the "Doctype" handler doc).

External DTD

The XML document includes a reference to an external DTD, and maybe entity declarations.

If you use the "load_DTD" when creating the twig the DTD information and the entity declarations can be accessed. The entity declarations will be "flush"'ed (or "print"'ed) either as is (if they have not been modified) or as reconstructed (badly, comments are lost, order is not kept).

You can change the doctype through the "$twig->set_doctype" method and print the dtd through the "$twig->dtd_text" or "$twig->dtd_print"
methods.

If you need to modify the entity list this is probably the easiest way to do it.

Flush

Remember that element handlers are called when the element is CLOSED, so if you have handlers for nested elements the inner handlers will be called first. It makes it for example trickier than it would seem to number nested sections (or clauses, or divs), as the titles in the inner sections are handled before the outer sections.

Alternative Modules

XML::Twig is not the only XML::Processing module available on CPAN (far from it!).

The main alternative I would recommend is XML::LibXML.

Here is a quick comparison of the 2 modules:

XML::LibXML, actually "libxml2" on which it is based, sticks to the standards, and implements a good number of them in a rather strict way: XML, XPath, DOM, RelaxNG, I must be forgetting a couple (XInclude?). It is fast and rather frugal memory-wise.

XML::Twig is older: when I started writing it XML::Parser/expat was the only game in town. It implements XML and that's about it (plus a subset of XPath, and you can use XML::Twig::XPath if you have XML::XPathEngine installed for full support). It is slower and requires more memory for a full tree than XML::LibXML. On the plus side (yes, there is a plus side!) it lets you process a big document in chunks, and thus let you tackle documents that couldn't be loaded in memory by XML::LibXML, and it offers a lot (and I mean a LOT!) of higher-level methods, for everything, from adding structure to "low-level" XML, to shortcuts for XHTML conversions and more. It also DWIMs quite a bit, getting comments and non-significant whitespaces out of the way but preserving them in the output for example. As it does not stick to the DOM, is also usually leads to shorter code than in XML::LibXML.

Beyond the pure features of the 2 modules, XML::LibXML seems to be preferred by "XML-purists", while XML::Twig seems to be more used by Perl Hackers who have to deal with XML. As you have noted, XML::Twig also comes with quite a lot of docs, but I am sure if you ask for help about XML::LibXML here or on Perlmonks you will get answers.

Note that it is actually quite hard for me to compare the 2 modules: on one hand I know XML::Twig inside-out and I can get it to do pretty much anything I need to (or I improve it ;--), while I have a very basic knowledge of XML::LibXML. So feature-wise, I'd rather use XML::Twig ;--). On the other hand, I am painfully aware of some of the deficiencies, potential bugs and plain ugly code that lurk in XML::Twig, even though you are unlikely to be affected by them (unless for example you need to change the DTD of a document programmatically), while I haven't looked much into XML::LibXML so it still looks shinny and clean to me.

That said, if you need to process a document that is too big to fit memory and XML::Twig is too slow for you, my reluctant advice would be to use "bare" XML::Parser. It won't be as easy to use as XML::Twig: basically with XML::Twig you trade some speed (depending on what you do from a factor 3 to... none) for ease-of-use, but it will be easier IMHO than using SAX (albeit not standard), and at this point a LOT faster (see the last test in <http://www.xmltwig.org/article/simple_benchmark/>).