XML::Twig - A perl module for processing huge XML documents in tree mode.

Note that this documentation is intended as a reference to the module.

Complete docs, including a tutorial, examples, an easier to use HTML version, a quick reference card and a FAQ are available at http://www.xmltwig.com/xmltwig

Small documents (loaded in memory as a tree):

  my $twig=XML::Twig->new();    # create the twig
  $twig->parsefile( 'doc.xml'); # build it
  my_process( $twig);           # use twig methods to process it 
  $twig->print;                 # output the twig

Huge documents (processed in combined stream/tree mode):

  # at most one div will be loaded in memory
  my $twig=XML::Twig->new(   
    twig_handlers => 
      { title   => sub { $_->set_tag( 'h2') }, # change title tags to h2
        para    => sub { $_->set_tag( 'p')  }, # change para to p
        hidden  => sub { $_->delete;       },  # remove hidden elements
        list    => \&my_list_process,          # process list elements
        div     => sub { $_[0]->flush;     },  # output and free memory
      },
    pretty_print => 'indented',                # output will be nicely formatted
    empty_tags   => 'html',                    # outputs <empty_tag />
                         );
    $twig->flush;                              # flush the end of the document

See XML::Twig 101 for other ways to use the module, as a filter for example

This module provides a way to process XML documents. It is build on top of CWXML::Parser.

The module offers a tree interface to the document, while allowing you to output the parts of it that have been completely processed.

It allows minimal resource (CPU and memory) usage by building the tree only for the parts of the documents that need actual processing, through the use of the CWtwig_roots and CWtwig_print_outside_roots options. The CWfinish and CWfinish_print methods also help to increase performances.

XML::Twig tries to make simple things easy so it tries its best to takes care of a lot of the (usually) annoying (but sometimes necessary) features that come with XML and XML::Parser.

XML::Twig can be used either on small XML documents (that fit in memory) or on huge ones, by processing parts of the document and outputting or discarding them once they are processed.

  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: CW$elt->{'att'}->{'foo'} return the CWfoo attribute for an element,

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

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

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

And much, much more, see Elt.

One of the strengths of XML::Twig is that it let you work with files that do not fit in memory (BTW storing an XML document in memory as a tree is quite memory-expensive, the expansion factor being often around 10).

To do this you can define handlers, that will be called once a specific element has been completely parsed. In these handlers you can access the element and process it as you see fit, using the navigation and the cut-n-paste methods, plus lots of convenient ones like CWprefix . Once the element is completely processed you can then CWflush it, which will output it and free the memory. You can also CWpurge 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');
  $t->flush; # don't forget to flush one last time in the end or anything
             # after the last </section> tag will not be output

  # 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.4, my favourite method...
      # 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
    }

There is of course more to it: you can trigger handlers on more elaborate conditions than just the name of the element, CWsection/title for example.

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

Here CWsub { $_->print } simply prints the current element (CW$_ is aliased to the element in the handler).

You can also trigger a handler on a test on an attribute:

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

You can also use CWstart_tag_handlers to process an element as soon as the start tag is found. Besides CWprefix you can also use CWsuffix ,

The twig_roots mode builds only the required sub-trees from the document Anything outside of the twig roots will just be 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.

You can combine the CWtwig_roots and the CWtwig_print_outside_roots options to build filters, which let you modify selected elements and will 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
    }

Before being uploaded to CPAN, XML::Twig 3.22 has been tested under the following environments:

linux-x86

perl 5.6.2, expat 1.95.8, XML::Parser 2.34 perl 5.8.0, expat 1.95.8, XML::Parser 2.34 perl 5.8.7, expat 1.95.8, XML::Parser2.34

Solaris

perl 5.6.1, expat 1.95.2, XML::Parser 2.31

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.8.3+ (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.com/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.6.*

Note that I can't compile XML::Parser 2.27 anymore, so I can't garantee 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 CWt/zz_dump_config.t

Whitespaces

Whitespaces that look non-significant are discarded, this behaviour can be controlled using the CWkeep_spaces , CWkeep_spaces_in and CWdiscard_spaces_in options.

Encoding

You can specify that you want the output in the same encoding as the input (provided you have valid XML, which means you have to specify the encoding either in the document or when you create the Twig object) using the CWkeep_encoding option You can also use CWoutput_encoding to convert the internal UTF-8 format to the required encoding.

Comments and Processing Instructions (PI)

Comments and PI's can be hidden from the processing, but still appear in the output (they are carried by the real element closer to them)

Pretty Printing

XML::Twig can output the document pretty printed so it is easier to read for us humans.

Surviving an untimely death

XML parsers are supposed to react violently when fed improper XML. XML::Parser just dies. XML::Twig provides the CWsafe_parse and the CWsafe_parsefile methods which wrap the parse in an eval and return either the parsed twig or 0 in case of failure.

Private attributes

Attributes with a name starting with # (illegal in XML) will not be output, so you can safely use them to store temporary values during processing. Note that you can store anything in a private attribute, not just text, it's just a regular Perl variable, so a reference to an object or a huge data structure is perfectly fine.

XML::Twig uses a very limited number of classes. The ones you are most likely to use are CWXML::Twig of course, which represents a complete XML document, including the document itself (the root of the document itself is CWroot), its handlers, its input or output filters... The other main class is CWXML::Twig::Elt, which models an XML element. Element here has a very wide definition: it can be a regular element, or but also text, with an element CWtag of CW#PCDATA (or CW#CDATA), an entity (tag is CW#ENT), a Processing Instruction (CW#PI), a comment (CW#COMMENT).

Those are the 2 commonly used classes.

You might want to look the CWelt_class option if you want to subclass CWXML::Twig::Elt.

Attributes are just attached to their parent element, they are not objects per se. (Please use the provided methods CWatt and CWset_att to access them, if you access them as a hash, then your code becomes implementaion deppndant and might break in the future).

Other classes that are seldom used are CWXML::Twig::Entity_list and CWXML::Twig::Entity.

If you use CWXML::Twig::XPath instead of CWXML::Twig, elements are then created as CWXML::Twig::XPath::Elt

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

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 XML::Twig specifics. New Options:

twig_handlers

This argument replaces the corresponding XML::Parser argument. It consists of a hash CW{ expression = \&handler}> where expression is a generic_attribute_condition, string_condition, an attribute_condition,full_path, a partial_path, a tag, a tag_regexp, _default_ or _all_. The idea is to support a usefull but efficient (thus limited) subset of XPATH. A fuller expression set will be supported in the future, as users ask for more and as I manage to implement it efficiently. This will never encompass all of XPATH due to the streaming nature of parsing (no lookahead after the element end tag). A generic_attribute_condition is a condition on an attribute, in the form CW*[@att="val"] or CW*[@att], simple quotes can be used instead of double quotes and the leading '*' is actually optional. No matter what the tag of the element is, the handler will be triggered either if the attribute has the specified value or if it just exists. A string_condition is a condition on the content of an element, in the form CWtag[string()="foo"], simple quotes can be used instead of double quotes, at the moment you cannot escape the quotes (this will be added as soon as I dig out my copy of Mastering Regular Expressions from its storage box). The text returned is, as per what I (and Matt Sergeant!) understood from the XPATH spec the concatenation of all the text in the element, excluding all markup. Thus to call a handler on the elementCW<p>text <b>bold</b></p> the appropriate condition is CWp[string()="text bold"]. Note that this is not exactly conformant to the XPATH spec, it just tries to mimic it while being still quite concise. A extension of that notation is CWtag[string(CBchild_tagCW)="foo"] where the handler will be called if a child of a CWtag element has a text value of CWfoo. At the moment only direct children of the CWtag element are checked. If you need to test on descendants of the element let me know. The fix is trivial but would slow down the checks, so I'd like to keep it the way it is. A regexp_condition is a condition on the content of an element, in the form CWtag[string()=~ /foo/"]. This is the same as a string condition except that the text of the element is matched to the regexp. The CWi, CWm, CWs and CWo modifiers can be used on the regexp. The CWtag[string(CBchild_tagCW)=~ /foo/"] extension is also supported. An attribute_condition is a simple condition of an attribute of the current element in the form CWtag[@att="val"] (simple quotes can be used instead of double quotes, you can escape quotes either). If several attribute_condition are true the same element all the handlers can be called in turn (in the order in which they were first defined). If the CW="val" part is ommited ( the condition is then CWtag[@att]) then the handler is triggered if the attribute actually exists for the element, no matter what it's value is. A full_path looks like CW'/doc/section/chapter/title', it starts with a / then lists all the tags to the element. The handler will be called if the path to the current element (in the input document) is exactly as defined by the CWfull_path. A partial_path is like a full_path except it does not start with a /: CW'chapter/title' for example. The handler will be called if the path to the element (in the input document) ends as defined in the CWpartial_path. WARNING: (hopefully temporary) at the moment CWstring_condition, CWregexp_condition and CWattribute_condition are only supported on a simple tag, not on a path. A tag_regexp is a regular expression (created with CWqr//), applied to the tag name. For example CWqr/^h\d$/i would match CWh1, CWH1, CWh2, CWH2... A tag. #CDATA can be used to call a handler for a CDATA. A special tag _all_ is used to call a function for each element. The special tag _default_ is used to call a handler for each element that does NOT have a specific handler. The order of precedence to trigger a handler is: generic_attribute_condition, string_condition, regexp_condition, attribute_condition, full_path, longer partial_path, shorter partial_path, tag_regexp, tag, _default_ . Important: once a handler has been triggered if it returns 0 then no other handler is called, exept a CW_all_ handler which will be called anyway. If a handler returns a true value and other handlers apply, then the next applicable handler will be called. Repeat, rince, lather..; The exception to that rule is when the CWdo_not_chain_handlers option is set, in which case only the first handler will be called. Note that it might be a good idea to explicitely return a short true value (like 1) from handlers: this ensures that other applicable handlers are called even if the last statement for the handler happens to evaluate to false. This might also speedup the code by avoiding the result of the last statement of the code to be copied and passed to the code managing handlers. It can really pay to have 1 instead of a long string returned. When an element is CLOSED the corresponding handler is called, with 2 arguments: the twig and the CW/Element . The twig includes the document tree that has been built so far, the element is the complete sub-tree for the element. This means that handlers for inner elements are called before handlers for outer elements. CW$_ is also set to the element, so it is easy to write inline handlers like

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

Text is stored in elements whose tag is #PCDATA (due to mixed content, text and sub-element in an element there is no way to store the text as just an attribute of the enclosing element). Warning: if you have used purge or flush on the twig the element might not be complete, some of its children might have been entirely flushed or purged, and the start tag might even have been printed (by CWflush) already, so changing its tag might not give the expected result. More generally, the full_path, partial_path, tag and tag_regexp expressions are evaluated against the input document. Which means that even if you have changed the tag of an element (changing the tag of a parent element from a handler for example) the change will not impact the expression evaluation. Attributes in attribute_condition are different though. As the initial value of attribute is not stored the handler will be triggered if the current attribute/value pair is found when the element end tag is found. Although this can be quite confusing it should not impact most of users, and allow others to play clever tricks with temporary attributes. Let me know if this is a problem for you.

twig_roots

This argument let's you build the tree only for those elements you are interested in.

  Example: my $t= XML::Twig->new( twig_roots => { title => 1, subtitle => 1});
           $t->parsefile( file);
           my $t= XML::Twig->new( twig_roots => { 'section/title' => 1});
           $t->parsefile( file);

return a twig containing a document including only CWtitle and CWsubtitle elements, as children of the root element. You can use generic_attribute_condition, attribute_condition, full_path, partial_path, tag, tag_regexp, _default_ and _all_ to trigger the building of the twig. string_condition and regexp_condition cannot be used as the content of the element, and the string, have not yet been parsed when the condition is checked. WARNING: path are checked for the document. Even if the CWtwig_roots option is used they will be checked against the full document tree, not the virtual tree created by XML::Twig WARNING: twig_roots elements should NOT be nested, that would hopelessly confuse XML::Twig ;--( Note: you can set handlers (twig_handlers) using twig_roots Example: my CW$t= XML::Twig->new( twig_roots => { title => sub { CW$_{1]->print;}, subtitle => \&process_subtitle } ); CW$t->parsefile( file);

twig_print_outside_roots

To be used in conjunction with the CWtwig_roots argument. When set to a true value this will print the document outside of the CWtwig_roots elements.

 Example: my $t= XML::Twig->new( twig_roots => { title => \&number_title },
                                twig_print_outside_roots => 1,
                               );
           $t->parsefile( file);
           { my $nb;
           sub number_title
             { my( $twig, $title);
               $nb++;
               $title->prefix( "$nb "; }
               $title->print;
             }
           }

This example prints the document outside of the title element, calls CWnumber_title for each CWtitle element, prints it, and then resumes printing the document. The twig is built only for the CWtitle elements. If the value is a reference to a file handle then the document outside the CWtwig_roots elements will be output to this file handle:

  open( OUT, ">out_file") or die "cannot open out file out_file:$!";
  my $t= XML::Twig->new( twig_roots => { title => \&number_title },
                         # default output to OUT
                         twig_print_outside_roots => \*OUT, 
                       );

         { my $nb;
           sub number_title
             { my( $twig, $title);
               $nb++;
               $title->prefix( "$nb "; }
               $title->print( \*OUT);    # you have to print to \*OUT here
             }
           }

start_tag_handlers

A hash CW{ expression = \&handler}>. Sets element handlers that are called when the element is open (at the end of the XML::Parser CWStart handler). The handlers are called with 2 params: the twig and the element. The element is empty at that point, its attributes are created though. You can use generic_attribute_condition, attribute_condition, full_path, partial_path, tag, tag_regexp, _default_ and _all_ to trigger the handler. string_condition and regexp_condition cannot be used as the content of the element, and the string, have not yet been parsed when the condition is checked. The main uses for those handlers are to change the tag name (you might have to do it as soon as you find the open tag if you plan to CWflush the twig at some point in the element, and to create temporary attributes that will be used when processing sub-element with CWtwig_hanlders. You should also use it to change tags if you use CWflush. If you change the tag in a regular CWtwig_handler then the start tag might already have been flushed. Note: CWstart_tag handlers can be called outside of CWtwig_roots if this argument is used, in this case handlers are called with the following arguments: CW$t (the twig), CW$tag (the tag of the element) and CW%att (a hash of the attributes of the element). If the CWtwig_print_outside_roots argument is also used, if the last handler called returns a CWtrue value, then the the start tag will be output as it appeared in the original document, if the handler returns a a CWfalse value then the start tag will not be printed (so you can print a modified string yourself for example). Note that you can use the ignore method in CWstart_tag_handlers (and only there).

end_tag_handlers

A hash CW{ expression = \&handler}>. Sets element handlers that are called when the element is closed (at the end of the XML::Parser CWEnd handler). The handlers are called with 2 params: the twig and the tag of the element. twig_handlers are called when an element is completely parsed, so why have this redundant option? There is only one use for CWend_tag_handlers: when using the CWtwig_roots option, to trigger a handler for an element outside the roots. It is for example very useful to number titles in a document using nested sections:

  my @no= (0);
  my $no;
  my $t= XML::Twig->new( 
          start_tag_handlers => 
           { section => sub { $no[$#no]++; $no= join '.', @no; push @no, 0; } },
          twig_roots         => 
           { title   => sub { $_[1]->prefix( $no); $_[1]->print; } },
          end_tag_handlers   => { section => sub { pop @no;  } },
          twig_print_outside_roots => 1
                      );
   $t->parsefile( $file);

Using the CWend_tag_handlers argument without CWtwig_roots will result in an error.

do_not_chain_handlers

If this option is set to a true value, then only one handler will be called for each element, even if several satisfy the condition Note that the CW_all_ handler will still be called regardeless

ignore_elts

This option lets you ignore elements when building the twig. This is useful in cases where you cannot use CWtwig_roots to ignore elements, for example if the element to ignore is a sibling of elements you are interested in. Example:

  my $twig= XML::Twig->new( ignore_elts => { elt => 1 });
  $twig->parsefile( 'doc.xml');

This will build the complete twig for the document, except that all CWelt elements (and their children) will be left out.

char_handler

A reference to a subroutine that will be called every time CWPCDATA is found. The subroutine receives the string as argument, and returns the modified string:

  # we want all strings in upper case
  sub my_char_handler
    { my( $text)= @_;
      $text= uc( $text);
      return $text;
    }

elt_class

The name of a class used to store elements. this class should inherit from CWXML::Twig::Elt (and by default it is CWXML::Twig::Elt). This option is used to subclass the element class and extend it with new methods. This option is needed because during the parsing of the XML, elements are created by CWXML::Twig, without any control from the user code.

keep_atts_order

Setting this option to a true value causes the attribute hash to be tied to a CWTie::IxHash object. This means that CWTie::IxHash needs to be installed for this option to be available. It also means that the hash keeps its order, so you will get the attributes in order. This allows outputing the attributes in the same order as they were in the original document.

keep_encoding

This is a (slightly?) evil option: if the XML document is not UTF-8 encoded and you want to keep it that way, then setting keep_encoding will use theCWExpat original_string method for character, thus keeping the original encoding, as well as the original entities in the strings. See the CWt/test6.t test file to see what results you can expect from the various encoding options. WARNING: if the original encoding is multi-byte then attribute parsing will be EXTREMELY unsafe under any Perl before 5.6, as it uses regular expressions which do not deal properly with multi-byte characters. You can specify an alternate function to parse the start tags with the CWparse_start_tag option (see below) WARNING: this option is NOT used when parsing with the non-blocking parser (CWparse_start, CWparse_more, parse_done methods) which you probably should not use with XML::Twig anyway as they are totally untested!

output_encoding

This option generates an output_filter using CWEncode, CWText::Iconv or CWUnicode::Map8 and CWUnicode::Strings, and sets the encoding in the XML declaration. This is the easiest way to deal with encodings, if you need more sophisticated features, look at CWoutput_filter below

output_filter

This option is used to convert the character encoding of the output document. It is passed either a string corresponding to a predefined filter or a subroutine reference. The filter will be called every time a document or element is processed by the print functions (CWprint, CWsprint, CWflush). Pre-defined filters:

latin1

uses either CWEncode, CWText::Iconv or CWUnicode::Map8 and CWUnicode::String or a regexp (which works only with XML::Parser 2.27), in this order, to convert all characters to ISO-8859-1 (aka latin1)

html

does the same conversion as CWlatin1, plus encodes entities using CWHTML::Entities (oddly enough you will need to have HTML::Entities intalled for it to be available). This should only be used if the tags and attribute names themselves are in US-ASCII, or they will be converted and the output will not be valid XML any more

safe

converts the output to ASCII (US) only plus character entities (CW&#nnn;) this should be used only if the tags and attribute names themselves are in US-ASCII, or they will be converted and the output will not be valid XML any more

safe_hex

same as CWsafe except that the character entities are in hexa (CW&#xnnn;)

encode_convert ($encoding)

Return a subref that can be used to convert utf8 strings to CW$encoding). Uses CWEncode.

   my $conv = XML::Twig::encode_convert( 'latin1');
   my $t = XML::Twig->new(output_filter => $conv);

iconv_convert ($encoding)

this function is used to create a filter subroutine that will be used to convert the characters to the target encoding using CWText::Iconv (which needs to be installed, look at the documentation for the module and for the CWiconv library to find out which encodings are available on your system)

   my $conv = XML::Twig::iconv_convert( 'latin1');
   my $t = XML::Twig->new(output_filter => $conv);

unicode_convert ($encoding)

this function is used to create a filter subroutine that will be used to convert the characters to the target encoding using CWUnicode::Strings and CWUnicode::Map8 (which need to be installed, look at the documentation for the modules to find out which encodings are available on your system)

   my $conv = XML::Twig::unicode_convert( 'latin1');
   my $t = XML::Twig->new(output_filter => $conv);

The CWtext and CWatt methods do not use the filter, so their result are always in unicode. Those predeclared filters are based on subroutines that can be used by themselves (as CWXML::Twig::foo).

html_encode ($string)

Use CWHTML::Entities to encode a utf8 string

safe_encode ($string)

Use either a regexp (perl < 5.8) or CWEncode to encode non-ascii characters in the string in CW&#<nnnn>; format

safe_encode_hex ($string)

Use either a regexp (perl < 5.8) or CWEncode to encode non-ascii characters in the string in CW&#x<nnnn>; format

regexp2latin1 ($string)

Use a regexp to encode a utf8 string into latin 1 (ISO-8859-1). Does not work with Perl 5.8.0!

output_text_filter

same as output_filter, except it doesn't apply to the brackets and quotes around attribute values. This is useful for all filters that could change the tagging, basically anything that does not just change the encoding of the output. CWhtml, CWsafe and CWsafe_hex are better used with this option.

input_filter

This option is similar to CWoutput_filter except the filter is applied to the characters before they are stored in the twig, at parsing time.

remove_cdata

Setting this option to a true value will force the twig to output CDATA sections as regular (escaped) PCDATA

parse_start_tag

If you use the CWkeep_encoding option then this option can be used to replace the default parsing function. You should provide a coderef (a reference to a subroutine) as the argument, this subroutine takes the original tag (given by XML::Parser::Expat CWoriginal_string() method) and returns a tag and the attributes in a hash (or in a list attribute_name/attribute value).

expand_external_ents

When this option is used external entities (that are defined) are expanded when the document is output using print functions such as CWprint , CWsprint , CWflush and CWxml_string . Note that in the twig the entity will be stored as an element whith a tag 'CW#ENT', the entity will not be expanded there, so you might want to process the entities before outputting it.

load_DTD

If this argument is set to a true value, CWparse or CWparsefile on the twig will load the DTD information. This information can then be accessed through the twig, in a CWDTD_handler for example. This will load even an external DTD. Default and fixed values for attributes will also be filled, based on the DTD. Note that to do this the module will generate a temporary file in the current directory. If this is a problem let me know and I will add an option to specify an alternate directory. See DTD Handling for more information

DTD_handler

Set a handler that will be called once the doctype (and the DTD) have been loaded, with 2 arguments, the twig and the DTD.

no_prolog

Does not output a prolog (XML declaration and DTD)

id

This optional argument gives the name of an attribute that can be used as an ID in the document. Elements whose ID is known can be accessed through the elt_id method. id defaults to 'id'. See CWBUGS

discard_spaces

If this optional argument is set to a true value then spaces are discarded when they look non-significant: strings containing only spaces are discarded. This argument is set to true by default.

keep_spaces

If this optional argument is set to a true value then all spaces in the document are kept, and stored as CWPCDATA. Warning: adding this option can result in changes in the twig generated: space that was previously discarded might end up in a new text element. see the difference by calling the following code with 0 and 1 as arguments:

  perl -MXML::Twig -e'print XML::Twig->new( keep_spaces => shift)->parse( "<d> \n<e/></d>")->_dump'

CWkeep_spaces and CWdiscard_spaces cannot be both set.

discard_spaces_in

This argument sets CWkeep_spaces to true but will cause the twig builder to discard spaces in the elements listed. The syntax for using this argument is:

  XML::Twig->new( discard_spaces_in => [ 'elt1', 'elt2']);

keep_spaces_in

This argument sets CWdiscard_spaces to true but will cause the twig builder to keep spaces in the elements listed. The syntax for using this argument is:

  XML::Twig->new( keep_spaces_in => [ 'elt1', 'elt2']);

Warning: adding this option can result in changes in the twig generated: space that was previously discarded might end up in a new text element.

pretty_print

Set the pretty print method, amongst 'CWnone' (default), 'CWnsgmls', 'CWnice', 'CWindented', 'CWindented_c', 'CWrecord' and 'CWrecord_c' pretty_print formats:

none

The document is output as one ling string, with no line breaks except those found within text elements

nsgmls

Line breaks are inserted in safe places: that is within tags, between a tag and an attribute, between attributes and before the > at the end of a tag. This is quite ugly but better than CWnone, and it is very safe, the document will still be valid (conforming to its DTD). This is how the SGML parser CWsgmls splits documents, hence the name.

nice

This option inserts line breaks before any tag that does not contain text (so element with textual content are not broken as the \n is the significant). WARNING: this option leaves the document well-formed but might make it invalid (not conformant to its DTD). If you have elements declared as

  <!ELEMENT foo (#PCDATA|bar)>

then a CWfoo element including a CWbar one will be printed as

  <foo>
  <bar>bar is just pcdata</bar>
  </foo>

This is invalid, as the parser will take the line break after the CWfoo tag as a sign that the element contains PCDATA, it will then die when it finds the CWbar tag. This may or may not be important for you, but be aware of it!

indented

Same as CWnice (and with the same warning) but indents elements according to their level

indented_c

Same as CWindented but a little more compact: the closing tags are on the same line as the preceeding text

record

This is a record-oriented pretty print, that display data in records, one field per line (which looks a LOT like CWindented)

record_c

Stands for record compact, one record per line

empty_tags

Set the empty tag display style ('CWnormal', 'CWhtml' or 'CWexpand').

comments

Set the way comments are processed: 'CWdrop' (default), 'CWkeep' or 'CWprocess' Comments processing options:

drop

drops the comments, they are not read, nor printed to the output

keep

comments are loaded and will appear on the output, they are not accessible within the twig and will not interfere with processing though Note: comments in the middle of a text element such as

  <p>text <!-- comment --> more text --></p>

are kept at their original position in the text. Using ˝print methods like CWprint or CWsprint will return the comments in the text. Using CWtext or CWfield on the other hand will not. Any use of CWset_pcdata on the CW#PCDATA element (directly or through other methods like CWset_content) will delete the comment(s).

process

comments are loaded in the twig and will be treated as regular elements (their CWtag is CW#COMMENT) this can interfere with processing if you expect CW$elt->{first_child} to be an element but find a comment there. Validation will not protect you from this as comments can happen anywhere. You can use CW$elt->first_child( 'tag') (which is a good habit anyway) to get where you want. Consider using CWprocess if you are outputing SAX events from XML::Twig.

pi

Set the way processing instructions are processed: 'CWdrop', 'CWkeep' (default) or 'CWprocess' Note that you can also set PI handlers in the CWtwig_handlers option:

  '?'       => \&handler
  '?target' => \&handler 2

The handlers will be called with 2 parameters, the twig and the PI element if CWpi is set to CWprocess, and with 3, the twig, the target and the data if CWpi is set to CWkeep. Of course they will not be called if CWpi is set to CWdrop. If CWpi is set to CWkeep the handler should return a string that will be used as-is as the PI text (it should look like "CW <?target data? >" or '' if you want to remove the PI), Only one handler will be called, CW?target or CW? if no specific handler for that target is available.

map_xmlns

This option is passed a hashref that maps uri's to prefixes. The prefixes in the document will be replaced by the ones in the map. The mapped prefixes can (actually have to) be used to trigger handlers, navigate or query the document. Here is an example:

  my $t= XML::Twig->new( map_xmlns => {'http://www.w3.org/2000/svg' => "svg"},
                         twig_handlers => 
                           { 'svg:circle' => sub { $_->set_att( r => 20) } },
                         pretty_print => 'indented', 
                       )
                  ->parse( '<doc xmlns:gr="http://www.w3.org/2000/svg">
                              <gr:circle cx="10" cy="90" r="10"/>
                           </doc>'
                         )
                  ->print;

This will output:

  <doc xmlns:svg="http://www.w3.org/2000/svg">
     <svg:circle cx="10" cy="90" r="20"/>
  </doc>

keep_original_prefix

When used with CWmap_xmlns this option will make CWXML::Twig use the original namespace prefixes when outputing a document. The mapped prefix will still be used for triggering handlers and in navigation and query methods.

  my $t= XML::Twig->new( map_xmlns => {'http://www.w3.org/2000/svg' => "svg"},
                         twig_handlers => 
                           { 'svg:circle' => sub { $_->set_att( r => 20) } },
                         keep_original_prefix => 1,
                         pretty_print => 'indented', 
                       )
                  ->parse( '<doc xmlns:gr="http://www.w3.org/2000/svg">
                              <gr:circle cx="10" cy="90" r="10"/>
                           </doc>'
                         )
                  ->print;

This will output:

  <doc xmlns:gr="http://www.w3.org/2000/svg">
     <gr:circle cx="10" cy="90" r="20"/>
  </doc>

This option creates lists of specific elements during the parsing of the XML. It takes a reference to either a list of triggering expressions or to a hash name => expression, and for each one generates the list of elements that match the expression. The list can be accessed through the CWindex method. example:

  # using an array ref
  my $t= XML::Twig->new( index => [ 'div', 'table' ])
                  ->parsefile( "foo.xml');
  my $divs= $t->index( 'div');
  my $first_div= $divs->[0];
  my $last_table= $t->index( table => -1);

  # using a hashref to name the indexes
  my $t= XML::Twig->new( index => { email => 'a[@href=~/^\s*mailto:/]')
                  ->parsefile( "foo.xml');
  my $last_emails= $t->index( email => -1);

Note that the index is not maintained after the parsing. If elements are deleted, renamed or otherwise hurt during processing, the index is NOT updated. Note: I _HATE_ the Java-like name of arguments used by most XML modules. So in pure TIMTOWTDI fashion all arguments can be written either as CWUglyJavaLikeName or as CWreadable_perl_name: CWtwig_print_outside_roots or CWTwigPrintOutsideRoots (or even CWtwigPrintOutsideRoots {shudder}). XML::Twig normalizes them before processing them. The CW$source parameter should either be a string containing the whole XML document, or it should be an open CWIO::Handle. Constructor options to CWXML::Parser::Expat given as keyword-value pairs may follow theCW$source parameter. These override, for this call, any options or attributes passed through from the XML::Parser instance. A die call is thrown if a parse error occurs. Otherwise it will return the twig built by the parse. Use CWsafe_parse if you want the parsing to return even when an error occurs.

parsestring

This is just an alias for CWparse for backwards compatibility.

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

Open CWFILE for reading, then call CWparse with the open handle. The file is closed no matter how CWparse returns. A CWdie call is thrown if a parse error occurs. Otherwise it will return the twig built by the parse. Use CWsafe_parsefile if you want the parsing to return even when an error occurs. Gets the data from CW$url and parse 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 CWget the XML file and then parse it as a string.

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

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

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

This method is similar to CWparse except that it wraps the parsing in an CWeval block. It returns the twig on success and 0 on failure (the twig object also contains the parsed twig). CW$@ 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 CWparsefile except that it wraps the parsing in an CWeval block. It returns the twig on success and 0 on failure (the twig object also contains the parsed twig) . CW$@ 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. Same as CWparseurl except that it wraps the parsing in an CWeval block. It returns the twig on success and 0 on failure (the twig object also contains the parsed twig) . CW$@ contains the error message on failure

parse_html

parse an HTML string or file handle (by converting it to XML using HTML::TreeBuilder, which needs to be available). Alpha: implementation, and thus generated XML could change.

parsefile_html

parse an HTML file (by converting it to XML using HTML::TreeBuilder, which needs to be available). The file is loaded completely in memory and converted to XML before being parsed. Alpha: implementation, and thus generated XML could change.

xparse ($thing_to_parse)

parse the CW$thing_to_parse, whether it is a filehandle, a string, an HTML file, an HTML URL, an 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. create a twig with the CW$optional_options, and parse the CW$thing_to_parse, whether it is a filehandle, a string, an HTML file, an HTML URL, an URL or a file. Examples:

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

parser

This method returns the CWexpat 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 CW$t->parser->current_line.

setTwigHandlers ($handlers)

Set the twig_handlers. CW$handlers is a reference to a hash similar to the one in the CWtwig_handlers option of new. All previous handlers are unset. The method returns the reference to the previous handlers. Set a single twig_handler for elements matching CW$exp. CW$handler is a reference to a subroutine. If the handler was previously set then the reference to the previous handler is returned.

setStartTagHandlers ($handlers)

Set the start_tag handlers. CW$handlers is a reference to a hash similar to the one in the CWstart_tag_handlers option of new. All previous handlers are unset. The method returns the reference to the previous handlers. Set a single start_tag handlers for elements matching CW$exp. CW$handler is a reference to a subroutine. If the handler was previously set then the reference to the previous handler is returned.

setEndTagHandlers ($handlers)

Set the end_tag handlers. CW$handlers is a reference to a hash similar to the one in the CWend_tag_handlers option of new. All previous handlers are unset. The method returns the reference to the previous handlers. Set a single end_tag handlers for elements matching CW$exp. CW$handler is a reference to a subroutine. If the handler was previously set then the reference to the previous handler is returned.

setTwigRoots ($handlers)

Same as using the CWtwig_roots option when creating the twig Set a CWchar_handler

setIgnoreEltsHandler ($exp)

Set a CWignore_elt handler (elements that match CW$exp will be ignored

setIgnoreEltsHandlers ($exp)

Set all CWignore_elt handlers (previous handlers are replaced)

dtd

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

xmldecl

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

doctype

Return the doctype for the document

dtd_text

Return the DTD text

dtd_print

Print the DTD

model ($tag)

Return the model (in the DTD) for the element CW$tag

root

Return the root element of a twig

set_root ($elt)

Set the root of a twig

first_elt ($optional_condition)

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

last_elt ($optional_condition)

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

elt_id ($id)

Return the element whose CWid attribute is CW$id

getEltById

Same as CWelt_id If the CW$optional_index argument is present, return the corresponding element in the index (created using the CWindex option for CWXML::Twig-new>) If the argument is not present, return an arrayref to the index

encoding

This method returns the encoding of the XML document, as defined by the CWencoding attribute in the XML declaration (ie it is CWundef if the attribute is not defined)

set_encoding

This method sets the value of the CWencoding 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

This method returns the XML version, as defined by the CWversion attribute in the XML declaration (ie it is CWundef if the attribute is not defined)

set_xml_version

This method sets the value of the CWversion attribute in the XML declaration. If the declaration did not exist it is created.

standalone

This method returns the value of the CWstandalone declaration for the document

set_standalone

This method sets the value of the CWstandalone 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

Set the CWencoding attribute in the XML declaration Set the doctype of the element. If an argument is CWundef (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

Return the entity list of a twig

entity_names

Return the list of all defined entities

entity ($entity_name)

Return the entity Performs a (very fast) global change. All elements CW$old_gi are now CW$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 CWBUGS Flushes a twig up to (and including) the current element, then deletes all unnecessary elements from the tree that's kept in memory. CWflush 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 the whole parsing don't forget toCWflush 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. options: use the CWupdate_DTD option if you have updated the (internal) DTD and/or the entity list and you want the updated DTD to be output The CWpretty_print option sets the pretty printing of the document.

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

Flushes up to the CW$elt element. This allows you to keep part of the tree in memory when you CWflush. options: see flush.

purge

Does the same as a CWflush 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 CW$elt element. This allows you to keep part of the tree in memory when you CWpurge. Prints the whole document associated with the twig. To be used only AFTER the parse. options: see CWflush. Prints the whole document associated with the twig to file CW$filename. To be used only AFTER the parse. options: see CWflush.

sprint

Return the text of the whole document associated with the twig. To be used only AFTER the parse. options: see CWflush.

trim

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

toSAX1 ($handler)

Send SAX events for the twig to the SAX1 handler CW$handler

toSAX2 ($handler)

Send SAX events for the twig to the SAX2 handler CW$handler

flush_toSAX1 ($handler)

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

flush_toSAX2 ($handler)

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

ignore

This method can only be called in CWstart_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 will 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 any more for it and what has already been built will be deleted)

set_pretty_print ($style)

Set the pretty print method, amongst 'CWnone' (default), 'CWnsgmls', 'CWnice', 'CWindented', 'CWrecord' and 'CWrecord_c' WARNING: the pretty print style is a GLOBAL variable, so once set it's applied to ALL CWprint's (and CWsprint's). Same goes if you use XML::Twig with CWmod_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)

Set the empty tag display style ('CWnormal', 'CWhtml' or 'CWexpand'). As with CWset_pretty_print this sets a global flag. CWnormal outputs an empty tag 'CW<tag/>', CWhtml adds a space 'CW<tag />' and CWexpand outputs 'CW<tag></tag>'

set_remove_cdata ($flag)

set (or unset) the flag that forces the twig to output CDATA sections as regular (escaped) PCDATA Prints the prolog (XML declaration + DTD + entity declarations) of a document. options: see CWflush. Return the prolog (XML declaration + DTD + entity declarations) of a document. options: see CWflush.

finish

Call Expat CWfinish 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 up a lot faster than with the handlers set.

finish_print

Stop 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.

set_expand_external_entities

Same as using the CWexpand_external_ents option when creating the twig

set_input_filter

Same as using the CWinput_filter option when creating the twig

set_keep_atts_order

Same as using the CWkeep_atts_order option when creating the twig

set_keep_encoding

Same as using the CWkeep_encoding option when creating the twig

set_output_filter

Same as using the CWoutput_filter option when creating the twig

set_output_text_filter

Same as using the CWoutput_text_filter option when creating the twig

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:

depth

Returns the size of the context list.

in_element

Returns true if NAME is equal to the name of the innermost cur‐ rently opened element. If namespace processing is being used and you want to check against a name that may be in a namespace, then use the generate_ns_name method to create the NAME argument.

within_element

Returns the number of times the given name appears in the context list. If namespace processing is being used and you want to check against a name that may be in a namespace, then use the gener‐ ate_ns_name method to create the NAME argument.

context

Returns a list of element names that represent open elements, with the last one being the innermost. Inside start and end tag han‐ dlers, this will be the tag of the parent element.

current_line

Returns the line number of the current position of the parse.

current_column

Returns the column number of the current position of the parse.

current_byte

Returns the current position of the parse.

position_in_context

Returns a string that shows the current parse position. LINES should be an integer >= 0 that represents the number of lines on either side of the current parse line to place into the returned string.

base ([NEWBASE])

Returns the current value of the base for resolving relative URIs. If NEWBASE is supplied, changes the base to that value.

current_element

Returns the name of the innermost currently opened element. Inside start or end handlers, returns the parent of the element associated with those tags.

element_index

Returns an integer that is the depth-first visit order of the cur‐ rent element. This will be zero outside of the root element. For example, this will return 1 when called from the start handler for the root element start tag.

recognized_string

Returns the string from the document that was recognized in order to call the current handler. For instance, when called from a start handler, it will give us the the start-tag string. The string is encoded in UTF-8. This method doesn't return a meaningful string inside declaration handlers.

original_string

Returns the verbatim string from the document that was recognized in order to call the current handler. The string is in the original document encoding. This method doesn't return a meaningful string inside declaration handlers.

xpcroak

Concatenate onto the given message the current line number within the XML document plus the message implied by ErrorContext. Then croak with the formed message.

xpcarp

Concatenate onto the given message the current line number within the XML document plus the message implied by ErrorContext. Then carp with the formed message.

xml_escape(TEXT [, CHAR [, CHAR ...]])

Returns TEXT with markup characters turned into character entities. Any additional characters provided as arguments are also turned into character references where found in TEXT. (this method is broken on some versions of expat/XML::Parser) Return the element context in a form similar to XPath's short form: 'CW/root/tag1/../tag' Performs a CWget_xpath on the document root (see <Elt|Elt>) If the CW$optional_array_ref argument is used the array must contain elements. The CW$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. same as CWget_xpath same as CWget_xpath (similar to the XML::LibXML method) Return the CWjoin of all texts of the results of appling CWget_xpath to the node (similar to the XML::LibXML method) subs_text does text substitution on the whole document, similar to perl's CW s/// operator.

dispose

Useful only if you don't have CWScalar::Util or CWWeakRef installed. Reclaims properly 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 CW$twig->dispose to clear this problem.

create_accessors (list_of_attribute_names)

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

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

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.

The CWtag is optional (but then you can't have a content ), the CW$optional_atts argument is a refreference to a hash of attributes, the content can be just a string or a list of strings and element. A content of 'CW#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');

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

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

gi

Return the gi of the element (the gi is the CWgeneric identifier the tag name in SGML parlance). CWtag and CWname are synonyms of CWgi.

tag

Same as CWgi

name

Same as CWtag

set_gi ($tag)

Set the gi (tag) of an element

set_tag ($tag)

Set the tag (=CWtag) of an element

set_name ($name)

Set the name (=CWtag) of an element

root

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

twig

Return the twig containing the element.

parent ($optional_condition)

Return the parent of the element, or the first ancestor matching the CW$optional_condition

first_child ($optional_condition)

Return the first child of the element, or the first child matching the CW$optional_condition

has_child ($optional_condition)

Return the first child of the element, or the first child matching the CW$optional_condition (same as first_child)

has_children ($optional_condition)

Return the first child of the element, or the first child matching the CW$optional_condition (same as first_child)

first_child_text ($optional_condition)

Return the text of the first child of the element, or the first child matching the CW$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:

last_child_text

prev_sibling_text

next_sibling_text

prev_elt_text

next_elt_text

child_text

parent_text

All this methods also exist in trimmed variant:

first_child_trimmed_text

last_child_trimmed_text

prev_sibling_trimmed_text

next_sibling_trimmed_text

prev_elt_trimmed_text

next_elt_trimmed_text

child_trimmed_text

parent_trimmed_text

field ($optional_condition)

Same method as CWfirst_child_text with a different name

trimmed_field ($optional_condition)

Same method as CWfirst_child_trimmed_text with a different name Set the content of the first child of the element that matches CW$condition, the rest of the arguments is tha same as for CWset_content If no child matches CW$condition _and_ if CW$condition is a valid XML element name, then a new element by that name is created and inserted as the last child.

first_child_matches ($optional_condition)

Return the element if the first child of the element (if it exists) passes the CW$optional_condition CWundef otherwise

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

is equivalent to

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

CWfirst_child_is is an other name for this method Similar methods are available for the other navigation methods:

last_child_matches

prev_sibling_matches

next_sibling_matches

prev_elt_matches

next_elt_matches

child_matches

parent_matches

is_first_child ($optional_condition)

returns true (the element) if the element is the first child of its parent (optionaly that satisfies the CW$optional_condition)

is_last_child ($optional_condition)

returns true (the element) if the element is the first child of its parent (optionaly that satisfies the CW$optional_condition)

prev_sibling ($optional_condition)

Return the previous sibling of the element, or the previous sibling matching CW$optional_condition

next_sibling ($optional_condition)

Return the next sibling of the element, or the first one matching CW$optional_condition. Return the next elt (optionally matching CW$optional_condition) of the element. This is defined as the next element which opens after the current element opens. Which usually means the first child of the element. Counter-intuitive as it might look this allows you to loop through the whole document by starting from the root. The CW$optional_elt is the root of a subtree. When the CWnext_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)

Return the previous elt (optionally matching CW$optional_condition) of the element. This is the first element which opens before the current one. It is usually either the last descendant of the previous sibling or simply the parent Return the CW$offset-th element that matches the CW$optional_condition

following_elt

Return the following element (as per the XPath following axis)

preceding_elt

Return the preceding element (as per the XPath preceding axis)

following_elts

Return the list of following elements (as per the XPath following axis)

preceding_elts

Return the pst of preceding elements (as per the XPath preceding axis)

children ($optional_condition)

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

children_count ($optional_condition)

Return the number of children of the element (optionally which matches CW$optional_condition)

children_text ($optional_condition)

Return an array containing the text of children of the element (optionally which matches CW$optional_condition)

children_trimmed_text ($optional_condition)

Return an array containing the trimmed text of children of the element (optionally which matches CW$optional_condition)

children_copy ($optional_condition)

Return a list of elements that are copies of the children of the element, optionally which matches CW$optional_condition

descendants ($optional_condition)

Return the list of all descendants (optionally which matches CW$optional_condition) of the element. This is the equivalent of the CWgetElementsByTagName of the DOM (by the way, if you are really a DOM addict, you can use CWgetElementsByTagName instead)

getElementsByTagName ($optional_condition)

Same as CWdescendants

find_by_tag_name ($optional_condition)

Same as CWdescendants

descendants_or_self ($optional_condition)

Same as CWdescendants except that the element itself is included in the list if it matches the CW$optional_condition

first_descendant ($optional_condition)

Return the first descendant of the element that matches the condition

last_descendant ($optional_condition)

Return the last descendant of the element that matches the condition

ancestors ($optional_condition)

Return the list of ancestors (optionally matching CW$optional_condition) of the element. The list is ordered from the innermost ancestor to the outtermost one NOTE: the element itself is not part of the list, in order to include it you will have to use ancestors_or_self

ancestors_or_self ($optional_condition)

Return the list of ancestors (optionally matching CW$optional_condition) of the element, including the element (if it matches the condition>). The list is ordered from the innermost ancestor to the outtermost one

passes ($condition)

Return the element if it passes the CW$condition

att ($att)

Return the value of attribute CW$att or CWundef Set the attribute of the element to the given value You can actually set several attributes this way:

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

del_att ($att)

Delete the attribute for the element You can actually delete several attributes at once:

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

cut

Cut the element from the tree. The element still exists, it can be copied or pasted somewhere else, it is just not attached to the tree anymore.

cut_children ($optional_condition)

Cut all the children of the element (or all of those which satisfy the CW$optional_condition). Return the list of children

copy ($elt)

Return a copy of the element. The copy is a deep copy: all sub elements of the element are duplicated. Paste a (previously CWcut or newly generated) element. Die if the element already belongs to a tree. Note that the calling element is pasted:

  $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:

first_child (default)

The element is pasted as the first child of CW$ref

last_child

The element is pasted as the last child of CW$ref

before

The element is pasted before CW$ref, as its previous sibling.

after

The element is pasted after CW$ref, as its next sibling.

within

In this case an extra argument, CW$offset, should be supplied. The element will be pasted in the reference element (or in its first text child) at the given offset. To achieve this the reference element will be split at the offset. Note that you can call directly the underlying method:

paste_before

paste_after

paste_first_child

paste_last_child

paste_within

Move an element in the tree. This is just a CWcut then a CWpaste. The syntax is the same as CWpaste.

replace ($ref)

Replaces an element in the tree. Sometimes it is just not possible toCWcut an element then CWpaste another in its place, so CWreplace comes in handy. The calling element replaces CW$ref.

replace_with (@elts)

Replaces the calling element with one or more elements

delete

Cut the element and frees the memory. Add a prefix to an element. If the element is a CWPCDATA element the text is added to the pcdata, if the elements first child is a CWPCDATA then the text is added to it's pcdata, otherwise a new CWPCDATA element is created and pasted as the first child of the element. If the option is CWasis then the prefix is added asis: it is created in a separate CWPCDATA element with an CWasis property. You can then write:

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

to create a CW<b> in the output of CWprint. Add a suffix to an element. If the element is a CWPCDATA element the text is added to the pcdata, if the elements last child is a CWPCDATA then the text is added to it's pcdata, otherwise a new PCDATA element is created and pasted as the last child of the element. If the option is CWasis then the suffix is added asis: it is created in a separate CWPCDATA element with an CWasis property. You can then write:

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

trim

Trim the element in-place: spaces at the beginning and at the end of the element are discarded and multiple spaces within the element (or its descendants) are replaced by a single space. 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.

simplify (%options)

Return 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)

content_key

forcearray

keyattr

noattr

normalize_space

aka normalise_space

variables (%var_hash)

%var_hash is a hash { name => value } This option allows variables in the XML to be expanded when the file is read. (there is no facility for putting the variable names back if you regenerate XML using XMLout). A 'variable' is any text of the form ${name} (or CW$name) which occurs in an attribute value or in the text content of an element. If 'name' matches a key in the supplied hashref, ${name} will be replaced with the corresponding value from the hashref. If no matching key is found, the variable will not be replaced.

var_att ($attribute_name)

This option gives the name of an attribute that will be used to create variables in the XML:

  <dirs>
    <dir name="prefix">/usr/local</dir>
    <dir name="exec_prefix">$prefix/bin</dir>
  </dirs>

use CWvar => 'name' to get CW$prefix replaced by /usr/local in the generated data structure By default variables are captured by the following regexp: /$(\w+)/

var_regexp (regexp)

This option changes the regexp used to capture variables. The variable name should be in CW$1

group_tags { grouping tag => grouped tag, grouping tag 2 => grouped tag 2...}

Option used to simplify the structure: elements listed will not be used. Their children will be, they will be considered children of the element parent. If the element is:

  <config host="laptop.xmltwig.com">
    <server>localhost</server>
    <dirs>
      <dir name="base">/home/mrodrigu/standards</dir>
      <dir name="tools">$base/tools</dir>
    </dirs>
    <templates>
      <template name="std_def">std_def.templ</template>
      <template name="dummy">dummy</template>
    </templates>
  </config>

Then calling simplify with CWgroup_tags => { dirs => 'dir', templates => 'template'} makes the data structure be exactly as if the start and end tags for CWdirs and CWtemplates were not there. A YAML dump of the structure

  base: '/home/mrodrigu/standards'
  host: laptop.xmltwig.com
  server: localhost
  template:
    - std_def.templ
    - dummy.templ
  tools: '$base/tools'

split_at ($offset)

Split a text (CWPCDATA or CWCDATA) element in 2 at CW$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 the text descendants of an element in place, the text is split using the CW$regexp, if the regexp includes () then the matched separators will be wrapped in elements. CW$1 is wrapped in CW$tag1, with attributes CW$atts1 if CW$atts1 is given (as a hashref), CW$2 is wrapped in CW$tag2... if CW$elt is CW<p>tati tata <b>tutu tati titi</b> tata tati tata</p>

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

will change CW$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 CWqr// (perl 5.005 and later), it defaults to \s+ just as the CWsplit built-in (but this would be quite a useless behaviour without the CW$optional_tag parameter) CW$optional_tag defaults to PCDATA or CDATA, depending on the initial element type The list of descendants is returned (including un-touched original elements and newly created ones) This method behaves exactly as split, except only the newly created elements are returned Wrap the children of the element that match the regexp in an element CW$tag. If CW$optional_attribute_hashref is passed then the new element will have these attributes. The CW$regexp_string includes tags, within pointy brackets, as in CW<title><para>+ and the usual Perl modifiers (+*?...). Tags can be further qualified with attributes: CW<para type="warning" classif="cosmic_secret">+. The values for attributes should be xml-escaped: CW<candy type="M&amp;Ms">* (CW<, CW& CB> and CW" should be escaped). Note that elements might get extra CWid attributes in the process. See add_id. Use strip_att to remove unwanted id's. Here is an example: If the element CW$elt has the following content:

  <elt>
   <p>para 1</p>
   <l_l1_1>list 1 item 1 para 1</l_l1_1>
     <l_l1>list 1 item 1 para 2</l_l1>
   <l_l1_n>list 1 item 2 para 1 (only para)</l_l1_n>
   <l_l1_n>list 1 item 3 para 1</l_l1_n>
     <l_l1>list 1 item 3 para 2</l_l1>
     <l_l1>list 1 item 3 para 3</l_l1>
   <l_l1_1>list 2 item 1 para 1</l_l1_1>
     <l_l1>list 2 item 1 para 2</l_l1>
   <l_l1_n>list 2 item 2 para 1 (only para)</l_l1_n>
   <l_l1_n>list 2 item 3 para 1</l_l1_n>
     <l_l1>list 2 item 3 para 2</l_l1>
     <l_l1>list 2 item 3 para 3</l_l1>
  </elt>

Then the code

  $elt->wrap_children( q{<l_l1_1><l_l1>*} , li => { type => "ul1" });
  $elt->wrap_children( q{<l_l1_n><l_l1>*} , li => { type => "ul" });

  $elt->wrap_children( q{<li type="ul1"><li type="ul">+}, "ul");
  $elt->strip_att( 'id');
  $elt->strip_att( 'type');
  $elt->print;

will output:

  <elt>
     <p>para 1</p>
     <ul>
       <li>
         <l_l1_1>list 1 item 1 para 1</l_l1_1>
         <l_l1>list 1 item 1 para 2</l_l1>
       </li>
       <li>
         <l_l1_n>list 1 item 2 para 1 (only para)</l_l1_n>
       </li>
       <li>
         <l_l1_n>list 1 item 3 para 1</l_l1_n>
         <l_l1>list 1 item 3 para 2</l_l1>
         <l_l1>list 1 item 3 para 3</l_l1>
       </li>
     </ul>
     <ul>
       <li>
         <l_l1_1>list 2 item 1 para 1</l_l1_1>
         <l_l1>list 2 item 1 para 2</l_l1>
       </li>
       <li>
         <l_l1_n>list 2 item 2 para 1 (only para)</l_l1_n>
       </li>
       <li>
         <l_l1_n>list 2 item 3 para 1</l_l1_n>
         <l_l1>list 2 item 3 para 2</l_l1>
         <l_l1>list 2 item 3 para 3</l_l1>
       </li>
     </ul>
  </elt>

subs_text does text substitution, similar to perl's CW s/// operator. CW$regexp must be a perl regexp, created with the CWqr operatot. CW$replace can include CW$1, $2... from the CW$regexp. It can also be used to create element and entities, by using CW&elt( tag => { att => val }, text) (similar syntax as CWnew) and CW&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 will replace text like link to http://www.xmltwig.com by see <a href=www.xmltwig.com>www.xmltwig.com</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 CWg modifier in a perl substitution, and that it is performed on all text descendants of the element. Bug: in the CW$regexp, you can only use CW\1, CW\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

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

set_id_seed ($prefix)

by default the id generated by CWadd_id is CWtwig_id_<nnnn>, CWset_id_seed changes the prefix to CW$prefix and resets the number to 1

strip_att ($att)

Remove the attribute CW$att from all descendants of the element (including the element) Return the element Change the name of the attribute from CW$old_name to CW$new_name. If there is no attribute CW$old_name nothing happens. Sort the children of the element in place according to their text. All children are sorted. Return the element, with its children sorted. %options are

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

Return the element, with its children sorted Sort the children of the element in place according to attribute CW$att. CW%options are the same as for CWsort_children_on_value Return the element. Sort the children of the element in place, according to the field CW$tag (the text of the first child of the child with this tag). CW%options are the same as for CWsort_children_on_value. Return the element, with its children sorted Sort the children of the element in place. The CW$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'
                     );

Turn the text of the first sub-element matched by CW$cond into the value of attribute CW$att of the element. If CW$att is ommited then CW$cond is used as the name of the attribute, which makes sense only if CW$cond is a valid element (and attribute) name. The sub-element is then cut. Take the value of attribute CW$att and create a sub-element CW$tag as first child of the element. If CW$tag is ommited then CW$att is used as the name of the sub-element. Return a list of elements satisfying the CW$xpath. CW$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"]
  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 will be returned in the document order. If CW$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 here are some more examples to get you started:

  my $p1= "p1";
  my $p2= "p2";
  my @res= $t->get_xpath( "p[string( '$p1') or string( '$p2')]");

  my $a= "a1";
  my @res= $t->get_xpath( "//*[@att=\"$a\"]);

  my $val= "a1";
  my $exp= "//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 natively full XPATH support, but you can use XML::Twig does not provide natively full XPATH support, but you can use CWXML::Twig::XPath to get CWfindnodes to use CWXML::XPath as the XPath engine, with full coverage of the spec. CWXML::Twig::XPath to get CWfindnodes to use CWXML::XPath as the XPath engine, with full coverage of the spec.

find_nodes

same asCWget_xpath

findnodes

same asCWget_xpath

text

Return a string consisting of all the CWPCDATA and CWCDATA in an element, without any tags. The text is not XML-escaped: base entities such as CW& and CW< are not escaped.

trimmed_text

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

set_text ($string)

Set the text for the element: if the element is a CWPCDATA, just set its text, otherwise cut all the children of the element and create a single CWPCDATA child for it, which holds the text. For each tag in the list inserts an element CW$tag as the only child of the element. The element gets the optional attributes inCW$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 CW$p in a table with a visible border, a single CWtr and a single CWtd and return the CWtable element:

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

wrap_in (@tag)

Wrap elements CW$tag as the successive ancestors of the element, returns the new element. CW$elt->wrap_in( 'td', 'tr', 'table') wraps the element as a single cell in a table for example. Combines a CWnew and a CWpaste : creates a new element using CW$tag, CW$opt_atts_hashref and CW@opt_content which are arguments similar to those for CWnew, then paste it, using CW$opt_position or CW'first_child', relative to CW$elt. Return the newly created element

erase

Erase the element: the element is deleted and all of its children are pasted in its place. Set the content for the element, from a list of strings and elements. Cuts all the element children, then pastes the list elements as the children. This method will create a CWPCDATA element for any strings in the list. The CW$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 ID's 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 strored in the ID list. A content of 'CW#EMPTY' creates an empty element;

namespace ($optional_prefix)

Return the URI of the namespace that CW$optional_prefix or the element name belongs to. If the name doesn't belong to any namespace, CWundef is returned.

local_name

Return the local name (without the prefix) for the element

ns_prefix

Return the namespace prefix for the element

current_ns_prefixes

Returna 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, '' appears in the list. Return 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 CW@optional_tag_list is supplied only those ancestors whose tag is in the list will be checked.

all_children_are ($optional_condition)

return 1 if all children of the element pass the CW$optional_condition, 0 otherwise

level ($optional_condition)

Return the depth of the element in the twig (root is 0). If CW$optional_condition is given then only ancestors that match the condition are counted. WARNING: in a tree created using the CWtwig_roots option this will not return the level in the document tree, level 0 will be the document root, level 1 will be the CWtwig_roots elements. During the parsing (in a CWtwig_handler) you can use the CWdepth method on the twig object to get the real parsing depth.

in ($potential_parent)

Return true if the element is in the potential_parent (CW$potential_parent is an element) Return true if the element is included in an element which passes CW$cond optionally within CW$optional_level levels. The returned value is the including element.

pcdata

Return the text of a CWPCDATA element or CWundef if the element is not CWPCDATA.

pcdata_xml_string

Return 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)

Set the text of a CWPCDATA element.

append_pcdata ($text)

Add the text at the end of a CWPCDATA element.

is_cdata

Return 1 if the element is a CWCDATA element, returns 0 otherwise.

is_text

Return 1 if the element is a CWCDATA or CWPCDATA element, returns 0 otherwise.

cdata

Return the text of a CWCDATA element or CWundef if the element is not CWCDATA.

cdata_string

Return the XML string of a CWCDATA element, including the opening and closing markers.

set_cdata ($text)

Set the text of a CWCDATA element.

append_cdata ($text)

Add the text at the end of a CWCDATA element.

remove_cdata

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

extra_data

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

set_extra_data ($extra_data)

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

append_extra_data ($extra_data)

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

set_asis

Set a property of the element that causes it to be output without being XML escaped by the print functions: if it contains CWa < b it will be output as such and not as CWa &lt; b. This can be useful to create text elements that will be output as markup. Note that all CWPCDATA descendants of the element are also marked as having the property (they are the ones taht are actually impacted by the change). If the element is a CWCDATA element it will also be output asis, without the CWCDATA markers. The same goes for any CWCDATA descendant of the element

set_not_asis

Unsets the CWasis property for the element and its text descendants.

is_asis

Return the CWasis property status of the element ( 1 or CWundef)

closed

Return true if the element has been closed. Might be usefull 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

Return the type of the element: 'CW#ELT' for real elements, or 'CW#PCDATA', 'CW#CDATA', 'CW#COMMENT', 'CW#ENT', 'CW#PI'

is_elt

Return the tag if the element is a real element, or 0 if it is CWPCDATA, CWCDATA...

contains_only_text

Return 1 if the element does not contain any other real element

contains_only ($exp)

Return the list of children if all children of the element match the expression CW$exp

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

contains_a_single ($exp)

If the element contains a single child that matches the expression CW$exp returns that element. Otherwise returns 0.

is_field

same as CWcontains_only_text

is_pcdata

Return 1 if the element is a CWPCDATA element, returns 0 otherwise.

is_ent

Return 1 if the element is an entity (an unexpanded entity) element, return 0 otherwise.

is_empty

Return 1 if the element is empty, 0 otherwise

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 CW<tag att="value""/>.

set_not_empty

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

is_pi

Return 1 if the element is a processing instruction (CW#PI) element, return 0 otherwise.

target

Return the target of a processing instruction

set_target ($target)

Set the target of a processing instruction

data

Return the data part of a processing instruction

set_data ($data)

Set the data of a processing instruction Set the target and data of a processing instruction

pi_string

Return the string form of a processing instruction (CW<?target data?>)

is_comment

Return 1 if the element is a comment (CW#COMMENT) element, return 0 otherwise.

set_comment ($comment_text)

Set the text for a comment

comment

Return the content of a comment (just the text, not the CW<!-- and CW-->)

comment_string

Return the XML string for a comment (CW<!-- comment -->)

set_ent ($entity)

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

ent

Return the entity for an entity (CW#ENT) element (CW&ent;)

ent_name

Return the entity name for an entity (CW#ENT) element (CWent)

ent_string

Return the entity, either expanded if the expanded version is available, or non-expanded (CW&ent;) otherwise Return the CW$offset-th child of the element, optionally the CW$offset-th child that matches CW$optional_condition. The children are treated as a list, so CW$elt->child( 0) is the first child, while CW$elt->child( -1) is the last child. Return the text of a child or CWundef if the sibling does not exist. Arguments are the same as child.

last_child ($optional_condition)

Return the last child of the element, or the last child matching CW$optional_condition (ie the last of the element children matching the condition).

last_child_text ($optional_condition)

Same as CWfirst_child_text but for the last child. Return the next or previous CW$offset-th sibling of the element, or the CW$offset-th one matching CW$optional_condition. If CW$offset is negative then a previous sibling is returned, if CW$offset is positive then a next sibling is returned. CW$offset=0 returns the element if there is no condition or if the element matches the condition>, CWundef otherwise. Return the text of a sibling or CWundef if the sibling does not exist. Arguments are the same as CWsibling.

prev_siblings ($optional_condition)

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

next_siblings ($optional_condition)

Return the list of siblings (optionaly matching CW$optional_condition) following the element. The elements are ordered in document order.

pos ($optional_condition)

Return the position of the element in the children list. The first child has a position of 1 (as in XPath). If the CW$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

Return a hash ref containing the element attributes Set the element attributes with the hash ref supplied as the argument

del_atts

Deletes all the element attributes.

att_nb

Return the number of attributes for the element

has_atts

Return true if the element has attributes (in fact return the number of attributes, thus being an alias to CWatt_nb

has_no_atts

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

att_names

return a list of the attribute names for the element Return the attribute value, where '&', '<' and CW$quote (" by default) are XML-escaped if CW$optional_quote is passed then it is used as the quote.

set_id ($id)

Set the CWid attribute of the element to the value. See CWelt_id to change the id attribute name

id

Gets the id attribute value

del_id ($id)

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

class

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

set_class ($class)

Set the CWclass attribute for the element to CW$class

add_to_class ($class)

Add CW$class to the element CWclass attribute: the new class is added only if it is not already present. Note that classes are sorted alphabetically, so the CWclass attribute can be changed even if the class is already there

att_to_class ($att)

Set the CWclass attribute to the value of attribute CW$att

add_att_to_class ($att)

Add the value of attribute CW$att to the CWclass attribute of the element

move_att_to_class ($att)

Add the value of attribute CW$att to the CWclass attribute of the element and delete the attribute

tag_to_class

Set the CWclass attribute of the element to the element tag

add_tag_to_class

Add the element tag to its CWclass attribute

set_tag_class ($new_tag)

Add the element tag to its CWclass attribute and sets the tag to CW$new_tag

in_class ($class)

Return true (CW1) if the element is in the class CW$class (if CW$class is one of the tokens in the element CWclass attribute)

DESTROY

Frees the element from memory.

start_tag

Return the string for the start tag for the element, including the CW/> at the end of an empty element tag

end_tag

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

xml_string

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

xml_text

Return the text of the element, encoded (and processed by the current CWoutput_filter or CWoutput_encoding options, without any tag.

set_pretty_print ($style)

Set the pretty print method, amongst 'CWnone' (default), 'CWnsgmls', 'CWnice', 'CWindented', 'CWrecord' and 'CWrecord_c' pretty_print styles:

none

the default, no CW\n is used

nsgmls

nsgmls style, with CW\n added within tags

nice

adds CW\n wherever possible (NOT SAFE, can lead to invalid XML)

indented

same as CWnice plus indents elements (NOT SAFE, can lead to invalid XML)

record

table-oriented pretty print, one field per line

record_c

table-oriented pretty print, more compact than CWrecord, one record per line

set_empty_tag_style ($style)

Set the method to output empty tags, amongst 'CWnormal' (default), 'CWhtml', and 'CWexpand',

set_remove_cdata ($flag)

set (or unset) the flag that forces the twig to output CDATA sections as regular (escaped) PCDATA

set_indent ($string)

Set the indentation for the indented pretty print style (default is 2 spaces)

set_quote ($quote)

Set the quotes used for attributes. can be 'CWdouble' (default) or 'CWsingle'

cmp ($elt)

  Compare the order of the 2 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)

Return 1 if CW$elt starts before the element, 0 otherwise. If the 2 elements are not in the same twig then return CWundef.

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

after ($elt)

Return 1 if CW$elt starts after the element, 0 otherwise. If the 2 elements are not in the same twig then return CWundef.

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

other comparison methods

lt

le

gt

ge

path

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

xpath

Return a unique XPath expression that can be used to find the element again. It looks like CW/doc/sect[3]/title: unique elements do not have an index, the others do.

private methods

Low-level methods on the twig:

set_parent ($parent)

set_first_child ($first_child)

set_last_child ($last_child)

set_prev_sibling ($prev_sibling)

set_next_sibling ($next_sibling)

set_twig_current

del_twig_current

twig_current

flush

This method should NOT be used, always flush the twig, not an element.

contains_text

Those methods should not be used, unless of course you find some creative and interesting, not to mention useful, ways to do it.

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

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

The condition can be

#ELT

return a real element (not a PCDATA, CDATA, comment or pi element)

#TEXT

return a PCDATA or CDATA element

regular expression

return an element whose tag matches the regexp. The regexp has to be created with CWqr// (hence this is available only on perl 5.005 and above)

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 implements a subset of XPath through the CWget_xpath method.

If you want to use the whole XPath power, then you can use CWXML::Twig::XPath instead. In this case CWXML::Twig uses CWXML::XPath to execute XPath queries. You will of course need CWXML::XPath installed to be able to use CWXML::Twig::XPath.

See XML::XPath for more information.

The methods you can use are:

findnodes ($path)

return a list of nodes found by CW$path.

findnodes_as_string ($path)

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

findvalue ($path)

return the concatenation of the text content of the result nodes

In order for CWXML::XPath to be used as the XPath engine the following methods are included in CWXML::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

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

findnodes ($path)

return a list of nodes found by CW$path.

findnodes_as_string ($path)

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

findvalue ($path)

return the concatenation of the text content of the result nodes

new

Create an entity list.

add ($ent)

Add an entity to an entity list. Create a new entity and add it to the entity list Delete an entity (defined by its name or by the Entity object) from the list.

print ($optional_filehandle)

Print the entity list.

list

Return the list as an array

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

print ($optional_filehandle)

Print an entity declaration.

name

Return the name of the entity

val

Return the value of the entity

sysid

Return the system id for the entity (for NDATA entities)

pubid

Return the public id for the entity (for NDATA entities)

ndata

Return true if the entity is an NDATA entity

text

Return the entity declaration text.

Additional examples (and a complete tutorial) can be found on the XML::Twig Page<http://www.xmltwig.com/xmltwig/>

To figure out what flush does call the following script with an XML file and an element name as arguments

  use XML::Twig;

  my ($file, $elt)= @ARGV;
  my $t= XML::Twig->new( twig_handlers => 
      { $elt => sub {$_[0]->flush; print "\n[flushed here]\n";} });
  $t->parsefile( $file, ErrorContext => 2);
  $t->flush;
  print "\n";

Useful methods:

elt_class

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

add_options

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

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 CWflush'ed (or CWprint'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 CW$twig->{twig_doctype}->{internal} field (straight from XML::Parser, see the CWDoctype handler doc)

External DTD

The XML document includes a reference to an external DTD, and maybe entity declarations. If you use the CWload_DTD when creating the twig the DTD information and the entity declarations can be accessed. The entity declarations will be CWflush'ed (or CWprint'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 CW$twig->set_doctype method and print the dtd through the CW$twig->dtd_text or CW$twig->dtd_print methods. If you need to modify the entity list this is probably the easiest way to do it.

If you set handlers and use CWflush, do not forget to flush the twig one last time AFTER the parsing, or you might be missing the end of the document.

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 clauses.

entity handling

Due to XML::Parser behaviour, non-base entities in attribute values disappear: CWatt="val&ent;" will be turned into CWatt => val, unless you use the CWkeep_encoding argument to CWXML::Twig->new

DTD handling

The DTD handling methods are quite bugged. No one uses them and it seems very difficult to get them to work in all cases, including with several slightly incompatible versions of XML::Parser and of libexpat. Basically you can read the DTD, output it back properly, and update entities, but not much more. So use XML::Twig with standalone documents, or with documents refering to an external DTD, but don't expect it to properly parse and even output back the DTD.

memory leak

If you use a lot of twigs you might find that you leak quite a lot of memory (about 2Ks per twig). You can use the CWdispose method to free that memory after you are done. If you create elements the same thing might happen, use the CWdelete method to get rid of them. Alternatively installing the CWScalar::Util (or CWWeakRef) module on a version of Perl that supports it (>5.6.0) will get rid of the memory leaks automagically.

ID list

The ID list is NOT updated when elements are cut or deleted.

change_gi

This method will not function properly if you do:

     $twig->change_gi( $old1, $new);
     $twig->change_gi( $old2, $new);
     $twig->change_gi( $new, $even_newer);

sanity check on XML::Parser method calls

XML::Twig should really prevent calls to some XML::Parser methods, especially the CWsetHandlers method.

pretty printing

Pretty printing (at least using the 'CWindented' style) is hard to get right! Only elements that belong to the document will be properly indented. Printing elements that do not belong to the twig makes it impossible for XML::Twig to figure out their depth, and thus their indentation level. Also there is an unavoidable bug when using CWflush and pretty printing for elements with mixed content that start with an embedded element:

  <elt><b>b</b>toto<b>bold</b></elt>

  will be output as

  <elt>
    <b>b</b>toto<b>bold</b></elt>

if you flush the twig when you find the CW<b> element

These are the things that can mess up calling code, especially if threaded. They might also cause problem under mod_perl.

Exported constants

Whether you want them or not you get them! These are subroutines to use as constant when creating or testing elements

  PCDATA  return '#PCDATA'
  CDATA   return '#CDATA'
  PI      return '#PI', I had the choice between PROC and PI :--(

Module scoped values: constants

these should cause no trouble:

  %base_ent= ( '>' => '>',
               '<' => '&lt;',
               '&' => '&amp;',
               "'" => '&apos;',
               '"' => '&quot;',
             );
  CDATA_START   = "<![CDATA[";
  CDATA_END     = "]]>";
  PI_START      = "<?";
  PI_END        = "?>";
  COMMENT_START = "<!--";
  COMMENT_END   = "-->";

pretty print styles

  ( $NSGMLS, $NICE, $INDENTED, $INDENTED_C, $WRAPPED, $RECORD1, $RECORD2)= (1..7);

empty tag output style

  ( $HTML, $EXPAND)= (1..2);

Module scoped values: might be changed

Most of these deal with pretty printing, so the worst that can happen is probably that XML output does not look right, but is still valid and processed identically by XML processors. CW$empty_tag_style can mess up HTML bowsers though and changing CW$ID would most likely create problems.

  $pretty=0;           # pretty print style
  $quote='"';          # quote for attributes
  $INDENT= '  ';       # indent for indented pretty print
  $empty_tag_style= 0; # how to display empty tags
  $ID                  # attribute used as an id ('id' by default)

Module scoped values: definitely changed

These 2 variables are used to replace tags by an index, thus saving some space when creating a twig. If they really cause you too much trouble, let me know, it is probably possible to create either a switch or at least a version of XML::Twig that does not perform this optimisation.

  %gi2index;     # tag => index
  @index2gi;     # list of tags

If you need to manipulate all those values, you can use the following methods on the XML::Twig object:

global_state

Return a hasref with all the global variables used by XML::Twig The hash has the following fields: CWpretty, CWquote, CWindent, CWempty_tag_style, CWkeep_encoding, CWexpand_external_entities, CWoutput_filter, CWoutput_text_filter, CWkeep_atts_order

set_global_state ($state)

Set the global state, CW$state is a hashref

save_global_state

Save the current global state

restore_global_state

Restore the previously saved (using CWLsave_global_state> state

SAX handlers

Allowing XML::Twig to work on top of any SAX parser

multiple twigs are not well supported

A number of twig features are just global at the moment. These include the ID list and the tag pool (if you use CWchange_gi then you change the tag for ALL twigs). A future version will try to support this while trying not to be to hard on performance (at least when a single twig is used!).

Michel Rodriguez <mirod@xmltwig.com>

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

Bug reports should be sent using: RT <http://rt.cpan.org/NoAuth/Bugs.html?Dist=XML-Twig>

Comments can be sent to mirod@xmltwig.com

The XML::Twig page is at <http://www.xmltwig.com/xmltwig/> It includes the development version of the module, a slightly better version of the documentation, examples, a tutorial and a: Processing XML efficiently with Perl and XML::Twig: <http://www.xmltwig.com/xmltwig/tutorial/index.html>

Complete docs, including a tutorial, examples, an easier to use HTML version of the docs, a quick reference card and a FAQ are available at <http://www.xmltwig.com/xmltwig/>

XML::Parser, XML::Parser::Expat, XML::XPath, Encode, Text::Iconv, Scalar::Utils

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 CWlibxml2 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::XPath 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 prefered 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 programatically), while I haven't looked much into XML::LibXML so it still looks shinny and clean to me.

That said, ifyou 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.com/article/simple_benchmark/>).