# XML::Handler::XMLWriter - phpMan

## NAME
    [XML::Handler::XMLWriter] - a PerlSAX handler for writing readable XML

## SYNOPSIS
     use [XML::Parser::PerlSAX];
     use [XML::Handler::XMLWriter];

     $my_handler = [XML::Handler::XMLWriter]->new( I<OPTIONS> );

     [XML::Parser::PerlSAX]->new->parse(Source => { SystemId => 'REC-xml-19980210.xml' },
                                      Handler => $my_handler);

## DESCRIPTION
    "[XML::Handler::XMLWriter]" is a PerlSAX handler for writing readable XML
    (in contrast to Canonical XML, for example). [XML::Handler::XMLWriter] can
    be used with a parser to reformat XML, with [XML::DOM] or [XML::Grove] to
    write out XML, or with other PerlSAX modules that generate events.

    "[XML::Handler::XMLWriter]" is intended to be used with PerlSAX event
    generators and does not perform any checking itself (for example,
    matching start and end element events). If you want to generate XML
    directly from your Perl code, use the [XML::Writer] module. [XML::Writer]
    has an easy to use interface and performs many checks to make sure that
    the XML you generate is well-formed.

    "[XML::Handler::XMLWriter]" is a subclass of "[XML::Handler::Subs]".
    "[XML::Handler::XMLWriter]" can be further subclassed to alter it's
    behavior or to add element-specific handling. In the subclass, each time
    an element starts, a method by that name prefixed with `s_' is called
    with the element to be processed. Each time an element ends, a method
    with that name prefixed with `e_' is called. Any special characters in
    the element name are replaced by underscores. If there isn't a start or
    end method for an element, the default action is to write the start or
    end tag. Start and end methods can use the `"print_start_element()"' and
    `"print_end_element()"' methods to print start or end tags. Subclasses
    can call the `"print()"' method to write additional output.

    Subclassing [XML::Handler::XMLWriter] in this way is similar to
    [XML::Parser]'s Stream style.

    [XML::Handler::Subs] maintains a stack of element names,
    `"$self-"{Names}', and a stack of element nodes, `"$self-"{Nodes}>' that
    can be used by subclasses. The current element is pushed on the stacks
    before calling an element-name start method and popped off the stacks
    after calling the element-name end method.

    See [XML::Handler::Subs] for additional methods.

    In addition to the standard PerlSAX handler methods (see PerlSAX for
    descriptions), [XML::Handler::XMLWriter] supports the following methods:

    new( *OPTIONS* )
        Creates and returns a new instance of [XML::Handler::XMLWriter] with
        the given *OPTIONS*. Options may be changed at any time by modifying
        them directly in the hash returned. *OPTIONS* can be a list of key,
        value pairs or a hash. The following *OPTIONS* are supported:

        Output
            An [IO::Handle] or one of it's subclasses (such as [IO::File]), if
            this parameter is not present and the AsString option is not
            used, the module will write to standard output.

        AsString
            Return the generated XML as a string from the `"parse()"' method
            of the PerlSAX event generator.

        Newlines
            A true or false value; if this parameter is present and its
            value is true, then the module will insert an extra newline
            before the closing delimiter of start, end, and empty tags to
            guarantee that the document does not end up as a single, long
            line. If the parameter is not present, the module will not
            insert the newlines.

        IsSGML
            A true or false value; if this parameter is present and its
            value is true, then the module will generate SGML rather than
            XML.

    print_start_element($element)
        Print a start tag for `$element'. This is the default action for the
        PerlSAX `"start_element()"' handler, but subclasses may use this if
        they define a start method for an element.

    print_end_element($element)
        Prints an end tag for `$element'. This is the default action for the
        PerlSAX `"end_element()"' handler, but subclasses may use this if
        they define a start method for an element.

    print($output)
        Write `$output' to Output and/or append it to the string to be
        returned. Subclasses may use this to write additional output.

## TODO
    *   An Elements option that provides finer control over newlines than
        the Newlines option, where you can choose before and after newline
        for element start and end tags. Inspired by the Python XMLWriter.

    *   Support Doctype and XML declarations.

## AUTHOR
    Ken MacLeod, <ken@bitsko.slc.ut.us> This module is partially derived from
    [XML::Writer] by David Megginson.

## SEE ALSO
    [perl(1)], [PerlSAX.pod(3)]