vitalnix user management suite 3.2.0


Description

The libvxcli library provides a few common functions for the command-line (CLI) variants of various programs included.

Structures

#include <vitalnix/libvxcli/libvxcli.h>

struct vxcq_entry {
    const char *msg;
    const char *prompt;
    const char *defl;
    unsigned int type;
    unsigned int flags;
    void *ptr;
    int (*validate)(const struct vxcq_entry *);
};

struct vxcq_entry

The struct vxcq_entry is used to query a vector of questions.

->msg tooltip string to be printed, e.g. "Enter a file which contains..."
->prompt a prompt string, e.g. "Filename"
->defl default answer, if any
->type the type of ->ptr. Can be either of HXTYPE_STRING, HXTYPE_INT, HXTYPE_LONG or HXTYPE_DOUBLE
->flags a bitmask of CQ_ABORT and/or CQ_EMPTY (see below for details). You can specify CQ_NONE for convenience in favor of 0
->ptr pointer to where the answer should be stored
->validate a function that will be called (if non-NULL) to validate the user input. The question is asked again if validation returns zero

All pointers can be NULL.

Constants

VXCQ_TABLE_END is a macro that should be used as a sentinel to a struct vxcq_entry.

Function overview

#include <libvxcli/libvxcli.h>

char *vxcli_query(const char *msg, const char *prompt, const char *defl, unsigned int flags, char *buf, unsigned int size);
unsigned int vxcli_query_v(const struct vxcq_entry *table);

vxcli_query

Prints a message, a prompt and the default answer (msg, prompt and defl, respectively) and awaits input from stdin. flags is a bitmask that can contain:

VXCQ_ABORT If the input consists of a single ^A control character, the dialog is aborted.
VXCQ_EMPTY If the input consists of a single ^E control character, the answer is seen as empty. This is so that a truly empty answer (string length = 0) can be used for the default answer.
VXCQ_ZNULL If the answer is empty, *ptr will be assigned NULL.

If buf is not NULL, the result is put into buf, writing at most size-1 characters plus a '\0' character. buf is returned. If however, buf is NULL, the size paramter is ignored and a dynamic-size hmc_t container is returned. If the dialog was aborted, NULL is returned.

vxcli_query_v

Queries a vector of questions. It takes an array of struct vxcq_entrys and stores the results of each query in ->ptr. For strings, this will always create a hmc_t object. See example below for details. After each question, the ->validate function is invoked to see if the input is valid; if not, the query is repeated.

Returns the number of successfully answered questions.

Example

static int ymd_validate(const char *s) {
    return isdigit(s[0]) && isdigit(s[1]) && s[2] == '-' &&
           isdigit(s[3]) && isdigit(s[4]) && s[5] == '-' &&
           isdigit(s[6]) && isdigit(s[7]) &&
           isdigit(s[8]) && isdigit(s[9]);
}

hmc_t *today_date = NULL;
struct vxcq_entry tbl[] = {
    {
        .msg      = "Enter today's date",
        .defl     = "2006-03-04",
        .prompt   = "YYYY-MM-DD",
        .type     = HXTYPE_STRING,
        .ptr      = &today_date,
        .flags    = CQ_ABORT,
        .validate = ymd_validate,
    },
    VXCQ_TABLE_END,
};
vxcli_query_v(tbl);

Which would show up as:

Enter today's date
(Use <CTRL+A>,<Enter> to abort)
YYYY-MM-DD [2006-03-04] >