#include <stdio.h>
#include "param_value.h"
#include "parameter.h"

Macros
#define	PARAM_SET_ERROR_BASE 0x30001

Typedefs
typedef struct PARAM_SET_st	PARAM_SET

Functions
const char *	PST_getVersion (void)

int	PARAM_SET_new (const char names, PARAM_SET *set)

void	PARAM_SET_free (PARAM_SET *set)

int	PARAM_SET_addControl (PARAM_SET set, const char names, int(controlFormat)(const char ), int(controlContent)(const char ), int(convert)(const char , char , unsigned), int(extractObject)(void *, const char , void **))

int	PARAM_SET_setPrintName (PARAM_SET set, const char names, const char constv, const char (getPrintName)(PARAM param, char *buf, unsigned buf_len))

int	PARAM_SET_setPrintNameAlias (PARAM_SET set, const char names, const char constv, const char (getPrintName)(PARAM param, char *buf, unsigned buf_len))

int	PARAM_SET_setHelpText (PARAM_SET set, const char names, const char *txt)

char *	PARAM_SET_helpToString (const PARAM_SET set, const char names, int indent, int header, int rowWidth, char *buf, size_t buf_len)

int	PARAM_SET_add (PARAM_SET set, const char name, const char value, const char source, int priority)

int	PARAM_SET_getStr (PARAM_SET set, const char name, const char source, int priority, int at, char *value)

int	PARAM_SET_getObj (PARAM_SET set, const char name, const char source, int priority, int at, void *obj)

int	PARAM_SET_getObjExtended (PARAM_SET set, const char name, const char source, int priority, int at, void ctx, void **obj)

int	PARAM_SET_getAtr (PARAM_SET set, const char name, const char source, int priority, int at, PARAM_ATR atr)

int	PARAM_SET_getPrintName (PARAM_SET set, const char name, const char **print_name)

int	PARAM_SET_getPrintNameAlias (PARAM_SET set, const char name, const char **print_name)

int	PARAM_SET_clearParameter (PARAM_SET set, const char names)

int	PARAM_SET_clearValue (PARAM_SET set, const char names, const char *source, int priority, int at)

int	PARAM_SET_getValueCount (PARAM_SET set, const char names, const char source, int priority, int count)

int	PARAM_SET_isSetByName (const PARAM_SET set, const char names)

int	PARAM_SET_isOneOfSetByName (const PARAM_SET set, const char names)

int	PARAM_SET_isFormatOK (const PARAM_SET *set)

int	PARAM_SET_isConstraintViolation (const PARAM_SET *set)

int	PARAM_SET_isTypoFailure (const PARAM_SET *set)

int	PARAM_SET_isSyntaxError (const PARAM_SET *set)

int	PARAM_SET_isUnknown (const PARAM_SET *set)

int	PARAM_SET_readFromFile (PARAM_SET set, const char fname, const char *source, int priority)

int	PARAM_SET_readFromCMD (PARAM_SET set, int argc, char argv, const char source, int priority)

int	PARAM_SET_parseCMD (PARAM_SET set, int argc, char argv, const char source, int priority)

int	PARAM_SET_setParseOptions (PARAM_SET set, const char names, int options)

int	PARAM_SET_IncludeSet (PARAM_SET target, PARAM_SET src)

char *	PARAM_SET_toString (PARAM_SET set, char buf, size_t buf_len)

char *	PARAM_SET_typosToString (PARAM_SET set, const char prefix, char *buf, size_t buf_len)

char *	PARAM_SET_unknownsToString (const PARAM_SET set, const char prefix, char *buf, size_t buf_len)

char *	PARAM_SET_invalidParametersToString (const PARAM_SET set, const char prefix, const char (getErrString)(int), char *buf, size_t buf_len)

char *	PARAM_SET_constraintErrorToString (const PARAM_SET set, const char prefix, char *buf, size_t buf_len)

const char *	PARAM_SET_errorToString (int err)

char *	PARAM_SET_syntaxErrorsToString (const PARAM_SET set, const char prefix, char *buf, size_t buf_len)

const char *	extract_next_name (const char name_string, int(isValidNameChar)(int), char buf, short len, int flags)

int	parse_key_value_pair (const char line, char key, char *value, size_t buf_len)

int	read_line (FILE file, char buf, size_t len, size_t row_pointer, size_t read_count)

int	PARAM_SET_setWildcardExpander (PARAM_SET set, const char names, const char charList, void ctx, void(ctx_free)(void ), int(expand_wildcard)(PARAM_VAL param_value, void ctx, int value_shift))

Macro Definition Documentation

◆ PARAM_SET_ERROR_BASE

#define PARAM_SET_ERROR_BASE 0x30001

Typedef Documentation

◆ PARAM_SET

typedef struct PARAM_SET_st PARAM_SET

Parameter set object. Holds multiple parameters, performs parsing and access to the parameter values.

Enumeration Type Documentation

◆ PARAM_SET_ERR_enum

enum PARAM_SET_ERR_enum

List of error codes returned by the functions.

Enumerator
PST_OK	Everything is OK!
PST_INVALID_ARGUMENT	Function parameters are invalid, check for `NULL` pointers or out of range values.
PST_INVALID_FORMAT	Input content or syntax is wrong (e.g. parsing command line or configuration file).
PST_INDEX_OVF	Index out of boundaries.
PST_PARAMETER_NOT_FOUND	Parameter with the given name does not exist in the given set.
PST_PARAMETER_VALUE_NOT_FOUND	Parameter value with the given constraints does not exist.
PST_PARAMETER_EMPTY	The parameter value count is zero.
PST_PARAMETER_IS_TYPO	Parameter added to the set is possibly a typo.
PST_PARAMETER_IS_UNKNOWN	Parameter added to the set is unknown.
PST_PARAMETER_UNIMPLEMENTED_OBJ	Object extractor function is not implemented.
PST_PARAMETER_UNIMPLEMENTED_WILDCARD	The function for extracting wildcard is not implemented.
PST_OUT_OF_MEMORY	PST out of memory.
PST_IO_ERROR	PST IO error (e.g. when reading configuration file).
PST_PRIORITY_NEGATIVE	Priority value is negative.
PST_PRIORITY_TOO_LARGE	Priority value is too large.
PST_PARAMETER_INVALID_FORMAT	The format of the parameter is invalid.
PST_TASK_ZERO_CONSISTENT_TASKS	It was not possible to extract a consistent task from the task set.
PST_TASK_MULTIPLE_CONSISTENT_TASKS	There are two consistent tasks while only one is expected.
PST_TASK_SET_HAS_NO_DEFINITIONS	Task set is empty.
PST_TASK_SET_NOT_ANALYZED	Task set is not analyzed with PARAM_SET object.
PST_TASK_UNABLE_TO_ANALYZE_PARAM_SET_CHANGED	Task set is reanalyzed with different PARAM_SET object.
PST_WILDCARD_ERROR	Wildcard processor error occurred.
PST_UNDEFINED_BEHAVIOUR	Undefined behaviour occurred (e.g. a bug, unrecognised memory error).
PST_PRSCMD_INVALID_COMBINATION	Unable to set the combination of command-line parser options.
PST_PARAM_CONVERT_NOT_PERFORMED	Parameter conversion is not performed, original input must be used. (See PARAM_addControl and PARAM_SET_addControl).
PST_ALIAS_NOT_SPECIFIED	Parameter alias is not specified and it is not possible to work with it.
PST_UNKNOWN_ERROR	Unknown error.

Function Documentation

◆ extract_next_name()

const char* extract_next_name	(	const char *	name_string,
		int(*)(int)	isValidNameChar,
		char *	buf,
		short	len,
		int *	flags
	)

Separates names from a string. A function isValidNameChar must be defined to separate valid name characters from the separators.

Parameters

name_string	A string full of names that are separated from each other.
isValidNameChar	Function that defines valid name characters.
buf	Buffer for storing extracted name.
len	Buffer size.
flags	Can be `NULL`.

Returns: Pointer inside name_string that points to next character after name extracted or NULL if end of string reached or no name can be extracted.

◆ PARAM_SET_add()

int PARAM_SET_add	(	PARAM_SET *	set,
		const char *	name,
		const char *	value,
		const char *	source,
		int	priority
	)

Appends value to the set. Invalid value format or content is not handled as error, but the state is saved. Internal format, content or count errors can be detected - see PARAM_SET_isFormatOK. If parameter name dose not exist, function will fail. When parameter is not found it is examined as a typo or unknown (see PARAM_SET_isTypoFailure and PARAM_SET_isUnknown).

Parameters

set	PARAM_SET object.
name	Parameter name.
value	Parameter value as c-string. Can be `NULL`.
source	Source description as c-string. Can be `NULL`.
priority	Priority that can be PST_PRIORITY_VALID_BASE (`0`) or higher.

Returns: PST_OK if successful, error code otherwise. When parameter is not part of the set it is pushed to the unknown or typo list and error code PST_PARAMETER_IS_UNKNOWN or PST_PARAMETER_IS_TYPO is returned.

See also: PARAM_SET_unknownsToString, PARAM_SET_typosToString and PARAM_SET_invalidParametersToString to display errors.

◆ PARAM_SET_addControl()

int PARAM_SET_addControl	(	PARAM_SET *	set,
		const char *	names,
		int()(const char )	controlFormat,
		int()(const char )	controlContent,
		int()(const char , char *, unsigned)	convert,
		int()(void , const char , void **)	extractObject
	)

Adds several optional functions to a set of parameters. Each function takes one parameter as C-string value (must not fail if is NULL). All the functions except extractObject are applied when adding the value to the PARAM_SET object. Function extractObject is applied when calling PARAM_SET_getObj or PARAM_SET_getObjExtended.

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

int (*controlFormat)(const char *str)

Function controlContent is to check the content. Return 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. Return 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)

Function extractObject is used to extract an object from the parameter value. Function extractObject affects PARAM_SET_getObj and PARAM_SET_getObjExtended behavior. 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_SET_getObj 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 is returned, error code otherwise.

int (*extractObject)(void **extra, const char *str, void **obj)

Parameters

set	PARAM_SET object.
names	List of names to add the functions for.
controlFormat	Function for format checking.
controlContent	Function for content checking.
convert	Function for value conversion.
extractObject	Function for object extraction.

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.

See also: PARAM_SET_setParseOptions, PARAM_SET_setPrintName and PARAM_SET_setWildcardExpander. To get error reports related to functions controlFormat and controlContent, see PARAM_SET_isFormatOK and PARAM_SET_invalidParametersToString.

◆ PARAM_SET_clearParameter()

int PARAM_SET_clearParameter	(	PARAM_SET *	set,
		const char *	names
	)

Removes all values from the specified parameter list. Parameter list is defined as 'p1,p2,p3 ...'.

Parameters

set	PARAM_SET object.
names	Parameter name list.

Returns: PST_OK if successful, error code otherwise.

Note: Parameter is not deleted but only its values leaving it empty.

◆ PARAM_SET_clearValue()

int PARAM_SET_clearValue	(	PARAM_SET *	set,
		const char *	names,
		const char *	source,
		int	priority,
		int	at
	)

Removes a value specified by the constraints from the specified parameter list. Parameter list is defined as 'p1,p2,p3 ...'.

Parameters

set	PARAM_SET object.
names	Parameter name list.
source	Constraint for the source, can be `NULL`.
priority	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 if successful, error code otherwise.

◆ PARAM_SET_constraintErrorToString()

char* PARAM_SET_constraintErrorToString	(	const PARAM_SET *	set,
		const char *	prefix,
		char *	buf,
		size_t	buf_len
	)

Generates constraint error report. See PARAM_CONSTRAINTS and PARAM_SET_new.

Parameters

set	PARAM_SET object.
prefix	Prefix for each constraint error string. Can be `NULL`.
buf	Receiving buffer.
buf_len	Receiving buffer size.

Returns: buf if successful, NULL otherwise.

◆ PARAM_SET_errorToString()

const char* PARAM_SET_errorToString ( int err )

Converts PST_* error codes to string.

Parameters

err	Error code from PARAM_SET_ERR_enum.

Returns: Error string mapped from specified error code.

◆ PARAM_SET_free()

void PARAM_SET_free ( PARAM_SET * set )

Frees the PARAM_SET.

Parameters

set	PARAM_SET object.

◆ PARAM_SET_getAtr()

int PARAM_SET_getAtr	(	PARAM_SET *	set,
		const char *	name,
		const char *	source,
		int	priority,
		int	at,
		PARAM_ATR *	atr
	)

Extract attributes with the given constraints.

Parameters

set	PARAM_SET object.
name	Parameter name.
source	Constraint for the source, can be `NULL`.
priority	Priority that can be PST_PRIORITY_VALID_BASE (`0`) or higher.
at	Parameter index in the matching set composed with the constraints.
atr	Output parameter filled with attributes.

Returns: PST_OK when successful, error code otherwise. Some more common error codes: PST_INVALID_ARGUMENT, PST_PARAMETER_NOT_FOUND, PST_PARAMETER_EMPTY, PST_PARAMETER_VALUE_NOT_FOUND.

◆ PARAM_SET_getObj()

int PARAM_SET_getObj	(	PARAM_SET *	set,
		const char *	name,
		const char *	source,
		int	priority,
		int	at,
		void **	obj
	)

Extracts object from the PARAM_SET. If no object extractor (see PARAM_SET_addControl) is set, a string (see PARAM_SET_getStr instead) value is returned. By default the user must not free the returned object. If a custom object extractor function is used, object must be freed if implementation requires it.

Values are filtered by constraints. If multiple names (e.g. name1,name2,name3) are specified, process is started with the first name and at is used to index over all specified values. If some parameters in the name list do not contain any values matching the constraints, the next name is selected without an error (if there exists a next value). If all parameters are empty PST_PARAMETER_EMPTY is returned, if some values are found and the end of the list is reached PST_PARAMETER_VALUE_NOT_FOUND is returned.

Parameters

set	PARAM_SET object.
name	Parameter name.
source	Constraint for the source, can be `NULL`.
priority	Priority that can be PST_PRIORITY_VALID_BASE (`0`) or higher.
at	Parameter index in the matching set composed with the constraints.
obj	Pointer to receiving pointer to `object` returned.

Returns: PST_OK when successful, error code otherwise. If object extractor implementation returns an error code, it is returned by this functionSome more common error codes: PST_INVALID_ARGUMENT, PST_PARAMETER_NOT_FOUND, PST_PARAMETER_EMPTY, PST_PARAMETER_INVALID_FORMAT, PST_PARAMETER_UNIMPLEMENTED_OBJ, PST_PARAMETER_VALUE_NOT_FOUND.

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!

See also: PARAM_SET_add, PARAM_SET_addControl and PARAM_SET_getObjExtended.

◆ PARAM_SET_getObjExtended()

int PARAM_SET_getObjExtended	(	PARAM_SET *	set,
		const char *	name,
		const char *	source,
		int	priority,
		int	at,
		void *	ctx,
		void **	obj
	)

Same as PARAM_SET_getObj, but the ctx fed to object extractor contains two pointers void **extra = {set, ctx}.

Parameters

set	PARAM_SET object.
name	Parameter name.
source	Constraint for the source, can be `NULL`.
priority	Priority that can be PST_PRIORITY_VALID_BASE (`0`) or higher.
at	Parameter index in the matching set composed with the constraints.
ctx	Pointer to extra context.
obj	Pointer to receiving pointer to `object` returned.

Returns: PST_OK when successful, error code otherwise. Some more common error codes: PST_INVALID_ARGUMENT, PST_PARAMETER_NOT_FOUND, PST_PARAMETER_EMPTY, PST_PARAMETER_INVALID_FORMAT, PST_PARAMETER_UNIMPLEMENTED_OBJ and PST_PARAMETER_VALUE_NOT_FOUND.

◆ PARAM_SET_getPrintName()

int PARAM_SET_getPrintName	(	PARAM_SET *	set,
		const char *	name,
		const char **	print_name
	)

Extracts parameter's print name that is also displayed in (error) messages and help text.

Parameters

set	PARAM_SET object.
name	Parameter name.
print_name	Pointer to receiving pointer.

Returns: PST_OK when successful, error code otherwise. Some more common error codes: PST_INVALID_ARGUMENT, PST_PARAMETER_NOT_FOUND;

See also: To change the print name value see PARAM_SET_setPrintName.

◆ PARAM_SET_getPrintNameAlias()

int PARAM_SET_getPrintNameAlias	(	PARAM_SET *	set,
		const char *	name,
		const char **	print_name
	)

Same as PARAM_SET_getPrintName but works with alias.

Parameters

set	PARAM_SET object.
name	Parameters alias name.
print_name	Pointer to receiving pointer.

Returns: PST_OK when successful, error code otherwise. Some more common error codes: PST_INVALID_ARGUMENT, PST_PARAMETER_NOT_FOUND or PST_ALIAS_NOT_SPECIFIED;

See also: PARAM_SET_setPrintNameAlias to change the print name value.

◆ PARAM_SET_getStr()

int PARAM_SET_getStr	(	PARAM_SET *	set,
		const char *	name,
		const char *	source,
		int	priority,
		int	at,
		char **	value
	)

Extracts strings from the PARAM_SET (see PARAM_SET_add). If object extractor is set, a string value is always extracted. The user MUST NOT free the returned string.

Values are filtered by constraints. If multiple names (e.g. name1,name2,name3) are specified, process is started with the first name and at is used to index over all specified values. If some parameters in the name list do not contain any values matching the constraints, the next name is selected without an error (if there exists a next value). If all parameters are empty PST_PARAMETER_EMPTY is returned, if some values are found and the end of the list is reached PST_PARAMETER_VALUE_NOT_FOUND is returned.

Parameters

set	PARAM_SET object.
name	Parameter name.
source	Constraint for the source, can be `NULL`.
priority	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 string returned.

Returns: PST_OK when successful, error code otherwise. Some more common error codes: PST_INVALID_ARGUMENT, PST_PARAMETER_NOT_FOUND, PST_PARAMETER_EMPTY, PST_PARAMETER_INVALID_FORMAT and PST_PARAMETER_VALUE_NOT_FOUND.

See also: PARAM_SET_getObj.

◆ PARAM_SET_getValueCount()

int PARAM_SET_getValueCount	(	PARAM_SET *	set,
		const char *	names,
		const char *	source,
		int	priority,
		int *	count
	)

Counts all the existing parameter values in the list composed by the parameter list and constraints specified. Parameter list is defined as 'p1,p2,p3 ...'.

Parameters

set	PARAM_SET object.
names	Parameter name list.
source	Constraint for the source, can be `NULL`.
priority	Priority that can be PST_PRIORITY_VALID_BASE (`0`) or higher.
count	Pointer to integer for storing the value count.

Returns: PST_OK if successful, error code otherwise. If parameter does not exist PST_PARAMETER_NOT_FOUND is returned.

◆ PARAM_SET_helpToString()

char* PARAM_SET_helpToString	(	const PARAM_SET *	set,
		const char *	names,
		int	indent,
		int	header,
		int	rowWidth,
		char *	buf,
		size_t	buf_len
	)

Generates help text for parameters. Before any help text can be generated it must be configured for all the parameters with function PARAM_SET_setHelpText. The way the parameter is represented can be modified with PARAM_SET_setPrintName function.

Parameters

set	PARAM_SET object.
names	List of names to generate help for.
indent	Help text indention.
header	The size of the header (all the text and space before 'parameter' in ' -a - parameter A.').
rowWidth	The size of the row.
buf	Buffer.
buf_len	The size of `buf`.

Returns: Returns buf if successful, NULL otherwise.

◆ PARAM_SET_IncludeSet()

int PARAM_SET_IncludeSet	(	PARAM_SET *	target,
		PARAM_SET *	src
	)

Extracts all parameters from src known to target and appends all the values to the target PARAM_SET. Values are added via PARAM_SET_add and all check and extract functions that are used are from the target set. After successful operation both sets must be freed separately and operations applied to each set fo not affect the other one.

Parameters

target	Target PARAM_SET.
src	Source PARAM_SET.

Returns: PST_OK if successful, error code otherwise.

◆ PARAM_SET_invalidParametersToString()

char* PARAM_SET_invalidParametersToString	(	const PARAM_SET *	set,
		const char *	prefix,
		const char ()(int)	getErrString,
		char *	buf,
		size_t	buf_len
	)

Generates a string from invalid parameter list (see PARAM_SET_addControl). By default error strings generated contain only error code. To make the messages more human-readable define function getErrString that takes error code as input and returns const string describing the failure.

Parameters

set	PARAM_SET object.
prefix	Prefix for each failure string. Can be `NULL`.
getErrString	Function pointer to make error codes to string. Can be `NULL`.
buf	Receiving buffer.
buf_len	Receiving buffer size.

Returns: buf if successful, NULL otherwise.

See also: PARAM_SET_isFormatOK.

◆ PARAM_SET_isConstraintViolation()

int PARAM_SET_isConstraintViolation ( const PARAM_SET * set )

Controls if the the constraints are violated.

Parameters

set	PARAM_SET object.

Returns: 0 if constraints are OK, 1 otherwise. -1 if an error occurred.

See also: PARAM_SET_new.

◆ PARAM_SET_isFormatOK()

int PARAM_SET_isFormatOK ( const PARAM_SET * set )

Controls if the format and content of the parameters are OK.

Parameters

set	PARAM_SET object.

Returns: 0 if format is invalid, 1 otherwise.

See also: PARAM_SET_addControl and PARAM_SET_invalidParametersToString.

◆ PARAM_SET_isOneOfSetByName()

int PARAM_SET_isOneOfSetByName	(	const PARAM_SET *	set,
		const char *	names
	)

Searches for a parameter defined in the list by name and checks if at least one of the parameters have at least on values set. Even if the value format or content is invalid, true is returned. Parameter list is defined as 'p1,p2,p3 ...'.

Parameters

set	PARAM_SET object.
names	Parameter name list.

Returns: 1 if is at least one is set, 0 otherwise.

◆ PARAM_SET_isSetByName()

int PARAM_SET_isSetByName	(	const PARAM_SET *	set,
		const char *	names
	)

Searches for a parameter defined in the list by name and checks if all the parameters have at least one values set. Even if the value format or content is invalid, true is returned. Parameter list is defined as 'p1,p2,p3 ...'.

Parameters

set	PARAM_SET object.
names	Parameter name list.

Returns: 1 if is set, 0 otherwise.

◆ PARAM_SET_isSyntaxError()

int PARAM_SET_isSyntaxError ( const PARAM_SET * set )

Controls if there are some syntax errors after reading configuration file.

Parameters

set	PARAM_SET object.

Returns: 0 if set contains possible typos, 1 otherwise.

See also: PARAM_SET_readFromFile.

◆ PARAM_SET_isTypoFailure()

int PARAM_SET_isTypoFailure ( const PARAM_SET * set )

Controls if there are some undefined parameters read from command line or file, similar to the defined ones - possible typos. Typos are detected using the difference value calculated as specified below:

                   levenshtein_distance(token, param_name)
difference = 100 * --------------------------------------- - (is_sub_str * 15 + is_sub_str_at_beginning * 15)  , where
                               param_name_len
  levenshtein_distance - function that calculates edit distance for two strings.
  token - unknown token whose similarity is compared with existing parameters.
  param_name - parameter name.
  param_name_len - parameter name length in characters.
  is_sub_str - 1 if token is a substring, 0 otherwise.
  is_sub_str_at_beginning - 1 if token matches with the beginning of param_name, 0 otherwise.

The difference value with the unknown token is calculated for every known parameter in the set and the smallest value is saved as smdiff. An unknown token is interpreted as typo if there exists at least one parameter so that:

difference < 90 && difference < (smdiff + 10)

Parameters

set	PARAM_SET object.

Returns: 0 if set contains possible typos, 1 otherwise.

See also: PARAM_SET_typosToString, PARAM_SET_add, PARAM_SET_parseCMD and PARAM_SET_readFromFile.

◆ PARAM_SET_isUnknown()

int PARAM_SET_isUnknown ( const PARAM_SET * set )

Controls if there are some undefined parameters read from command line or file.

Parameters

set	PARAM_SET object.

Returns: 0 if set contains unknown parameters, 1 otherwise.

See also: PARAM_SET_unknownsToString, PARAM_SET_add, PARAM_SET_parseCMD and PARAM_SET_readFromFile.

◆ PARAM_SET_new()

int PARAM_SET_new	(	const char *	names,
		PARAM_SET **	set
	)

Creates new PARAM_SET object using parameter names. Parameter names are defined using string '{name|alias}*{name|alias}*...' where

name - parameter name,

alias - alias for the name (optional),

* - indicates the possibility of multiple values (optional), for usage instructions, see PARAM_SET_isConstraintViolation and PARAM_SET_constraintErrorToString.

Example: {h|help}{file}*{o}*{n}

Parameters

names	Pointer to parameter names.
set	Pointer to receiving pointer to PARAM_SET object.

Returns: PST_OK if successful, error code otherwise.

◆ PARAM_SET_parseCMD()

int PARAM_SET_parseCMD	(	PARAM_SET *	set,
		int	argc,
		char **	argv,
		const char *	source,
		int	priority
	)

Parses command-line parameters. It is similar to PARAM_SET_readFromCMD but extends its functionality. For example it is possible to have a parameter that always interprets the next token as its value, even if it is identical to some command-line parameter. To redirect all tokens after '--' to specified parameter, or process some parameters with configured wildcard expander see PARAM_SET_setParseOptions.

To specify parse option for each command line parameter:

--long       - Long parameter without value.
--long <arg> - Long parameter with value.
-i <arg>     - Short parameter with value.
-vxn         - Bunch of flags.

Parameters

set	PARAM_SET object.
argc	Count of command line strings.
argv	Array of command line strings.
source	Source description as c-string. Can be `NULL`.
priority	Priority that can be PST_PRIORITY_VALID_BASE (`0`) or higher.

Returns: PST_OK if successful, error code otherwise.

See also: PARAM_PARSE_OPTIONS, PARAM_SET_addControl, PARAM_SET_isSetByName, PARAM_SET_getStr, PARAM_SET_getObj, PARAM_SET_isTypoFailure, PARAM_SET_isUnknown, PARAM_SET_unknownsToString and PARAM_SET_typosToString.

◆ PARAM_SET_readFromCMD()

int PARAM_SET_readFromCMD	(	PARAM_SET *	set,
		int	argc,
		char **	argv,
		const char *	source,
		int	priority
	)

Reads parameter values from command line into predefined PARAM_SET. Parameters are stored in internal data structures where one parameter can have multiple values. If configured, all values read are checked against checking functions (see PARAM_SET_addControl). See PARAM_SET_isSetByName, PARAM_SET_getStr and PARAM_SET_getObj to get command-line parameter values. If there are some misspelled and/or unknown parameters, it is detected and it is possible to get error reports. See PARAM_SET_isTypoFailure and PARAM_SET_isUnknown to check for errors. See PARAM_SET_unknownsToString and PARAM_SET_typosToString to get error reports.

Command-line format:

--long       - Long parameter without value.
--long <arg> - Long parameter with value.
-i <arg>     - Short parameter with value.
-vxn         - Bunch of flags.

Parameters

set	PARAM_SET object.
argc	Count of command line strings.
argv	Array of command line strings.
source	Source description as c-string. Can be `NULL`.
priority	Priority that can be PST_PRIORITY_VALID_BASE (`0`) or higher.

Returns: PST_OK if successful, error code otherwise.

See also: PARAM_SET_readFromCMD for more advanced behaviour.

◆ PARAM_SET_readFromFile()

int PARAM_SET_readFromFile	(	PARAM_SET *	set,
		const char *	fname,
		const char *	source,
		int	priority
	)

Reads parameter values from file into predefined PARAM_SET. File must be formatted one parameter (and its possible value) per line. To add a comment '#' must be inserted at the beginning of the line. To learn how the key-value pairs are precisely extracted see parse_key_value_pair and read_line. Format of parameters:

# comment    - a line with comment.
--long       - Long parameter without value.
--long <arg> - Long parameter with value.
-i <arg>     - Short parameter with value.
-vxn         - Bunch of flags.

Parameters

set	PARAM_SET object.
fname	File path.
source	Source description as c-string. Can be `NULL`.
priority	Priority that can be PST_PRIORITY_VALID_BASE (`0`) or higher.

Returns: PST_OK if successful, error code otherwise. If file format is invalid, PST_INVALID_FORMAT is returned.

◆ PARAM_SET_setHelpText()

int PARAM_SET_setHelpText	(	PARAM_SET *	set,
		const char *	names,
		const char *	txt
	)

Specify help text for a parameter.

Parameters

set	PARAM_SET object.
names	List of names to add the help text for.
txt	Help text for a parameter. Value is copied. Must NOT be `NULL`.

Returns: PST_OK when successful, error code otherwise.

See also: PARAM_SET_setPrintName and PARAM_SET_helpToString.

◆ PARAM_SET_setParseOptions()

int PARAM_SET_setParseOptions	(	PARAM_SET *	set,
		const char *	names,
		int	options
	)

Specifies the parsing options (PARAM_PARSE_OPTIONS) used by PARAM_SET_parseCMD.

Parameters

set	PARAM_SET object.
names	Parameter name list.
options	Parsing options.

Returns: PST_OK if successful, error code otherwise.

See also: PARAM_SET_addControl, PARAM_SET_setPrintName, and PARAM_SET_setWildcardExpander.

◆ PARAM_SET_setPrintName()

int PARAM_SET_setPrintName	(	PARAM_SET *	set,
		const char *	names,
		const char *	constv,
		const char ()(PARAM param, char buf, unsigned buf_len)	getPrintName
	)

Alters the way the parameter is represented in (error) messages, help text and returned by PARAM_getPrintName.

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 parameters are '--long' and '-a'.

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

param - this 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 parameter.

Parameters

set	PARAM_SET object.
names	List of names to add the functions for.
constv	Constant string representation of the parameter, may be `NULL`.
getPrintName	Abstract function implementation. Has effect only when `constv` is `NULL`. May be `NULL`.

Returns: PST_OK when successful, error code otherwise.

See also: PARAM_SET_addControl, PARAM_SET_setParseOptions and PARAM_SET_setWildcardExpander.

◆ PARAM_SET_setPrintNameAlias()

int PARAM_SET_setPrintNameAlias	(	PARAM_SET *	set,
		const char *	names,
		const char *	constv,
		const char ()(PARAM param, char buf, unsigned buf_len)	getPrintName
	)

Same as PARAM_SET_setPrintName but works with alias.

Parameters

set	PARAM_SET object.
names	List of names to add the functions for.
constv	Constant string representation of the parameter alias. Can be `NULL`.
getPrintName	Abstract function implementation. Has effect only when `constv` is `NULL`. Can be `NULL`.

Returns: PST_OK when successful, error code otherwise.

See also: PARAM_SET_addControl, PARAM_SET_setParseOptions and PARAM_SET_setWildcardExpander.

◆ PARAM_SET_setWildcardExpander()

int PARAM_SET_setWildcardExpander	(	PARAM_SET *	set,
		const char *	names,
		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

set	PARAM_SET object.
names	List of names to add the functionality.
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: PARAM_SET_setPrintName, PARAM_SET_addControl, PARAM_expandWildcard, PARAM_setWildcardExpander and Implemented wildcard expanders.

◆ PARAM_SET_syntaxErrorsToString()

char* PARAM_SET_syntaxErrorsToString	(	const PARAM_SET *	set,
		const char *	prefix,
		char *	buf,
		size_t	buf_len
	)

Generates syntax error report.

Parameters

set	PARAM_SET object.
prefix	Prefix for each constraint error string. Can be `NULL`.
buf	Receiving buffer.
buf_len	Receiving buffer size.

Returns: buf if successful, NULL otherwise.

See also: PARAM_SET_readFromFile and PARAM_SET_isSyntaxError.

◆ PARAM_SET_toString()

char* PARAM_SET_toString	(	PARAM_SET *	set,
		char *	buf,
		size_t	buf_len
	)

Generates PARAM_SET string representation for debugging.

Parameters

set	PARAM_SET object.
buf	Receiving buffer.
buf_len	Receiving buffer size.

Returns: buf if successful, NULL otherwise.

◆ PARAM_SET_typosToString()

char* PARAM_SET_typosToString	(	PARAM_SET *	set,
		const char *	prefix,
		char *	buf,
		size_t	buf_len
	)

Generates typo failure report.

Parameters

set	PARAM_SET object.
prefix	Prefix to each typo failure string. Can be `NULL`.
buf	Receiving buffer.
buf_len	Receiving buffer size.

Returns: buf if successful, NULL otherwise.

See also: PARAM_SET_isTypoFailure.

◆ PARAM_SET_unknownsToString()

char* PARAM_SET_unknownsToString	(	const PARAM_SET *	set,
		const char *	prefix,
		char *	buf,
		size_t	buf_len
	)

Generates unknown parameter report.

Parameters

set	PARAM_SET object.
prefix	Prefix to each unknown failure string. Can be `NULL`.
buf	Receiving buffer.
buf_len	Receiving buffer size.

Returns: buf if successful, NULL otherwise.

See also: PARAM_SET_isUnknown.

◆ parse_key_value_pair()

int parse_key_value_pair	(	const char *	line,
		char *	key,
		char *	value,
		size_t	buf_len
	)

Extracts a key value pair from the line. Value part can be wrapped inside double quote marks (") to include whitespace characters. Use back slash (\) as escape character for itself and for double quotes. Some examples:

key = value
key = "value 1"
  key = value
key value
key "value 1"
  key value
key "value=\"test\""

Parameters

line	Input line.
key	Pointer to receiving key.
value	Pointer to receiving value.
buf_len	Maximum size of both `key` and `value` buffer.

Returns: PST_OK if successful, error code otherwise. Some more common error codes: PST_INVALID_FORMAT.

◆ PST_getVersion()

const char* PST_getVersion ( void )

Returns: A constant pointer to a constant string describing the version number of the package.

◆ read_line()

int read_line	(	FILE *	file,
		char *	buf,
		size_t	len,
		size_t *	row_pointer,
		size_t *	read_count
	)

Reads a line from a file (opened with fopen in mode r) and tracks the lines. Supported line endings:

MAC  \r      CR      0x0d
Unix \n      LF      0x0a
Win  \r\n    CRLF    0x0d0a

Parameters

file	A file pointer that is us used for reading from.
buf	A buffer to store the line.
len	Size of the buffer.
row_pointer	Pointer to the row counting value. Initial value pointed to must be 0. If not used can be `NULL`.
read_count	Pointer to character counting value. If not used can be `NULL`.

Returns: Return 0 if successful, EOF if end of file.

Enumerations
enum	PARAM_SET_ERR_enum { PST_OK = 0, PST_INVALID_ARGUMENT = PARAM_SET_ERROR_BASE, PST_INVALID_FORMAT, PST_INDEX_OVF, PST_PARAMETER_NOT_FOUND, PST_PARAMETER_VALUE_NOT_FOUND, PST_PARAMETER_EMPTY, PST_PARAMETER_IS_TYPO, PST_PARAMETER_IS_UNKNOWN, PST_PARAMETER_UNIMPLEMENTED_OBJ, PST_PARAMETER_UNIMPLEMENTED_WILDCARD, PST_OUT_OF_MEMORY, PST_IO_ERROR, PST_PRIORITY_NEGATIVE, PST_PRIORITY_TOO_LARGE, PST_PARAMETER_INVALID_FORMAT, PST_TASK_ZERO_CONSISTENT_TASKS, PST_TASK_MULTIPLE_CONSISTENT_TASKS, PST_TASK_SET_HAS_NO_DEFINITIONS, PST_TASK_SET_NOT_ANALYZED, PST_TASK_UNABLE_TO_ANALYZE_PARAM_SET_CHANGED, PST_WILDCARD_ERROR, PST_UNDEFINED_BEHAVIOUR, PST_PRSCMD_INVALID_COMBINATION, PST_PARAM_CONVERT_NOT_PERFORMED, PST_ALIAS_NOT_SPECIFIED, PST_UNKNOWN_ERROR }

Macros

Typedefs

Enumerations

Functions

Macro Definition Documentation

◆ PARAM_SET_ERROR_BASE

Typedef Documentation

◆ PARAM_SET

Enumeration Type Documentation

◆ PARAM_SET_ERR_enum

Function Documentation

◆ extract_next_name()

◆ PARAM_SET_add()

◆ PARAM_SET_addControl()

◆ PARAM_SET_clearParameter()

◆ PARAM_SET_clearValue()

◆ PARAM_SET_constraintErrorToString()

◆ PARAM_SET_errorToString()

◆ PARAM_SET_free()

◆ PARAM_SET_getAtr()

◆ PARAM_SET_getObj()

◆ PARAM_SET_getObjExtended()

◆ PARAM_SET_getPrintName()

◆ PARAM_SET_getPrintNameAlias()

◆ PARAM_SET_getStr()

◆ PARAM_SET_getValueCount()

◆ PARAM_SET_helpToString()

◆ PARAM_SET_IncludeSet()

◆ PARAM_SET_invalidParametersToString()

◆ PARAM_SET_isConstraintViolation()

◆ PARAM_SET_isFormatOK()

◆ PARAM_SET_isOneOfSetByName()

◆ PARAM_SET_isSetByName()

◆ PARAM_SET_isSyntaxError()

◆ PARAM_SET_isTypoFailure()

◆ PARAM_SET_isUnknown()

◆ PARAM_SET_new()

◆ PARAM_SET_parseCMD()

◆ PARAM_SET_readFromCMD()

◆ PARAM_SET_readFromFile()

◆ PARAM_SET_setHelpText()

◆ PARAM_SET_setParseOptions()

◆ PARAM_SET_setPrintName()

◆ PARAM_SET_setPrintNameAlias()

◆ PARAM_SET_setWildcardExpander()

◆ PARAM_SET_syntaxErrorsToString()

◆ PARAM_SET_toString()

◆ PARAM_SET_typosToString()

◆ PARAM_SET_unknownsToString()

◆ parse_key_value_pair()

◆ PST_getVersion()

◆ read_line()