NAME

XML::Flow - Store (restore) perl data structures in XML stream.

SYNOPSIS

  #read - write by imported functions ref2xml() and  xml2ref()
  use XML::Flow qw( ref2xml xml2ref);
  my $data = {1=>2,4=>[1,2,3]};
  my $xml_string = ref2xml($data);
  my $data_restored = xml2ref($xml_string);
  my $ref1 = xml2ref(\*DATA); #from embedded __DATA__

  #Write XML
  use XML::Flow;
  my $wr = new XML::Flow:: "test.xml";
  $wr->startTag("Root"); #start root tag
  $wr->startTag("Data");
  $wr->write({1=>2},[4..6]);
  $wr->closeTag("Data");
  $wr->closeTag("Root");
  $wr->close;


  #Read
  my $fs = new IO::File:: "<test.xml";
  my $rd = new XML::Flow:: $fs;
  my %tags = (
       Root=>undef,
       Data=>sub { print Dumper(\@_) },
       );
  $rd->read(\%tags);
  $fs->close;

DESCRIPTION

Easy store and restore perl data structures. It use XML::Parser for read and XML::Writer for write xml.

FUNCTIONS

ref2xml( $ref )

Serilize reference to XML string. Where $ref is reference to SCALAR, HASH or ARRAY. This function will return XML string.

    use XML::Flow qw( ref2xml xml2ref);
    my $test = {1=>2,4=>[1,2,3]};
    print ref2xml($test);

The above example would print out the message:

    <?xml version="1.0" encoding="UTF-8"?>
    <XML-FLow-Data>
      <flow_data_struct>
        <value type="hashref">
          <key name="4">
            <value type="arrayref">
              <key name="1">2</key>
              <key name="0">1</key>
              <key name="2">3</key>
            </value>
          </key>
          <key name="1">2</key>
        </value>
      </flow_data_struct>
    </XML-FLow-Data>

xml2ref($string || reference to GLOB)

This function will deserilize string generated by ref2xml.Return reference. For example:

    use XML::Flow qw( ref2xml xml2ref);
    use Data::Dumper;
    my $testxml = q{<?xml version="1.0" encoding="UTF-8"?>
    <XML-FLow-Data>
      <flow_data_struct>
        <value type="hashref">
          <key name="4">
            <value type="arrayref">
              <key name="1">2</key>
              <key name="0">1</key>
              <key name="2">3</key>
            </value>
          </key>
          <key name="1">2</key>
        </value>
      </flow_data_struct>
    </XML-FLow-Data>};
    print Dumper(xml2ref($testxml))

will print:

    $VAR1 = {
          '1' => '2',
          '4' => [
                 '1',
                 '2',
                 '3'
               ]
        };

METHODS

new($filehandle|$filename| a reference to a text string )

Create a new XML::Flow object. The first parameter should either be a string containing filename, a reference to a text string or it should be an open IO::Handle. For example:

 my $wr = new XML::Flow:: "test.xml";

 my $rd = new XML::Flow:: \$string_with_xml;

 my $fs = new IO::File:: "<test.xml";
 my $rd = new XML::Flow:: $fs;

 my $fz = IO::Zlib->new($file, "wb9");
 my $wr = new XML::Flow:: $fz;

 my $string_for_write_xml;
 my $wr = new XML::Flow:: \$string_buffer_for_write_xml;

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

Add a start tag to an XML document. This method is wraper for XML::Writer::startTag.

endTag([$name])

Add a end tag to an XML document. This method is wraper for XML::Writer::endTag.

write($ref1[, $ref2, ...])

Serilize references to XML. Where $ref is reference to SCALAR, HASH or ARRAY. This method used only for write XML mode.

 $wr->write({1=>2},[4..6]);
 my $a="1";
 $wr->write(\$a);

read({tag1=>sub1{}[, tag2=>\&sub2 })

Run XML parser. Argument is a reference to hash with tag => handler. If handler eq undef, then tag ignore. If subroutine return non undef result, it passed to parent tag handler. Handler called with args: ( {hash of attributes}, <reference to data> [,<reference to data>] ). For example:

Source xml :

 <?xml version="1.0" encoding="UTF-8"?>
 <Root>
  <Obj>
    <Also>
      <flow_data_struct>
        <value type="scalarref">
          <key name="scalar">3</key>
        </value>
      </flow_data_struct>
      <flow_data_struct>
        <value type="hashref">
          <key name="1" value="undef"></key>
        </value>
      </flow_data_struct>
    </Also>
  </Obj>
 </Root>

Read code:

 my $rd = new XML::Flow:: "test.xml";
 my %tags = (
    Root=>undef,
    Obj=>sub { print Dumper(\@_) },
    Also=>sub { 
        shift; #reference to hash of attributes
        return @_},
    );
 $rd->read(\%tags);
 $rd->close;

Output:

 $VAR1 = [
          {}, #reference to hash of xml tag attributes
          \'3',
          {
            '1' => undef
          }
        ];

close()

Close all handlers (including internal).

AUTHOR

Zahatski Aliaksandr, <zag@cpan.org>

COPYRIGHT AND LICENSE

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.8 or, at your option, any later version of Perl 5 you may have available.