prelude-option: libprelude Reference Manual

## prelude-option prelude-option |

## Functions

int | (*prelude_option_destroy_callback_t) ()
int | (*prelude_option_commit_callback_t) ()
int | (*prelude_option_get_callback_t) ()
int | (*prelude_option_set_callback_t) ()
void | prelude_option_set_priority ()
void | prelude_option_print ()
int | prelude_option_wide_send_msg ()
void | prelude_option_destroy ()
int | prelude_option_read ()
int | prelude_option_add ()
void | prelude_option_set_type ()
prelude_option_type_t | prelude_option_get_type ()
void | prelude_option_set_warnings ()
char | prelude_option_get_shortname ()
const char * | prelude_option_get_longname ()
void | prelude_option_set_data ()
void * | prelude_option_get_data ()
void * | prelude_option_context_get_data ()
void | prelude_option_context_set_data ()
int | prelude_option_invoke_commit ()
int | prelude_option_invoke_set ()
int | prelude_option_invoke_get ()
int | prelude_option_invoke_destroy ()
int | prelude_option_new_root ()
int | prelude_option_new ()
void | prelude_option_set_longopt ()
const char * | prelude_option_get_longopt ()
void | prelude_option_set_description ()
const char * | prelude_option_get_description ()
void | prelude_option_set_has_arg ()
prelude_option_argument_t | prelude_option_get_has_arg ()
void | prelude_option_set_value ()
const char * | prelude_option_get_value ()
void | prelude_option_set_help ()
const char * | prelude_option_get_help ()
void | prelude_option_set_input_validation_regex ()
const char * | prelude_option_get_input_validation_regex ()
void | prelude_option_set_input_type ()
prelude_option_input_type_t | prelude_option_get_input_type ()
prelude_list_t * | prelude_option_get_optlist ()
prelude_option_t * | prelude_option_get_next ()
prelude_bool_t | prelude_option_has_optlist ()
prelude_option_t * | prelude_option_get_parent ()
void | prelude_option_set_destroy_callback ()
prelude_option_destroy_callback_t | prelude_option_get_destroy_callback ()
void | prelude_option_set_set_callback ()
prelude_option_set_callback_t | prelude_option_get_set_callback ()
void | prelude_option_set_get_callback ()
prelude_option_get_callback_t | prelude_option_get_get_callback ()
void | prelude_option_set_commit_callback ()
prelude_option_commit_callback_t | prelude_option_get_commit_callback ()
void | prelude_option_set_default_context ()
int | prelude_option_new_context ()
void | prelude_option_context_destroy ()
prelude_option_t * | prelude_option_search ()
prelude_option_context_t * | prelude_option_search_context ()

## Types and Values

enum | prelude_option_type_t
enum | prelude_option_input_type_t
typedef | prelude_option_t
typedef | prelude_option_context_t
enum | prelude_option_argument_t
enum | prelude_option_priority_t
enum | prelude_option_warning_t

## Description

## Functions

### prelude_option_destroy_callback_t ()

    int
    (*prelude_option_destroy_callback_t) (prelude_option_t *opt,
                                          prelude_string_t *out,
                                          void *context);

### prelude_option_commit_callback_t ()

    int
    (*prelude_option_commit_callback_t) (prelude_option_t *opt,
                                         prelude_string_t *out,
                                         void *context);

### prelude_option_get_callback_t ()

    int
    (*prelude_option_get_callback_t) (prelude_option_t *opt,
                                      prelude_string_t *out,
                                      void *context);

### prelude_option_set_callback_t ()

    int
    (*prelude_option_set_callback_t) (prelude_option_t *opt,
                                      const char *optarg,
                                      prelude_string_t *err,
                                      void *context);

### prelude_option_set_priority ()

    void
    prelude_option_set_priority (prelude_option_t *option,
                                 prelude_option_priority_t priority);

prelude_option_set_priority() can be used to associate a priority with an option. This can be used to solve dependancies problem within differents options.

A priority of -1 mean an option will always be executed last (with all other option with a -1 priority).

The default priority for an option is 0, the caller is responssible for the way it assign priority (knowing that highest priority are always executed first).

#### Parameters

option | Pointer on an option object. |
priority | Priority of the option object. |

### prelude_option_print ()

    void
    prelude_option_print (prelude_option_t *opt,
                          prelude_option_type_t type,
                          int descoff,
                          FILE *fd);

Dump option available in `opt` and hooked to the given types. If `opt` is NULL, then the root of the option list is used.

#### Parameters

opt | Option(s) to print out. |
type | Only option with specified types will be printed. |
descoff | offset from the begining of the line where the description should start. |
fd | File descriptor where the option should be dumped. |

### prelude_option_wide_send_msg ()

    int
    prelude_option_wide_send_msg (prelude_msgbuf_t *msgbuf,
                                  void *context);

### prelude_option_destroy ()

    void
    prelude_option_destroy (prelude_option_t *option);

Destroy a prelude_option_t object and all data associated with it (including all suboption).

#### Parameters

option | Pointer on an option object. |

### prelude_option_read ()

    int
    prelude_option_read (prelude_option_t *option,
                         const char **filename,
                         int *argc,
                         char **argv,
                         prelude_string_t **err,
                         void *context);

prelude_option_read(), parse the given argument and try to match them against option in `option` . If an option match, it's associated callback function is called with the eventual option argument if any.

Option not matched on the command line are searched in the configuration file specified by `filename` .

if `option` is NULL, all system option will be matched against argc, and argv.

#### Parameters

option | A pointer on an option (list). |
filename | Pointer to the config filename. |
argc | Number of argument. |
argv | Argument list. |
err | Pointer to a prelude_string_t object where to store an error string. |
context | Pointer to an optional option context. |

#### Returns

The index of the first unhandled parameter if option parsing succeeded, or a negative value if an error occured.

### prelude_option_add ()

    int
    prelude_option_add (prelude_option_t *parent,
                        prelude_option_t **retopt,
                        prelude_option_type_t type,
                        char shortopt,
                        const char *longopt,
                        const char *desc,
                        prelude_option_argument_t has_arg,
                        int (*set) (prelude_option_t *opt, const char *optarg, prelude_string_t *err, void *context),
                        int (*get) (prelude_option_t *opt, prelude_string_t *out, void *context));

prelude_option_add() create a new option. The option is set to be the child of `parent` , unless it is NULL. In this case the option is a root option.

The `type` parameters can be set to PRELUDE_OPTION_TYPE_CLI (telling the option may be searched on the command line), PRELUDE_OPTION_TYPE_CFG (telling the option may be searched in the configuration file) or both.

#### Parameters

parent | Pointer on a parent option. |
retopt | Pointer where to store the created option. |
type | bitfields. |
shortopt | Short option name. |
longopt | Long option name. |
desc | Description of the option. |
has_arg | Define if the option has argument. |
set | Callback to be called when the value for this option change. |
get | Callback to be called to get the value for this option. |

#### Returns

Pointer on the option object, or NULL if an error occured.

### prelude_option_set_type ()

    void
    prelude_option_set_type (prelude_option_t *opt,
                             prelude_option_type_t type);

### prelude_option_get_type ()

    prelude_option_type_t
    prelude_option_get_type (prelude_option_t *opt);

### prelude_option_set_warnings ()

    void
    prelude_option_set_warnings (prelude_option_warning_t new_warnings,
                                 prelude_option_warning_t *old_warnings);

### prelude_option_get_shortname ()

    char
    prelude_option_get_shortname (prelude_option_t *opt);

### prelude_option_get_longname ()

    const char *
    prelude_option_get_longname (prelude_option_t *opt);

### prelude_option_set_data ()

    void
    prelude_option_set_data (prelude_option_t *opt,
                             void *data);

### prelude_option_get_data ()

    void *
    prelude_option_get_data (prelude_option_t *opt);

### prelude_option_context_get_data ()

    void *
    prelude_option_context_get_data (prelude_option_context_t *oc);

### prelude_option_context_set_data ()

    void
    prelude_option_context_set_data (prelude_option_context_t *oc,
                                     void *data);

### prelude_option_invoke_commit ()

    int
    prelude_option_invoke_commit (prelude_option_t *opt,
                                  const char *ctname,
                                  prelude_string_t *value,
                                  void *context);

### prelude_option_invoke_set ()

    int
    prelude_option_invoke_set (prelude_option_t *opt,
                               const char *ctname,
                               prelude_string_t *value,
                               void **context);

### prelude_option_invoke_get ()

    int
    prelude_option_invoke_get (prelude_option_t *opt,
                               const char *ctname,
                               prelude_string_t *value,
                               void *context);

### prelude_option_invoke_destroy ()

    int
    prelude_option_invoke_destroy (prelude_option_t *opt,
                                   const char *ctname,
                                   prelude_string_t *value,
                                   void *context);

### prelude_option_new_root ()

    int
    prelude_option_new_root (prelude_option_t **retopt);

### prelude_option_new ()

    int
    prelude_option_new (prelude_option_t *parent,
                        prelude_option_t **retopt);

### prelude_option_set_longopt ()

    void
    prelude_option_set_longopt (prelude_option_t *opt,
                                const char *longopt);

### prelude_option_get_longopt ()

    const char *
    prelude_option_get_longopt (prelude_option_t *opt);

### prelude_option_set_description ()

    void
    prelude_option_set_description (prelude_option_t *opt,
                                    const char *description);

### prelude_option_get_description ()

    const char *
    prelude_option_get_description (prelude_option_t *opt);

### prelude_option_set_has_arg ()

    void
    prelude_option_set_has_arg (prelude_option_t *opt,
                                prelude_option_argument_t has_arg);

### prelude_option_get_has_arg ()

    prelude_option_argument_t
    prelude_option_get_has_arg (prelude_option_t *opt);

### prelude_option_set_value ()

    void
    prelude_option_set_value (prelude_option_t *opt,
                              const char *value);

### prelude_option_get_value ()

    const char *
    prelude_option_get_value (prelude_option_t *opt);

### prelude_option_set_help ()

    void
    prelude_option_set_help (prelude_option_t *opt,
                             const char *help);

### prelude_option_get_help ()

    const char *
    prelude_option_get_help (prelude_option_t *opt);

### prelude_option_set_input_validation_regex ()

    void
    prelude_option_set_input_validation_regex
                                   (prelude_option_t *opt,
                                    const char *regex);

### prelude_option_get_input_validation_regex ()

    const char *
    prelude_option_get_input_validation_regex
                                   (prelude_option_t *opt);

### prelude_option_set_input_type ()

    void
    prelude_option_set_input_type (prelude_option_t *opt,
                                   prelude_option_input_type_t input_type);

### prelude_option_get_input_type ()

    prelude_option_input_type_t
    prelude_option_get_input_type (prelude_option_t *opt);

### prelude_option_get_optlist ()

    prelude_list_t *
    prelude_option_get_optlist (prelude_option_t *opt);

### prelude_option_get_next ()

    prelude_option_t *
    prelude_option_get_next (prelude_option_t *start,
                             prelude_option_t *cur);

### prelude_option_has_optlist ()

    prelude_bool_t
    prelude_option_has_optlist (prelude_option_t *opt);

### prelude_option_get_parent ()

    prelude_option_t *
    prelude_option_get_parent (prelude_option_t *opt);

### prelude_option_set_destroy_callback ()

    void
    prelude_option_set_destroy_callback (prelude_option_t *opt,
                                         prelude_option_destroy_callback_t destroy);

### prelude_option_get_destroy_callback ()

    prelude_option_destroy_callback_t
    prelude_option_get_destroy_callback (prelude_option_t *opt);

### prelude_option_set_set_callback ()

    void
    prelude_option_set_set_callback (prelude_option_t *opt,
                                     prelude_option_set_callback_t set);

### prelude_option_get_set_callback ()

    prelude_option_set_callback_t
    prelude_option_get_set_callback (prelude_option_t *opt);

### prelude_option_set_get_callback ()

    void
    prelude_option_set_get_callback (prelude_option_t *opt,
                                     int (*get) (prelude_option_t *opt, prelude_string_t *out, void *context));

### prelude_option_get_get_callback ()

    prelude_option_get_callback_t
    prelude_option_get_get_callback (prelude_option_t *opt);

### prelude_option_set_commit_callback ()

    void
    prelude_option_set_commit_callback (prelude_option_t *opt,
                                        prelude_option_commit_callback_t commit);

### prelude_option_get_commit_callback ()

    prelude_option_commit_callback_t
    prelude_option_get_commit_callback (prelude_option_t *opt);

### prelude_option_set_default_context ()

    void
    prelude_option_set_default_context (prelude_option_t *opt,
                                        void *context);

### prelude_option_new_context ()

    int
    prelude_option_new_context (prelude_option_t *opt,
                                prelude_option_context_t **ctx,
                                const char *name,
                                void *data);

### prelude_option_context_destroy ()

    void
    prelude_option_context_destroy (prelude_option_context_t *oc);

### prelude_option_search ()

    prelude_option_t *
    prelude_option_search (prelude_option_t *parent,
                           const char *name,
                           prelude_option_type_t type,
                           prelude_bool_t walk_children);

### prelude_option_search_context ()

    prelude_option_context_t *
    prelude_option_search_context (prelude_option_t *opt,
                                   const char *name);

## Types and Values

### enum prelude_option_type_t

#### Members

PRELUDE_OPTION_TYPE_CLI |  |
PRELUDE_OPTION_TYPE_CFG |  |
PRELUDE_OPTION_TYPE_WIDE |  |
PRELUDE_OPTION_TYPE_CONTEXT |  |
PRELUDE_OPTION_TYPE_ROOT |  |
PRELUDE_OPTION_TYPE_DESTROY |  |

### enum prelude_option_input_type_t

#### Members

PRELUDE_OPTION_INPUT_TYPE_STRING |  |
PRELUDE_OPTION_INPUT_TYPE_INTEGER |  |
PRELUDE_OPTION_INPUT_TYPE_BOOLEAN |  |

### prelude_option_t

    typedef struct prelude_option prelude_option_t;

### prelude_option_context_t

    typedef struct prelude_option_context prelude_option_context_t;

### enum prelude_option_argument_t

#### Members

PRELUDE_OPTION_ARGUMENT_REQUIRED |  |
PRELUDE_OPTION_ARGUMENT_OPTIONAL |  |
PRELUDE_OPTION_ARGUMENT_NONE |  |

### enum prelude_option_priority_t

#### Members

PRELUDE_OPTION_PRIORITY_IMMEDIATE |  |
PRELUDE_OPTION_PRIORITY_FIRST |  |
PRELUDE_OPTION_PRIORITY_NONE |  |
PRELUDE_OPTION_PRIORITY_LAST |  |

### enum prelude_option_warning_t

#### Members

PRELUDE_OPTION_WARNING_OPTION |  |
PRELUDE_OPTION_WARNING_ARG |  |