## visu_configFile

visu_configFile — Defines methods to access (read/write) to config files and to create different entries

## Synopsis

    #define     VISU_CONFIGFILE_PARAMETER
    #define     VISU_CONFIGFILE_RESOURCE
    typedef     VisuConfigFileEntry;
    gboolean    (*visuConfigFileExportFunc)     (GString *data,
                                                 int *nbLinesWritten,
                                                 VisuData *dataObj);
    gboolean    (*visuConfigFileReadFunc)       (gchar **lines,
                                                 int nbLines,
                                                 int position,
                                                 GString *errorMessage);
    struct      foreachFuncExport_struct;

    VisuConfigFileEntry* visuConfigFileAdd_entry
                                                (int kind,
                                                 gchar *key,
                                                 gchar *description,
                                                 int nbLines,
                                                 visuConfigFileReadFunc readFunc);
    void        visuConfigFileAdd_exportFunction
                                                (int kind,
                                                 visuConfigFileExportFunc writeFunc);
    void        visuConfigFileAdd_knownTag      (gchar *tag);
    void        visuConfigFileSet_tag           (VisuConfigFileEntry *entry,
                                                 gchar *tag);

    gboolean    visuConfigFileLoad              (int kind,
                                                 const char *fileName,
                                                 GString **message);
    gboolean    visuConfigFileSave              (int kind,
                                                 const char *fileName,
                                                 GString **message,
                                                 int *lines,
                                                 VisuData *dataObj);

    GList*      visuConfigFileGet_pathList      (int kind);
    gchar*      visuConfigFileGet_validPath     (int kind,
                                                 int mode,
                                                 int utf8);
    gchar*      visuConfigFileGet_nextValidPath (int kind,
                                                 int accessMode,
                                                 GList **list,
                                                 int utf8);
    gchar*      visuConfigFileGet_defaultFileName
                                                (int kind);

    int         visuConfigFileSet_floatValue    (float *variable,
                                                 float value,
                                                 float min,
                                                 float max);

    int         visuConfigFile_init             ();

## Description

V_Sim uses two different configuration files. The first stores the configuration of the program itself and is called parameters file. The second stores differents values that control the way files are rendered. It is called resources file. For example, their is an entry in the parameters file that controls your favorite rendering method ; and there is is an entry in the resources file that codes that vacancy elements are rendered by cube in the atomic rendering method. Most methods of this part uses a first argument usually called 'kind', that control if the method will apply on the parameters file or on the resources file. VISU_CONFIGFILE_PARAMETER and VISU_CONFIGFILE_RESOURCE are the two flags that should be used for the 'kind' argument.

There are different paths where these files can be stored. These paths are stored in V_Sim with an order : for example parameters file are first looked for in the current working directory, then in the $HOME/.v_sim directory and finally in the installation directory. This is transparent for the user and `visuConfigFileGet_validPath()` is the right method to access to the best readable configuration file.

Different part of V_Sim can add entries in these files. The method `visuConfigFileAdd_entry()` is designed to this purpose. The entries are defined by their name and they appear in the configuration file as 'name:' followed by the data associated to this entry. In the parameters file, the data are on the same line. In the resources file, the data begin the line after and can be longer that one line. When a configuration file is read, the method associated to each entry (`visuConfigFileReadFunc()`) is called with a copy of their data lines. The method `visuConfigFileAdd_exportFunction()` should be used to add a callback when the configurations files are written, then each part of V_Sim that have entries can put some lines in the configuration files.

## Details

### VISU_CONFIGFILE_PARAMETER

    #define VISU_CONFIGFILE_PARAMETER 0

This defines a parameter entry in the config files.

### VISU_CONFIGFILE_RESOURCE

    #define VISU_CONFIGFILE_RESOURCE 1

This defines a resource entry in the config files.

### VisuConfigFileEntry

    typedef struct VisuConfigFileEntry_struct VisuConfigFileEntry;

### visuConfigFileExportFunc ()

    gboolean    (*visuConfigFileExportFunc)     (GString *data,
                                                 int *nbLinesWritten,
                                                 VisuData *dataObj);

This prototype defines a method that is used to export some resources or parameters. The `data` argument is an empty GString where the export has to be written. If the argument `dataObj` is not null, only resources related to the VisuData object should be exported (for parameters files, `dataObj` is always NULL).

`data` : | an empty GString to store the export ;
`nbLinesWritten` : | a pointer to store the number of lines written ;
`dataObj` : | a VisuData object.
Returns : | TRUE if everything goes right, FALSE otherwise.

### visuConfigFileReadFunc ()

    gboolean    (*visuConfigFileReadFunc)       (gchar **lines,
                                                 int nbLines,
                                                 int position,
                                                 GString *errorMessage);

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 `errorMessage` arguument is used to store some text messages. They should be in UTF8. The `position` argument give the number of the first line given in `lines` argument. Will be soon deprecated.

`lines` : | an array of strings ;
`nbLines` : | an integer ;
`position` : | an integer ;
`errorMessage` : | a pointer to a GString or NULL.
Returns : | TRUE if everything goes right, FALSE otherwise.

### struct foreachFuncExport_struct

    struct foreachFuncExport_struct {
      GString *data;
      int *nbLinesWritten;
      VisuData *dataObj;
    };

This structure can be used to encapsulate the arguments of an export method when used in a foreach glib loop.

### visuConfigFileAdd_entry ()

    VisuConfigFileEntry* visuConfigFileAdd_entry
                                                (int kind,
                                                 gchar *key,
                                                 gchar *description,
                                                 int nbLines,
                                                 visuConfigFileReadFunc readFunc);

This creates a new VisuConfigFileEntry object with the given values. The key argument is copied.

`kind` : | an integer ;
`key` : | a string (should not be NULL) ;
`description` : | a string (can be NULL) ;
`nbLines` : | an integer ;
`readFunc` : | a visuConfigFileReadFunc.
Returns : | the newly created VisuConfigFileEntry object.

### visuConfigFileAdd_exportFunction ()

    void        visuConfigFileAdd_exportFunction
                                                (int kind,
                                                 visuConfigFileExportFunc writeFunc);

This stores the `writeFunc` given. It will be called when resources or parameters will be exported to disk.

`kind` : | an integer to identify resources or parameters ;
`writeFunc` : | a visuConfigFileExportFunc method.

### visuConfigFileAdd_knownTag ()

    void        visuConfigFileAdd_knownTag      (gchar *tag);

If parameter entries have a tag, they are ignored except if their tag has been declared using this method.

`tag` : | a string (not nul or empty).

### visuConfigFileSet_tag ()

    void        visuConfigFileSet_tag           (VisuConfigFileEntry *entry,
                                                 gchar *tag);

This method is used to set a tag to the given entry. This tag is used to ignore or not the entry when the file is read. The `tag` argument is copied.

`entry` : | a VisuConfigFileEntry object ;
`tag` : | a string.

### visuConfigFileLoad ()

    gboolean    visuConfigFileLoad              (int kind,
                                                 const char *fileName,
                                                 GString **message);

Try to load the resources/parameters from the file name given in parameter. The parameter `message` is a buffer to store a message, it can be NULL, then no message are generated.

`kind` : | an integer to identify the kind of file ;
`fileName` : | the path to file to read ;
`message` : | a pointer to a *GString.
Returns : | TRUE if everything goes right. If `message` is not NULL it should be freed with `g_string_free()`.

### visuConfigFileSave ()

    gboolean    visuConfigFileSave              (int kind,
                                                 const char *fileName,
                                                 GString **message,
                                                 int *lines,
                                                 VisuData *dataObj);

Try to export the resources/parameters to the file name given in parameter. The parameter `message` is a buffer to store a message, it can be NULL, then no message are generated. If `lines` argument is not NULL, and everything went right, it stores the number of written lines. If the argument `dataObj` is not null, only resources related to the VisuData object should be exported (for parameters files, `dataObj` is always NULL).

`kind` : | an integer to identify the kind of file ;
`fileName` : | the path to file to read ;
`message` : | a pointer to a *GString (can be NULL) ;
`lines` : | a pointer to an integer (can be NULL) ;
`dataObj` : | a VisuData object (can be NULL).
Returns : | TRUE if everything goes right. If `message` is not NULL it should be freed with `g_string_free()`.

### visuConfigFileGet_pathList ()

    GList*      visuConfigFileGet_pathList      (int kind);

V_Sim stores a list of paths where to look for resources or parameters files, this method is used to get these lists.

`kind` : | an integer identifier.
Returns : | the list of the parameters or resources paths. This list is read-only.

### visuConfigFileGet_validPath ()

    gchar*      visuConfigFileGet_validPath     (int kind,
                                                 int mode,
                                                 int utf8);

Test the entries of the hadoc list to find a valid position to read or write a config file. It tests access for the specified file.

`kind` : | an integer identifier ;
`mode` : | a value from R_OK, W_OK and X_OK as described in unistd.h.
`utf8` : | if 1, the path is return in UTF-8 format, otherwise, the locale of the file system is used.
Returns : | the first valid path find in the list of known paths.

### visuConfigFileGet_nextValidPath ()

    gchar*      visuConfigFileGet_nextValidPath (int kind,
                                                 int accessMode,
                                                 GList **list,
                                                 int utf8);

Test the entries of the given list to find a valid position to read or write a config file. It tests access for the specified file. After a call to this method the `list` argument points to the next entry in the list, after the one found.

`kind` : | an integer identifier ;
`accessMode` : | a value from R_OK, W_OK and X_OK as described in unistd.h ;
`list` : | a pointer to a valid *GList ;
`utf8` : | if 1, the path is return in UTF-8 format, otherwise, the locale of the file system is used.
Returns : | the first valid path find in the given list of paths.

### visuConfigFileGet_defaultFileName ()

    gchar*      visuConfigFileGet_defaultFileName
                                                (int kind);

This methods is used to get the filename used for different config files.

`kind` : | an integer identifier.
Returns : | the filename of config file. The returned *gchar is owned by V_Sim and should not be freed or modified.

### visuConfigFileSet_floatValue ()

    int         visuConfigFileSet_floatValue    (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.

### visuConfigFile_init ()

    int         visuConfigFile_init             ();

Initialization, should not be called.

Returns : | 1 if everything goes right.