cmdline.h File Reference

Command-line argument parsing module. More...

#include <stdbool.h>

Go to the source code of this file.

Functions
int	cmdlineInit (int argc, char *argv[])
	Initializes the command-line parsing module.
const char *	cmdlineGetProgramName (void)
	Retrieves the program name.
const char *	cmdlineGetValueForKey (const char key[])
	Gets the corresponding value for a given option key ("-key=value" or "--key=value").
bool	cmdlineGetFlag (const char flag[])
	Checks if a given flag ("-flag" or "--flag") was passed via the command line.
unsigned int	cmdlineGetExtraArgCount (void)
const char *	cmdlineGetExtraArg (unsigned int index)
	Retrieves an extra argument.

Detailed Description

Command-line argument parsing module.

This module is useful for parsing the argv array passed to a program via the command line, which can consist of the following argument classes:

• The program name (argv[0]), which can be retrieved by calling cmdlineGetProgramName().
• Key-value pairs in the form "-key=value" or "--key=value". These can be queried using cmdlineGetValueForKey().
• Boolean flags in the form "-flag" or "--flag". The cmdlineGetFlag() function determines whether a specific flag has been set.
• Everything which has neither of the above formats is called an "extra argument". The user can retrieve the number of extra arguments via cmdlineGetExtraArgCount() and iterate over them by calling cmdlineGetExtraArg().

Both keys and flags must begin with one or two dashes followed by one alpha-numeric character and an arbitrary number of additional characters (excluding '\0' and '=').

Function Documentation

cmdlineGetExtraArg()

const char * cmdlineGetExtraArg

(

unsigned int

index

)

Retrieves an extra argument.

Parameters

index

Zero-based index of the extra argument.

Returns

The extra argument with the given index, or NULL if index is greater than or equal to the number of extra arguments.

cmdlineGetExtraArgCount()

unsigned int cmdlineGetExtraArgCount

(

void

)

Retrieves the number of extra command-line arguments.

cmdlineGetFlag()

bool cmdlineGetFlag

(

const char

flag[]

)

Checks if a given flag ("-flag" or "--flag") was passed via the command line.

Parameters

flag	Name of the flag. Leading dashes may be omitted.

Returns

true if the flag is set, otherwise false.

Note

This function cannot be used to query for the existence of a given key in a key-value pair. The canonical way for this is to call cmdlineGetValueForKey() and check its return value.

cmdlineGetProgramName()

const char * cmdlineGetProgramName

(

void

)

Retrieves the program name.

Returns

The value of argv[0].

cmdlineGetValueForKey()

const char * cmdlineGetValueForKey

(

const char

key[]

)

Gets the corresponding value for a given option key ("-key=value" or "--key=value").

If the same key appears several times in the command line, the value of its latest occurrence is returned.

Parameters

key	The key. Leading dashes may be omitted.

Returns

The value associated with the given key, or NULL if no such pair exists.

cmdlineInit()

int cmdlineInit	(	int	argc,
		char *	argv[]
	)

Initializes the command-line parsing module.

This function must be invoked before any of the other functions.

Parameters

argc	Number of command-line arguments.
argv	Array of command-line arguments. The contents of this array are not modified in any manner.

Returns

0 on success. If argc or argv is invalid, -1 is returned and errno is set to EINVAL.