NAME

Lab::XMLtree - Handle and store XML and perl data structures with precise declaration.

SYNOPSIS

 use Lab::XMLtree;
 
 my $data_declaration = {
     info                     => [#              type B
         'SCALAR',
         {
             basename    => ['PSCALAR'],#        type A
             title       => ['SCALAR'],#         type A
             place       => ['SCALAR']#          type A
         }
     ],
     column                  => [#               type K
         'ARRAY',
         'id',
         {
             # PSCALAR means that this element will not
             # be saved. Does not work for YAML yet.
             min         => ['PSCALAR'],#        type A
             max         => ['PSCALAR'],#        type A
             description => ['SCALAR']#          type A
         }
     ],
     axis                    => [#               type F
         'HASH',
         'label',
         {
             unit        => ['SCALAR'],#         type A
             logscale    => ['SCALAR'],#         type A
             description => ['SCALAR']#          type A
         }
     ]
 };
 #create Lab::XMLtree object from file
 $data=Lab::XMLtree->read_xml($data_declaration,'filename.xml');

 #the autoloader
 # get
 print $data->info_title;
 # get with $id
 print $data->column_description($id);
 # set with $key and $value
 $data->axis_description($label,'descriptiontext');

 #save data as YAML
 $data->save_yaml('filename.yaml');

DESCRIPTION

Lab::XMLtree will take you to similar spots as XML::Simple does, but in a bigger bus and with fewer wild animals.

That's not a bad thing. You get more control of the data transformation processes and you get some extra functionality.

DATA DECLARATION

Lab::XMLtree uses a data declaration, that describes, what the perl data structure looks like, and how this data structure is converted to XML.

Necessary information for each element

1) taucht es einmal oder mehrmals aus?
   a) nur einmal
   b) mehrmals
      wie soll dieses mehrmals auftauchende
      element gespeichert werden?
       i) speichern in hash (welcher key?)
      ii) speichern in array (welche id?)

2) gibt es unterelemente oder nur skalaren content?
   (system erlaubt keinen mixed content)
   a) skalar
   b) children existieren

Simple ansatz: Each element is represented by name=>$value with (ref $value eq 'ARRAY')

@$value=(
    # mandatory
    SCALAR|HASH|ARRAY|PSCALAR|PHASH|PARRAY
    
    # optional for hash, array. not used for scalar.
    [,$key|$id]
    
    # optional.
    # otherwise scalar content
    # (don't mix up with scalar|array|hash above)
    [,{children}]
)

Possible combinations

(A) SCALAR
(B) SCALAR,{children}
(C) HASH                    should work. autonumbers as keys.
(D) HASH,{children}         same
(E) HASH,$key
(F) HASH,$key,{children}
(G) ARRAY                   should work.
(H) ARRAY,{children}        same.
(I) ARRAY,$id
(K) ARRAY,$id,{children}

The first two elements define the folding behaviour.

SCALAR|PSCALAR

Element occurs zero or one time. No folding necessary.

Examples:

$data->{dataset_title}='content';

ARRAY|PARRAY

Element occurs zero or more times. Folding will be done using an array reference. If $id is given, this XML element will be used as an id.

Example:

$data->{column}->[4]->{label}='testlabel';

HASH|PHASH

Element occurs zero or more times. Folding will be done using a hash reference. If $key is given, this XML element will be used as a key.

Example:

$data->{axis}->{gate voltage}->{unit}="mV";

CONSTRUCTORS

new($declaration,[$data])

Create a new Lab::XMLtree. $data must be hashref and should match the declaration. Returns Lab::XMLtree object.

read_xml($declaration,$filename)

Opens a XML file $filename. Returns Lab::XMLtree object.

read_yaml($declaration,$filename)

Opens a YAML file $filename. Returns Lab::XMLtree object.

METHODS

merge_tree($tree)

Merge another Lab::XMLtree into this one. Other tree must not necessarily be blessed.

save_xml($filename)

Saves the tree as XML to $filename.

save_yaml($filename)

Saves the tree as YAML to $filename. PSCALAR etc. don't work yet.

to_string()

Returns a stringified version of the object. (Using Data::Dumper.)

autoload

Get/set anything you want. Accounts the data declaration.

PRIVATE FUNCTIONS

_load_xml($declaration,$filename)

_merge_node_lists($declaration,$destination_perlnode_list,$source_perlnode_list)

_parse_domnode_list($domnode_list,$defnode_list)

_write_node_list($generator,$defnode_list,$perlnode_list)

_getset_node_list_from_string($perlnode_list,$defnode_list,$nodes_string)

_get_defnode_type($defnode)

_magic_keys($defnode_list,$perlnode_list,$node_name,[@types])

_magic_get_perlnode($defnode_list,$perlnode_list,$node_name,$key,[@types])

_magic_set_perlnode($defnode_list,$perlnode_list,$node_name,$key,$value,[@types])

CAVEATS/BUGS

Lab::XMLtree does not support all possible kinds of perl data structures. It is also not too flexible when it comes to XML. It simply supports something that I needed.

SEE ALSO

XML::Simple

Lab::XMLtree is similar to XML::Simple (XML::Simple).

XML::DOM

Lab::XMLtree can use XML::DOM (XML::DOM) to retrieve stored data.

XML::Generator

Lab::XMLtree can use XML::Generator (XML::Generator) to store data as XML.

YAML

Lab::XMLtree can use YAML (YAML) for data storage.

AUTHOR/COPYRIGHT

This is $Id: XMLtree.pm 464 2006-07-16 01:12:23Z schroeer $

Copyright 2004 Daniel Schröer (http://www.danielschroeer.de)

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

cpanm Lab::Measurement

perl -MCPAN -e shell
install Lab::Measurement