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

or

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

or

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

or

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

or

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).

SEE ALSO

XML::Parser, XML::Writer

AUTHOR

Zahatski Aliaksandr, <zag@cpan.org>

COPYRIGHT AND LICENSE

Copyright (C) 2006-2010 by Zahatski Aliaksandr

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.