Helper functions for handling options

Overview

TAPI to handle tool options. More…

// typedefs

typedef te_errno (*tapi_job_opt_arg_format)(
    const void *opt,
    const void *priv,
    te_vec *arg
    );

typedef struct tapi_job_opt_bind tapi_job_opt_bind;
typedef struct tapi_job_opt_array tapi_job_opt_array;
typedef struct tapi_job_opt_struct tapi_job_opt_struct;
typedef te_optional_uint_t tapi_job_opt_uint_t;
typedef te_optional_uintmax_t tapi_job_opt_uintmax_t;
typedef te_optional_double_t tapi_job_opt_double_t;

// structs

struct tapi_job_opt_array;
struct tapi_job_opt_bind;
struct tapi_job_opt_struct;

// global functions

te_errno tapi_job_opt_build_args(const char* path, const tapi_job_opt_bind* binds, const void* opt, te_vec* tool_args);
te_errno tapi_job_opt_append_strings(const char** items, te_vec* tool_args);
te_errno tapi_job_opt_append_args(const tapi_job_opt_bind* binds, const void* opt, te_vec* tool_args);

// macros

#define TAPI_JOB_OPT_DOUBLE_UNDEF
#define TAPI_JOB_OPT_DOUBLE_VAL(_x)
#define TAPI_JOB_OPT_SET(...)
#define TAPI_JOB_OPT_UINTMAX_UNDEF
#define TAPI_JOB_OPT_UINTMAX_VAL(_x)
#define TAPI_JOB_OPT_UINT_UNDEF
#define TAPI_JOB_OPT_UINT_VAL(_x)

Detailed Documentation

TAPI to handle tool options.

Typedefs

typedef te_errno (*tapi_job_opt_arg_format)(
    const void *opt,
    const void *priv,
    te_vec *arg
    )

Formatting function pointer: put formatted command-line argument in a vector.

Parameters:

opt	Pointer to an argument, with specific type for every formatting function.
priv	Pointer to private data that may be needed for a formatting function.
arg	Vector to put formatted argument to. Functions are allowed to put multiple string in the vector. In that case multiple arguments will be created.
TE_ENOENT	The argument must be skipped (along with prefix/suffix);

Returns:

Status code

typedef struct tapi_job_opt_bind tapi_job_opt_bind

Bind between a tool’s option struct field and command line arguments.

Field here is a member of a struct. The struct is the tool’s custom struct with command line options.

typedef struct tapi_job_opt_array tapi_job_opt_array

The descriptor for an array-typed field. This structure shall never be used directly, see TAPI_JOB_OPT_ARRAY()

typedef struct tapi_job_opt_struct tapi_job_opt_struct

The descriptor for an struct-typed field. This structure shall never be used directly, see TAPI_JOB_OPT_STRUCT()

typedef te_optional_uint_t tapi_job_opt_uint_t

Unsigned integer which can be left undefined.

This is guaranteed to be assignment-compatible with te_optional_uint_t.

typedef te_optional_uintmax_t tapi_job_opt_uintmax_t

Unsigned long integer which can be left undefined.

This is guaranteed to be assignment-compatible with te_optional_uintmax_t.

typedef te_optional_double_t tapi_job_opt_double_t

Double which can be left undefined.

This is guaranteed to be assignment-compatible with te_optional_double_t.

Global Functions

te_errno tapi_job_opt_build_args(const char* path, const tapi_job_opt_bind* binds, const void* opt, te_vec* tool_args)

Create a vector with command line arguments by processing option binds.

tool_args contents is overwritten by this function, so it should have no elements prior to the call, or a memory leak would ensue.

Parameters:

path	Tool path (program location).
binds	Binds between `opt` and produced arguments, or `NULL`.
opt	Tool’s custom option struct which is forwarded to argument formatting callback, or `NULL` if the previous argument is `NULL`.
tool_args	Vector with command line arguments.

Returns:

Status code.

Macros

#define TAPI_JOB_OPT_DOUBLE_UNDEF

Undefined value for tapi_job_opt_double_t.

#define TAPI_JOB_OPT_DOUBLE_VAL(_x)

Defined value for tapi_job_opt_double_t.

Parameters:

_x	Value to set.

#define TAPI_JOB_OPT_SET(...)

A convenience vector constructor to define option binds

#define TAPI_JOB_OPT_UINTMAX_UNDEF

Undefined value for tapi_job_opt_uintmax_t.

#define TAPI_JOB_OPT_UINTMAX_VAL(_x)

Defined value for tapi_job_opt_uintmax_t.

Parameters:

_x	Value to set.

#define TAPI_JOB_OPT_UINT_UNDEF

Undefined value for tapi_job_opt_uint_t.

#define TAPI_JOB_OPT_UINT_VAL(_x)

Defined value for tapi_job_opt_uint_t.

Parameters:

_x	Value to set.

items	`NULL-terminated` array of strings (they are strdup’ed in the vector).
tool_args	Argument vector (must be initialized).