## toolConfigFile toolConfigFile — Generic read methods of the configuration files are defined here. |

## Synopsis

    #define             TOOL_CONFIGFILE_ERROR
    GQuark              tool_configFile_getQuark            ();
    enum                ToolConfigFileError;
    gboolean            tool_configFile_readFloatFromTokens (gchar **tokens,
                                                             int *position,
                                                             float *values,
                                                             guint size,
                                                             int lineId,
                                                             GError **error);
    gboolean            tool_configFile_readFloat           (gchar *line,
                                                             int position,
                                                             float *values,
                                                             guint size,
                                                             GError **error);
    gboolean            tool_configFile_readFloatWithElement
                                                            (gchar *line,
                                                             int position,
                                                             float *values,
                                                             guint size,
                                                             VisuElement **ele,
                                                             GError **error);
    gboolean            tool_configFile_readIntegerFromTokens
                                                            (gchar **tokens,
                                                             int *position,
                                                             int *values,
                                                             guint size,
                                                             int lineId,
                                                             GError **error);
    gboolean            tool_configFile_readInteger         (gchar *line,
                                                             int position,
                                                             int *values,
                                                             guint size,
                                                             GError **error);
    gboolean            tool_configFile_readBooleanFromTokens
                                                            (gchar **tokens,
                                                             int *position,
                                                             gboolean *values,
                                                             guint size,
                                                             int lineId,
                                                             GError **error);
    gboolean            tool_configFile_readBoolean         (gchar *line,
                                                             int position,
                                                             gboolean *values,
                                                             guint size,
                                                             GError **error);
    gboolean            tool_configFile_readBooleanWithElement
                                                            (gchar *line,
                                                             int position,
                                                             gboolean *values,
                                                             guint size,
                                                             VisuElement **ele,
                                                             GError **error);
    gboolean            tool_configFile_readStringFromTokens
                                                            (gchar **tokens,
                                                             int *position,
                                                             gchar ***values,
                                                             guint size,
                                                             int lineId,
                                                             GError **error);
    gboolean            tool_configFile_readString          (gchar *line,
                                                             int position,
                                                             gchar ***values,
                                                             guint size,
                                                             gboolean join,
                                                             GError **error);
    gboolean            tool_configFile_readStringWithElement
                                                            (gchar *line,
                                                             int position,
                                                             gchar ***values,
                                                             guint size,
                                                             VisuElement **ele,
                                                             GError **error);
    gboolean            tool_configFile_readElementFromTokens
                                                            (gchar **tokens,
                                                             int *position,
                                                             VisuElement **values,
                                                             guint size,
                                                             int lineId,
                                                             GError **error);
    gboolean            tool_configFile_clampFloat          (float *variable,
                                                             float value,
                                                             float min,
                                                             float max);

## Description

These methods give generic tools to read common data in the configuration files, such as arrays of float values or one VisuElement... It also defines a enumeration of detailed errors (see ToolConfigFileError) when reading a file. All read elements are either from tokens (given `g_strsplit()`) or strings.

## Details

### TOOL_CONFIGFILE_ERROR

    #define TOOL_CONFIGFILE_ERROR tool_configFile_getQuark()

Domain used to parse config files.

### tool_configFile_getQuark ()

    GQuark              tool_configFile_getQuark            ();

Internal routine for error handling.

Returns : | the GQuark associated to errors related to configuration files.

### enum ToolConfigFileError

    typedef enum
      {
        TOOL_CONFIGFILE_ERROR_EMPTY_LINE,
        TOOL_CONFIGFILE_ERROR_BAD_ELEMENT_NAME,
        TOOL_CONFIGFILE_ERROR_MAX_ELEMENT,
        TOOL_CONFIGFILE_ERROR_CREATED_ELEMENT,
        TOOL_CONFIGFILE_ERROR_VALUE,
        TOOL_CONFIGFILE_ERROR_READ,
        TOOL_CONFIGFILE_ERROR_MISSING,
        TOOL_CONFIGFILE_ERROR_TAG,
        TOOL_CONFIGFILE_ERROR_MARKUP
      } ToolConfigFileError;

Possible errors when parsing a config file.

`TOOL_CONFIGFILE_ERROR_EMPTY_LINE` | error when reading the file, found an empty line, where something should have been.
`TOOL_CONFIGFILE_ERROR_BAD_ELEMENT_NAME` | error when reading a VisuElement name.
`TOOL_CONFIGFILE_ERROR_MAX_ELEMENT` | error because too much VisuElement have been created.
`TOOL_CONFIGFILE_ERROR_CREATED_ELEMENT` | error when creating a new VisuElement.
`TOOL_CONFIGFILE_ERROR_VALUE` | error of file format, values read are out of bounds.
`TOOL_CONFIGFILE_ERROR_READ` | error of file format (can't read variables...).
`TOOL_CONFIGFILE_ERROR_MISSING` | error of file format (missing variables...).
`TOOL_CONFIGFILE_ERROR_TAG` | error dealing with a tag.
`TOOL_CONFIGFILE_ERROR_MARKUP` | error dealing with a markup (unkown one...).

### tool_configFile_readFloatFromTokens ()

    gboolean            tool_configFile_readFloatFromTokens (gchar **tokens,
                                                             int *position,
                                                             float *values,
                                                             guint size,
                                                             int lineId,
                                                             GError **error);

Read `size` floating point values from `tokens`, store them in `values` and returns the new head in `tokens`.

`tokens` : | array of tokens resulting from a call to `g_strsplit()` with " " as separator ;
`position` : | IN, the position of the beginning in `tokens` ; OUT, one token after the last read ;
`values` : | allocated area to store read values ;
`size` : | the number of floating point values to be read ;
`lineId` : | the number of the line of the config file which the `line` argument is taken from ;
`error` : | a location to store a possible reading error.
Returns : | TRUE if no error occured.

### tool_configFile_readFloat ()

    gboolean            tool_configFile_readFloat           (gchar *line,
                                                             int position,
                                                             float *values,
                                                             guint size,
                                                             GError **error);

Read `size` floating point values from `line` and store them in `values`.

`line` : | string where values are read from ;
`position` : | the number of the line of the config file which the `line` argument is taken from ;
`values` : | allocated area to store read values ;
`size` : | the number of floating point values to be read ;
`error` : | a location to store a possible reading error.
Returns : | TRUE if no error occured.

### tool_configFile_readFloatWithElement ()

    gboolean            tool_configFile_readFloatWithElement
                                                            (gchar *line,
                                                             int position,
                                                             float *values,
                                                             guint size,
                                                             VisuElement **ele,
                                                             GError **error);

Same as `tool_configFile_readFloat()` but begins by reading an element at the begining of the line.

`line` : | string where values are read from ;
`position` : | the number of the line of the config file which the `line` argument is taken from ;
`values` : | allocated area to store read values ;
`size` : | the number of floating point values to be read ;
`ele` : | a pointer to a VisuElement location ;
`error` : | a location to store a possible reading error.
Returns : | TRUE if no error occured.

### tool_configFile_readIntegerFromTokens ()

    gboolean            tool_configFile_readIntegerFromTokens
                                                            (gchar **tokens,
                                                             int *position,
                                                             int *values,
                                                             guint size,
                                                             int lineId,
                                                             GError **error);

Read `size` integer values from `tokens`, store them in `values` and returns the new head in `tokens`.

`tokens` : | array of tokens resulting from a call to `g_strsplit()` with " " as separator ;
`position` : | IN, the position of the beginning in `tokens` ; OUT, one token after the last read ;
`values` : | allocated area to store read values ;
`size` : | the number of floating point values to be read ;
`lineId` : | the number of the line of the config file which the `line` argument is taken from ;
`error` : | a location to store a possible reading error.
Returns : | TRUE if no error occured.

### tool_configFile_readInteger ()

    gboolean            tool_configFile_readInteger         (gchar *line,
                                                             int position,
                                                             int *values,
                                                             guint size,
                                                             GError **error);

Read `size` integers from `line` and store them in `values`.

`line` : | string where values are read from ;
`position` : | the number of the line of the config file which the `line` argument is taken from ;
`values` : | allocated area to store read values ;
`size` : | the number of floating point values to be read ;
`error` : | a location to store a possible reading error.
Returns : | TRUE if no error occured.

### tool_configFile_readBooleanFromTokens ()

    gboolean            tool_configFile_readBooleanFromTokens
                                                            (gchar **tokens,
                                                             int *position,
                                                             gboolean *values,
                                                             guint size,
                                                             int lineId,
                                                             GError **error);

Read `size` boolean values from `tokens`, store them in `values` and returns the new head in `tokens`.

`tokens` : | array of tokens resulting from a call to `g_strsplit()` with " " as separator ;
`position` : | IN, the position of the beginning in `tokens` ; OUT, one token after the last read ;
`values` : | allocated area to store read values ;
`size` : | the number of floating point values to be read ;
`lineId` : | the number of the line of the config file which the `line` argument is taken from ;
`error` : | a location to store a possible reading error.
Returns : | TRUE if no error occured.

### tool_configFile_readBoolean ()

    gboolean            tool_configFile_readBoolean         (gchar *line,
                                                             int position,
                                                             gboolean *values,
                                                             guint size,
                                                             GError **error);

Read `size` boolean values from `line` and store them in `values`.

`line` : | string where values are read from ;
`position` : | the number of the line of the config file which the `line` argument is taken from ;
`values` : | allocated area to store read values ;
`size` : | the number of boolean values to be read ;
`error` : | a location to store a possible reading error.
Returns : | TRUE if no error occured.

### tool_configFile_readBooleanWithElement ()

    gboolean            tool_configFile_readBooleanWithElement
                                                            (gchar *line,
                                                             int position,
                                                             gboolean *values,
                                                             guint size,
                                                             VisuElement **ele,
                                                             GError **error);

Same as `tool_configFile_readBoolean()` but begins by reading an element at the begining of the line.

`line` : | string where values are read from ;
`position` : | the number of the line of the config file which the `line` argument is taken from ;
`values` : | allocated area to store read values ;
`size` : | the number of boolean values to be read ;
`ele` : | a pointer to a VisuElement location ;
`error` : | a location to store a possible reading error.
Returns : | TRUE if no error occured.

### tool_configFile_readStringFromTokens ()

    gboolean            tool_configFile_readStringFromTokens
                                                            (gchar **tokens,
                                                             int *position,
                                                             gchar ***values,
                                                             guint size,
                                                             int lineId,
                                                             GError **error);

Read `size` strings from `tokens`, store them in `values` and returns the new head in `tokens`.

`tokens` : | array of tokens resulting from a call to `g_strsplit()` with " " as separator ;
`position` : | IN, the position of the beginning in `tokens` ; OUT, one token after the last read ;
`values` : | a location to point on a gchar** ;
`size` : | the number of floating point values to be read ;
`lineId` : | the number of the line of the config file which the `line` argument is taken from ;
`error` : | a location to store a possible reading error.
Returns : | TRUE if no error occured.

### tool_configFile_readString ()

    gboolean            tool_configFile_readString          (gchar *line,
                                                             int position,
                                                             gchar ***values,
                                                             guint size,
                                                             gboolean join,
                                                             GError **error);

Read `size` strings from `line` and `values` points on them. If more strings than `size` are available, an error is raised ; except if `join` is TRUE. In that case, the method return `size` tokens, joining all remaining ones.

`line` : | string where values are read from ;
`position` : | the number of the line of the config file which the `line` argument is taken from ;
`values` : | a location to point on a gchar** ;
`size` : | the number of strings to be read ;
`join` : | a boolean ;
`error` : | a location to store a possible reading error.
Returns : | TRUE if no error occured, then `values` point on an allocated memory area that is NULL terminated and that must be freed with `g_strfreev()`.

### tool_configFile_readStringWithElement ()

    gboolean            tool_configFile_readStringWithElement
                                                            (gchar *line,
                                                             int position,
                                                             gchar ***values,
                                                             guint size,
                                                             VisuElement **ele,
                                                             GError **error);

Same as `tool_configFile_readString()` but begins by reading an element at the begining of the line.

`line` : | string where values are read from ;
`position` : | the number of the line of the config file which the `line` argument is taken from ;
`values` : | a location to point on a gchar** ;
`size` : | the number of strings to be read ;
`ele` : | a pointer to a VisuElement location ;
`error` : | a location to store a possible reading error.
Returns : | TRUE if no error occured, then `values` point on an allocated memory area that is NULL terminated and that must be freed with `g_strfreev()`.

### tool_configFile_readElementFromTokens ()

    gboolean            tool_configFile_readElementFromTokens
                                                            (gchar **tokens,
                                                             int *position,
                                                             VisuElement **values,
                                                             guint size,
                                                             int lineId,
                                                             GError **error);

Read `size` VisuElement from `tokens`, store them in `values` and returns the new head in `tokens`.

`tokens` : | array of tokens resulting from a call to `g_strsplit()` with " " as separator ;
`position` : | IN, the position of the beginning in `tokens` ; OUT, one token after the last read ;
`values` : | allocated area to store read values ;
`size` : | the number of VisuElement to be read ;
`lineId` : | the number of the line of the config file which the `line` argument is taken from ;
`error` : | a location to store a possible reading error.
Returns : | TRUE if no error occured.

### tool_configFile_clampFloat ()

    gboolean            tool_configFile_clampFloat          (float *variable,
                                                             float value,
                                                             float min,
                                                             float max);

It puts value in a variable if value is in min and max or put min or max in if not. It return true if value is out of bounds. Min and max are inclusive values. If there is no max bounds then put max at a lower value than min and if there is no min bound, put min at a higher value than max.

`variable` : | a pointer to a storage for the value ;
`value` : | the value to put in the storage ;
`min` : | a lower bound ;
`max` : | a upper bound.
Returns : | TRUE if the value is out of bounds.