NAME

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

SYNOPSIS

single-tree mode    
    my $t= new XML::Twig();
    $t->parse( '<doc><para>para1</para></doc>');
    $t->print;

chunk mode 
    my $t= new XML::Twig( Handlers => { section => \&flush});
    $t->parsefile( 'doc.xml');
    $t->flush;
    sub flush { $_[0]->flush; }

DESCRIPTION

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 to output the parts of it that have been completely processed.

What should you use it for: xml to xml or xml to html conversions of documents that are small enough to fit in memory, or that can be divided in chunks that can be processed separately.

METHODS

Twigs

A twig is a subclass of XML::Parser, so all XML::Parser methods can be used on one, including parse and parsefile. setHandlers on the other hand should not be used for Start, End and Char, see "BUGS"

- new

This is a class method, the constructor for XML::Twig. Options are passed as keyword value pairs. Recognized options are the same as XML::Parser, plus some XML::Twig specifics:

- TwigHandlers

This argument replaces the corresponding XML::Parser argument. It consists of a hash { gi => \&handler} A gi (generic identifier I guess) is just a tag name by the way. When an element is CLOSED the corresponding handler is called, with 2 arguments, the twig and the "Element". The twig includes the document tree taht has been built so far, the element is the complete sub-tree for the element. Text is stored in elements which gi 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).

- 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 "BUGS"

root

Returns the root element of a twig

entity_list

Returns the entity list of a twig

change_gi ($old_gi, $new_gi)

Performs a (very fast) global change. All elements old_gi are now new_gi. See "BUGS"

flush OPTIONAL_FILEHANDLE

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 to flush one more time to print the end of the document. The doctype and entity declarations are also printed by the way.

flush take an optional filehandle as an argument.

print OPTIONNAL_FILEHANDLE

Oddly enough this is just an alias for the flush method. For sanity's sake just try to use it only for trees that have been completely loaded, there is no check right now but I might add one soon.

print_prolog OPTIONNAL_FILEHANDLE

Prints the prolog (XML declaration + DTD + entity declarations) of a document. Does not print the DTD at the moment.

Element

new

Should be private.

set_gi ($gi)

Sets the gi of an element

gi

Returns the gi of the element

closed

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

set_pcdata ($text)

Sets the text of a #PCDATA element. Returns the text or undef if the element was not a #PCDATA.

pcdata

Returns the text of a #PCDATA element or undef

root

Returns the root of the twig containing the element

twig

Returns the twig containing the element.

parent ($optional_gi)

Returns the parent of the element, or the first ancestor whose gi is $gi.

first_child ($optional_gi)

Returns the first child of the element, or the first child whose gi is $gi. (ie the first of the element children whose gi matches) .

last_child ($optional_gi)

Returns the last child of the element, or the last child whose gi is $gi. (ie the last of the element children whose gi matches) .

prev_sibling ($optional_gi)

Returns the previous sibling of the element, or the first one whose gi is $gi.

next_sibling ($optional_gi)

Returns the next sibling of the element, or the first one whose gi is $gi.

atts

Returns a hash containing the element attributes

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

Sets the element attributes with the hash supplied as argument

del_atts

Deletes all the element attributes.

set_att ($att, $att_value)

Sets the attribute of the element to a value

att ($att)

Returns the attribute value

del_att { delete $_[0]->{'att'}->{$_[1]}; }

Delete the attribute for the element

set_id ($id)

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

id

Gets the id attribute vakue

children ($optional_gi)

Returns the list of children (optionally whose gi is $gi) of the element

ancestors ($optional_gi)

Returns the list of ancestors (optionally whose gi is $gi) of the element

next_elt ($optional_gi)

Returns the next elt (optionally whose gi is $gi) 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.

prev_elt ($optional_gi)

Returns the previous elt (optionally whose gi is $gi) of the element. This is the first element which open the current one. So it's usually either the last descendant of the previous sibling or simply the parent

level

Returns the depth of the element in the tree (root is 1)

in ($potential_parent)

Returns true if the element is in the potential_parent

in_context ($gi, $optional_level)

Returns true if the element is included in an element whose gi is $gi, within $level levels.

cut

Cuts the element from the tree.

paste ($optional_position, $ref)

Pastes a (previously cut) element. The optionnal position element can be

- first_child (default)

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

- last_child

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

- before

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

- after

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

erase

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

delete

Cut the element and frees the memory

DESTROY

Frees the element from memory

start_tag

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

end_tag

Returns the string for the end tag of an element, empty for an empty one.

print OPTIONNAL_FILEHANDLE

Prints an entire element, including the tags, optionally to a FILEHANDLE

sprint

Returns the string for an entire element, including the tags. To be used with caution!

text

Returns a string consisting of all the PCDATA in an element, without the tagging

private methods

close

set_parent ( $parent)

set_first_child ( $first_child)

set_last_child ( $last_child)

set_prev_sibling ( $set_prev_sibling)

set_next_sibling ( $set_next_sibling)

flushed

flush

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

Entity_list

new

Creates an entity list

add ($ent)

Adds an entity to an entity list.

delete ($ent or $gi).

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

print (OPTIONAL_FILEHANDLE)

Prints the entity list

Entity

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

Same arguments has the Entity handler for XML::Parser

print (OPTIONNAL_FILEHANDLE)

Prints an entity declaration

text

Returns the entity declaration text

EXAMPLES

See the test file in XML-Twig-1.6/t/test1.t

HINTS

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.

BUGS

- ID list

The ID list is NOT updated at the moment when ID's are modified or elements cut or deleted.

- change_gi

Does not work 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 setHandlers one.

- Notation declarations

Are not output (in fact they are completely ignored).

TODO

- multiple twigs are not well supported

A number of twig features are just global at the moment. These include the ID list and the "gi pool" (if you use change_gi then you change the gi for ALL twigs).

Next version will try to support these while trying not to be to hard on performances (at least when a single twig is used!).

- XML::Parser-like handlers

Sometimes it would be nice to be able to use both XML::Twig handlers and XML::Parser handlers, for example to perform generic tasks on all open tags, like adding an ID, or taking care of the autonumbering.

Next version...

- create an element (not a twig) from a string

AUTHOR

Michel Rodriguez <m.v.rodriguez@ieee.org>

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

Bug reports and comments to m.v.rodriguez@ieee.org.

SEE ALSO

XML::Parser

cpanm XML::Twig

perl -MCPAN -e shell
install XML::Twig