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 the XML::Parser manpage.

    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 `the section on "/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 the XML::Parser manpage, 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 `the
            section on "/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 `the section on "/BUGS'"

    root
        Returns the root element of a twig

    change_gi      (old_gi, new_gi)
        Performs a (very fast) global change. All elements old_gi
        are now new_gi. See `the section on "/BUGS'"

    flush            [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. flush take an
        optional filehandle as an argument

  Element

    new Should be private.

    set_gi         ($gi)
    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        [$gi]
        Returns the parent of the element, or the first ancestor
        whose gi is $gi.

    first_child   [$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    [$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  [$gi]
    Returns the previous sibling of the element, or the first one whose gi is $gi
    next_sibling  [$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 `the section on "/elt_id'" to change the id attribute name
    id
    Gets the id attribute vakue
    children     [$gi]
    Returns the list of children (optionally whose gi is $gi) of the element
    ancestors    [$gi]
    Returns the list of ancestors (optionally whose gi is $gi) of the element
    next_elt     [$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     [$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, [$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       ([$pos], $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 =item - 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         [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.

EXAMPLES
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
    the XML::Parser manpage

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.

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
