kdbopts.h File Reference

#include <kdb.h>

Include dependency graph for kdbopts.h:

This graph shows which files directly or indirectly include this file:

Functions
int	elektraGetOpts (KeySet *ks, int argc, const char **argv, const char **envp, Key *parentKey)
	This functions parses a specification of program options, together with a list of arguments and environment variables to extract the option values. More...
char *	elektraGetOptsHelpMessage (Key *errorKey, const char *usage, const char *prefix)
	Extracts the help message from the errorKey used in elektraGetOpts(). More...

Detailed Description

Copyright

BSD License (see LICENSE.md or https://www.libelektra.org)

Function Documentation

elektraGetOpts()

int elektraGetOpts	(	KeySet *	ks,
		int	argc,
		const char **	argv,
		const char **	envp,
		Key *	parentKey
	)

This functions parses a specification of program options, together with a list of arguments and environment variables to extract the option values.

The options have to be defined in the metadata of keys in the spec namespace. If an option value is found for any of the given keys, a new key with the same path but inside the proc namespace will be inserted into ks. This enables a cascading lookup to find these values.

Take look at https://www.libelektra.org/tutorials/command-line-options for information on how exactly the specification works.

NOTE: Per default option processing DOES NOT stop, when a non-option string is encountered in argv. If you want processing to stop, set the metadata posixly = 1 on parentKey.

The basic usage of this function is as follows:

        KDB * kdb = kdbOpen (parentKey);
        KeySet * ks = ksNew (0, KS_END);
 
        kdbGet (kdb, ks, parentKey);
 
        int result = elektraGetOpts (ks, argc, argv, (const char **) environ, parentKey);
        if (result == -1)
        {
                fprintf (stderr, "ERROR: %s\n", keyString (keyGetMeta (parentKey, "error/reason")));
                keyDel (parentKey);
                ksDel (ks);
                return EXIT_FAILURE;
        }
 
        if (result == 1)
        {
                char * help = elektraGetOptsHelpMessage (parentKey, NULL, NULL);
                fprintf (stderr, "%s\n", help);
                elektraFree (help);
                keyDel (parentKey);
                ksDel (ks);
                return EXIT_SUCCESS;
        }
 

Parameters

ks	The KeySet containing the specification for the options.
argc	The number of strings in argv.
argv	The arguments to be processed.
envp	A list of environment variables. This needs to be a null-terminated list of strings of the format 'KEY=VALUE'.
parentKey	The parent key below which the function while search for option specifications. Also used for error reporting. The key will be translated into the spec namespace automatically, i.e. 'user/test/parent' will be translated into 'spec/test/parent', before checking against spec keys.

Return values

0	on success, this is the only case in which ks will be modified
-1	on error, the error will be set as metadata in errorKey
1	if the help option --help was found, use elektraGetOptsHelpMessage() access the generated help message

elektraGetOptsHelpMessage()

char* elektraGetOptsHelpMessage	(	Key *	errorKey,
		const char *	usage,
		const char *	prefix
	)

Extracts the help message from the errorKey used in elektraGetOpts().

Parameters

errorKey	The same Key as passed to elektraGetOpts() as errorKey.
usage	If this is not NULL, it will be used instead of the default usage line. Use elektraGetOptsHelpCommand() to check which command was invoked to get the right usage line.
prefix	If this is not NULL, it will be inserted between the usage line and the options list.

Returns

The full help message extracted from errorKey, or NULL if no help message was found. The returned string has to be freed with elektraFree().