Re: [Confuse-devel] Some questions regarding the libConfuse

[Martin Hedenfalk]

On Tue, 2004-06-01 at 10:14, Kai Duncan wrote:
> Hello,
> 
> First of all I would like to thank you for making such
> a useful tool.

Thank you!

>  I am using libConfuse 2.3 have a few
> questions regarding its usage listed below. Keep in
> mind that my configuration file consists of several
> sections with identical fields (character strings,
> integers, and 1 boolean type). Each section will be
> loaded into a dynamically allocated data C structure
> and woven into a linked list.
> 
> 1. How can I make each option field REQUIRED so that
> if the library is reading a section and it is missing
> an option that is needed in the data structure it will
> error and exit? Is this possible using the existing
> code in the library?

There is no direct support in libConfuse for this. However, you can use
a validating callback function on the section. For the code sample below
this would look something like:

  cfg = cfg_init(...);
  cfg_set_validate_func(cfg, "section", validate_section);
  cfg_parse(cfg, ...);

The function validate_section() is then defined as:

int validate_section(cfg_t *cfg, cfg_opt_t *opt)
{
    /* get the last parsed section */
    cfg_t *sec = cfg_opt_getnsec(opt, cfg_opt_size(opt) - 1);

    /* validate that a "string" option is set in the section */
    if(cfg_size(sec, "string") > 0 && cfg_getstr(sec, "string") != NULL)
        return CFG_SUCCESS;

    /* otherwise the option is not set at all, log a message and
     * return error */
    cfg_error(cfg, "missing string option in section");
    return CFG_PARSE_ERROR;
}

For single options (ie, not lists) there is currently no way to NOT
specify a default value. So at least for integers, floats and booleans
there is no clean way to check if an option is set in the configuration
file, or if the default value is used.

For strings with a default value of NULL, cfg_size() will return 1 (as
it will for integers etc.) but the value returned by cfg_getstr() will
return NULL.

Hmmm... this might be a good feature request :-) Both a flag
CFGF_NO_DEFAULT and a flag CFGF_REQUIRED.

> 2. I am using something along the lines of this:
>    cfg_t *cfg, *section;
>    num_sections = cfg_size(cfg, "section");
>    for(counter = 0; counter < num_sections; counter++)
>    {
>       section = cfg_getnsec(cfg, "section", counter);
> //do stuff in here.
>    }
> cfg is my initialized and parsed configuration file,
> and section is a pointer to each individual section in
> that configuration file. My question is, what is the
> procedure for freeing memory associated with this file
> in the event that the function must exit within that
> for loop (for example, a failed malloc call)?
> Currently I am calling cfg_free() on both pointers. Is
> this necessary? If not what all needs to be
> cfg_free()'d?

You should not call cfg_free on the section returned by cfg_getnsec.
Only call cfg_free on the top cfg pointer (as returned by cfg_init).

> 3. I have been operating under the assumption that
> cfg_getstr() returns a malloc()'d string that must be
> eventually free()'d. Is this assumption true? I did a
> small test and free()'d one of the strings returned by
> this function and it did not crash the program, but I
> would just like to confirmation from the creators. :)

No, cfg_get(n)str returns the string directly. It is not malloc'ed, and
should not be free'd directly. cfg_free(cfg) will free the string.

> 4. CFG_STR is defined as CFG_STR(name, def, flags).
> What is the significance of the second paramater;
> default value or what? Also, what kind of flags can be
> passed to this function? Maybe some flag could be
> passed to satisfy what I was asking about in question
> #1?

Yes, the second parameter is the default value for the string (or
whatever value it is).

Currently there are no flags you can set, just pass in CFGF_NONE.

> 5. Is there a comprehensive tutorial or usage guide
> for libConfuse? It seems to be a very useful tool but
> it is leaving me a li(l)b(it)Confuse(d) (sorry,
> couldnt resist). If not I think this is the only
> lacking element that is preventing the library from
> being an outstanding piece of work. The Doxygen
> generated help files seem to lack focus and direction.

Unfortunately there isn't, except for the example programs (and they are
not structured as a tutorial). A comprehensive tutorial will be written
in my copious free time :-)

> Thanks so much for your reply and this wonderful
> software.
> 
> -k
> 

HTH
/Martin Hedenfalk