cmdline.h File Reference

Command line parameter parser. More...

#include <Uefi.h>

Go to the source code of this file.

Data Structures
union	cmdline_value_t
	one parsed command line value More...
struct	cmdline_argument_t
	model for one command line argument More...
struct	cmdline_argument_group_t
	model for group of command line arguments More...

Macros
#define	RV_HELP   0x10000000
	EFI_STATUS compatible return value, indicating user wanted the help screen.
#define	ARG_GROUP(VARIABLE, LIST, DESCRIPTION)   cmdline_argument_group_t VARIABLE={DESCRIPTION,sizeof(LIST)/sizeof(cmdline_argument_t),LIST};
	shortcut macro for quickly defining an argument group More...
#define	DOUBLE_RANGE_VALIDATOR(FUNC, FIELD, MIN, MAX)   static BOOLEAN FUNC(cmdline_value_t v) { return validate_double_range(v,FIELD,MIN,MAX); }
	shortcut macro for quickly defining a validator for "double" type arguments More...
#define	INT_RANGE_VALIDATOR(FUNC, FIELD, MIN, MAX)   static BOOLEAN FUNC(cmdline_value_t v) { return validate_uint64_range(v,FIELD,MIN,MAX); }
	shortcut macro for quickly defining a validator for "integer" type arguments More...

Typedefs
typedef BOOLEAN	validate_argument_f(cmdline_value_t)
	function pointer type for command line argument validators

Enumerations
enum	argument_type { ARG_BOOL =1, ARG_INT, ARG_DOUBLE, ARG_STRING }
	the supported command line argument types More...

Functions
BOOLEAN	wctype_int (CHAR16 *string)
	Checks whether a string looks like an integer. More...
BOOLEAN	wctype_float (CHAR16 *string)
	Checks whether a string looks like a number. More...
double	_wcstof (CHAR16 *str)
	Converts a numeric string into a double value. More...
BOOLEAN	validate_double_range (cmdline_value_t v, CHAR16 *field, double min, double max)
	Checks whether a double command line parameter is within boundaries. More...
BOOLEAN	validate_uint64_range (cmdline_value_t v, CHAR16 *field, UINT64 min, UINT64 max)
	Checks whether a uint64 command line parameter is within boundaries. More...
EFI_STATUS	parse_parameters (INTN argc, CHAR16 **argv, UINTN group_count, VA_LIST groups)
	Parses command-line parameters. More...
void	print_help_text (UINTN group_count, VA_LIST groups)
	Outputs the help text for all argument groups, including the built-in ones. More...
CHAR16 **	argv_from_ascii (int argc, char **argv_ascii)
	Converts ASCII command line parameters to UTF-16. More...
void	free_argv ()
	Frees the memory pages for the internal _argv storage.

Detailed Description

Command line parameter parser.

Author

Richard Nusser

Copyright

2017-2018 Richard Nusser

License

GPLv3 (see http://www.gnu.org/licenses/)

See also

https://github.com/rinusser/UEFIStarter

Macro Definition Documentation

ARG_GROUP

#define ARG_GROUP	(		VARIABLE,
			LIST,
			DESCRIPTION
	)		cmdline_argument_group_t VARIABLE={DESCRIPTION,sizeof(LIST)/sizeof(cmdline_argument_t),LIST};

shortcut macro for quickly defining an argument group

Parameters

VARIABLE	the group variable to define
LIST	the list of arguments, as cmdline_argument_t[]
DESCRIPTION	the group's name or description, may be NULL

DOUBLE_RANGE_VALIDATOR

#define DOUBLE_RANGE_VALIDATOR	(		FUNC,
			FIELD,
			MIN,
			MAX
	)		static BOOLEAN FUNC(cmdline_value_t v) { return validate_double_range(v,FIELD,MIN,MAX); }

shortcut macro for quickly defining a validator for "double" type arguments

Parameters

FUNC	the function name to define
FIELD	the field name to use in error messages
MIN	the minimum value (inclusive)
MAX	the maximum value (inclusive)

INT_RANGE_VALIDATOR

#define INT_RANGE_VALIDATOR	(		FUNC,
			FIELD,
			MIN,
			MAX
	)		static BOOLEAN FUNC(cmdline_value_t v) { return validate_uint64_range(v,FIELD,MIN,MAX); }

shortcut macro for quickly defining a validator for "integer" type arguments

Parameters

FUNC	the function name to define
FIELD	the field name to use in error messages
MIN	the minimum value (inclusive)
MAX	the maximum value (inclusive)

Enumeration Type Documentation

argument_type

enum argument_type

the supported command line argument types

Enumerator
ARG_BOOL	boolean
ARG_INT	integer
ARG_DOUBLE	double
ARG_STRING	UTF-16 string.

Function Documentation

wctype_int()

BOOLEAN wctype_int

(

CHAR16 *

string

)

Checks whether a string looks like an integer.

Parameters

string

the string to check, as UTF-16

Returns

whether it's an integer

wctype_float()

BOOLEAN wctype_float

(

CHAR16 *

string

)

Checks whether a string looks like a number.

Parameters

string

the string to check, as UTF-16

Returns

whether it's a decimal number

_wcstof()

double _wcstof

(

CHAR16 *

str

)

Converts a numeric string into a double value.

Errors will produce an ERROR level log message.

Parameters

str	the string to convert

Returns

the parsed number; -1.0 on error

Todo:

replace _wcstof() with built-in, or move to separate file

validate_double_range()

BOOLEAN validate_double_range	(	cmdline_value_t	v,
		CHAR16 *	field,
		double	min,
		double	max
	)

Checks whether a double command line parameter is within boundaries.

Parameters

v	the command line parameter
field	the field name to use in error messages, as UTF-16
min	the lowest allowed value (inclusive)
max	the highest allowed value (inclusive)

Returns

whether the parameter is within the boundaries

validate_uint64_range()

BOOLEAN validate_uint64_range	(	cmdline_value_t	v,
		CHAR16 *	field,
		UINT64	min,
		UINT64	max
	)

Checks whether a uint64 command line parameter is within boundaries.

Parameters

v	the command line parameter
field	the field name to use in error messages, as UTF-16
min	the lowest allowed value (inclusive)
max	the highest allowed value (inclusive)

Returns

whether the parameter is within the boundaries

parse_parameters()

EFI_STATUS parse_parameters	(	INTN	argc,
		CHAR16 **	argv,
		UINTN	group_count,
		VA_LIST	args
	)

Parses command-line parameters.

Parameters

argc	the number of command-line arguments
argv	the list of command-line arguments, as UTF-16
group_count	the number of command line argument groups passed
args	the vararg list of command line groups (as cmdline_argument_group_t *)

Returns

an EFI status code

print_help_text()

void print_help_text	(	UINTN	argument_group_count,
		VA_LIST	args
	)

Outputs the help text for all argument groups, including the built-in ones.

Parameters

argument_group_count	the number of argument groups passed
args	the vararg list of argument groups (cmdline_argument_group_t *)

argv_from_ascii()

CHAR16** argv_from_ascii	(	int	argc,
		char **	argv_ascii
	)

Converts ASCII command line parameters to UTF-16.

The StdLib's entry function passes arguments as ASCII, you can use this function to convert the arguments list.

Parameters

argc	the number of command-line arguments
argv_ascii	the list of command-line arguments, as ASCII

Returns

the same command-line arguments, as UTF-16