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.

        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::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 [,$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::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 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::NDS::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::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 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::NDS::Multifile;
                $obj = new Data::NDS::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)

