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 XML::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 twig_roots and
twig_print_outside_roots options. The
finish and finish_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: $elt->{'att'}->{'foo'} return the foo attribute for an
element,
set_att : $elt->set_att( foo => "bar") sets the foo
attribute to the bar value,
next_sibling: $elt->{next_sibling} return the next sibling
in the document (in the example $title->{next_sibling} is the first
para, you can also (and actually should) use
$elt->next_sibling( 'para') to get it
The document can also be transformed through the use of the cut,
copy, paste and move methods:
$title->cut; $title->paste( after => $p); for example
And much, much more, see 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 prefix .
Once the element is completely processed you can then flush it,
which will output it and free the memory. You can also purge it
if you don't need to output it (if you are just extracting some data from
the document for example). The handler will be called again once the next
relevant element has been parsed.
my $t= XML::Twig->new( twig_handlers =>
{ section => \§ion,
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, section/title for example.
my $t= XML::Twig->new( twig_handlers =>
{ 'section/title' => sub { $_->print } }
)
->parsefile( 'doc.xml');
Here sub { $_->print } simply prints the current element ($_ 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 start_tag_handlers to process an
element as soon as the start tag is found. Besides prefix you
can also use suffix ,
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 twig_roots and the twig_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:
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:
When in doubt, upgrade expat, XML::Parser and Scalar::Util
Finally, for some optional features, XML::Twig depends on some additional
modules. The complete list, which depends somewhat on the version of Perl
that you are running, is given by running t/zz_dump_config.t
keep_spaces ,
keep_spaces_in and
discard_spaces_in options.
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
keep_encoding option
You can also use output_encoding to convert the internal UTF-8 format
to the required encoding.
XML parsers are supposed to react violently when fed improper XML. XML::Parser just dies.
XML::Twig provides the safe_parse and the
safe_parsefile methods which wrap the parse in an eval
and return either the parsed twig or 0 in case of failure.
XML::Twig uses a very limited number of classes. The ones you are most likely to use
are XML::Twig of course, which represents a complete XML document, including the
document itself (the root of the document itself is root), its handlers, its
input or output filters... The other main class is XML::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 tag of #PCDATA (or #CDATA), an entity (tag is
#ENT), a Processing Instruction (#PI), a comment (#COMMENT).
Those are the 2 commonly used classes.
You might want to look the elt_class option if you want to subclass XML::Twig::Elt.
Attributes are just attached to their parent element, they are not objects per se. (Please
use the provided methods att and set_att to access them, if you access them
as a hash, then your code becomes implementaion dependent and might break in the future).
Other classes that are seldom used are XML::Twig::Entity_list and XML::Twig::Entity.
If you use XML::Twig::XPath instead of XML::Twig, elements are then created as
XML::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.
setHandlers on the other hand cannot be used, see BUGS
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:
This argument consists of a hash { expression = \&handler}> where
expression is a an XPath-like expression (+ some others).
XPath expressions are limited to using the child and descendant axis
(indeed you can't specify an axis), and predicates cannot be nested.
You can use the string, or string(<tag>) function (except
in twig_roots triggers).
Additionally you can use regexps (/ delimited) to match attribute and string values.
Examples:
foo foo/bar foo//bar /foo/bar /foo//bar /foo/bar[@att1 = "val1" and @att2 = "val2"]/baz[@a >= 1] foo[string()=~ /^duh!+/] /foo[string(bar)=~ /\d+/]/baz[@att != 3]
#CDATA can be used to call a handler for a CDATA. #COMMENT can be used to call a handler for comments
Some additional (non-XPath) expressions are also provided for convenience:
'?' or '#PI' triggers the handler for any processing instruction,
and '?<target>' or '#PI <target>' triggers a handler for processing
instruction with the given target( ex: '#PI xml-stylesheet').
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. There is an exception to this: "private" attributes (which name start with a '#', and can only be created during the parsing, as they are not valid XML) are checked against the current twig.
Handlers are triggered in fixed order, sorted by their type (xpath expressions
first, then regexps, then level), then by whether they specify a full path
(starting at the root element) or
not, then by by number of steps in the expression , then number of
predicates, then number of tests in predicates. Handlers where the last
step does not specify a step (foo/bar/*) are triggered after other XPath handlers.
Finally _all_ handlers are triggered last.
Important: once a handler has been triggered if it returns 0 then no other
handler is called, except a _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, rinse, lather..; The exception
to that rule is when the do_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 explicitly 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 /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.
$_ 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 flush) already, so changing
its tag might not give the expected result.
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 title and subtitle
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 twig_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 $t= XML::Twig->new( twig_roots => { title => sub { $_{1]->print;}, subtitle => \&process_subtitle } ); $t->parsefile( file);
To be used in conjunction with the twig_roots argument. When set to a true
value this will print the document outside of the twig_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
number_title for each title element, prints it, and then resumes printing
the document. The twig is built only for the title elements.
If the value is a reference to a file handle then the document outside the
twig_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
}
}
A hash { expression = \&handler}>. Sets element handlers that are called when
the element is open (at the end of the XML::Parser Start 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 flush the twig at some
point in the element, and to create temporary attributes that will be used
when processing sub-element with twig_hanlders.
You should also use it to change tags if you use flush. If you change the tag
in a regular twig_handler then the start tag might already have been flushed.
Note: start_tag handlers can be called outside of twig_roots if this
argument is used, in this case handlers are called with the following arguments:
$t (the twig), $tag (the tag of the element) and %att (a hash of the
attributes of the element).
If the twig_print_outside_roots argument is also used, if the last handler
called returns a true value, then the the start tag will be output as it
appeared in the original document, if the handler returns a a false 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 start_tag_handlers
(and only there).
A hash { expression = \&handler}>. Sets element handlers that are called when
the element is closed (at the end of the XML::Parser End 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 end_tag_handlers: when using
the twig_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 end_tag_handlers argument without twig_roots will result in an
error.
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 _all_ handler will still be called regardless
This option lets you ignore elements when building the twig. This is useful
in cases where you cannot use twig_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 elt
elements (and their children) will be left out.
A reference to a subroutine that will be called every time PCDATA 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;
}
The name of a class used to store elements. this class should inherit from
XML::Twig::Elt (and by default it is XML::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 XML::Twig, without any control from the user code.
Tie::IxHash object.
This means that Tie::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 outputting the attributes in the same
order as they were in the original document.
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 theExpat
original_string method for character, thus keeping the original encoding, as
well as the original entities in the strings.
See the t/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 parse_start_tag option
(see below)
WARNING: this option is NOT used when parsing with the non-blocking parser
(parse_start, parse_more, parse_done methods) which you probably should
not use with XML::Twig anyway as they are totally untested!
Encode, Text::Iconv or
Unicode::Map8 and Unicode::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 output_filter below
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 (print, sprint, flush).
Pre-defined filters:
Encode, Text::Iconv or Unicode::Map8 and Unicode::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)
latin1, plus encodes entities using
HTML::Entities (oddly enough you will need to have HTML::Entities installed
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
&#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 except that the character entities are in hexa (&#xnnn;)
Return a subref that can be used to convert utf8 strings to $encoding).
Uses Encode.
my $conv = XML::Twig::encode_convert( 'latin1'); my $t = XML::Twig->new(output_filter => $conv);
this function is used to create a filter subroutine that will be used to
convert the characters to the target encoding using Text::Iconv (which needs
to be installed, look at the documentation for the module and for the
iconv 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);
this function is used to create a filter subroutine that will be used to
convert the characters to the target encoding using Unicode::Strings
and Unicode::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 text and att 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 XML::Twig::foo).
HTML::Entities to encode a utf8 string
Encode to encode non-ascii characters
in the string in &#<nnnn>; format
Encode to encode non-ascii characters
in the string in &#x<nnnn>; format
html, safe and safe_hex are better used with this option.
output_filter except the filter is applied to
the characters before they are stored in the twig, at parsing time.
keep_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 original_string() method) and returns a tag and the
attributes in a hash (or in a list attribute_name/attribute value).
When this option is used external entities (that are defined) are expanded
when the document is output using "print" functions such as print ,
sprint , flush and xml_string .
Note that in the twig the entity will be stored as an element with a
tag '#ENT', the entity will not be expanded there, so you might want to
process the entities before outputting it.
If an external entity is not available, then the parse will fail.
A special case is when the value of this option is -1. In that case a missing
entity will not cause the parser to die, but its name, sysid and pubid
will be stored in the twig as $twig->{twig_missing_system_entities}
(a reference to an array of hashes { name => <name>, sysid => <sysid>,
pubid => <pubid> }). Yes, this is a bit of a hack, but it's useful in some
cases.
If this argument is set to a true value, parse or parsefile on the twig
will load the DTD information. This information can then be accessed through
the twig, in a DTD_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
BUGS
If this optional argument is set to a true value then all spaces in the
document are kept, and stored as PCDATA.
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'
keep_spaces and discard_spaces cannot be both set.
This argument sets keep_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']);
This argument sets discard_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.
Set the pretty print method, amongst 'none' (default), 'nsgmls',
'nice', 'indented', 'indented_c', 'indented_a', cvs,
wrapped, 'record' and 'record_c'
pretty_print formats:
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 none, and it is very safe, the document
will still be valid (conforming to its DTD).
This is how the SGML parser sgmls splits documents, hence the name.
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 foo element including a bar 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 foo tag
as a sign that the element contains PCDATA, it will then die when it finds the
bar tag. This may or may not be important for you, but be aware of it!
nice (and with the same warning) but indents elements according to
their level
indented but a little more compact: the closing tags are on the
same line as the preceding text
This formats XML files in a line-oriented version control friendly way. The format is described in http://tinyurl.com/2kwscq (that's an Oracle document with an insanely long URL).
Note that to be totaly conformant to the "spec", the order of attributes
should not be changed, so if they are not already in alphabetical order
you will need to use the keep_atts_order option.
idented_a.
indented_c but lines are wrapped using Text::Wrap::wrap. The
default length for lines is the default for $Text::Wrap::columns, and can
be changed by changing that variable.
indented)
Set the empty tag display style ('normal', 'html' or 'expand').
normal outputs an empty tag '<tag/>', html adds a space
'<tag />' for elements that can be empty in XHTML and expand outputs
'<tag></tag>'
single' or 'double').
Set the way comments are processed: 'drop' (default), 'keep' or
'process'
Comments processing options:
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 print or sprint will return the comments in the
text. Using text or field on the other hand will not.
Any use of set_pcdata on the #PCDATA element (directly or
through other methods like set_content) will delete the comment(s).
comments are loaded in the twig and will be treated as regular elements
(their tag is #COMMENT) this can interfere with processing if you
expect $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 $elt->first_child( 'tag') (which is a good habit anyway)
to get where you want.
Consider using process if you are outputting SAX events from XML::Twig.
Set the way processing instructions are processed: 'drop', 'keep'
(default) or 'process'
Note that you can also set PI handlers in the twig_handlers option:
'?' => \&handler '?target' => \&handler 2
The handlers will be called with 2 parameters, the twig and the PI element if
pi is set to process, and with 3, the twig, the target and the data if
pi is set to keep. Of course they will not be called if pi is set to
drop.
If pi is set to keep the handler should return a string that will be used
as-is as the PI text (it should look like " <?target data? >" or '' if you
want to remove the PI),
Only one handler will be called, ?target or ? if no specific handler for
that target is available.
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>
When used with map_xmlns this option will make XML::Twig use the original
namespace prefixes when outputting 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 index 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
UglyJavaLikeName or as readable_perl_name: twig_print_outside_roots
or TwigPrintOutsideRoots (or even twigPrintOutsideRoots {shudder}).
XML::Twig normalizes them before processing them.
The $source parameter should either be a string containing the whole XML
document, or it should be an open IO::Handle. Constructor options to
XML::Parser::Expat given as keyword-value pairs may follow the$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 safe_parse if you want the parsing
to return even when an error occurs.
If this method is called as a class method
(XML::Twig->parse( $some_xml_or_html)) then an XML::Twig object is
created, using the parameters except the last one (eg
XML::Twig->parse( pretty_print => 'indented', $some_xml_or_html))
and xparse is called on it.
parse for backwards compatibility.
Open FILE for reading, then call parse with the open handle. The file
is closed no matter how parse returns.
A die call is thrown if a parse error occurs. Otherwise it will return
the twig built by the parse. Use safe_parsefile if you want the parsing
to return even when an error occurs.
Parse and update a file "in place". It does this by creating a temp file, selecting it as the default for print() statements (and methods), then parsing the input file. If the parsing is successful, then the temp file is moved to replace the input file.
If an extension is given then the original file is backed-up (the rules for the extension are the same as the rule for the -i option in perl).
Gets the data from $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 get the XML file and then parse it as a string.
use XML::Twig; use LWP::Simple; my $twig= XML::Twig->new(); $twig->parse( LWP::Simple::get( $URL ));
or
use XML::Twig; my $twig= XML::Twig->nparse( $URL);
If the $optional_user_agent argument is used then it is used, otherwise a
new one is created.
This method is similar to parse except that it wraps the parsing in an
eval block. It returns the twig on success and 0 on failure (the twig object
also contains the parsed twig). $@ contains the error message on failure.
Note that the parsing still stops as soon as an error is detected, there is no way to keep going after an error.
This method is similar to parsefile except that it wraps the parsing in an
eval block. It returns the twig on success and 0 on failure (the twig object
also contains the parsed twig) . $@ contains the error message on failure
Note that the parsing still stops as soon as an error is detected, there is no way to keep going after an error.
parseurl except that it wraps the parsing in an eval block. It
returns the twig on success and 0 on failure (the twig object also contains
the parsed twig) . $@ contains the error message on failure
parse an HTML string or file handle (by converting it to XML using HTML::TreeBuilder, which needs to be available).
This works nicely, but some information gets lost in the process: newlines are removed, and (at least on the version I use), comments get get an extra CDATA section inside ( <!-- foo --> becomes <!-- <![CDATA[ foo ]]> -->
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.
parseurl_html> except that it wraps the parsing in an eval
block. It returns the twig on success and 0 on failure (the twig object also
contains the parsed twig) . $@ contains the error message on failure
parsefile_html> except that it wraps the parsing in an eval
block. It returns the twig on success and 0 on failure (the twig object also
contains the parsed twig) . $@ contains the error message on failure
parse_html except that it wraps the parsing in an eval block.
It returns the twig on success and 0 on failure (the twig object also contains
the parsed twig) . $@ contains the error message on failure
parse the $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 $optional_options, and parse the $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");
nparse but also sets the pretty_print option to indented.
nparse but also sets the error_context option to 1.
nparse but also sets the pretty_print option to indented
and the error_context option to 1.
expat object (actually the XML::Parser::Expat object)
used during parsing. It is useful for example to call XML::Parser::Expat methods
on it. To get the line of a tag for example use $t->parser->current_line.
$handlers is a reference to a hash similar to the
one in the twig_handlers option of new. All previous handlers are unset.
The method returns the reference to the previous handlers.
$exp. $handler is a
reference to a subroutine. If the handler was previously set then the reference
to the previous handler is returned.
$handlers is a reference to a hash similar to the
one in the start_tag_handlers option of new. All previous handlers are unset.
The method returns the reference to the previous handlers.
$exp. $handler is a
reference to a subroutine. If the handler was previously set then the reference
to the previous handler is returned.
$handlers is a reference to a hash similar to the
one in the end_tag_handlers option of new. All previous handlers are unset.
The method returns the reference to the previous handlers.
$exp. $handler is a
reference to a subroutine. If the handler was previously set then the
reference to the previous handler is returned.
twig_roots option when creating the twig
char_handler
ignore_elt handler (elements that match $exp will be ignored
ignore_elt handlers (previous handlers are replaced)
$tag
$optional_condition of a twig, if
no condition is given then the root is returned
$optional_condition of a twig, if
no condition is given then the last element of the twig is returned
id attribute is $id
elt_id
If the $optional_index argument is present, return the corresponding element
in the index (created using the index option for XML::Twig-new>)
If the argument is not present, return an arrayref to the index
erase, this will give you
a "clean" document in which there all text elements are as long as possible).
encoding attribute in the XML declaration (ie it is undef if the attribute
is not defined)
encoding attribute in the XML declaration.
Note that if the document did not have a declaration it is generated (with
an XML version of 1.0)
version attribute in
the XML declaration (ie it is undef if the attribute is not defined)
version attribute in the XML declaration.
If the declaration did not exist it is created.
standalone declaration for the document
standalone attribute in the XML
declaration. Note that if the document did not have a declaration it is
generated (with an XML version of 1.0)
encoding "attribute" in the XML declaration
undef (or not present)
then its former value is retained, if a false ('' or 0) value is passed then
the former value is deleted;
Performs a (very fast) global change. All elements $old_gi are now
$new_gi. This is a bit dangerous though and should be avoided if
< possible, as the new tag might be ignored in subsequent processing.
See BUGS
Flushes a twig up to (and including) the current element, then deletes
all unnecessary elements from the tree that's kept in memory.
flush keeps track of which elements need to be open/closed, so if you
flush from handlers you don't have to worry about anything. Just keep
flushing the twig every time you're done with a sub-tree and it will
come out well-formed. After the whole parsing don't forget toflush
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 update_DTD option if you have updated the (internal) DTD
and/or the entity list and you want the updated DTD to be output
The pretty_print option sets the pretty printing of the document.
Example: $t->flush( Update_DTD => 1);
$t->flush( $filehandle, pretty_print => 'indented');
$t->flush( \*FILE);
Flushes up to the $elt element. This allows you to keep part of the
tree in memory when you flush.
options: see flush.
flush except it does not print the twig. It just deletes
all elements that have been completely parsed so far.
$elt element. This allows you to keep part of the tree in
memory when you purge.
Prints the whole document associated with the twig. To be used only AFTER the parse.
options: see flush.
Prints the whole document associated with the twig to file $filename.
To be used only AFTER the parse.
options: see flush.
Return the text of the whole document associated with the twig. To be used only AFTER the parse.
options: see flush.
$handler
$handler
$handler instead of the twig being printed
$handler instead of the twig being printed
This method should be called during parsing, usually in start_tag_handlers.
It causes the element to be skipped during the parsing: the twig is not built
for this element, it will not be accessible during parsing or after it. The
element 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 the pretty print method, amongst 'none' (default), 'nsgmls',
'nice', 'indented', indented_c, 'wrapped', 'record' and
'record_c'
WARNING: the pretty print style is a GLOBAL variable, so once set it's
applied to ALL print's (and sprint's). Same goes if you use XML::Twig
with mod_perl . This should not be a problem as the XML that's generated
is valid anyway, and XML processors (as well as HTML processors, including
browsers) should not care. Let me know if this is a big problem, but at the
moment the performance/cleanliness trade-off clearly favors the global
approach.
Set the empty tag display style ('normal', 'html' or 'expand'). As
with set_pretty_print this sets a global flag.
normal outputs an empty tag '<tag/>', html adds a space
'<tag />' for elements that can be empty in XHTML and expand outputs
'<tag></tag>'
Prints the prolog (XML declaration + DTD + entity declarations) of a document.
options: see flush.
Return the prolog (XML declaration + DTD + entity declarations) of a document.
options: see flush.
finish method.
Unsets all handlers (including internal ones that set context), but expat
continues parsing to the end of the document or until it finds an error.
It should finish up a lot faster than with the handlers set.
finish_now is called).
Execution resumes after the Lparse> or parsefile call. The content
of the twig is what has been parsed so far (all open elements at the time
finish_now is called are considered closed).
expand_external_ents option when creating the twig
input_filter option when creating the twig
keep_atts_order option when creating the twig
keep_encoding option when creating the twig
output_filter option when creating the twig
output_text_filter option when creating the twig
Adds an external stylesheet to an XML document.
Supported types and options:
option: the url of the stylesheet
Example:
$t->add_stylesheet( xsl => "xsl_style.xsl");
will generate the following PI at the beginning of the document:
<?xml-stylesheet type="text/xsl" href="xsl_style.xsl"?>
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:
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)
/root/tag1/../tag'
Performs a get_xpath on the document root (see <Elt|"Elt">)
If the $optional_array_ref argument is used the array must contain
elements. The $xpath expression is applied to each element in turn
and the result is union of all results. This way a first query can be
refined in further steps.
get_xpath
get_xpath (similar to the XML::LibXML method)
join of all texts of the results of applying get_xpath
to the node (similar to the XML::LibXML method)
s/// operator.
Useful only if you don't have Scalar::Util or WeakRef 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
$twig->dispose to clear this problem.
A convenience method that creates l-valued accessors for attributes.
So $twig->create_accessors( 'foo') will create a foo method
that can be called on elements:
$elt->foo; # equivalent to $elt->{'att'}->{'foo'};
$elt->foo( 'bar'); # equivalent to $elt->set_att( foo => 'bar');
The tag is optional (but then you can't have a content ), the $optional_atts
argument is a reference to a hash of attributes, the content can be just a
string or a list of strings and element. A content of '#EMPTY' creates an empty
element;
Examples: my $elt= XML::Twig::Elt->new();
my $elt= XML::Twig::Elt->new( para => { align => 'center' });
my $elt= XML::Twig::Elt->new( para => { align => 'center' }, 'foo');
my $elt= XML::Twig::Elt->new( br => '#EMPTY');
my $elt= XML::Twig::Elt->new( 'para');
my $elt= XML::Twig::Elt->new( para => 'this is a para');
my $elt= XML::Twig::Elt->new( para => $elt3, 'another para');
The strings are not parsed, the element is not attached to any twig.
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 stored in the ID list.
Note that #COMMENT, #PCDATA or #CDATA are valid tag names, that will
create text elements.
To create an element foo containing a CDATA section:
my $foo= XML::Twig::Elt->new( '#CDATA' => "content of the CDATA section")
->wrap_in( 'foo');
An attribute of '#CDATA', will create the content of the attribute as CDATA:
my $elt= XML::Twig::Elt->new( 'p' => { #CDATA => 1}, 'foo < bar');
creates an element
<p><![CDATA[foo < bar]]></>
Creates an element from an XML string. The string is actually
parsed as a new twig, then the root of that twig is returned.
The arguments in %args are passed to the twig.
As always if the parse fails the parser will die, so use an
eval if you want to trap syntax errors.
As obviously the element does not exist beforehand this method has to be called on the class:
my $elt= parse XML::Twig::Elt( "<a> string to parse, with <sub/>
<elements>, actually tons of </elements>
h</a>");
Prints an entire element, including the tags, optionally to a
$optional_filehandle, optionally with a $pretty_print_style.
The print outputs XML data so base entities are escaped.
Return the gi of the element (the gi is the generic identifier the tag
name in SGML parlance).
tag and name are synonyms of gi.
gi
tag
tag) of an element
tag) of an element
$optional_condition
$optional_condition
$optional_condition (same as first_child)
$optional_condition (same as first_child)
Return the text of the first child of the element, or the first child
matching the $optional_condition
If there is no first_child then returns ''. This avoids getting the
child, checking for its existence then getting the text for trivial cases.
Similar methods are available for the other navigation methods:
All this methods also exist in "trimmed" variant:
first_child_text with a different name
Return the list of field (text of first child matching the conditions), missing fields are returned as the empty string.
Same method as first_child_text with a different name
first_child_trimmed_text with a different name
Set the content of the first child of the element that matches
$condition, the rest of the arguments is the same as for set_content
If no child matches $condition _and_ if $condition is a valid
XML element name, then a new element by that name is created and
inserted as the last child.
Return the element if the first child of the element (if it exists) passes
the $optional_condition undef otherwise
if( $elt->first_child_matches( 'title')) ...
is equivalent to
if( $elt->{first_child} && $elt->{first_child}->passes( 'title'))
first_child_is is an other name for this method
Similar methods are available for the other navigation methods:
$optional_condition)
$optional_condition)
$optional_condition
$optional_condition.
Return the next elt (optionally matching $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 $optional_elt is the root of a subtree. When the next_elt is out of the
subtree then the method returns undef. You can then walk a sub tree with:
my $elt= $subtree_root;
while( $elt= $elt->next_elt( $subtree_root)
{ # insert processing code here
}
$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
$offset-th element that matches the $optional_condition
$optional_condition) of
the element. The list is in document order.
$optional_condition)
In array context, reeturns an array containing the text of children of the
element (optionally which matches $optional_condition)
In scalar context, returns the concatenation of the text of children of the element
In array context, returns an array containing the trimmed text of children
of the element (optionally which matches $optional_condition)
In scalar context, returns the concatenation of the trimmed text of children of the element
$optional_condition
$optional_condition) of the element. This is the equivalent of the
getElementsByTagName of the DOM (by the way, if you are really a DOM
addict, you can use getElementsByTagName instead)
descendants
descendants
descendants except that the element itself is included in the list
if it matches the $optional_condition
Return the list of ancestors (optionally matching $optional_condition) of the
element. The list is ordered from the innermost ancestor to the outermost one
NOTE: the element itself is not part of the list, in order to include it you will have to use ancestors_or_self
$optional_condition) of the
element, including the element (if it matches the condition>).
The list is ordered from the innermost ancestor to the outermost one
$condition
$att or undef
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");
Delete the attribute for the element
You can actually delete several attributes at once:
$elt->del_att( 'att1', 'att2', 'att3');
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.
Note that the "old" links to the parent, previous and next siblings can still be accessed using the former_* methods
Returns the former next sibling of a cut node (or undef if the node has not been cut)
This makes it easier to write loops where you cut elements:
my $child= $parent->first_child( 'achild');
while( $child->{'att'}->{'cut'})
{ $child->cut; $child= $child->former_next_sibling; }
Cut all the children of the element (or all of those which satisfy the
$optional_condition).
Return the list of children
Paste a (previously cut 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:
$ref
$ref
$ref, as its previous sibling.
$ref, as its next sibling.
$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:
cut then a paste. The syntax is the same as paste.
cut
an element then paste another in its place, so replace comes in handy.
The calling element replaces $ref.
Add a prefix to an element. If the element is a PCDATA element the text
is added to the pcdata, if the elements first child is a PCDATA then the
text is added to it's pcdata, otherwise a new PCDATA element is created
and pasted as the first child of the element.
If the option is asis then the prefix is added asis: it is created in
a separate PCDATA element with an asis property. You can then write:
$elt1->prefix( '<b>', 'asis');
to create a <b> in the output of print.
Add a suffix to an element. If the element is a PCDATA element the text
is added to the pcdata, if the elements last child is a PCDATA 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 asis then the suffix is added asis: it is created in
a separate PCDATA element with an asis property. You can then write:
$elt2->suffix( '</b>', 'asis');
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.
erase, this will give you
a "clean" element in which there all text fragments are as long as possible).
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)
%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 $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.
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 var => 'name' to get $prefix replaced by /usr/local in the
generated data structure
By default variables are captured by the following regexp: /$(\w+)/
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 group_tags => { dirs => 'dir',
templates => 'template'}
makes the data structure be exactly as if the start and end tags for dirs and
templates 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 a text (PCDATA or CDATA) element in 2 at $offset, the original
element now holds the first part of the string and a new element holds the
right part. The new element is returned
If the element is not a text element then the first text child of the element is split
Split the text descendants of an element in place, the text is split using
the $regexp, if the regexp includes () then the matched separators will be
wrapped in elements. $1 is wrapped in $tag1, with attributes $atts1 if
$atts1 is given (as a hashref), $2 is wrapped in $tag2...
if $elt is <p>tati tata <b>tutu tati titi</b> tata tati tata</p>
$elt->split( qr/(ta)ti/, 'foo', {type => 'toto'} )
will change $elt to
<p><foo type="toto">ta</foo> tata <b>tutu <foo type="toto">ta</foo>
titi</b> tata <foo type="toto">ta</foo> tata</p>
The regexp can be passed either as a string or as qr// (perl 5.005 and
later), it defaults to \s+ just as the split built-in (but this would be
quite a useless behaviour without the $optional_tag parameter)
$optional_tag defaults to PCDATA or CDATA, depending on the initial element
type
The list of descendants is returned (including un-touched original elements and newly created ones)
Wrap the children of the element that match the regexp in an element $tag.
If $optional_attribute_hashref is passed then the new element will
have these attributes.
The $regexp_string includes tags, within pointy brackets, as in
<title><para>+ and the usual Perl modifiers (+*?...).
Tags can be further qualified with attributes:
<para type="warning" classif="cosmic_secret">+. The values
for attributes should be xml-escaped: <candy type="M&Ms">*
(<, & > and " should be escaped).
Note that elements might get extra id attributes in the process. See add_id.
Use strip_att to remove unwanted id's.
Here is an example:
If the element $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 s/// operator.
$regexp must be a perl regexp, created with the qr operator.
$replace can include $1, $2... from the $regexp. It can also be
used to create element and entities, by using
&elt( tag => { att => val }, text) (similar syntax as new) and
&ent( name).
Here is a rather complex example:
$elt->subs_text( qr{(?<!do not )link to (http://([^\s,]*))},
'see &elt( a =>{ href => $1 }, $2)'
);
This 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 ):
$elt->subs_text( qr{ }, '&ent( " ")');
or, using a variable:
my $ent=" ";
$elt->subs_text( qr{ }, "&ent( '$ent')");
Note that the substitution is always global, as in using the g modifier
in a perl substitution, and that it is performed on all text descendants
of the element.
Bug: in the $regexp, you can only use \1, \2... if the replacement
expression does not include elements or attributes. eg
t->subs_text( qr/((t[aiou])\2)/, '$2'); # ok, replaces toto, tata, titi, tutu by to, ta, ti, tu t->subs_text( qr/((t[aiou])\2)/, '&elt(p => $1)' ); # NOK, does not find toto...
Add an id to the element.
The id is an attribute, id by default, see the id option for XML::Twig
new to change it. Use an id starting with # to get an id that's not
output by print, flush or sprint, yet that allows you to use the
elt_id method to get the element easily.
If the element already has an id, no new id is generated.
By default the method create an id of the form twig_id_<nnnn>,
where <nnnn> is a number, incremented each time the method is called
successfully.
add_id is twig_id_<nnnn>,
set_id_seed changes the prefix to $prefix and resets the number
to 1
Remove the attribute $att from all descendants of the element (including
the element)
Return the element
$old_name to $new_name. If there is no
attribute $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 $att.
%options are the same as for sort_children_on_value
Return the element.
Sort the children of the element in place, according to the field $tag (the
text of the first child of the child with this tag). %options are the same
as for sort_children_on_value.
Return the element, with its children sorted
Sort the children of the element in place. The $get_key argument is
a reference to a function that returns the sort key when passed an element.
For example:
$elt->sort_children( sub { $_[0]->{'att'}->{"nb"} + $_[0]->text },
type => 'numeric', order => 'reverse'
);
Turn the text of the first sub-element matched by $cond into the value of
attribute $att of the element. If $att is omitted then $cond is used
as the name of the attribute, which makes sense only if $cond is a valid
element (and attribute) name.
The sub-element is then cut.
$att and create a sub-element $tag as first
child of the element. If $tag is omitted then $att is used as the name of
the sub-element.
Return a list of elements satisfying the $xpath. $xpath is an XPATH-like
expression.
A subset of the XPATH abbreviated syntax is covered:
tag
tag[1] (or any other positive number)
tag[last()]
tag[@att] (the attribute exists for the element)
tag[@att="val"]
tag[@att=~ /regexp/]
tag[att1="val1" and att2="val2"]
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 recommendationhttp://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 $optional_offset is used then only one element will be returned, the one
with the appropriate offset in the list, starting at 0
Quoting and interpolating variables can be a pain when the Perl syntax and the XPATH syntax collide, so use alternate quoting mechanisms like q or qq (I like q{} and qq{} myself).
Here are some more examples to get you started:
my $p1= "p1";
my $p2= "p2";
my @res= $t->get_xpath( qq{p[string( "$p1") or string( "$p2")]});
my $a= "a1";
my @res= $t->get_xpath( qq{//*[@att="$a"]});
my $val= "a1";
my $exp= qq{//p[ \@att='$val']}; # you need to use \@ or you will get a warning
my @res= $t->get_xpath( $exp);
Note that the only supported regexps delimiters are / and that you must backslash all / in regexps AND in regular strings.
XML::Twig does not provide natively full XPATH support, but you can use
XML::Twig::XPath to get findnodes to use XML::XPath as the
XPath engine, with full coverage of the spec.
XML::Twig::XPath to get findnodes to use XML::XPath as the
XPath engine, with full coverage of the spec.
get_xpath
get_xpath
Return a string consisting of all the PCDATA and CDATA in an element,
without any tags. The text is not XML-escaped: base entities such as &
and < are not escaped.
The 'no_recurse' option will only return the text of the element, not
of any included sub-elements (same as text_only).
text except that the text returned doesn't include
the text of sub-elements.
text except that the text is trimmed: leading and trailing spaces
are discarded, consecutive spaces are collapsed
PCDATA, just set its
text, otherwise cut all the children of the element and create a single
PCDATA child for it, which holds the text.
$elt2 within the element
For each tag in the list inserts an element $tag as the only child of the
element. The element gets the optional attributes in$optional_atts<n>.
All children of the element are set as children of the new element.
The upper level element is returned.
$p->insert( table => { border=> 1}, 'tr', 'td')
put $p in a table with a visible border, a single tr and a single td
and return the table element:
<p><table border="1"><tr><td>original content of p</td></tr></table></p>
Wrap elements in @tag as the successive ancestors of the element, returns the
new element.
$elt->wrap_in( 'td', 'tr', 'table') wraps the element as a single cell in a
table for example.
Optionally each tag can be followed by a hashref of attributes, that will be set on the wrapping element:
$elt->wrap_in( p => { class => "advisory" }, div => { class => "intro", id => "div_intro });
Combines a new and a paste : creates a new element using
$tag, $opt_atts_hashref and @opt_content which are arguments similar
to those for new, then paste it, using $opt_position or 'first_child',
relative to $elt.
Return the newly created element
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 PCDATA element
for any strings in the list.
The $optional_atts argument is the ref of a hash of attributes. If this
argument is used then the previous attributes are deleted, otherwise they
are left untouched.
WARNING: if you rely on 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 stored in the ID list.
A content of '#EMPTY' creates an empty element;
$optional_prefix or the element name
belongs to. If the name doesn't belong to any namespace, undef is returned.
@optional_tag_list is supplied only those
ancestors whose tag is in the list will be checked.
$optional_condition,
0 otherwise
Return the depth of the element in the twig (root is 0).
If $optional_condition is given then only ancestors that match the condition are
counted.
WARNING: in a tree created using the twig_roots option this will not return
the level in the document tree, level 0 will be the document root, level 1
will be the twig_roots elements. During the parsing (in a twig_handler)
you can use the depth method on the twig object to get the real parsing depth.
$potential_parent is
an element)
$cond
optionally within $optional_level levels. The returned value is the
including element.
PCDATA element or undef if the element is not
PCDATA.
PCDATA element.
PCDATA element.
CDATA element, returns 0 otherwise.
CDATA or PCDATA element, returns 0 otherwise.
CDATA element or undef if the element is not
CDATA.
CDATA element, including the opening and
closing markers.
CDATA element.
CDATA element.
CDATA sections in the element into regular PCDATA elements. This is useful
when converting XML to HTML, as browsers do not support CDATA sections.
Set a property of the element that causes it to be output without being XML
escaped by the print functions: if it contains a < b it will be output
as such and not as a < b. This can be useful to create text elements
that will be output as markup. Note that all PCDATA descendants of the
element are also marked as having the property (they are the ones that are
actually impacted by the change).
If the element is a CDATA element it will also be output asis, without the
CDATA markers. The same goes for any CDATA descendant of the element
asis property for the element and its text descendants.
asis property status of the element ( 1 or undef)
#ELT' for "real" elements, or '#PCDATA',
'#CDATA', '#COMMENT', '#ENT', '#PI'
PCDATA,
CDATA...
Return the list of children if all children of the element match
the expression $exp
if( $para->contains_only( 'tt')) { ... }
$exp
returns that element. Otherwise returns 0.
contains_only_text
PCDATA element, returns 0 otherwise.
<tag att="value""/>.
<tag att="value""></tag>
#PI) element,
return 0 otherwise.
<?target data?>)
#COMMENT) element,
return 0 otherwise.
<!--
and -->)
<!-- comment -->)
#ENT). $entity) is the entity
text (&ent;)
#ENT) element (&ent;)
#ENT) element (ent)
&ent;) otherwise
$offset-th child of the element, optionally the $offset-th
child that matches $optional_condition. The children are treated as a list, so
$elt->child( 0) is the first child, while $elt->child( -1) is
the last child.
undef if the sibling does not exist. Arguments
are the same as child.
$optional_condition (ie the last of the element children matching
the condition).
first_child_text but for the last child.
$offset-th sibling of the element, or the
$offset-th one matching $optional_condition. If $offset is negative then a
previous sibling is returned, if $offset is positive then a next sibling is
returned. $offset=0 returns the element if there is no condition or
if the element matches the condition>, undef otherwise.
undef if the sibling does not exist.
Arguments are the same as sibling.
$optional_condition)
for the element. The elements are ordered in document order.
$optional_condition)
following the element. The elements are ordered in document order.
Return the position of the element in the children list. The first child has a position of 1 (as in XPath).
If the $optional_condition is given then only siblings that match the condition
are counted. If the element itself does not match the condition then
0 is returned.
att_nb
Return the attribute value, where '&', '<' and $quote (" by default) are XML-escaped
if $optional_quote is passed then it is used as the quote.
id attribute of the element to the value.
See elt_id to change the id attribute name
id attribute of the element and remove it from the id list
for the document
class attribute for the element (methods on the class
attribute are quite convenient when dealing with XHTML, or plain XML that
will eventually be displayed using CSS)
class attribute for the element to $class
$class to the element class attribute: the new class is added
only if it is not already present. Note that classes are sorted alphabetically,
so the class attribute can be changed even if the class is already there
class attribute to the value of attribute $att
$att to the class attribute of the element
$att to the class attribute of the element
and delete the attribute
class attribute of the element to the element tag
class attribute
class attribute and sets the tag to $new_tag
1) if the element is in the class $class (if $class is
one of the tokens in the element class attribute)
span and set its class to the old tag
div and set its class to the old tag
/> at the end of an empty element tag
Equivalent to $elt->sprint( 1), returns the string for the entire
element, excluding the element's tags (but nested element tags are present)
The 'no_recurse' option will only return the text of the element, not
of any included sub-elements (same as xml_text_only).
output_filter or output_encoding options, without any tag.
xml_text except that the text returned doesn't include
the text of sub-elements.
Set the pretty print method, amongst 'none' (default), 'nsgmls',
'nice', 'indented', 'record' and 'record_c'
pretty_print styles:
\n is used
\n added within tags
\n wherever possible (NOT SAFE, can lead to invalid XML)
nice plus indents elements (NOT SAFE, can lead to invalid XML)
record, one record per line
Set the method to output empty tags, amongst 'normal' (default), 'html',
and 'expand',
normal outputs an empty tag '<tag/>', html adds a space
'<tag />' for elements that can be empty in XHTML and expand outputs
'<tag></tag>'
double' (default) or 'single'
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
Return 1 if $elt starts before the element, 0 otherwise. If the 2 elements
are not in the same twig then return undef.
if( $a->cmp( $b) == -1) { return 1; } else { return 0; }
Return 1 if $elt starts after the element, 0 otherwise. If the 2 elements
are not in the same twig then return undef.
if( $a->cmp( $b) == -1) { return 1; } else { return 0; }
/root/tag1/../tag'
Return a unique XPath expression that can be used to find the element again.
It looks like /doc/sect[3]/title: unique elements do not have an index,
the others do.
Low-level methods on the twig:
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 children or
ancestors ) that passes the condition is returned.
The condition is a single step of an XPath expression using the XPath subset
defined by get_xpath. Additional conditions are:
The condition can be
qr// (hence this is available only on perl 5.005 and above)
XML::Twig implements a subset of XPath through the get_xpath method.
If you want to use the whole XPath power, then you can use XML::Twig::XPath
instead. In this case XML::Twig uses XML::XPath to execute XPath queries.
You will of course need XML::XPath installed to be able to use XML::Twig::XPath.
See XML::XPath for more information.
The methods you can use are:
$path.
In order for XML::XPath to be used as the XPath engine the following methods
are included in XML::Twig:
in XML::Twig
in XML::Twig::Elt
The methods you can use are the same as on XML::Twig::XPath elements:
$path.
Additional examples (and a complete tutorial) can be found on the XML::Twig Pagehttp://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:
XML::Twig you will probably need to subclass also
XML::Twig::Elt. Use the elt_class option when you create the
XML::Twig object to get the elements created in a different class
(which should be a subclass of XML::Twig::Elt.
XML::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:
The XML document includes an internal DTD, and maybe entity declarations.
If you use the load_DTD option when creating the twig the DTD information and the entity declarations can be accessed.
The DTD and the entity declarations will be flush'ed (or print'ed) either
as is (if they have not been modified) or as reconstructed (poorly, comments
are lost, order is not kept, due to it's content this DTD should not be viewed
by anyone) if they have been modified. You can also modify them directly by
changing the $twig->{twig_doctype}->{internal} field (straight from
XML::Parser, see the Doctype handler doc)
The XML document includes a reference to an external DTD, and maybe entity declarations.
If you use the load_DTD when creating the twig the DTD information and the
entity declarations can be accessed. The entity declarations will be
flush'ed (or print'ed) either as is (if they have not been modified) or
as reconstructed (badly, comments are lost, order is not kept).
You can change the doctype through the $twig->set_doctype method and
print the dtd through the $twig->dtd_text or $twig->dtd_print
methods.
If you need to modify the entity list this is probably the easiest way to do it.
If you set handlers and use flush, 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.
att="val&ent;" will be turned into att => val, unless you use the
keep_encoding argument to XML::Twig->new
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.
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 dispose method to free
that memory after you are done.
If you create elements the same thing might happen, use the delete
method to get rid of them.
Alternatively installing the Scalar::Util (or WeakRef) module on a version
of Perl that supports it (>5.6.0) will get rid of the memory leaks automagically.
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);
setHandlers method.
Pretty printing (at least using the 'indented' 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 flush 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 <b> element
These are the things that can mess up calling code, especially if threaded. They might also cause problem under mod_perl.
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 :--(
these should cause no trouble:
%base_ent= ( '>' => '>',
'<' => '<',
'&' => '&',
"'" => ''',
'"' => '"',
);
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);
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.
$empty_tag_style can mess up HTML bowsers though and changing $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)
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 optimization.
%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:
Return a hashref with all the global variables used by XML::Twig
The hash has the following fields: pretty, quote, indent,
empty_tag_style, keep_encoding, expand_external_entities,
output_filter, output_text_filter, keep_atts_order
$state is a hashref
Lsave_global_state> state
A number of twig features are just global at the moment. These include
the ID list and the "tag pool" (if you use change_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 libxml2 on which it is based, sticks to the standards,
and implements a good number of them in a rather strict way: XML, XPath, DOM,
RelaxNG, I must be forgetting a couple (XInclude?). It is fast and rather
frugal memory-wise.
XML::Twig is older: when I started writing it XML::Parser/expat was the only game in town. It implements XML and that's about it (plus a subset of XPath, and you can use XML::Twig::XPath if you have XML::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/).