le_args.h File Reference

Go to the source code of this file.

Typedefs

typedef void(* le_arg_FlagCallbackFunc_t) (void)
 
typedef void(* le_arg_IntCallbackFunc_t) (int value)
 
typedef void(* le_arg_StringCallbackFunc_t) (const char *value)
 
typedef size_t(* le_arg_ErrorHandlerFunc_t) (size_t argIndex, le_result_t errorCode)
 

Functions

const char * le_arg_GetProgramName (void)
 
size_t le_arg_NumArgs (void)
 
const char * le_arg_GetArg (size_t argIndex)
 
le_result_t le_arg_GetFlagOption (const char *shortName, const char *longName)
 
le_result_t le_arg_GetIntOption (int *varPtr, const char *shortName, const char *longName)
 
le_result_t le_arg_GetStringOption (const char **varPtr, const char *shortName, const char *longName)
 
void le_arg_SetFlagVar (bool *varPtr, const char *shortName, const char *longName)
 
void le_arg_SetIntVar (int *varPtr, const char *shortName, const char *longName)
 
void le_arg_SetStringVar (const char **varPtr, const char *shortName, const char *longName)
 
void le_arg_SetFlagCallback (le_arg_FlagCallbackFunc_t func, const char *shortName, const char *longName)
 
void le_arg_SetIntCallback (le_arg_IntCallbackFunc_t func, const char *shortName, const char *longName)
 
void le_arg_SetStringCallback (le_arg_StringCallbackFunc_t func, const char *shortName, const char *longName)
 
void le_arg_AddPositionalCallback (le_arg_StringCallbackFunc_t func)
 
void le_arg_AllowMorePositionalArgsThanCallbacks (void)
 
void le_arg_AllowLessPositionalArgsThanCallbacks (void)
 
void le_arg_SetErrorHandler (le_arg_ErrorHandlerFunc_t errorHandlerFunc)
 
void le_arg_SetExitOnError (bool exitOnError)
 
le_result_t le_arg_GetScanResult (void)
 
void le_arg_Scan (void)
 
void le_arg_SetArgs (const size_t argc, const char **argv)
 
le_result_t le_arg_Split (const char *firstStr, char *cmdlinePtr, int *argc, const char **argv)
 

Detailed Description

Legato Command Line Arguments API include file.

Typedef Documentation

◆ le_arg_ErrorHandlerFunc_t

typedef size_t(* le_arg_ErrorHandlerFunc_t) (size_t argIndex, le_result_t errorCode)

Error handler function prototype. All argument error handler functions (passed into le_arg_SetErrorHandler() ) must conform to this prototype.

Errors that can be reported to this function are:

  • LE_BAD_PARAMETER - The argument is not expected.
  • LE_NOT_FOUND - The argument should have a value, but no value was given.
  • LE_FORMAT_ERROR - The argument should have a numerical value, but was given something else.
  • LE_OUT_OF_RANGE - Magnitude of numerical argument too big to be stored in chosen data type.
  • LE_OVERFLOW - Too many positional arguments found on command line.
  • LE_UNDERFLOW - Too few positional arguments found on command line.
  • LE_UNSUPPORTED - The argument should not have a value but was given one.
Returns
The number of arguments to skip before resuming argument scanning. 0 = resume scanning at argIndex + 1; 1 = resume at argIndex + 2; etc.
Parameters
argIndexIndex of argument that is bad (0 = first arg after program name).
errorCodeCode indicating the type of error that was encountered.

◆ le_arg_FlagCallbackFunc_t

typedef void(* le_arg_FlagCallbackFunc_t) (void)

Flag argument callback functions registered using le_arg_SetFlagCallback() must conform to this prototype.

If the flag appears N times on the command line, the callback will be called N times.

◆ le_arg_IntCallbackFunc_t

typedef void(* le_arg_IntCallbackFunc_t) (int value)

Integer argument callback functions registered using le_arg_SetIntCallback() must conform to this prototype.

If the option appears N times on the command line, the callback will be called N times.

Parameters
valueThe value of the integer option.

◆ le_arg_StringCallbackFunc_t

typedef void(* le_arg_StringCallbackFunc_t) (const char *value)

String argument callback functions registered using le_arg_SetStringCallback() or le_arg_AddPositionalCallback() must conform to this prototype.

If the option appears N times on the command line, the callback will be called N times.

Parameters
valuePointer to the value of the string option.

Function Documentation

◆ le_arg_AddPositionalCallback()

void le_arg_AddPositionalCallback ( le_arg_StringCallbackFunc_t  func)

Register a callback function to be called if an argument appears outside of any options. For example, in the following command-line, "foo" and "bar" are positional arguments (while "-l" is a flag option and "ls" is the program name):

$ ls -l foo bar

Each callback function registered using this method is added to the positional callback list. When the first positional argument is encountered, the first positional callback function is called. When the Nth positional argument is encountered, the Nth positional callback is called. If there are N positional arguments and M positional callbacks, and N > M, then the last positional callback will be called once for each positional argument from M through N, inclusive.

Parameters
funcThe callback function address.

◆ le_arg_AllowLessPositionalArgsThanCallbacks()

void le_arg_AllowLessPositionalArgsThanCallbacks ( void  )

Tell the argument parser to allow less positional arguments than positional callbacks.

If less positional arguments are encountered than the number of positional callbacks when this is allowed, any positional callbacks that don't have arguments won't be called. If this is not allowed, le_arg_Scan() will print an error message to the standard error stream and exit the process with EXIT_FAILURE if there are less positional arguments than there are positional callbacks.

◆ le_arg_AllowMorePositionalArgsThanCallbacks()

void le_arg_AllowMorePositionalArgsThanCallbacks ( void  )

Tell the argument parser to allow more positional arguments than positional callbacks.

If more positional arguments are encountered than the number of positional callbacks when this is allowed, le_arg_Scan() will call the last positional callback again for each extra positional argument it finds. If this is not allowed, le_arg_Scan() will print an error message to the standard error stream and exit the process with EXIT_FAILURE if there are more positional arguments than there are positional callbacks.

◆ le_arg_GetArg()

const char* le_arg_GetArg ( size_t  argIndex)

Gets a command line argument by index.

Returns
Pointer to the argument string (null-terminated), or NULL if the index is out of range.
Parameters
[in]argIndexIndex of the argument (0 = first argument after the program name).

◆ le_arg_GetFlagOption()

le_result_t le_arg_GetFlagOption ( const char *  shortName,
const char *  longName 
)

Searches the argument list for a flag option. Can search for a short name (e.g., -f) or a long name (e.g., --flag) for the same flag at the same time.

Returns
  • LE_OK if found,
  • LE_NOT_FOUND if not found,
  • LE_FORMAT_ERROR if found but has a value (e.g., --flag=foo).
Note
If both shortName and longName are NULL, LE_NOT_FOUND will be returned.
Parameters
[in]shortNameName that appears after a single '-' (can be NULL).
[in]longNameName that appears afer a "--" (can be NULL).

◆ le_arg_GetIntOption()

le_result_t le_arg_GetIntOption ( int *  varPtr,
const char *  shortName,
const char *  longName 
)

Searches the argument list for an option with an integer value. Can search for a short name (e.g., -c 1234) or a long name (e.g., --count=1234) form of the same option at the same time.

Returns
  • LE_OK if found and successfully converted to an integer.
  • LE_NOT_FOUND if not found.
  • LE_FORMAT_ERROR if the option wasn't provided with an integer value.
  • LE_OUT_OF_RANGE - Magnitude of integer value too big to be stored in an int.
Note
If both shortName and longName are NULL, LE_NOT_FOUND will be returned.
Parameters
[out]varPtrVariable into which the value will be stored if found.
[in]shortNameName that appears after a single '-' (can be NULL).
[in]longNameName that appears afer a "--" (can be NULL).

◆ le_arg_GetProgramName()

const char* le_arg_GetProgramName ( void  )

Gets the program name.

Returns
Pointer to the null-terminated program name string.

◆ le_arg_GetScanResult()

le_result_t le_arg_GetScanResult ( void  )

Determine if argument scanning failed.

If process termination is disabled via le_arg_SetExitOnError(), then this function may be used to get the result of argument scanning (le_arg_Scan()).

Returns
The result of the last argument scan.

◆ le_arg_GetStringOption()

le_result_t le_arg_GetStringOption ( const char **  varPtr,
const char *  shortName,
const char *  longName 
)

Searches the argument list for an option with a string value. Can search for a short name (e.g., -f foo) or a long name (e.g., --file=foo) form of the same option at the same time.

Note
--file= is a valid string option with an empty string ("") value. The equivalent short name version of that option would be something like -f "".
Returns
  • LE_OK if found.
  • LE_NOT_FOUND if not found.
  • LE_FORMAT_ERROR if the option wasn't provided with a value.
Note
If both shortName and longName are NULL, LE_NOT_FOUND will be returned.
Parameters
[out]varPtrVariable into which to store a pointer to the value if found.
[in]shortNameName that appears after a single '-' (can be NULL).
[in]longNameName that appears afer a "--" (can be NULL).

◆ le_arg_NumArgs()

size_t le_arg_NumArgs ( void  )

Gets the number of command line arguments available not including the program name.

Returns
Number of command line arguments available.

◆ le_arg_Scan()

void le_arg_Scan ( void  )

Scans the argument list, setting variables and calling callbacks registered using the le_arg_SetXxxVar(), le_arg_SetXxxCallback(), and le_arg_AddPositionalParameters() functions.

◆ le_arg_SetArgs()

void le_arg_SetArgs ( const size_t  argc,
const char **  argv 
)

Passes argc and argv to the argument parser for later use by le_arg_Scan().

Note
This function is normally called by main(). If the Legato application framework is automatically generating main() for you, then you can just ignore this function.
Parameters
[in]argcargc from main().
[in]argvargv from main().

◆ le_arg_SetErrorHandler()

void le_arg_SetErrorHandler ( le_arg_ErrorHandlerFunc_t  errorHandlerFunc)

Register an error handler function to be called by le_arg_Scan() whenever an unexpected argument is encountered or an option's value cannot be converted to the correct data type.

Parameters
[in]errorHandlerFuncThe error handler function.

◆ le_arg_SetExitOnError()

void le_arg_SetExitOnError ( bool  exitOnError)

Control whether an argument scanning error should cause the process to exit.

The default behaviour is to exit. If this is set to false then le_arg_GetScanResult() should be called after le_arg_Scan() to determine if an error occured.

Parameters
[in]exitOnErrorExit on scan error.

◆ le_arg_SetFlagCallback()

void le_arg_SetFlagCallback ( le_arg_FlagCallbackFunc_t  func,
const char *  shortName,
const char *  longName 
)

Register a callback function to be called if a given flag option appears on the argument list.

No value is expected after the option name.

One or the other of shortName or longName may be NULL. If not NULL, these MUST be pointers to strings that are never deallocated or changed.

Parameters
funcThe callback function address.
shortNameShort form of option name (e.g., "h" will match "-h").
longNameLong form of option name (e.g., "help" will match "--help").

◆ le_arg_SetFlagVar()

void le_arg_SetFlagVar ( bool *  varPtr,
const char *  shortName,
const char *  longName 
)

Register a boolean variable to be set if a given flag option appears on the argument list.

No value is expected after the option name.

One or the other of shortName or longName may be NULL. If not NULL, these MUST be pointers to strings that are never deallocated or changed.

Parameters
varPtrPtr to the variable to be set true if the flag option is found.
shortNameShort form of option name (e.g., "h" will match "-h").
longNameLong form of option name (e.g., "help" will match "--help").

◆ le_arg_SetIntCallback()

void le_arg_SetIntCallback ( le_arg_IntCallbackFunc_t  func,
const char *  shortName,
const char *  longName 
)

Register a callback function to be called if a given integer value option appears on the argument list.

An integer value is expected after the option name.

One or the other of shortName or longName may be NULL. If not NULL, these MUST be pointers to strings that are never deallocated or changed.

Parameters
funcThe callback function address.
shortNameShort form of option name (e.g., "n" will match "-n 1234").
longNameLong form of name ("max-count" matches "--max-count=1234").

◆ le_arg_SetIntVar()

void le_arg_SetIntVar ( int *  varPtr,
const char *  shortName,
const char *  longName 
)

Register an integer variable to be set if a given option appears on the argument list.

An integer value is expected after the option name.

One or the other of shortName or longName may be NULL. If not NULL, these MUST be pointers to strings that are never deallocated or changed.

Parameters
varPtrPtr to the variable to be set if the option is found.
shortNameShort form of option name (e.g., "n" will match "-n 1234").
longNameLong form of name ("max-count" matches "--max-count=1234").

◆ le_arg_SetStringCallback()

void le_arg_SetStringCallback ( le_arg_StringCallbackFunc_t  func,
const char *  shortName,
const char *  longName 
)

Register a callback function to be called if a given string option appears on the argument list.

A string value is expected after the option name.

One or the other of shortName or longName may be NULL. If not NULL, these MUST be pointers to strings that are never deallocated or changed.

Parameters
funcThe callback function address.
shortNameShort form of option name (e.g., "n" will match "-n foo").
longNameLong form of name ("name" matches "--name=foo").

◆ le_arg_SetStringVar()

void le_arg_SetStringVar ( const char **  varPtr,
const char *  shortName,
const char *  longName 
)

Register a string variable to be set if a given option appears on the argument list.

A value is expected after the option name.

const char* namePtr = "default";
le_arg_SetStringVar(&namePtr, "n", "name");

One or the other of shortName or longName may be NULL. If not NULL, these MUST be pointers to strings that are never deallocated or changed.

Parameters
varPtrPtr to the variable to be set if the option is found.
shortNameShort form of option name (e.g., "n" will match "-n foo").
longNameLong form of name ("name" matches "--name=foo").

◆ le_arg_Split()

le_result_t le_arg_Split ( const char *  firstStr,
char *  cmdlinePtr,
int *  argc,
const char **  argv 
)

Tokenizes a string into individual arguments. Simple quoting is allowed using either ' or " to enclose multi-word arguments.

Returns
  • LE_OK on success.
  • LE_BAD_PARAMETER if a parameter is invalid.
  • LE_OUT_OF_RANGE if more arguments are present than can be captured in the provided array (those that can be captured will be).
Parameters
[in]firstStrA separate string to treat as the first argument (for example, the program name). May be NULL.
[in,out]cmdlinePtrCommand line argument string to split. This string will be modified in-place.
[in,out]argcAs input, the size of the argv array. As output, the number of arguments obtained.
[out]argvThe tokenized arguments. These will be pointers into the firstStr and modified cmdlinePtr buffers.