The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
XML-MinWriter-0.02
River stage one • 1 direct dependent • 1 total dependent
++
/ XML::MinWriter

NAME

XML::MinWriter - Perl extension for writing XML.

SYNOPSIS

Here is a simple example of how to use XML::MinWriter:

  use XML::MinWriter;

  open my $fh, '>', \my $xml or die $!;
  my $wrt = XML::MinWriter->new(OUTPUT => $fh, LINE_MODE => 1, DATA_INDENT => 2);

  $wrt->xmlDecl('iso-8859-1');
  $wrt->startTag('alpha');
  $wrt->startTag('beta', p1 => 'dat1', p2 => 'dat2');
  $wrt->characters('abcdefg');
  $wrt->endTag('beta');
  $wrt->write_pyx('(gamma');
  $wrt->write_pyx('-hijklmn');
  $wrt->write_pyx(')gamma');
  $wrt->endTag('alpha');

  $wrt->end;
  close $fh;

  print "The XML generated is as follows:\n\n";
  print $xml, "\n";

...and this is the output:

  <?xml version="1.0" encoding="iso-8859-1"?>
  <alpha>
    <beta p1="dat1" p2="dat2">
      abcdefg
    </beta>
    <gamma>
      hijklmn
    </gamma>
  </alpha>

Here is the same example, but with DATA_MODE => 1 instead of LINE_MODE => 1

  use XML::MinWriter;

  open my $fh, '>', \my $xml or die $!;
  my $wrt = XML::MinWriter->new(OUTPUT => $fh, DATA_MODE => 1, DATA_INDENT => 2);

  $wrt->xmlDecl('iso-8859-1');
  $wrt->startTag('alpha');
  $wrt->startTag('beta', p1 => 'dat1', p2 => 'dat2');
  $wrt->characters('abcdefg');
  $wrt->endTag('beta');
  $wrt->write_pyx('(gamma');
  $wrt->write_pyx('-hijklmn');
  $wrt->write_pyx(')gamma');
  $wrt->endTag('alpha');

  $wrt->end;
  close $fh;

  print "The XML generated is as follows:\n\n";
  print $xml, "\n";

...and this is the output:

  <?xml version="1.0" encoding="iso-8859-1"?>
  <alpha>
    <beta p1="dat1" p2="dat2">abcdefg</beta>
    <gamma>hijklmn</gamma>
  </alpha>

DESCRIPTION

XML::MinWriter is a module to write XML. It is largely compatible to XML::Writer, but XML::MinWriter does not perform checks whether the XML is well formed. There is also additional support for writing XML from a PYX data source (For example, both modules XML::TiePYX and XML::Reader can produce PYX which can then be fed into XML::MinWriter to generate XML).

Object creation

To create an XML::MinWriter object, the following syntax is used:

  my $wrt = XML::MinWriter->new(OUTPUT => $fh, LINE_MODE => 1, DATA_INDENT => 2);

One or more of the following options can be used (those options are largely compatible with XML::Writer):

option OUTPUT =>

Option OUTPUT => $fh determines that the XML is written to filehandle $fh, the default is OUTPUT => \*STDOUT.

option LINE_MODE =>

The option LINE_MODE => 0|1 is a true or false value; if this parameter is present and its value is true (1), then XML::MinWriter will enter a special line mode, inserting newlines automatically around elements. The default is LINE_MODE => 0.

option DATA_MODE =>

The option DATA_MODE => 0|1 is a true or false value; if this parameter is present and its value is true (1), then XML::MinWriter will enter a special Data mode, to be compatible with XML::Writer. The default is DATA_MODE => 0.

option DATA_INDENT =>

Represents the indent step for elements in data mode (it will be ignored when not in data mode). The default is DATA_INDENT => 0.

option NEWLINES =>

The option NEWLINES => 0|1 is a true or false value; if this parameter is present and its value is true (1), then XML::MinWriter 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 false (0), then the module will not insert the newlines. The default is NEWLINES => 0.

option APOS =>

Determines whether apostrophes or quotes are used to write attribute values. APOS => 1 uses apostrophes, APOS => 0 uses quotes. The default is APOS => 0. For example, with APOS => 0, attributes are written with quotes as follows:

  <test attr1="t1" attr2="t2">

With APOS => 1, attributes are written with apostrophes as follows:

  <test attr1='t1' attr2='t2'>

Methods

The following methods are compatible with XML::Writer:

startTag ($name [, $aname1 => $value1, ...])

The startTag() method creates a start tag in the XML output. Given the following call:

  $wrt->startTag('st', attr1 => 'v1', attr2 => 'v2');

then the following tag will be written to the XML output file:

  <st attr1="v1" attr2="v2">

Of course, the attributes (attr1 => 'v1', attr2 => 'v2') are optional, so a call to startTag() with a simple argument:

  $wrt->startTag('st');

produces the following tag in the XML output file:

  <st>
characters ($data)

The characters() method simply writes the text to the XML output file, with the additional transformation of the special characters '<', '>' and '&'. For example, the following call:

  $wrt->characters('abc < > & def');

produces the following XML output:

  abc &lt; &gt; &amp; def
endTag ($name)

The endTag() method creates an end tag in the XML output. Given the following call:

  $wrt->endTag('st');

then the following tag will be written to the XML output file:

  </st>
dataElement ($name, $data [, $aname1 => $value1, ...])

The dataElement() method prints an entire element containing only character data. The following call:

  $wrt->dataElement('item', 'text123', attr1 => 'v1', attr2 => 'v2');

is equivalent to the following sequence:

  $wrt->startTag('item', attr1 => 'v1', attr2 => 'v2');
  $wrt->characters('text123');
  $wrt->endTag('item');

and produces the following XML output:

  <item attr1="v1" attr2="v2">
    text123
  </item>
emptyTag ($name [, $aname1 => $value1, ...])

The emptyTag() method creates an empty tag in the XML output. Given the following call:

  $wrt->emptyTag('st', attr1 => 'v1', attr2 => 'v2');

then the following tag will be written to the XML output file:

  <st attr1="v1" attr2="v2" />

Of course, the attributes (attr1 => 'v1', attr2 => 'v2') are optional, so a call to emptyTag() with a simple argument:

  $wrt->emptyTag('st');

produces the following tag in the XML output file:

  <st />
doctype ($name, [$publicId, $systemId])

The doctype() method adds a DOCTYPE declaration to an XML document. For example, the following call:

  $wrt->doctype('delta', 'p1', 's1');

produces the following XML output:

  <!DOCTYPE delta PUBLIC "p1" "s1">

You can also pass $publicId = undef to emit $systemId only:

  $wrt->doctype('delta', undef, 's1');

That produces the following XML output:

  <!DOCTYPE delta SYSTEM "s1">

Or you can leave out $publicId and $systemId alltogether:

  $wrt->doctype('delta');

That produces the following XML output:

  <!DOCTYPE delta>
comment ($text)

The comment() method adds a comment to the XML output. The following call:

  $wrt->comment('This is a comment');

will produce the following XML output:

  <!-- This is a comment -->
pi ($target [, $data])

The pi() method adds a processing instruction to an XML document. The following call:

  $wrt->pi('xml-stylesheet', 'href="style.css" type="text/css"');

will produce the following XML output:

  <?xml-stylesheet href="style.css" type="text/css"?>
end ()

The end() method terminates writing to the XML output. It should be the last call before closing the XML output file.

There are two new methods that are not compatible with XML::Writer:

procInst ($name [, $aname1 => $value1, ...])

The procInst() method adds a processing instruction to an XML document. It is very similar to the pi() method, however, the parameters are passed differently. The following call:

  $wrt->procInst('xml-stylesheet', href => 'style.css', type => 'text/css');

will produce the following XML output:

  <?xml-stylesheet href="style.css" type="text/css"?>
write_pyx ($pyx_data)

The write_pyx() method writes the XML for the given PYX data.

Pyx

Pyx is a line-oriented text format to represent XML. The first character of a line in Pyx represents the type. This first character type can be:

  '(' => a Start tag,          '(item'         translates into '<item>'
  ')' => an End  tag,          ')item'         translates into '</item>'
  '-' => Character data,       '-data'         translates into 'data'
  'A' => Attributes,           'Aattr v1'      translates into '<... attr="v1">'
  '?' => Process Instructions, '?xml dat="p1"' translates into '<?xml dat="p1"?>'
  '#' => Comments,             '#remark'       translates into '<!-- remark -->'

EXAMPLES

Example using Pyx

For example the following PYX code:

  use XML::MinWriter;

  open my $fh, '>', \my $xml or die $!;
  my $wrt = XML::MinWriter->new(OUTPUT => $fh, LINE_MODE => 1, DATA_INDENT => 2);

  $wrt->write_pyx('?xml version="1.0" encoding="iso-8859-1"');
  $wrt->write_pyx('(data');
  $wrt->write_pyx('(item');
  $wrt->write_pyx('Aattr1 p1');
  $wrt->write_pyx('Aattr2 p2');
  $wrt->write_pyx('-line');
  $wrt->write_pyx(')item');
  $wrt->write_pyx('(level');
  $wrt->write_pyx('#remark');
  $wrt->write_pyx(')level');
  $wrt->write_pyx(')data');

  $wrt->end;
  close $fh;

  print "The XML generated is as follows:\n\n";
  print $xml, "\n";

...generates the following XML:

  <?xml version="1.0" encoding="iso-8859-1"?>
  <data>
    <item attr1="p1" attr2="p2">
      line
    </item>
    <level>
      <!-- remark -->
    </level>
  </data>

Example using XML::Reader

A sample code fragment that uses XML::Reader together with XML::MinWriter:

  use XML::Reader;
  use XML::MinWriter;

  my $line = q{
  <data>
    <order>
      <database>
        <customer name="aaa" >one</customer>
        <customer name="bbb" >two</customer>
        <other>iuertyieruyt</other>
        <customer name="ccc" >three</customer>
        <customer name="ddd" >four</customer>
      </database>
    </order>
  </data>
  };

  my $rdr = XML::Reader->new(\$line, {
              using => '/data/order/database/customer',
              mode  => 'pyx',
            });

  open my $fh, '>', \my $xml or die "Error-0010: Can't open > xml because $!";
  my $wrt = XML::MinWriter->new(OUTPUT => $fh, DATA_MODE => 1, DATA_INDENT => 2);

  $wrt->xmlDecl('iso-8859-1');
  $wrt->doctype('delta', 'public', 'system');
  $wrt->startTag('delta');

  while ($rdr->iterate) {
      $wrt->write_pyx($rdr->pyx);
  }

  $wrt->endTag('delta');
  $wrt->end;

  close $fh;

  print $xml, "\n";

This is the resulting XML:

  <?xml version="1.0" encoding="iso-8859-1"?>
  <!DOCTYPE delta PUBLIC "public" "system">
  <delta>
    <customer name="aaa">one</customer>
    <customer name="bbb">two</customer>
    <customer name="ccc">three</customer>
    <customer name="ddd">four</customer>
  </delta>

AUTHOR

Klaus Eichner, October 2011

COPYRIGHT AND LICENSE

Copyright (C) 2011 by Klaus Eichner

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

SEE ALSO

XML::TiePYX, XML::Reader, XML::Writer.