/* 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, version 2, as published by the Free Software Foundation.

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, write to the Free Software Foundation, Inc.,
51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. */

/** 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 tango.scrapple.text.convert.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);
}