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

• 1

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

• 2

  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

© MM-MMXI, John McNamara.

All Rights Reserved. This module is free software. It may be used, redistributed and/or modified under the same terms as Perl itself.

cpanm Spreadsheet::WriteExcelXML

perl -MCPAN -e shell
install Spreadsheet::WriteExcelXML