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_entry
s 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] >