/* LICENSE BLOCK
Part of mde: a Modular D game-oriented Engine
Copyright © 2007-2008 Diggory Hardy

This program is free software: you can redistribute it and/or modify it under the terms
of the GNU General Public License as published by the Free Software Foundation, either
version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY;
without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program.  If not, see <http://www.gnu.org/licenses/>. */

/** This module contains the interface IDataSection used by DataSet.
*
* It has been given its own module to avoid cyclic dependancies and separate out the functionality
* of mergetag.
*
* Also some base mergetag symbols have been moved here.
*/
module mde.mergetag.iface.IDataSection;

/** Typedef for data & section indexes.
*
* Make it an alias, there doesn't appear to be any point having it as a typedef. */
alias char[] ID;

/**
 * Interface for data storage classes, generally called DataSections, which contain all data-tags
 * loaded from a single section of a file.
 *
 * A class implementing this may implement the addTag function to do whatever it likes with the
 * data passed. DefaultData is one implementation which separates this data out into supported
 * types and stores it appropriately (allowing merging with existing entries by keeping whichever
 * tag was last loaded), while ignoring unsupported types. A different
 * implementation could filter out the tags desired and use them directly, and ignore the rest.
 *
 * The mde.mergetag.parse.parseTo module provides a useful set of templated functions to
 * convert the data accordingly. It is advised to keep the type definitions as defined in the file-
 * format except for user-defined types, although this isn't necessary for library operation
 * (addTag and writeAll are solely responsible for using and setting the type, ID and data fields).
 *
 * Another idea for a DataSection class:
 * Use a void*[ID] variable to store all data (may also need a type var for each item).
 * addTag should call a templated function which calls parse then casts to a void* and stores the data.
 * Use a templated get(T)(ID) method which checks the type and casts to T.
 */
interface IDataSection
{
    /** Delegate passed to writeAll. */
    typedef void delegate (char[],ID,char[]) ItemDelg;
    
    /** Handles parsing of data items for all recognised types.
     *
     * Should ignore unsupported types/unwanted tags.
     *
     * TextExceptions (thrown by parseTo/parseFrom) are caught and a warning logged; execution
     * then continues (so the offending tag gets dropped). */
    void addTag (char[],ID,char[]);
    
    /** Responsible for getting all data tags saved.
    *
    * writeAll should call the ItemDelg once for each tag to be saved with parameters in the same
    * form as received by addTag (char[] type, ID id, char[] data). */
    void writeAll (ItemDelg);
}