libcfg+: command line and configuration file parsing library
Prev | Chapter 2. Usage | Next

# 2.4. Parsing

After a libcfg+ context is created and its flags are set (optional), one can initiate the parsing. This chapter provides information about the available parsing methods.

    #include <cfg+.h>

``int cfg_parse`(const CFG_CONTEXT con);`

``int cfg_get_next_opt`(const CFG_CONTEXT con);`

These functions take a context as their only argument. Depending on the type of the context, either a file or a command line option will be processed. If the option just parsed matches one of the options in the option set (see Options set section) and the arguments of the parsed option are stored in memory and `value` is set to point to them. However, if the `value` of the relevant option in the option is set to `NULL`, the arguments will not be stored.

The main and only difference between the two functions is in the way they interpret the `val` field of the relevant option after a matching token was found in the token stream. The function `cfg_get_next_opt()` respects the value of this field and if it is not `0`, returns the value upon a match. If the field is set to `0`, the function proceeds to the next token without returning a value. In the case of `cfg_parse()`, `val` is ignored.

If an error occurs during parsing, the functions return a negative integer. This is why it is a good idea to set the `val` member of the cfg_option to a value equal or greater than `0`. Detailed information about error codes as well as their descriptions can be found in the Error handling section.

At the end of parsing `0` is returned.

The following functions provide additional information about a matched option.

    #include <cfg+.h>

``char *cfg_get_cur_opt`(const CFG_CONTEXT con);`

``char *cfg_get_cur_arg`(const CFG_CONTEXT con);`

``int cfg_get_cur_idx`(const CFG_CONTEXT con);`

Use `cfg_get_cur_opt()` to get the name of the option being processed. Use `cfg_get_cur_arg()`to get the current argument. Finally, use `cfg_get_cur_idx()` to get the current offset in the parsing stream. If the context is associated with the command line, the value is the current offset in the `argv` array. If the context is associated with a configuration file, then depending on the value of `CFG_FILE_LINE_POS_USAGE`, it is either the current byte offset or line number in the file.

Prev | Home | Next
Context flags | Up | Error handling