/** @mainpage

    <table>
        <tr><th>Library     <td>SimpleIni
        <tr><th>File        <td>SimpleIni.h
        <tr><th>Author      <td>Brodie Thiesfield [code at jellycan dot com]
        <tr><th>Source      <td>http://code.jellycan.com/simpleini/
        <tr><th>Version     <td>4.5
    </table>

    Jump to the @link CSimpleIniTempl CSimpleIni @endlink interface documentation.

    @section intro INTRODUCTION

    This component allows an INI-style configuration file to be used on both
    Windows and Linux/Unix. It is fast, simple and source code using this
    component will compile unchanged on either OS.


    @section features FEATURES

    - MIT Licence allows free use in all software (including GPL and commercial)
    - multi-platform (Windows 95/98/ME/NT/2K/XP/2003, Windows CE, Linux, Unix)
    - loading and saving of INI-style configuration files
    - configuration files can have any newline format on all platforms
    - liberal acceptance of file format
        - key/values with no section
        - removal of whitespace around sections, keys and values
    - support for multi-line values (values with embedded newline characters)
    - optional support for multiple keys with the same name
    - optional case-insensitive sections and keys (for ASCII characters only)
    - saves files with sections and keys in the same order as they were loaded
    - preserves comments on the file, section and keys where possible.
    - supports both char or wchar_t programming interfaces
    - supports both MBCS (system locale) and UTF-8 file encodings
    - system locale does not need to be UTF-8 on Linux/Unix to load UTF-8 file
    - support for non-ASCII characters in section, keys, values and comments
    - support for non-standard character types or file encodings
      via user-written converter classes
    - support for adding/modifying values programmatically
    - compiles cleanly in the following compilers:
        - Windows/VC6 (warning level 3)
        - Windows/VC.NET 2003 (warning level 4)
        - Windows/VC 2005 (warning level 4)
        - Linux/gcc (-Wall)


    @section usage USAGE SUMMARY

    -#  Define the appropriate symbol for the converter you wish to use and
        include the SimpleIni.h header file. If no specific converter is defined
        then the default converter is used. The default conversion mode uses
        SI_CONVERT_WIN32 on Windows and SI_CONVERT_GENERIC on all other
        platforms. If you are using ICU then SI_CONVERT_ICU is supported on all
        platforms.
    -#  Declare an instance the appropriate class. Note that the following
        definitions are just shortcuts for commonly used types. Other types
        (PRUnichar, unsigned short, unsigned char) are also possible.
        <table>
            <tr><th>Interface   <th>Case-sensitive  <th>Load UTF-8  <th>Load MBCS   <th>Typedef
        <tr><th>SI_CONVERT_GENERIC
            <tr><td>char        <td>No              <td>Yes         <td>Yes #1      <td>CSimpleIniA
            <tr><td>char        <td>Yes             <td>Yes         <td>Yes         <td>CSimpleIniCaseA
            <tr><td>wchar_t     <td>No              <td>Yes         <td>Yes         <td>CSimpleIniW
            <tr><td>wchar_t     <td>Yes             <td>Yes         <td>Yes         <td>CSimpleIniCaseW
        <tr><th>SI_CONVERT_WIN32
            <tr><td>char        <td>No              <td>No #2       <td>Yes         <td>CSimpleIniA
            <tr><td>char        <td>Yes             <td>Yes         <td>Yes         <td>CSimpleIniCaseA
            <tr><td>wchar_t     <td>No              <td>Yes         <td>Yes         <td>CSimpleIniW
            <tr><td>wchar_t     <td>Yes             <td>Yes         <td>Yes         <td>CSimpleIniCaseW
        <tr><th>SI_CONVERT_ICU
            <tr><td>char        <td>No              <td>Yes         <td>Yes         <td>CSimpleIniA
            <tr><td>char        <td>Yes             <td>Yes         <td>Yes         <td>CSimpleIniCaseA
            <tr><td>UChar       <td>No              <td>Yes         <td>Yes         <td>CSimpleIniW
            <tr><td>UChar       <td>Yes             <td>Yes         <td>Yes         <td>CSimpleIniCaseW
        </table>
        #1  On Windows you are better to use CSimpleIniA with SI_CONVERT_WIN32.<br>
        #2  Only affects Windows. On Windows this uses MBCS functions and
            so may fold case incorrectly leading to uncertain results.
    -# Call Load() or LoadFile() to load and parse the INI configuration file
    -# Access and modify the data of the file using the following functions
        <table>
            <tr><td>GetAllSections  <td>Return all section names
            <tr><td>GetAllKeys      <td>Return all key names within a section
            <tr><td>GetAllValues    <td>Return all values within a section & key
            <tr><td>GetSection      <td>Return all key names and values in a section
            <tr><td>GetSectionSize  <td>Return the number of keys in a section
            <tr><td>GetValue        <td>Return a value for a section & key
            <tr><td>SetValue        <td>Add or update a value for a section & key
            <tr><td>Delete          <td>Remove a section, or a key from a section
        </table>
    -# Call Save() or SaveFile() to save the INI configuration data

    @section iostreams IO STREAMS

    SimpleIni supports reading from and writing to STL IO streams. Enable this
    by defining SI_SUPPORT_IOSTREAMS before including the SimpleIni.h header
    file. Ensure that if the streams are backed by a file (e.g. ifstream or
    ofstream) then the flag ios_base::binary has been used when the file was
    opened.

    @section multiline MULTI-LINE VALUES

    Values that span multiple lines are created using the following format.

        <pre>
        key = <<<ENDTAG
        .... multiline value ....
        ENDTAG
        </pre>

    Note the following:
    - The text used for ENDTAG can be anything and is used to find
      where the multi-line text ends.
    - The newline after ENDTAG in the start tag, and the newline
      before ENDTAG in the end tag is not included in the data value.
    - The ending tag must be on it's own line with no whitespace before
      or after it.
    - The multi-line value is modified at load so that each line in the value
      is delimited by a single '\\n' character on all platforms. At save time
      it will be converted into the newline format used by the current
      platform.

    @section comments COMMENTS

    Comments are preserved in the file within the following restrictions:
    - Every file may have a single "file comment". It must start with the
      first character in the file, and will end with the first non-comment
      line in the file.
    - Every section may have a single "section comment". It will start
      with the first comment line following the file comment, or the last
      data entry. It ends at the beginning of the section.
    - Every key may have a single "key comment". This comment will start
      with the first comment line following the section start, or the file
      comment if there is no section name.
    - MultiKey entries may have only a single comment and will take the
      comment associated with the first key found.
    - Comments are set at the time that the file, section or key is first
      created. The only way to modify a comment on a section or a key is to
      delete that entry and recreate it with the new comment. There is no
      way to change the file comment.

    @section save SAVE ORDER

    The sections and keys are written out in the same order as they were
    read in from the file. Sections and keys added to the data after the
    file has been loaded will be added to the end of the file when it is
    written. There is no way to specify the location of a section or key
    other than in first-created, first-saved order.

    @section notes NOTES

    - To load UTF-8 data on Windows 95, you need to use Microsoft Layer for
      Unicode, or SI_CONVERT_GENERIC, or SI_CONVERT_ICU.
    - When using SI_CONVERT_GENERIC, ConvertUTF.c must be compiled and linked.
    - When using SI_CONVERT_ICU, ICU header files must be on the include
      path and icuuc.lib must be linked in.
    - To load a UTF-8 file on Windows AND expose it with SI_CHAR == char,
      you should use SI_CONVERT_GENERIC.
    - The collation (sorting) order used for sections and keys returned from
      iterators is NOT DEFINED. If collation order of the text is important
      then it should be done yourself by either supplying a replacement
      SI_STRLESS class, or by sorting the strings external to this library.
    - Usage of the <mbstring.h> header on Windows can be disabled by defining
      SI_NO_MBCS. This is defined automatically on Windows CE platforms.


    @section licence MIT LICENCE

    The licence text below is the boilerplate "MIT Licence" used from:
    http://www.opensource.org/licenses/mit-license.php

    Copyright (c) 2006, Brodie Thiesfield

    Permission is hereby granted, free of charge, to any person obtaining a copy
    of this software and associated documentation files (the "Software"), to deal
    in the Software without restriction, including without limitation the rights
    to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
    copies of the Software, and to permit persons to whom the Software is furnished
    to do so, subject to the following conditions:

    The above copyright notice and this permission notice shall be included in
    all copies or substantial portions of the Software.

    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
    IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
    FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
    COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
    IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
    CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
*/

#ifndef INCLUDED_SimpleIni_h
#define INCLUDED_SimpleIni_h

#if defined(_MSC_VER) && (_MSC_VER >= 1020)
# pragma once
#endif

// Disable these warnings in MSVC:
//  4127 "conditional expression is constant" as the conversion classes trigger
//  it with the statement if (sizeof(SI_CHAR) == sizeof(char)). This test will
//  be optimized away in a release build.
//  4503 'insert' : decorated name length exceeded, name was truncated
//  4702 "unreachable code" as the MS STL header causes it in release mode.
//  Again, the code causing the warning will be cleaned up by the compiler.
//  4786 "identifier truncated to 256 characters" as this is thrown hundreds
//  of times VC6 as soon as STL is used.
#ifdef _MSC_VER
# pragma warning (push)
# pragma warning (disable: 4127 4503 4702 4786)
#endif

#include <string>
#include <map>
#include <list>
#include <algorithm>
#include <stdio.h>

#ifdef SI_SUPPORT_IOSTREAMS
# include <iostream>
#endif // SI_SUPPORT_IOSTREAMS

#ifdef _DEBUG
# ifndef assert
#  include <cassert>
# endif
# define SI_ASSERT(x)   assert(x)
#else
# define SI_ASSERT(x)
#endif

enum SI_Error {
    SI_OK       =  0,   //!< No error
    SI_UPDATED  =  1,   //!< An existing value was updated
    SI_INSERTED =  2,   //!< A new value was inserted

    // note: test for any error with (retval < 0)
    SI_FAIL     = -1,   //!< Generic failure
    SI_NOMEM    = -2,   //!< Out of memory error
    SI_FILE     = -3    //!< File error (see errno for detail error)
};

#define SI_UTF8_SIGNATURE     "\xEF\xBB\xBF"

#ifdef _WIN32
# define SI_NEWLINE_A   "\r\n"
# define SI_NEWLINE_W   L"\r\n"
#else // !_WIN32
# define SI_NEWLINE_A   "\n"
# define SI_NEWLINE_W   L"\n"
#endif // _WIN32

#if defined(SI_CONVERT_ICU)
# include <unicode/ustring.h>
#endif

#if defined(_WIN32)
# define SI_HAS_WIDE_FILE
# define SI_WCHAR_T     wchar_t
#elif defined(SI_CONVERT_ICU)
# define SI_HAS_WIDE_FILE
# define SI_WCHAR_T     UChar
#endif


// ---------------------------------------------------------------------------
//                              MAIN TEMPLATE CLASS
// ---------------------------------------------------------------------------

/** Simple INI file reader.

    This can be instantiated with the choice of unicode or native characterset,
    and case sensitive or insensitive comparisons of section and key names.
    The supported combinations are pre-defined with the following typedefs:

    <table>
        <tr><th>Interface   <th>Case-sensitive  <th>Typedef
        <tr><td>char        <td>No              <td>CSimpleIniA
        <tr><td>char        <td>Yes             <td>CSimpleIniCaseA
        <tr><td>wchar_t     <td>No              <td>CSimpleIniW
        <tr><td>wchar_t     <td>Yes             <td>CSimpleIniCaseW
    </table>

    Note that using other types for the SI_CHAR is supported. For instance,
    unsigned char, unsigned short, etc. Note that where the alternative type
    is a different size to char/wchar_t you may need to supply new helper
    classes for SI_STRLESS and SI_CONVERTER.
 */
template<class SI_CHAR, class SI_STRLESS, class SI_CONVERTER>
class CSimpleIniTempl
{
public:
    /** key entry */
    struct Entry {
        const SI_CHAR * pItem;
        const SI_CHAR * pComment;
        int             nOrder;

        Entry(const SI_CHAR * a_pszItem = NULL, int a_nOrder = 0)
            : pItem(a_pszItem)
            , pComment(NULL)
            , nOrder(a_nOrder)
        { }
        Entry(const Entry & rhs) { operator=(rhs); }
        Entry & operator=(const Entry & rhs) {
            pItem    = rhs.pItem;
            pComment = rhs.pComment;
            nOrder   = rhs.nOrder;
            return *this;
        }

#if defined(_MSC_VER) && _MSC_VER <= 1200
        /** STL of VC6 doesn't allow me to specify my own comparator for list::sort() */
        bool operator<(const Entry & rhs) const { return LoadOrder()(*this, rhs); }
        bool operator>(const Entry & rhs) const { return LoadOrder()(rhs, *this); }
#endif

        /** Strict less ordering by name of key only */
        struct KeyOrder : std::binary_function<Entry, Entry, bool> {
            bool operator()(const Entry & lhs, const Entry & rhs) const {
                const static SI_STRLESS isLess = SI_STRLESS();
                return isLess(lhs.pItem, rhs.pItem);
            }
        };

        /** Strict less ordering by order, and then name of key */
        struct LoadOrder : std::binary_function<Entry, Entry, bool> {
            bool operator()(const Entry & lhs, const Entry & rhs) const {
                if (lhs.nOrder != rhs.nOrder) {
                    return lhs.nOrder < rhs.nOrder;
                }
                return KeyOrder()(lhs.pItem, rhs.pItem);
            }
        };
    };

    /** map keys to values */
    typedef std::multimap<Entry,const SI_CHAR *,typename Entry::KeyOrder> TKeyVal;

    /** map sections to key/value map */
    typedef std::map<Entry,TKeyVal,typename Entry::KeyOrder> TSection;

    /** set of dependent string pointers. Note that these pointers are
        dependent on memory owned by CSimpleIni.
    */
    typedef std::list<Entry> TNamesDepend;

    /** interface definition for the OutputWriter object to pass to Save()
        in order to output the INI file data.
    */
    class OutputWriter {
    public:
        OutputWriter() { }
        virtual ~OutputWriter() { }
        virtual void Write(const char * a_pBuf) = 0;
    private:
        OutputWriter(const OutputWriter &);             // disable
        OutputWriter & operator=(const OutputWriter &); // disable
    };

    /** OutputWriter class to write the INI data to a file */
    class FileWriter : public OutputWriter {
        FILE * m_file;
    public: