Configuration files

Configuration files

ALLEGRO_CONFIG

typedef struct ALLEGRO_CONFIG ALLEGRO_CONFIG;

ALLEGRO_CONFIG_ENTRY

typedef struct ALLEGRO_CONFIG_ENTRY ALLEGRO_CONFIG_ENTRY;

ALLEGRO_CONFIG_SECTION

typedef struct ALLEGRO_CONFIG_SECTION ALLEGRO_CONFIG_SECTION;

al_config_add_comment

void al_config_add_comment(ALLEGRO_CONFIG *config,
   const char *section, const char *comment)

Add a comment in a section of a configuration. If the section doesn't yet exist, it will be created. The section can be NULL or "" for the global section.

The comment may or may not begin with a hash character. Any newlines in the comment string will be replaced by space characters.

al_config_add_section

void al_config_add_section(ALLEGRO_CONFIG *config, const char *name)

Add a section to a configuration structure.

al_config_destroy

void al_config_destroy(ALLEGRO_CONFIG *config)

Free the resources used by a configuration structure. Does nothing if passed NULL.

al_config_get_value

static bool config_get_value(const ALLEGRO_CONFIG *config,
   const ALLEGRO_USTR section, const ALLEGRO_USTR key,
   ALLEGRO_USTR *ret_value)

Gets a pointer to an internal character buffer that will only remain valid as long as the ALLEGRO_CONFIG structure is not destroyed. Copy the value if you need a copy. The section can be NULL or "" for the global section. Returns NULL if the section or key do not exist.

al_config_merge

ALLEGRO_CONFIG *al_config_merge(const ALLEGRO_CONFIG *cfg1,
    const ALLEGRO_CONFIG *cfg2)

Merge two configuration structures, and return the result as a new configuration. Values in configuration 'cfg2' override those in 'cfg1'. Neither of the input configuration structures are modified. Comments from 'cfg2' are not retained.

al_config_merge_into

void al_config_merge_into(ALLEGRO_CONFIG *master, const ALLEGRO_CONFIG *add)

Merge one configuration structure into another. Values in configuration 'add' override those in 'master'. 'master' is modified. Comments from 'add' are not retained.

al_config_read

ALLEGRO_CONFIG *al_config_read(const char *filename)

Read a configuration file. Returns NULL on error.

al_config_set_value

void al_config_set_value(ALLEGRO_CONFIG *config,
   const char *section, const char *key, const char *value)

Set a value in a section of a configuration. If the section doesn't yet exist, it will be created. If a value already existed for the given key, it will be overwritten. The section can be NULL or "" for the global section.

For consistency with the on-disk format of config files, any leading and trailing whitespace will be stripped from the value. If you have significant whitespace you wish to preserve, you should add your own quote characters and remove them when reading the values back in.

al_config_write

int al_config_write(const ALLEGRO_CONFIG *config, const char *filename)

Write out a configuration file. Returns zero on success, non-zero on error.