/ 
Data-Nested-3.12
River stage zero No dependents
/ Data::Nested::Multifile

NAME

Data::Nested::Multifile - A multi-file version of Data::Nested::Multiele

SYNOPSIS

use Data::Nested::Multifile;

DESCRIPTION

This module is an extension to the Data::Nested::Multiele module, and an understanding of that module is assumed in this documentation.

The Data::Nested::Multiele module accesses a set of data elements in a single data source. This module adds the ability to treat a set of data elements from multiple files as one set of elements.

There are some limitations to this functionality that are not present in the Data::Nested::Multiele module:

Ordered lists are not supported

Separating ordered elements across files makes several operations difficult, so this is currently not supported. Only unordered lists are used.

Default elements only apply to the file

A default element in one file ONLY applies to data elements in that file. If the same default is required in other files, the data element must be added to each file.

All files must be identical in many ways

All will use the same Data::Nested object, so they will have identical structural characteristics. All files must contain hashes OR list, not a mixture of the two.

All elements must be unique

For hash files, the same element may not appear in multiple files.

Default elements must be unique

Since every element must be unique, the same name may not be used for default elements in two different files. If there is a default element in one file named _default, an element of the same name may not exist in a second file.

List element indexes differ

Since multiple files are read in, the index of list elements is the index in the combined list of elements with all of the elements from all files.

METHODS

new
file

A new Data::Nested::Multifile object can be created and assigned to data sources using these methods. In order to create a new object and bind it to two different files, use the following calls:

$obj = new Data::Nested::Multifile [NDS];
$obj->file(LABEL1,FILE1);
$obj->file(LABEL2,FILE2);

or an equivalent one call method:

$obj = new Data::Nested::Multifile [NDS,] LABEL1, FILE1, LABEL2, FILE2;

A Data::Nested object is needed. If one is passed in as an argument to the new method, it is used. By creating an NDS, and then passing it in to the new method, the same NDS can be used for multiple Data::Nested::Multiele/Data::Nested::Multifile objects, each reading elements independent of each other. In this way, all structural information in the NDS applies to all elements use by all of the objects.

If no Data::Nested object is passed in, one is created.

Creating two Data::Nested::Multifile objects which use the same NDS can be done in the following way:

$NDS  = new Data::Nested;
$obj1 = new Data::Nested::Multifile $NDS [LABEL1a, FILE1a, ...];
$obj2 = new Data::Nested::Multifile $NDS [LABEL2a, FILE2a, ...];

The same effect can be achieved with:

$obj1 = new Data::Nested::Multifile [LABEL1a, FILE1a, ...];
$obj2 = $obj1->new([LABEL2a, FILE2a, ...]);

If no file is passed in to the new method, you need to use the file method to set it and read the data.

One note about labels: they should not be strictly numeric since there are times when that may conflict with numeric element indices in data consisting of lists. Add any non-digit character to them to avoid this problem.

All file calls must be done immediately after the object is created, and before any other operations (including default_element oeprations).

nme
$NME = $obj->nme(LABEL);

This returns the Data::Nested::Multiele object associated with a label.

ele_file
$label = $obj->ele_file($ele);

Returns the label for the file that $ele belongs to. Returns nothing if the element does not exist.

default_element
$obj->default_element($label [,$ruleset] [,$path,$val,...]);
$obj->default_element($ele   [,$ruleset] [,$path,$val,...]);

This is used to declare that one of the elements that was read in from one of the data file is used to provide defaults for other elements in that same data file.

If the data files contains lists of elements, the first form is used ($label must be passed in as the first argument). The first element from the given file is used as a default.

If the data files contain hashes of elements, the second form is used ($ele is passed in as the first argument). The named element (in whichever file it occurs) is used as a default. It should be noted that default elements must be uniquely named in a Multifile object.

The default_element methods must be done immediately after the file methods, and before any other operations.

rename_ele
$obj->rename_ele($ele,$newele);

This is identical to the function in Data::Nested::Multiele. The only thing to note is that the renamed element will remain in the same file. The only way to move an element from one file to another is to first delete it, and then add it in the new file.

The rename_ele method is not applicable to a file containing a list of elements since the order of the elements is not currently used, and ordered lists are not supported.

add_ele
$obj->add_ele([$label,] [$ele,] $nds [,$new]);

This adds a new element to a file. The new element is checked for validity, and then added. Note that the element is not actually stored in the data file. Use the save method to do that.

Because the NDS does not have defaults applied, the new element may have additional data present once defaults are applied.

The location (and file) where the new element is added depends on several things.

If the data files contain lists, there are three different ways to call this:

$obj->add_ele([$label,] $nds [,$new]);

This adds the element to the end of the given file, or the last data file if $label is not included.

$obj->add_ele($ele,$nds [,$new]);

This inserts the new element at $ele (which must refer to an existing element) in the same data file as $ele.

If the data file contains a hash, there is only one way to call it:

$obj->add_ele([$label,] $ele,$nds [,$new]);

If $label is not given, it is inserted into the last data file. Otherwise, it is inserted into the file specifed by $label.

copy_ele
$obj->copy_ele($ele [,$label] [,$newele]);

This will create a new element which is a copy of another element. The new element is created in the same way as the add_ele method based on the value of $newele and the type of data.

If $label is not given, it defaults to the same file as the original element.

version
nds
err
errmsg
eles
ele
which
path_valid
value
keys
values
path_values
path_in_use
delete_ele
update_ele
is_default_value
dump
save

These work the same as in the Data::Nested::Multiele module and are fully documented in that module.

Any method not documented here, especially those beginning with an underscore (_), are for internal use only. Please do not use them. Absolutely no support is offered for them.

ERROR CODES

Each error code produced by a method in the Data::Nested::Multifile module is prefixed by the characters "nmf", followed by a 3 character operation code which tells what type of operation failed, followed by 2 digits.

The following error codes are used to identify problems working with files containing data:

nmffil01   An even number of arguments required to
           specify files.
nmffil02   An attempt to reuse a file label already in use.
nmffil03   An error occurred reading the data file.
nmffil04   All files must contain the same type of data (list
           or hash).
nmffil05   A data element is duplicated in 2 files.
nmffil06   An invalid file label was used.
nmffil07   An attempt to read in a file after element
           operations have been done.
nmffil08   No file has been set.
nmffil09   Defaults must be set immediately after the files
           are read in.

The following error codes identify problems accessing an element:

nmfele01   Attempt to access an undefined element.
nmfele02   Attempt to overwrite an existing element.
nmfele03   When accessing a hash element, a name must be given.
nmfele04   When adding an element, a name must be given.

BUGS AND QUESTIONS

If you find a bug in this module, please send it directly to me (see the AUTHOR section below). Alternately, you can submit it on CPAN. This can be done at the following URL:

http://rt.cpan.org/Public/Dist/Display.html?Name=Data-NDS-Multifile

Please do not use other means to report bugs (such as usenet newsgroups, or forums for a specific OS or linux distribution) as it is impossible for me to keep up with all of them.

When filing a bug report, please include the following information:

  • The version of the module you are using. You can get this by using the script:

    use Data::Nested::Multifile;
$obj = new Data::Nested::Multifile;
print $obj->version(),"\n";

  • The output from "perl -V"

If you have a problem using the module that perhaps isn't a bug (can't figure out the syntax, etc.), you're in the right place. Go right back to the top of this manual and start reading. If this still doesn't answer your question, mail me directly.

KNOWN PROBLEMS

None at this point.

LICENSE

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

AUTHOR

Sullivan Beck (sbeck@cpan.org)