#include "param_value.h"

Data Structures
struct	PARAM_ATR_st

Typedefs
typedef struct PARAM_st	PARAM

typedef enum PARAM_PARSE_OPTIONS_enum	PARAM_PARSE_OPTIONS

typedef enum PARAM_CONSTRAINTS_enum	PARAM_CONSTRAINTS

typedef struct PARAM_ATR_st	PARAM_ATR

Enumerations
enum	PARAM_CONSTRAINTS_enum { PARAM_SINGLE_VALUE = 0x0002, PARAM_SINGLE_VALUE_FOR_PRIORITY_LEVEL = 0x0004, PARAM_INVALID_CONSTRAINT = 0x8000 }

enum	PARAM_PARSE_OPTIONS_enum { PST_PRSCMD_NONE = 0x0000, PST_PRSCMD_HAS_NO_VALUE = 0x0002, PST_PRSCMD_HAS_VALUE = 0x0004, PST_PRSCMD_HAS_VALUE_SEQUENCE = 0x0008, PST_PRSCMD_BREAK_WITH_POTENTIAL_PARAMETER = 0x0010, PST_PRSCMD_BREAK_WITH_EXISTING_PARAMETER_MATCH = 0x0020, PST_PRSCMD_DEFAULT = 0x0001 \| PST_PRSCMD_BREAK_WITH_POTENTIAL_PARAMETER, PST_PRSCMD_COLLECT_LOOSE_VALUES = 0x0040, PST_PRSCMD_COLLECT_LOOSE_FLAGS = 0x0080, PST_PRSCMD_COLLECT_WHEN_PARSING_IS_CLOSED = 0x0100, PST_PRSCMD_CLOSE_PARSING = 0x0200, PST_PRSCMD_COLLECT_HAS_LOWER_PRIORITY = 0x0400, PST_PRSCMD_HAS_NO_FLAG = 0x0800, PST_PRSCMD_NO_TYPOS = 0x1000, PST_PRSCMD_FORMAT_CONTROL_ONLY_FOR_LAST_HIGHST_PRIORITY_VALUE = 0x2000, PST_PRSCMD_EXPAND_WILDCARD = 0x4000, PST_PRSCMD_COLLECT_LIMITER_BREAK_ON = 0x00008000, PST_PRSCMD_COLLECT_LIMITER_1X = 0x00010000, PST_PRSCMD_COLLECT_LIMITER_MAX_MASK = 0xffff0000 }

Functions
int	PARAM_new (const char flagName, const char flagAlias, int constraint, int pars_opt, PARAM **newObj)

void	PARAM_free (PARAM *param)

int	PARAM_addControl (PARAM param, int(controlFormat)(const char ), int(controlContent)(const char ), int(convert)(const char , char , unsigned))

int	PARAM_isParseOptionSet (PARAM *param, int state)

int	PARAM_setParseOption (PARAM *param, int option)

int	PARAM_setObjectExtractor (PARAM param, int(extractObject)(void *, const char , void **))

int	PARAM_addValue (PARAM param, const char value, const char *source, int prio)

int	PARAM_getValue (PARAM param, const char source, int prio, int at, PARAM_VAL **value)

int	PARAM_getAtr (PARAM param, const char source, int prio, int at, PARAM_ATR *atr)

int	PARAM_getName (PARAM param, const char name, const char *alias)

int	PARAM_getObject (PARAM param, const char source, int prio, int at, void extra, void value)

int	PARAM_getInvalid (PARAM param, const char source, int prio, int at, PARAM_VAL **value)

int	PARAM_getValueCount (PARAM param, const char source, int prio, int *count)

int	PARAM_getInvalidCount (PARAM param, const char source, int prio, int *count)

int	PARAM_setPrintName (PARAM param, const char constv, const char (getPrintName)(PARAM param, char buf, unsigned buf_len))

int	PARAM_setPrintNameAlias (PARAM param, const char constv, const char (getPrintNameAlias)(PARAM param, char buf, unsigned buf_len))

const char *	PARAM_getPrintName (PARAM *obj)

const char *	PARAM_getPrintNameAlias (PARAM *obj)

int	PARAM_setHelpText (PARAM param, const char txt)

const char *	PARAM_getHelpText (PARAM *obj)

int	PARAM_checkConstraints (const PARAM *param, int constraints)

int	PARAM_clearAll (PARAM *param)

int	PARAM_clearValue (PARAM param, const char source, int prio, int at)

int	PARAM_setWildcardExpander (PARAM param, const char charList, void ctx, void(ctx_free)(void ), int(expand_wildcard)(PARAM_VAL param_value, void ctx, int *value_shift))

int	PARAM_expandWildcard (PARAM param, int count)

char *	PARAM_toString (const PARAM param, char buf, size_t buf_len)

char *	PARAM_constraintErrorToString (PARAM param, const char prefix, char *buf, size_t buf_len)

Typedef Documentation

◆ PARAM

typedef struct PARAM_st PARAM

Parameter object that has a name and list of values. Accessing values in sequence (index is increased) is optimized. Contains optional functionality for format and content checking.

◆ PARAM_ATR

typedef struct PARAM_ATR_st PARAM_ATR

◆ PARAM_CONSTRAINTS

typedef enum PARAM_CONSTRAINTS_enum PARAM_CONSTRAINTS

◆ PARAM_PARSE_OPTIONS

typedef enum PARAM_PARSE_OPTIONS_enum PARAM_PARSE_OPTIONS

Enumeration Type Documentation

◆ PARAM_CONSTRAINTS_enum

enum PARAM_CONSTRAINTS_enum

Enumerator
PARAM_SINGLE_VALUE	Only a single value is allowed.
PARAM_SINGLE_VALUE_FOR_PRIORITY_LEVEL	Only a single value is allowed at each priority level.
PARAM_INVALID_CONSTRAINT	Invalid constraint.

◆ PARAM_PARSE_OPTIONS_enum

enum PARAM_PARSE_OPTIONS_enum

This is the list of PARAM parsing options that will affect how the parameters are parsed from the command line. Parsing options will guide how function PARAM_SET_parseCMD fills PARAM_SET internal PARAM values.

(Potential) parameter for a command-line parser is a token that has dash in prefix (e.q. '-x', '-xy', '--zzz', '---'). Unknown parameter is parameter that is not specified in PARAM_SET parameter list. Note that by using parsing options it is still possible to interpret "parameters" as values (e.g. parameter '--conf' may take configuration file with odd name '--conf' as input: '--conf --conf').

Terms used in parsing option descriptions:

curr - Current parameter whose parsing options are active.
known or unknown - A known and unknown parameter, accordingly.
param - Both known and unknown parameter.
bindv - A value that belongs to curr and is bound with it.
loose value or parameter - A value that is not bound with param or unknown parameter, accordingly.
token - Can be interpreted as anything.

Usage examples:

1) Default behavior.
  cmd: "-a -a x z -b y"
  PARAM_SET = {a, b}
    a = PST_PRSCMD_DEFAULT
    b = PST_PRSCMD_DEFAULT
  PARSE cmd:
    a = {NULL, x}
    b = {y}
    unknown/typo = {z}
2) Has a value and has not a value.
  cmd = "-a -a -b -a -b -b -b v -b"
  PARAM_SET = {a, b, c}
    a = PST_PRSCMD_HAS_NO_VALUE
    b = PST_PRSCMD_HAS_VALUE
    c = PST_PRSCMD_DEFAULT
  PARSE cmd:
    a = {NULL, NULL}
    b = {"-a", "-b", "v", NULL}
    c = {}
3) Has value with break.
  cmd = "-a y -a -b -x -b -a z"
  PARAM_SET = {a, b}
    a = PST_PRSCMD_HAS_VALUE | PST_PRSCMD_BREAK_WITH_POTENTIAL_PARAMETER
    b = PST_PRSCMD_HAS_VALUE | PST_PRSCMD_BREAK_WITH_EXISTING_PARAMETER_MATCH
  PARSE cmd:
    a = {"y", NULL, "z"}
    b = {"-x", NULL}
4) Value with and without typos.
  cmd = "xbc xde"
  PARAM_SET = {abc, bde}
    abc = PST_PRSCMD_HAS_NO_VALUE | PST_PRSCMD_NO_TYPOS
    bde = PST_PRSCMD_HAS_NO_VALUE
  PARSE cmd:
    unknown = {xbc}
    typo = {xde}
    abc = {}
    bde = {}
5) Has value sequence with break.
  cmd = "-a x y z -c v -a -a w -b -x -y -c w"
  PARAM_SET = {a, b, c}
    a = PST_PRSCMD_HAS_VALUE_SEQUENCE | PST_PRSCMD_BREAK_WITH_POTENTIAL_PARAMETER
    b = PST_PRSCMD_HAS_VALUE_SEQUENCE | PST_PRSCMD_BREAK_WITH_EXISTING_PARAMETER_MATCH
    c = PST_PRSCMD_DEFAULT
  PARSE cmd:
    a = {"x", "y", "z", NULL, "w"}
    b = {"-x", "-y"}
    c = {"v", "w"}
6) Collect values not bound with any parameter.
  cmd = "-i x -b y z -a w"
  PARAM_SET = {i, a, b}
    i = PST_PRSCMD_HAS_VALUE | PST_PRSCMD_COLLECT_LOOSE_VALUES
    a = PST_PRSCMD_HAS_VALUE
    b = PST_PRSCMD_HAS_NO_VALUE
  PARSE cmd:
    i = {"x", "y", "z"}
    a = {"w"}
    b = {NULL}
7) Collect all loose values and enable parameter '--' to close parsing and redirect all tokens to parameter 'j'.
  cmd = "x y z -i v -j w -i -- -- -- - -i -j"
  PARAM_SET = {i, j}
    i = PST_PRSCMD_HAS_VALUE | PST_PRSCMD_COLLECT_LOOSE_VALUES
    j = PST_PRSCMD_HAS_VALUE | PST_PRSCMD_CLOSE_PARSING | PST_PRSCMD_COLLECT_WHEN_PARSING_IS_CLOSED
  PARSE cmd:
    i = {"x", "y", "z", "v", "--"}
    j = {"w", "--", "-", "-i", "-j"}
8) Create a hidden parameter (that can not be explicitly added from the command-line) to collect all tokens after '--'.
  cmd = "-i x -a y -- z w v"
  PARAM_SET = {a, i}
    a = PST_PRSCMD_HAS_VALUE
    i = PST_PRSCMD_HAS_VALUE | PST_PRSCMD_CLOSE_PARSING | PST_PRSCMD_COLLECT_WHEN_PARSING_IS_CLOSED | PST_PRSCMD_HAS_NO_FLAG | PST_PRSCMD_NO_TYPOS
  PARSE cmd:
    a = {"y"}
    i = {"z", "w", "v"}
    unknown/typo = {"-i", "x"}
9) Create a parameter that has no flag but can collect up to 3 values that are not bound with any parameter.
  cmd = "x -a v y -i z w"
  PARAM_SET = {a, i}
    a = PST_PRSCMD_HAS_VALUE
    i = PST_PRSCMD_HAS_VALUE | PST_PRSCMD_HAS_NO_FLAG | PST_PRSCMD_NO_TYPOS | PST_PRSCMD_COLLECT_LOOSE_VALUES | PST_PRSCMD_COLLECT_LIMITER_BREAK_ON | ((PST_PRSCMD_COLLECT_LIMITER_1X * 3) & PST_PRSCMD_COLLECT_LIMITER_MAX_MASK)
  PARSE cmd:
    a = {"v"}
    i = {"x", "y", "z"}
    unknown/typo = {"-i", "w"}
10) Implement and apply Wildcard expander that selects a value from the list:
  cmd = "-w qwe -w *c -w p* -w *e"
  list = {"abc", "qwe", "xbc", "aee"}
  PARAM_SET = {w}
    w = PST_PRSCMD_HAS_VALUE | PST_PRSCMD_EXPAND_WILDCARD
  PARSE cmd:
    w = {"qwe", ("abc", "xbc"),(),("qwe", "aee")}

See also: PARAM_SET_new and PARAM_SET_setParseOptions.

Enumerator
PST_PRSCMD_NONE
PST_PRSCMD_HAS_NO_VALUE	If set, the parameter must not have a value and next token from the command line is interpreted as next possible parameter (or unknown token). If the value is set to `NULL`, that indicates the occurrence of the parameter. curr token token ...
PST_PRSCMD_HAS_VALUE	If set, the parameter takes next token as its value even if it equals known/unknown parameter. If there is no next value to be read or a break occurred (see `notes`), the value is set to `NULL` indicating that the parameter was specified but it was not possible to get its value. // Without a break. curr bindv token ... // With potential parameter break. curr param token ... // With known parameter break. curr known token ... Note Using additional options PST_PRSCMD_BREAK_WITH_POTENTIAL_PARAMETER or PST_PRSCMD_BREAK_WITH_EXISTING_PARAMETER_MATCH it is possible to interpret the next token as parameter.
PST_PRSCMD_HAS_VALUE_SEQUENCE	If set, the parameter takes all the next tokens as its values even if some values equals to known/unknown parameters. If there is no next value to be read or a break occurred (see `notes`), the parsing of current parameter is closed. If during the parsing there were no values bound with the current parameter, its value is set to `NULL`, otherwise the parsing is closed without adding any new data to the PARAM. // Without a break. curr bindv bindv ... bindv // With potential parameter break. curr bindv bindv ... param token ... // With known parameter break. curr bindv bindv ... known token ... Note Using additional options PST_PRSCMD_BREAK_WITH_POTENTIAL_PARAMETER or PST_PRSCMD_BREAK_WITH_EXISTING_PARAMETER_MATCH it is possible to break the parsing of the current parameter and interpret the next token as parameter.
PST_PRSCMD_BREAK_WITH_POTENTIAL_PARAMETER	If parameter has dash in prefix, it is a potential parameter that can even be unknown parameter not specified in PARAM_SET (e.q. '-x', '-xy', '--zzz', '---'). Note Note that when PST_PRSCMD_CLOSE_PARSING is set for any parameter (not just the current one) in the set, '--' is considered as legal known parameter that will perform the break.
PST_PRSCMD_BREAK_WITH_EXISTING_PARAMETER_MATCH	If set and the next token matches with existing parameter, the value is interpreted as next parameter. Note Note that when PST_PRSCMD_CLOSE_PARSING is set for any parameter (not just the current one) in the set, '--' is considered as known parameter that will perform the break.
PST_PRSCMD_DEFAULT	The default parsing options interpret each token as potential parameter which can bind next token as its single value. curr bindv param param token ...
PST_PRSCMD_COLLECT_LOOSE_VALUES	Collects all tokens that are not bound with some parameter and that do not look like potential parameters. If used together with PST_PRSCMD_COLLECT_LIMITER_BREAK_ON, collect maximum count is limited. Note Note that by default, if not bound with some parameter, '-' and '--' are considered as loose values. But in case PST_PRSCMD_CLOSE_PARSING is set for any parameter (not just the current one) on the set, '--' is considered as known parameter that is not collected as a loose value.
PST_PRSCMD_COLLECT_LOOSE_FLAGS	Collects all loose (unknown or misspelled) parameters (e.q. '-x', '-xy', '--zzz', '---'). If used together with PST_PRSCMD_COLLECT_LIMITER_BREAK_ON, collect maximum count is limited. Attention No typos or unknowns are detected as all unknown or misspelled parameters are redirected to parameters with this options set.
PST_PRSCMD_COLLECT_WHEN_PARSING_IS_CLOSED	Using with PST_PRSCMD_CLOSE_PARSING collects everything after the parsing is closed. If used together with PST_PRSCMD_COLLECT_LIMITER_BREAK_ON collect maximum count is limited.
PST_PRSCMD_CLOSE_PARSING	Enables parameter '--' that ends the parsing of the command line, after that all tokens are redirected to parameters that have PST_PRSCMD_COLLECT_WHEN_PARSING_IS_CLOSED set. Value '--' can still be used when it is bound with a parameter (see PST_PRSCMD_HAS_VALUE). Note This option affects PST_PRSCMD_BREAK_WITH_POTENTIAL_PARAMETER, PST_PRSCMD_BREAK_WITH_EXISTING_PARAMETER_MATCH and PST_PRSCMD_COLLECT_LOOSE_VALUES.
PST_PRSCMD_COLLECT_HAS_LOWER_PRIORITY	Collect has one point lower priority.
PST_PRSCMD_HAS_NO_FLAG	Hides existing parameter from command-line parser. Parameter with this option can only be added from the code. Use together with PST_PRSCMD_NO_TYPOS to completely hide the parameter from the user.
PST_PRSCMD_NO_TYPOS	With this parameter no typos are generated for a parameter.
PST_PRSCMD_FORMAT_CONTROL_ONLY_FOR_LAST_HIGHST_PRIORITY_VALUE	Only the highest priority last parameter format is checked in functions PARAM_SET_isFormatOK and PARAM_SET_invalidParametersToString. The error status is set in spite of the given option.
PST_PRSCMD_EXPAND_WILDCARD	If set, searches for the wildcard characters (`WC`) '``' and '`?`' in parameter values. If found, the value containing the `WC` is removed and replaced with the matching values. If no match was found, the removed value is not* pushed back. The `WC` expanding is performed by abstract `WC` expander function that must be implemented (see PARAM_SET_setWildcardExpander and PARAM_setWildcardExpander). If not implemented, parsing fails. See also PARAM_expandWildcard and PARAM_SET_parseCMD.
PST_PRSCMD_COLLECT_LIMITER_BREAK_ON	If set, this option will affect the maximum possible count of collected values during entire command-line parsing. It is possible to create multiple parameters with different count limits that are computed separately. If the limit for all counters is exceeded, the value is redirected to typo or unknown parameter check. This must be used together with PST_PRSCMD_COLLECT_LIMITER_1X * `N`, where `N` is the maximum count permitted. See PST_PRSCMD_COLLECT_LIMITER_MAX_MASK to get the maximum count value supported for a parameter. Example: PST_PRSCMD_COLLECT_LIMITER_BREAK_ON \| ((PST_PRSCMD_COLLECT_LIMITER_1X * 5) & PST_PRSCMD_COLLECT_LIMITER_MAX_MASK) Attention Make sure that the count value specified does not exceed the maximum supported value or spoil some other parse options. Use PST_PRSCMD_COLLECT_LIMITER_MAX_MASK to clean collect limiter parse option.
PST_PRSCMD_COLLECT_LIMITER_1X	One `unit` for collect limiter that is used together with PST_PRSCMD_COLLECT_LIMITER_BREAK_ON.
PST_PRSCMD_COLLECT_LIMITER_MAX_MASK	Collector count limit mask.

Function Documentation

◆ PARAM_addControl()

int PARAM_addControl	(	PARAM *	param,
		int()(const char )	controlFormat,
		int()(const char )	controlContent,
		int()(const char , char *, unsigned)	convert
	)

Adds several optional functions to a parameter. Each function takes the first parameters as C-string value (must not fail if is NULL). All the functions are applied when adding the value to the PARAM object.

Function controlFormat is to check the format. Returns 0 if format is ok, error code otherwise.

int (*controlFormat)(const char *str)

Function controlContent is to check the content. Returns 0 if content is ok, error code otherwise.

int (*controlContent)(const char *str)

Function convert is used to repair/convert the C-string value before any content or format check is performed. Takes two extra parameters for buffer and its size. Returns PST_OK if conversion is successful or PST_PARAM_CONVERT_NOT_PERFORMED to skip conversion. Any other error code will break adding the value.

int (*convert)(const char *value, char *buf, unsigned *buf_len)

Parameters

param	PARAM object.
controlFormat	Function for format checking.
controlContent	Function for content checking.
convert	Function for parameter value conversion.

Returns: PST_OK if successful, error code otherwise.

Note: Note that controlFormat and controlContent may return any error code but convert function should return PST_OK and PST_PARAM_CONVERT_NOT_PERFORMED as any other error code will break adding the simple value, parsing configuration file or command line.

◆ PARAM_addValue()

int PARAM_addValue	(	PARAM *	param,
		const char *	value,
		const char *	source,
		int	prio
	)

Appends value to the parameter. Invalid value format or content is not handled as error, but the state is saved. Internal format or content errors can be detected - see PARAM_getInvalid.

Parameters

param	PARAM object.
value	Parameter value as C-string. Can be `NULL`.
source	Source description as C-string. Can be `NULL`.
prio	Priority that can be `PST_PRIORITY_VALID_BASE` (`0`) or higher.

Returns: PST_OK when successful, error code otherwise.

See also: PARAM_getValueCount, PARAM_getInvalidCount, PARAM_getValue and PARAM_getInvalid.

◆ PARAM_checkConstraints()

int PARAM_checkConstraints	(	const PARAM *	param,
		int	constraints
	)

Checks if parameter constraints are satisfied (see PARAM_new and PARAM_CONSTRAINTS). Constraint values can be concatenated using '|'. Returned value contains all failed constraints concatenated ('|').

Parameters

param	PARAM object.
constraints	Concatenated constraints to be checked.

Returns: PST_OK when successful, error code otherwise. If failure due to NULL pointer PARAM_INVALID_CONSTRAINT is returned.

◆ PARAM_clearAll()

int PARAM_clearAll ( PARAM * param )

Clears all the values.

Parameters

param PARAM object.

Returns: PST_OK when successful, error code otherwise.

◆ PARAM_clearValue()

int PARAM_clearValue	(	PARAM *	param,
		const char *	source,
		int	prio,
		int	at
	)

Removes specified value.

Parameters

param	PARAM object.
source	Constraint for the source, can be `NULL`.
prio	Priority that can be `PST_PRIORITY_VALID_BASE` (`0`) or higher.
at	Parameter index in the matching set composed with the constraints.

Returns: PST_OK when successful, error code otherwise.

◆ PARAM_constraintErrorToString()

char* PARAM_constraintErrorToString	(	PARAM *	param,
		const char *	prefix,
		char *	buf,
		size_t	buf_len
	)

Generates constraint failure report.

Parameters

param	PARAM object.
prefix	Prefix to each constraint failure string. Can be `NULL`.
buf	Receiving buffer.
buf_len	Receiving buffer size.

Returns: buf if successful, NULL otherwise.

◆ PARAM_expandWildcard()

int PARAM_expandWildcard	(	PARAM *	param,
		int *	count
	)

Expands the values containing wildcard characters (WC). Before using WC expander abstract function must be implemented (See PARAM_setWildcardExpander).

Parameters

param	PARAM object.
count	The count of new values inserted.

Returns: PST_OK if successful, error code otherwise.

◆ PARAM_free()

void PARAM_free ( PARAM * param )

Frees PARAM object.

Parameters

param Pointer to object to be freed.

◆ PARAM_getAtr()

int PARAM_getAtr	(	PARAM *	param,
		const char *	source,
		int	prio,
		int	at,
		PARAM_ATR *	atr
	)

Same as PARAM_getValue, but instead of PARAM_VAL object it fills output parameter with PARAM attributes. Note that name in PARAM_ATR is the real string representation of the parameter name and is not altered by function PARAM_setPrintName. See PARAM_getPrintName to extract parameters print name.

Parameters

param	PARAM object.
source	Constraint for the source, can be `NULL`.
prio	Priority that can be `PST_PRIORITY_VALID_BASE` (`0`) or higher.
at	Parameter index in the matching set composed with the constraints.
atr	Pointer to PARAM_ATR object to store the result.

Returns: PST_OK when successful, error code otherwise. More common errors PST_INVALID_ARGUMENT, PST_PARAMETER_EMPTY and PST_PARAMETER_VALUE_NOT_FOUND.

◆ PARAM_getHelpText()

const char* PARAM_getHelpText ( PARAM * obj )

Returns the help text of the parameter. See PARAM_setHelpText to change the value.

Parameters

obj	PARAM object.

Returns: String that is the help text of the parameter. If value is not specified, NULL is returned.

◆ PARAM_getInvalid()

int PARAM_getInvalid	(	PARAM *	param,
		const char *	source,
		int	prio,
		int	at,
		PARAM_VAL **	value
	)

Same as PARAM_getValue but extracts only values that have invalid content or error status set. See PARAM_addControl how to apply value checking.

Parameters

param	PARAM object.
source	Constraint for the source, can be `NULL`.
prio	Priority that can be `PST_PRIORITY_VALID_BASE` (`0`) or higher.
at	Parameter index in the matching set composed with the constraints.
value	Pointer to receiving pointer to `PARAM_VAL` object.

Returns: PST_OK when successful, error code otherwise.

◆ PARAM_getInvalidCount()

int PARAM_getInvalidCount	(	PARAM *	param,
		const char *	source,
		int	prio,
		int *	count
	)

Returns parameter's invalid value count matching the constraints. See PARAM_addControl how to apply value checking.

Parameters

param	PARAM object.
source	Constraint for the source, can be `NULL`.
prio	Priority that can be `PST_PRIORITY_VALID_BASE` (`0`) or higher.
count	Pointer to to store the count value.

Returns: PST_OK when successful, error code otherwise.

◆ PARAM_getName()

int PARAM_getName	(	PARAM *	param,
		const char **	name,
		const char **	alias
	)

Extracts real name of parameter and/or its alias.

Parameters

param	PARAM object.
name	Pointer to receiving pointer to name.
alias	Pointer to receiving pointer to alias.

Returns: PST_OK when successful, error code otherwise.

◆ PARAM_getObject()

int PARAM_getObject	(	PARAM *	param,
		const char *	source,
		int	prio,
		int	at,
		void **	extra,
		void **	value
	)

Similar to function PARAM_getValue, but is used to extract a specific object from the C-string value. The functionality must be implemented by setting object extractor function. See PARAM_setObjectExtractor for more details.

Parameters

param	PARAM object.
source	Constraint for the source, can be `NULL`.
prio	Priority that can be `PST_PRIORITY_VALID_BASE` (`0`) or higher.
at	Parameter index in the matching set composed with the constraints.
extra	Pointer to optional extra data array.
value	Pointer to the receiving pointer to the value.

Returns: PST_OK when successful, error code otherwise. If object extractor implementation returns an error code, it is returned by this function. More common errors PST_INVALID_ARGUMENT, PST_PARAMETER_EMPTY, PST_PARAMETER_VALUE_NOT_FOUND, PST_PARAMETER_INVALID_FORMAT and PST_PARAMETER_UNIMPLEMENTED_OBJ.

Note: Note that if format or content status is invalid, it is not possible to extract the object. Custom object extractor may return error values that overlaps with local error codes!

Attention: Returned value must be freed by the user if the implementation requires it.

◆ PARAM_getPrintName()

const char* PARAM_getPrintName ( PARAM * obj )

Returns the string representation of the parameter. See PARAM_setPrintName to alter behaviour of this function. Default print format for long and short parameter is '--long' and '-a'.

Parameters

obj	PARAM object.

Returns: String that is the string representation of the parameter. Can return NULL.

◆ PARAM_getPrintNameAlias()

const char* PARAM_getPrintNameAlias ( PARAM * obj )

Same as PARAM_getPrintName but works with alias.

Parameters

obj	PARAM object.

Returns: String that is the string representation of the parameter alias. If alias does not exist, NULL is returned.

◆ PARAM_getValue()

int PARAM_getValue	(	PARAM *	param,
		const char *	source,
		int	prio,
		int	at,
		PARAM_VAL **	value
	)

Values are filtered by constraints where parameter at is used to index over values. If parameter is empty, PST_PARAMETER_EMPTY is returned. If there is no value matching the constraints error, PST_PARAMETER_VALUE_NOT_FOUND is returned.

Use PST_INDEX_LAST as at to extract the last value matching the constraints. If there are values with different priority levels use PST_PRIORITY_HIGHEST (see PST_PRIORITY_enum) to get the values with the highest priority. To extract values that have source specified, set source as desired value or if there is need to ignore the source, set source as NULL.

Parameters

param	PARAM object.
source	Constraint for the source, can be `NULL`.
prio	Priority that can be `PST_PRIORITY_VALID_BASE` (`0`) or higher.
at	Parameter index in the matching set composed with the constraints.
value	Pointer to receiving pointer to `PARAM_VAL` object.

Returns: PST_OK when successful, error code otherwise.

◆ PARAM_getValueCount()

int PARAM_getValueCount	(	PARAM *	param,
		const char *	source,
		int	prio,
		int *	count
	)

Returns parameter value count matching the constraints.

Parameters

param	PARAM object.
source	Constraint for the source, can be `NULL`.
prio	Priority that can be `PST_PRIORITY_VALID_BASE` (`0`) or higher.
count	Pointer to to store the count value.

Returns: PST_OK when successful, error code otherwise.

◆ PARAM_isParseOptionSet()

int PARAM_isParseOptionSet	(	PARAM *	param,
		int	state
	)

Checks if parse option or a group is set (can be concatenated together with '|').

Parameters

param	PARAM object.
state	A state to be controlled.

Returns: PST_OK if successful, error code otherwise.

See also: PARAM_PARSE_OPTIONS, PARAM_setParseOption and PARAM_SET_parseCMD for more information.

◆ PARAM_new()

int PARAM_new	(	const char *	flagName,
		const char *	flagAlias,
		int	constraint,
		int	pars_opt,
		PARAM **	newObj
	)

Creates a new and empty parameter.

Parameters

flagName	The parameter name.
flagAlias	The alias for the name. Can be `NULL`.
constraint	Constraints for the parameter and its values (see PARAM_CONSTRAINTS).
pars_opt	Parsing options (see PARAM_PARSE_OPTIONS). Can be `0`.
newObj	Pointer to receiving pointer to new object.

Returns: PST_OK when successful, error code otherwise.

Note: Note that it is possible to add multiple values to the list using function PARAM_addValue no matter what the constraint value is set to. To check the constraints see PARAM_checkConstraints.

◆ PARAM_setHelpText()

int PARAM_setHelpText	(	PARAM *	param,
		const char *	txt
	)

Sets help text for a parameter. The input value is copied.

Parameters

param	PARAM object.
txt	Help text for a parameter. Value is copied.

Returns: PST_OK when successful, error code otherwise.

◆ PARAM_setObjectExtractor()

int PARAM_setObjectExtractor	(	PARAM *	param,
		int()(void , const char , void **)	extractObject
	)

Sets object extractor to the parameter that implements PARAM_getObject.

Function extractObject is used to extract an object from the parameter value. Function extractObject affects PARAM_getObject behaviour. If not specified, the default function is used that extracts the C-string value. Parameter extra is void** pointer to array with 2 elements, str is parameter value and obj is pointer to receiving pointer. Calling PARAM_getObject both array elements in extra are pointing to PARAM_SET itself (void **extra = {set, set}), when calling PARAM_SET_getObjExtended, the second value is determined by the function call and extra parameter given (void **extra = {set, extra}). If extracting of the object is successful PST_OK must be returned, error code otherwise. int (*extractObject)(void **extra, const char *str, void **obj)

Parameters

param	PARAM object.
extractObject	Object extractor.

Returns: PST_OK when successful, error code otherwise.

◆ PARAM_setParseOption()

int PARAM_setParseOption	(	PARAM *	param,
		int	option
	)

Specifies parsing options (PARAM_PARSE_OPTIONS) used by PARAM_SET_parseCMD.

Parameters

param	PARAM object.
option	Parsing options.

Returns: PST_OK if successful, error code otherwise. PST_PRSCMD_INVALID_COMBINATION is returned if conflicting parsing option combination is fed to the function.

◆ PARAM_setPrintName()

int PARAM_setPrintName	(	PARAM *	param,
		const char *	constv,
		const char ()(PARAM param, char buf, unsigned buf_len)	getPrintName
	)

Alters the way the parameter is represented in (error) messages or returned by PARAM_getPrintName. It does not change the parameters real name that is used to get it from PARAM_SET object.

If constv is not NULL, a user specified constant value is used. If constv is NULL an abstract function getPrintName must be specified that formats the string. Default print format for long and short parameter is '--long' and '-a'.

const char* (*getPrintName)(PARAM *param, char *buf, unsigned buf_len) param - PARAM object. buf - Internal buffer with constant size. May be left unused. buf_len - The size of the internal buffer. Returns string that is the string representation of the parameter.

Parameters

param	PARAM object.
constv	Constant string representation of the parameter. Value is copied. Can be `NULL`.
getPrintName	Abstract function's implementation. Has effect only when `constv` is `NULL`. Can be `NULL`.

Returns: PST_OK when successful, error code otherwise.

◆ PARAM_setPrintNameAlias()

int PARAM_setPrintNameAlias	(	PARAM *	param,
		const char *	constv,
		const char ()(PARAM param, char buf, unsigned buf_len)	getPrintNameAlias
	)

Same as PARAM_setPrintName but works with the alias.

Parameters

param	PARAM object.
constv	Constant string representation of the parameter alias. Value is copied. Can be `NULL`.
getPrintNameAlias	Abstract function's implementation. Has effect only when `constv` is `NULL`. Can be `NULL`.

Returns: PST_OK when successful, error code otherwise. Return PST_ALIAS_NOT_SPECIFIED if parameter do not have alias.

◆ PARAM_setWildcardExpander()

int PARAM_setWildcardExpander	(	PARAM *	param,
		const char *	charList,
		void *	ctx,
		void()(void )	ctx_free,
		int()(PARAM_VAL param_value, void ctx, int value_shift)	expand_wildcard
	)

Specifies a function to expand tokens that contain wildcard character (WC) to array of new values. By default characters '?' and '*' are WC. Values containing WC are removed and replaced with the expanded values. To use default WC set charList as NULL.

int (*expand_wildcard)(PARAM_VAL *param_value, void *ctx, int *value_shift)

param_value - The value of the current parameter that contains WC. ctx - Additional data structure (same object as PARAM_SET_setWildcardExpander input parameter ctx. value_shift - Output parameter for the count of values expanded.

Parameters

param	PARAM_SET object.
charList	List of wildcard characters used. When set to `NULL` '`*?`' is used.
ctx	Data structure used by Wildcard expander. Can be `NULL`.
ctx_free	Data structure release function. Can be `NULL`.
expand_wildcard	Function pointer to wildcard Expander function.

Returns: PST_OK if successful, error code otherwise.

Note: PARAM_SET_parseCMD must be used and parsing option PST_PRSCMD_EXPAND_WILDCARD must be set using PARAM_SET_setParseOptions.

See also: Implemented wildcard expanders

◆ PARAM_toString()

char* PARAM_toString	(	const PARAM *	param,
		char *	buf,
		size_t	buf_len
	)

Generates PARAM object description string. Useful for debugging.

Parameters

param	PARAM object.
buf	Receiving buffer.
buf_len	Receiving buffer size.

Returns: buf if successful, NULL otherwise.

Data Structures

Typedefs

Enumerations

Functions

Typedef Documentation

◆ PARAM

◆ PARAM_ATR

◆ PARAM_CONSTRAINTS

◆ PARAM_PARSE_OPTIONS

Enumeration Type Documentation

◆ PARAM_CONSTRAINTS_enum

◆ PARAM_PARSE_OPTIONS_enum

Function Documentation

◆ PARAM_addControl()

◆ PARAM_addValue()

◆ PARAM_checkConstraints()

◆ PARAM_clearAll()

◆ PARAM_clearValue()

◆ PARAM_constraintErrorToString()

◆ PARAM_expandWildcard()

◆ PARAM_free()

◆ PARAM_getAtr()

◆ PARAM_getHelpText()

◆ PARAM_getInvalid()

◆ PARAM_getInvalidCount()

◆ PARAM_getName()

◆ PARAM_getObject()

◆ PARAM_getPrintName()

◆ PARAM_getPrintNameAlias()

◆ PARAM_getValue()

◆ PARAM_getValueCount()

◆ PARAM_isParseOptionSet()

◆ PARAM_new()

◆ PARAM_setHelpText()

◆ PARAM_setObjectExtractor()

◆ PARAM_setParseOption()

◆ PARAM_setPrintName()

◆ PARAM_setPrintNameAlias()

◆ PARAM_setWildcardExpander()

◆ PARAM_toString()