## toolConfigFile

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

## Synopsis

    gboolean    (*configFileReadFunc)           (gchar **lines,
                                                 int nbLines,
                                                 int position,
                                                 VisuData *dataObj,
                                                 GError **error);
    enum        toolConfigFileError;
    gboolean    configFileRead_elementFromTokens
                                                (gchar **tokens,
                                                 int *position,
                                                 VisuElement **values,
                                                 guint size,
                                                 int lineId,
                                                 GError **error);
    gboolean    configFileRead_float            (gchar *line,
                                                 int position,
                                                 float *values,
                                                 guint size,
                                                 GError **error);
    gboolean    configFileRead_floatWithElement (gchar *line,
                                                 int position,
                                                 float *values,
                                                 guint size,
                                                 VisuElement **ele,
                                                 GError **error);
    gboolean    configFileRead_floatFromTokens  (gchar **tokens,
                                                 int *position,
                                                 float *values,
                                                 guint size,
                                                 int lineId,
                                                 GError **error);
    gboolean    configFileRead_string           (gchar *line,
                                                 int position,
                                                 gchar ***values,
                                                 guint size,
                                                 GError **error);
    gboolean    configFileRead_stringFromTokens (gchar **tokens,
                                                 int *position,
                                                 gchar ***values,
                                                 guint size,
                                                 int lineId,
                                                 GError **error);
    gboolean    configFileRead_stringWithElement
                                                (gchar *line,
                                                 int position,
                                                 gchar ***values,
                                                 guint size,
                                                 VisuElement **ele,
                                                 GError **error);
    gboolean    configFileRead_boolean          (gchar *line,
                                                 int position,
                                                 gboolean *values,
                                                 guint size,
                                                 GError **error);
    gboolean    configFileRead_booleanWithElement
                                                (gchar *line,
                                                 int position,
                                                 gboolean *values,
                                                 guint size,
                                                 VisuElement **ele,
                                                 GError **error);
    gboolean    configFileRead_booleanFromTokens
                                                (gchar **tokens,
                                                 int *position,
                                                 gboolean *values,
                                                 guint size,
                                                 int lineId,
                                                 GError **error);

## 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

### configFileReadFunc ()

    gboolean    (*configFileReadFunc)           (gchar **lines,
                                                 int nbLines,
                                                 int position,
                                                 VisuData *dataObj,
                                                 GError **error);

This prototype corresponds to methods called when an entry is found. The `lines` argument is an array of lines read from the files. These strings are copies and can be modified but not freed. There are `nbLines` and this value correspond to the number of lines defined for the entry. The `error` argument is used to store some text messages and error ids. They should be in UTF8. The `error` argument must be initialised with (GError*)0. The `position` argument give the number of the first line given in `lines` argument. If the `dataObj` argument is not null, some updates should be done with read values.

`lines` : | an array of strings ;
`nbLines` : | an integer ;
`position` : | an integer ;
`dataObj` : | a VisuData object ;
`error` : | a pointer to a GError pointer.
Returns : | TRUE if everything goes right, FALSE otherwise.

### enum toolConfigFileError

    typedef enum
      {
        CONFIG_FILE_ERROR_EMPTY_LINE,
        CONFIG_FILE_ERROR_BAD_ELEMENT_NAME,
        CONFIG_FILE_ERROR_MAX_ELEMENT,
        CONFIG_FILE_ERROR_CREATED_ELEMENT,
        CONFIG_FILE_ERROR_VALUE,
        CONFIG_FILE_ERROR_READ,
        CONFIG_FILE_ERROR_MISSING
      } toolConfigFileError;

Possible errors when parsing a config file.

`CONFIG_FILE_ERROR_EMPTY_LINE` | error when reading the file, found an empty line, where something should have been.
`CONFIG_FILE_ERROR_BAD_ELEMENT_NAME` | error when reading a VisuElement name.
`CONFIG_FILE_ERROR_MAX_ELEMENT` | error because too much VisuElement have been created.
`CONFIG_FILE_ERROR_CREATED_ELEMENT` | error when creating a new VisuElement.
`CONFIG_FILE_ERROR_VALUE` | error of file format, values read are out of bounds.
`CONFIG_FILE_ERROR_READ` | error of file format (can't read variables...).
`CONFIG_FILE_ERROR_MISSING` | error of file format (missing variables...).

### configFileRead_elementFromTokens ()

    gboolean    configFileRead_elementFromTokens
                                                (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 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.

### configFileRead_float ()

    gboolean    configFileRead_float            (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.

### configFileRead_floatWithElement ()

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

Same as `configFileRead_float()` 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.

### configFileRead_floatFromTokens ()

    gboolean    configFileRead_floatFromTokens  (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.

### configFileRead_string ()

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

Read `size` strings from `line` and `values` points on them.

`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 ;
`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()`.

### configFileRead_stringFromTokens ()

    gboolean    configFileRead_stringFromTokens (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.

### configFileRead_stringWithElement ()

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

Same as `configFileRead_string()` 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()`.

### configFileRead_boolean ()

    gboolean    configFileRead_boolean          (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.

### configFileRead_booleanWithElement ()

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

Same as `configFileRead_boolean()` 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.

### configFileRead_booleanFromTokens ()

    gboolean    configFileRead_booleanFromTokens
                                                (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.