## prelude-option

prelude-option

## Synopsis

    enum                prelude_option_type_t;
    enum                prelude_option_input_type_t;
    typedef             prelude_option_t;
    typedef             prelude_option_context_t;
    int                 (*prelude_option_destroy_callback_t)
                                                            (prelude_option_t *opt,
                                                             prelude_string_t *out,
                                                             void *context);
    int                 (*prelude_option_commit_callback_t) (prelude_option_t *opt,
                                                             prelude_string_t *out,
                                                             void *context);
    int                 (*prelude_option_get_callback_t)    (prelude_option_t *opt,
                                                             prelude_string_t *out,
                                                             void *context);
    int                 (*prelude_option_set_callback_t)    (prelude_option_t *opt,
                                                             const char *optarg,
                                                             prelude_string_t *err,
                                                             void *context);
    enum                prelude_option_argument_t;
    enum                prelude_option_priority_t;
    enum                prelude_option_warning_t;
    void                prelude_option_set_priority         (prelude_option_t *option,
                                                             prelude_option_priority_t priority);
    void                prelude_option_print                (prelude_option_t *opt,
                                                             prelude_option_type_t type,
                                                             int descoff,
                                                             FILE *fd);
    int                 prelude_option_wide_send_msg        (prelude_msgbuf_t *msgbuf,
                                                             void *context);
    void                prelude_option_destroy              (prelude_option_t *option);
    int                 prelude_option_read                 (prelude_option_t *option,
                                                             const char **filename,
                                                             int *argc,
                                                             char **argv,
                                                             prelude_string_t **err,
                                                             void *context);
    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 (setprelude_option_t *opt, const char *optarg, prelude_string_t *err, void *context) (),
                                                             int (getprelude_option_t *opt, prelude_string_t *out, void *context) ());
    void                prelude_option_set_type             (prelude_option_t *opt,
                                                             prelude_option_type_t type);
    prelude_option_type_t  prelude_option_get_type          (prelude_option_t *opt);
    void                prelude_option_set_warnings         (prelude_option_warning_t new_warnings,
                                                             prelude_option_warning_t *old_warnings);
    char                prelude_option_get_shortname        (prelude_option_t *opt);
    const char *        prelude_option_get_longname         (prelude_option_t *opt);
    void                prelude_option_set_data             (prelude_option_t *opt,
                                                             void *data);
    void *              prelude_option_get_data             (prelude_option_t *opt);
    void *              prelude_option_context_get_data     (prelude_option_context_t *oc);
    void                prelude_option_context_set_data     (prelude_option_context_t *oc,
                                                             void *data);
    int                 prelude_option_invoke_commit        (prelude_option_t *opt,
                                                             const char *ctname,
                                                             prelude_string_t *value,
                                                             void *context);
    int                 prelude_option_invoke_set           (prelude_option_t *opt,
                                                             const char *ctname,
                                                             prelude_string_t *value,
                                                             void **context);
    int                 prelude_option_invoke_get           (prelude_option_t *opt,
                                                             const char *ctname,
                                                             prelude_string_t *value,
                                                             void *context);
    int                 prelude_option_invoke_destroy       (prelude_option_t *opt,
                                                             const char *ctname,
                                                             prelude_string_t *value,
                                                             void *context);
    int                 prelude_option_new_root             (prelude_option_t **retopt);
    int                 prelude_option_new                  (prelude_option_t *parent,
                                                             prelude_option_t **retopt);
    void                prelude_option_set_longopt          (prelude_option_t *opt,
                                                             const char *longopt);
    const char *        prelude_option_get_longopt          (prelude_option_t *opt);
    void                prelude_option_set_description      (prelude_option_t *opt,
                                                             const char *description);
    const char *        prelude_option_get_description      (prelude_option_t *opt);
    void                prelude_option_set_has_arg          (prelude_option_t *opt,
                                                             prelude_option_argument_t has_arg);
    prelude_option_argument_t  prelude_option_get_has_arg   (prelude_option_t *opt);
    void                prelude_option_set_value            (prelude_option_t *opt,
                                                             const char *value);
    const char *        prelude_option_get_value            (prelude_option_t *opt);
    void                prelude_option_set_help             (prelude_option_t *opt,
                                                             const char *help);
    const char *        prelude_option_get_help             (prelude_option_t *opt);
    void                prelude_option_set_input_validation_regex
                                                            (prelude_option_t *opt,
                                                             const char *regex);
    const char *        prelude_option_get_input_validation_regex
                                                            (prelude_option_t *opt);
    void                prelude_option_set_input_type       (prelude_option_t *opt,
                                                             prelude_option_input_type_t input_type);
    prelude_option_input_type_t  prelude_option_get_input_type
                                                            (prelude_option_t *opt);
    prelude_list_t *    prelude_option_get_optlist          (prelude_option_t *opt);
    prelude_option_t *  prelude_option_get_next             (prelude_option_t *start,
                                                             prelude_option_t *cur);
    prelude_bool_t      prelude_option_has_optlist          (prelude_option_t *opt);
    prelude_option_t *  prelude_option_get_parent           (prelude_option_t *opt);
    void                prelude_option_set_destroy_callback (prelude_option_t *opt,
                                                             prelude_option_destroy_callback_t destroy);
    prelude_option_destroy_callback_t  prelude_option_get_destroy_callback
                                                            (prelude_option_t *opt);
    void                prelude_option_set_set_callback     (prelude_option_t *opt,
                                                             prelude_option_set_callback_t set);
    prelude_option_set_callback_t  prelude_option_get_set_callback
                                                            (prelude_option_t *opt);
    void                prelude_option_set_get_callback     (prelude_option_t *opt,
                                                             int (getprelude_option_t *opt, prelude_string_t *out, void *context) ());
    prelude_option_get_callback_t  prelude_option_get_get_callback
                                                            (prelude_option_t *opt);
    void                prelude_option_set_commit_callback  (prelude_option_t *opt,
                                                             prelude_option_commit_callback_t commit);
    prelude_option_commit_callback_t  prelude_option_get_commit_callback
                                                            (prelude_option_t *opt);
    void                prelude_option_set_default_context  (prelude_option_t *opt,
                                                             void *context);
    int                 prelude_option_new_context          (prelude_option_t *opt,
                                                             prelude_option_context_t **ctx,
                                                             const char *name,
                                                             void *data);
    void                prelude_option_context_destroy      (prelude_option_context_t *oc);
    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_context_t * prelude_option_search_context
                                                            (prelude_option_t *opt,
                                                             const char *name);

## Description

## Details

### enum prelude_option_type_t

    typedef enum {
            PRELUDE_OPTION_TYPE_CLI  = 0x01,
            PRELUDE_OPTION_TYPE_CFG  = 0x02,
            PRELUDE_OPTION_TYPE_WIDE = 0x04,
            PRELUDE_OPTION_TYPE_CONTEXT = 0x08,
            PRELUDE_OPTION_TYPE_ROOT    = 0x10,
            PRELUDE_OPTION_TYPE_DESTROY = 0x20
    } prelude_option_type_t;

### enum prelude_option_input_type_t

    typedef enum {
            PRELUDE_OPTION_INPUT_TYPE_STRING   = 1,
            PRELUDE_OPTION_INPUT_TYPE_INTEGER  = 2,
            PRELUDE_OPTION_INPUT_TYPE_BOOLEAN  = 3
    } prelude_option_input_type_t;

### prelude_option_t

    typedef struct prelude_option prelude_option_t;

### prelude_option_context_t

    typedef struct prelude_option_context prelude_option_context_t;

### prelude_option_destroy_callback_t ()

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

`opt` : |
`out` : |
`context` : |
Returns : |

### prelude_option_commit_callback_t ()

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

`opt` : |
`out` : |
`context` : |
Returns : |

### prelude_option_get_callback_t ()

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

`opt` : |
`out` : |
`context` : |
Returns : |

### prelude_option_set_callback_t ()

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

`opt` : |
`optarg` : |
`err` : |
`context` : |
Returns : |

### enum prelude_option_argument_t

    typedef enum {
            PRELUDE_OPTION_ARGUMENT_REQUIRED = 1,
            PRELUDE_OPTION_ARGUMENT_OPTIONAL = 2,
            PRELUDE_OPTION_ARGUMENT_NONE     = 3
    } prelude_option_argument_t;

### enum prelude_option_priority_t

    typedef enum {
            PRELUDE_OPTION_PRIORITY_IMMEDIATE = -2,
            PRELUDE_OPTION_PRIORITY_FIRST     = -1,
            PRELUDE_OPTION_PRIORITY_NONE      =  0,
            PRELUDE_OPTION_PRIORITY_LAST      =  2
    } prelude_option_priority_t;

### enum prelude_option_warning_t

    typedef enum {
            PRELUDE_OPTION_WARNING_OPTION    = 0x1,
            PRELUDE_OPTION_WARNING_ARG       = 0x2
    } prelude_option_warning_t;

### 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).

`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.

`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);

`msgbuf` : |
`context` : |
Returns : |

### 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).

`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.

`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 (setprelude_option_t *opt, const char *optarg, prelude_string_t *err, void *context) (),
                                                             int (getprelude_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.

`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);

`opt` : |
`type` : |

### prelude_option_get_type ()

    prelude_option_type_t  prelude_option_get_type          (prelude_option_t *opt);

`opt` : |
Returns : |

### prelude_option_set_warnings ()

    void                prelude_option_set_warnings         (prelude_option_warning_t new_warnings,
                                                             prelude_option_warning_t *old_warnings);

Set current warnings flags to `new_warnings`.

Uppon return, if not NULL, the pointer to `old_warnings` is updated to contain the old warnings.

`new_warnings` : | bitwise OR of prelude_option_warning_t.
`old_warnings` : | Pointer where to store the old prelude_option_warning_t to.

### prelude_option_get_shortname ()

    char                prelude_option_get_shortname        (prelude_option_t *opt);

`opt` : |
Returns : |

### prelude_option_get_longname ()

    const char *        prelude_option_get_longname         (prelude_option_t *opt);

`opt` : |
Returns : |

### prelude_option_set_data ()

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

`opt` : |
`data` : |

### prelude_option_get_data ()

    void *              prelude_option_get_data             (prelude_option_t *opt);

`opt` : |
Returns : |

### prelude_option_context_get_data ()

    void *              prelude_option_context_get_data     (prelude_option_context_t *oc);

`oc` : |
Returns : |

### prelude_option_context_set_data ()

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

`oc` : |
`data` : |

### prelude_option_invoke_commit ()

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

`opt` : |
`ctname` : |
`value` : |
`context` : |
Returns : |

### prelude_option_invoke_set ()

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

`opt` : |
`ctname` : |
`value` : |
`context` : |
Returns : |

### prelude_option_invoke_get ()

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

`opt` : |
`ctname` : |
`value` : |
`context` : |
Returns : |

### prelude_option_invoke_destroy ()

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

`opt` : |
`ctname` : |
`value` : |
`context` : |
Returns : |

### prelude_option_new_root ()

    int                 prelude_option_new_root             (prelude_option_t **retopt);

`retopt` : |
Returns : |

### prelude_option_new ()

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

`parent` : |
`retopt` : |
Returns : |

### prelude_option_set_longopt ()

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

`opt` : |
`longopt` : |

### prelude_option_get_longopt ()

    const char *        prelude_option_get_longopt          (prelude_option_t *opt);

`opt` : |
Returns : |

### prelude_option_set_description ()

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

`opt` : |
`description` : |

### prelude_option_get_description ()

    const char *        prelude_option_get_description      (prelude_option_t *opt);

`opt` : |
Returns : |

### prelude_option_set_has_arg ()

    void                prelude_option_set_has_arg          (prelude_option_t *opt,
                                                             prelude_option_argument_t has_arg);

`opt` : |
`has_arg` : |

### prelude_option_get_has_arg ()

    prelude_option_argument_t  prelude_option_get_has_arg   (prelude_option_t *opt);

`opt` : |
Returns : |

### prelude_option_set_value ()

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

`opt` : |
`value` : |

### prelude_option_get_value ()

    const char *        prelude_option_get_value            (prelude_option_t *opt);

`opt` : |
Returns : |

### prelude_option_set_help ()

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

`opt` : |
`help` : |

### prelude_option_get_help ()

    const char *        prelude_option_get_help             (prelude_option_t *opt);

`opt` : |
Returns : |

### prelude_option_set_input_validation_regex ()

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

`opt` : |
`regex` : |

### prelude_option_get_input_validation_regex ()

    const char *        prelude_option_get_input_validation_regex
                                                            (prelude_option_t *opt);

`opt` : |
Returns : |

### prelude_option_set_input_type ()

    void                prelude_option_set_input_type       (prelude_option_t *opt,
                                                             prelude_option_input_type_t input_type);

`opt` : |
`input_type` : |

### prelude_option_get_input_type ()

    prelude_option_input_type_t  prelude_option_get_input_type
                                                            (prelude_option_t *opt);

`opt` : |
Returns : |

### prelude_option_get_optlist ()

    prelude_list_t *    prelude_option_get_optlist          (prelude_option_t *opt);

`opt` : |
Returns : |

### prelude_option_get_next ()

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

`start` : |
`cur` : |
Returns : |

### prelude_option_has_optlist ()

    prelude_bool_t      prelude_option_has_optlist          (prelude_option_t *opt);

`opt` : |
Returns : |

### prelude_option_get_parent ()

    prelude_option_t *  prelude_option_get_parent           (prelude_option_t *opt);

`opt` : |
Returns : |

### prelude_option_set_destroy_callback ()

    void                prelude_option_set_destroy_callback (prelude_option_t *opt,
                                                             prelude_option_destroy_callback_t destroy);

`opt` : |
`destroy` : |

### prelude_option_get_destroy_callback ()

    prelude_option_destroy_callback_t  prelude_option_get_destroy_callback
                                                            (prelude_option_t *opt);

`opt` : |
Returns : |

### prelude_option_set_set_callback ()

    void                prelude_option_set_set_callback     (prelude_option_t *opt,
                                                             prelude_option_set_callback_t set);

`opt` : |
`set` : |

### prelude_option_get_set_callback ()

    prelude_option_set_callback_t  prelude_option_get_set_callback
                                                            (prelude_option_t *opt);

`opt` : |
Returns : |

### prelude_option_set_get_callback ()

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

`opt` : |
`get` : |

### prelude_option_get_get_callback ()

    prelude_option_get_callback_t  prelude_option_get_get_callback
                                                            (prelude_option_t *opt);

`opt` : |
Returns : |

### prelude_option_set_commit_callback ()

    void                prelude_option_set_commit_callback  (prelude_option_t *opt,
                                                             prelude_option_commit_callback_t commit);

`opt` : |
`commit` : |

### prelude_option_get_commit_callback ()

    prelude_option_commit_callback_t  prelude_option_get_commit_callback
                                                            (prelude_option_t *opt);

`opt` : |
Returns : |

### prelude_option_set_default_context ()

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

`opt` : |
`context` : |

### prelude_option_new_context ()

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

`opt` : |
`ctx` : |
`name` : |
`data` : |
Returns : |

### prelude_option_context_destroy ()

    void                prelude_option_context_destroy      (prelude_option_context_t *oc);

`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);

`parent` : |
`name` : |
`type` : |
`walk_children` : |
Returns : |

### prelude_option_search_context ()

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

`opt` : |
`name` : |
Returns : |