NAME

XMLwriter - A base class for Excel workbooks and worksheets.

SYNOPSIS

    #!/usr/bin/perl -w

    use strict;
    use Spreadsheet::WriteExcelXML::XMLwriter;

    my $writer  = Spreadsheet::WriteExcelXML::XMLwriter->new(*STDOUT);

    $writer->_write_xml_start_tag(0, 1, 0, 'Table', 'Rows', 4, 'Cols', 2);
    $writer->_write_xml_element  (1, 1, 0, 'Row', 'Index', '1');
    $writer->_write_xml_end_tag  (0, 1, 0, 'Table');

    __END__

    Prints:

    <Table Rows="4" Cols="2">
        <Row Index="1"/>
    </Table>

DESCRIPTION

This module is used in conjunction with Spreadsheet::WriteExcelXML. It is not intended to be a general purpose module.

As such this documentation is intended mainly for Spreadsheet::WriteExcelXML developers and maintainers.

METHODS

This section describes the methods of the "Spreadsheet::WriteExcelXML::XMLwriter" module.

set_indentation()

The "set_indentation()" method is used to define the style of indentation used in the output from "Spreadsheet::WriteExcelXML::XMLwriter". This is the only "public" method of the module.

The default indentation style is four spaces. Calling "set_indentation()" with "undef" or no argument will set the indentation style back to the default.

A special case argument is the null string ''. In addition to not adding any indentation this also overrides any newline settings so that the output is as compact as possible and in the form of a single line. This is useful for saving space or when streaming the output.

The following example shows some of the options:

    #!/usr/bin/perl -w

    use strict;
    use Spreadsheet::WriteExcelXML::XMLwriter;

    my $writer  = Spreadsheet::WriteExcelXML::XMLwriter->new(*STDOUT);

    # One space indent.
    $writer->set_indentation(' ');
    $writer->_write_xml_start_tag(1, 1, 1, 'Table');
    $writer->_write_xml_start_tag(2, 1, 1, 'Row'  );
    $writer->_write_xml_start_tag(3, 1, 1, 'Cell' );
    print "\n";

    # Undef. Four space indent, the default.
    $writer->set_indentation();
    $writer->_write_xml_start_tag(1, 1, 1, 'Table');
    $writer->_write_xml_start_tag(2, 1, 1, 'Row'  );
    $writer->_write_xml_start_tag(3, 1, 1, 'Cell' );
    print "\n";

    # Empty string. No indentation or newlines.
    $writer->set_indentation('');
    $writer->_write_xml_start_tag(1, 1, 1, 'Table');
    $writer->_write_xml_start_tag(2, 1, 1, 'Row'  );
    $writer->_write_xml_start_tag(3, 1, 1, 'Cell' );
    print "\n";

The output is as follows. Spaces shown as "." for clarity.

    .<Table>
    ..<Row>
    ...<Cell>

    ....<Table>
    ........<Row>
    ............<Cell>

    <Table><Row><Cell>

_format_tag($level, $nl, $list, @attributes)

This function formats an XML element tag for printing. This is a "private" method used by the "_write_xml_xxx" methods. The "_write_xml_xxx" methods can be considered as "protected" and share the same parameters as "_format_tag()".

The parameters are as follows:

$level: The $level parameter sets the indentation level. The type of indentation is defined using the set_indentation() method.
$nl: The $nl parameter sets the number of newlines after the tag.
$list: The $list parameter defines if element attributes are listed on more than one line. The value should be 0, 1 or 2 as follows:

No list.

    $writer->_format_tag(1, 1, 0, 'Foo', 'Color', 'red', 'Height', 12);

    # Returns
    <Foo Color="red" Height="12">

Automatic list. This option puts the attributes on separate lines if there is more than one attribute.

    # Implicit list (more than one attribute)
    $writer->_format_tag(1, 1, 1, 'Foo', 'Color', 'red', 'Height', 12);

    # Returns
    <Foo
        Color="red"
        Height="12">


    # No implicit list (one attribute only)
    $writer->_format_tag(1, 1, 1, 'Foo', 'Color', 'red');

    # Returns
    <Foo Color="red">

Explicit list. This option generates a list effect even when there is only one attribute.

    $writer->_format_tag(1, 1, 2, 'Foo', 'Color', 'red');

    # Returns
    <Foo
        Color="red">

Note: The $level, $nl and $list parameters could be set as defaults in the "_write_xml_xxx" methods. For example $level could be incremented and decremented automatically, and $nl and <$list> could be set to 1. The defaults could then be overridden on a per tag basis. However, we'll maintain the simpler direct approach for now.

_write_xml_start_tag()

Write an XML start tag with attributes if present. See the _format_tag() method for a list of the parameters.

    $writer->_write_xml_start_tag(0, 0, 0, 'Table', 'Rows', 4, 'Cols', 2);

    # Output
    <Table Rows="4" Cols="2">

_write_xml_end_tag()

Write an XML end tag with attributes if present. See the _format_tag() method for a list of the parameters.

    $writer->_write_xml_end_tag(0, 0, 0, 'Table');

    # Output
    </Table>

_write_xml_element()

Write a complete XML tag with attributes if present. See the _format_tag() method for a list of the parameters.

    $writer->_write_xml_element(0, 0, 0, 'Table', 'Rows', 4, 'Cols', 2);

    # Output
    <Table Rows="4" Cols="2"/>

_write_xml_directive()

Write an XML directive tag. See the _format_tag() method for a list of the parameters.

    $writer->_write_xml_directive(0, 0, 0, 'xml', 'version', '1.0');

    # Output
    <?xml version="1.0"?>

_write_xml_content()

Write the content section of a tag:

    <Tag>This is the content.</Tag>

It encodes any XML escapes that occur in the content. See the "_encode_xml_escapes" method.

_write_xml_unencoded_content()

This method is the same as "" except that it doesn't try to encode. This is used mainly to save a small amount of time when writing data types that doesn't need to be encoded such as <Number>.

_encode_xml_escapes()

Write some standard XML escapes, namely """, "&", "<", ">" and "\n".

The apostrophe character isn't escaped since "Spreadsheet::WriteExcelXML::XMLwriter" always uses double quoted strings for attribute values.

    print $writer->_encode_xml_escapes('foo < 3');

    # Outputs
    foo &lt; 3

AUTHOR

John McNamara jmcnamara@cpan.org

COPYRIGHT

POD ERRORS

Hey! The above document had some coding errors, which are explained below: