1 /*

     2  * Hedgewars, a free turn based strategy game

     3  * Copyright (C) 2012 Simeon Maxein <smaxein@googlemail.com>

     4  *

     5  * This program is free software; you can redistribute it and/or

     6  * modify it under the terms of the GNU General Public License

     7  * as published by the Free Software Foundation; either version 2

     8  * of the License, or (at your option) any later version.

     9  *

    10  * This program is distributed in the hope that it will be useful,

    11  * but WITHOUT ANY WARRANTY; without even the implied warranty of

    12  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the

    13  * GNU General Public License for more details.

    14  *

    15  * You should have received a copy of the GNU General Public License

    16  * along with this program; if not, write to the Free Software

    17  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.

    18  */

    19 

    20 /**

    21  * Convenience interface for ini reading/writing.

    22  *

    23  * We currently use iniparser in the background, but using its interface directly is a bit verbose.

    24  * This module is supposed to 1. make ini reading and writing a bit more convenient, and 2. hide

    25  * the iniparser dependency so it can at need be easily replaced.

    26  */

    27 

    28 #ifndef INIHELPER_H_

    29 #define INIHELPER_H_

    30 

    31 #include <stdbool.h>

    32 

    33 #define INI_ERROR_NOTFOUND -1

    34 #define INI_ERROR_FORMAT -2

    35 #define INI_ERROR_OTHER -100

    36 

    37 typedef struct _flib_ini flib_ini;

    38 

    39 /**

    40  * Create a new ini data structure, pre-filled with the contents of

    41  * the file "filename" if it exists. If filename is null, or the file

    42  * is not found, an empty ini will be created. However, if an error

    43  * occurs while reading the ini file (or any other error), null

    44  * is returned.

    45  *

    46  * This behavior is useful for modifying an existing ini file without

    47  * discarding unknown keys.

    48  */

    49 flib_ini *flib_ini_create(const char *filename);

    50 

    51 /**

    52  * Similar to flib_ini_create, but fails if the file is not found

    53  * or if filename is null.

    54  */

    55 flib_ini *flib_ini_load(const char *filename);

    56 

    57 /**

    58  * Store the ini to the file "filename", overwriting

    59  * the previous contents. Returns 0 on success.

    60  */

    61 int flib_ini_save(flib_ini *ini, const char *filename);

    62 

    63 void flib_ini_destroy(flib_ini *ini);

    64 

    65 /**

    66  * Enter the section with the specified name. Returns 0 on

    67  * success, INI_ERROR_NOTFOUND if the section does not exist

    68  * and a different value if another error occurs.

    69  * If an error occurs, there is no current section.

    70  *

    71  * The section name should only consist of letters and

    72  * numbers.

    73  */

    74 int flib_ini_enter_section(flib_ini *ini, const char *section);

    75 

    76 /**

    77  * Creates and enters the section with the specified name. Simply

    78  * enters the section if it exists already. Returns 0 on success

    79  * and a different value if another error occurs.

    80  * If an error occurs, there is no current section.

    81  */

    82 int flib_ini_create_section(flib_ini *ini, const char *section);

    83 

    84 /**

    85  * Find a key in the current section and store the value in outVar

    86  * as a newly allocated string. Returns 0 on success, INI_ERROR_NOTFOUND

    87  * if the key was not found and a different value for other errors,

    88  * e.g. if there is no current section.

    89  */

    90 int flib_ini_get_str(flib_ini *ini, char **outVar, const char *key);

    91 

    92 /**

    93  * Find a key in the current section and store the value in outVar

    94  * as a newly allocated string. If the key is not found, the default

    95  * value will be used instead. Returns 0 on success.

    96  */

    97 int flib_ini_get_str_opt(flib_ini *ini, char **outVar, const char *key, const char *def);

    98 

    99 /**

   100  * Find a key in the current section and store the value in outVar

   101  * as an int. Returns 0 on success, INI_ERROR_NOTFOUND

   102  * if the key was not found, INI_ERROR_FORMAT if it was found but

   103  * could not be converted to an int, and a different value for other

   104  * errors, e.g. if there is no current section.

   105  */

   106 int flib_ini_get_int(flib_ini *ini, int *outVar, const char *key);

   107 

   108 /**

   109  * Find a key in the current section and store the value in outVar

   110  * as an int. If the key is not found, the default value will be used instead.

   111  * Returns 0 on success, INI_ERROR_FORMAT if the value was found but

   112  * could not be converted to int, and another value otherwise.

   113  */

   114 int flib_ini_get_int_opt(flib_ini *ini, int *outVar, const char *key, int def);

   115 

   116 /**

   117  * Find a key in the current section and store the value in outVar

   118  * as a bool. Treats everything beginning with "Y", "T" or "1" as true,

   119  * everything starting with "N", "F" or "1" as false.

   120  *

   121  * Returns 0 on success, INI_ERROR_NOTFOUND if the key was not found,

   122  * INI_ERROR_FORMAT if the value could not be interpreted as boolean,

   123  * and another value otherwise.

   124  */

   125 int flib_ini_get_bool(flib_ini *ini, bool *outVar, const char *key);

   126 

   127 /**

   128  * Find a key in the current section and store the value in outVar

   129  * as a bool. If the key is not found, the default value will be

   130  * used instead. Returns 0 on success, INI_ERROR_FORMAT if the

   131  * value could not be interpreted as boolean, and another value otherwise.

   132  */

   133 int flib_ini_get_bool_opt(flib_ini *ini, bool *outVar, const char *key, bool def);

   134 

   135 /**

   136  * In the current section, associate key with value. Returns 0 on success.

   137  */

   138 int flib_ini_set_str(flib_ini *ini, const char *key, const char *value);

   139 

   140 /**

   141  * In the current section, associate key with value. Returns 0 on success.

   142  */

   143 int flib_ini_set_int(flib_ini *ini, const char *key, int value);

   144 

   145 /**

   146  * In the current section, associate key with value. Returns 0 on success.

   147  */

   148 int flib_ini_set_bool(flib_ini *ini, const char *key, bool value);

   149 

   150 /**

   151  * Returns the number of sections in the ini file, or a negative value on error.

   152  */

   153 int flib_ini_get_sectioncount(flib_ini *ini);

   154 

   155 /**

   156  * Returns the name of the section, or NULL on error. The returned string must

   157  * be free()d.

   158  *

   159  * Note: There is no guarantee that the order of the sections

   160  * will remain stable if the ini is modified.

   161  */

   162 char *flib_ini_get_sectionname(flib_ini *ini, int number);

   163 

   164 /**

   165  * Returns the number of keys in the current section, or -1 on error.

   166  */

   167 int flib_ini_get_keycount(flib_ini *ini);

   168 

   169 /**

   170  * Returns the name of the key in the current section, or NULL on error.

   171  * The returned string must be free()d.

   172  *

   173  * Note: There is no guarantee that the order of the keys in a section

   174  * will remain stable if the ini is modified.

   175  */

   176 char *flib_ini_get_keyname(flib_ini *ini, int number);

   177 

   178 #endif /* INIHELPER_H_ */