/ 
Data-NDS-Multifile-3.00
/ Data::NDS::Multifile

NAME

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

SYNOPSIS

use Data::NDS::Multifile;

DESCRIPTION

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

The Data::NDS::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::NDS::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::NDS 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::NDS::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::NDS::Multifile [NDS];
$obj->file(LABEL1,FILE1);
$obj->file(LABEL2,FILE2);

or an equivalent one call method:

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

A Data::NDS 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::NDS::Multiele/Data::NDS::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::NDS object is passed in, one is created.

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

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

The same effect can be achieved with:

$obj1 = new Data::NDS::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.

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

This returns the Data::NDS::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,] [$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, $label must be passed in, but $ele is NOT passed in.

If the data files contain hashes of elements, $ele is passed in, but $label is NOT passed in.

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

This is identical to the function in Data::NDS::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 the list. 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($nds [,$new]);

This adds the element to the end of the last data file.

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

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

This inserts the element at the end of the list contained in the given file label.

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 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
delete_ele
update_ele
is_default_value
dump
save

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

ERROR CODES

Each error code produced by a method in the Data::NDS::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 arguements 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.

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.

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)