Elektra  0.9.2
Functions
opts.c File Reference
#include <kdbopts.h>
#include <stdlib.h>
#include <string.h>
#include <kdbease.h>
#include <kdbhelper.h>
#include <kdbmeta.h>
#include <kdbassert.h>
#include <kdberrors.h>
Include dependency graph for opts.c:

Functions

char * generateUsageLine (const char *progname, const Key *command, const Key *commandArgs)
 Generate usage line for help message from optionsSpec. More...
 
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...
 
const char * elektraGetOptsHelpCommand (Key *errorKey)
 Extracts the command whose help message was requested from the errorKey used in elektraGetOpts(). More...
 
char * elektraGetOptsHelpMessage (Key *errorKey, const char *usage, const char *prefix)
 Extracts the help message from the errorKey used in elektraGetOpts(). More...
 

Detailed Description

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
ksThe KeySet containing the specification for the options.
argcThe number of strings in argv.
argvThe arguments to be processed.
envpA list of environment variables. This needs to be a null-terminated list of strings of the format 'KEY=VALUE'.
parentKeyThe 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
0on success, this is the only case in which ks will be modified
-1on error, the error will be set as metadata in errorKey
1if the help option --help was found, use elektraGetOptsHelpMessage() access the generated help message

◆ elektraGetOptsHelpCommand()

const char* elektraGetOptsHelpCommand ( Key *  errorKey)

Extracts the command whose help message was requested from the errorKey used in elektraGetOpts().

NOTE: this only works, if elektraGetOpts() returned 1.

Parameters
errorKeyThe same Key as passed to elektraGetOpts() as errorKey.
usageIf this is not NULL, it will be used instead of the default usage line.
prefixIf this is not NULL, it will be inserted between the usage line and the options list.
Returns
The command extracted from errorKey, or NULL if no command was found. The returned string MUST NOT be freed with elektraFree(). It will be valid as long as errorKey is not keyDel()'ed.

◆ elektraGetOptsHelpMessage()

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

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

Parameters
errorKeyThe same Key as passed to elektraGetOpts() as errorKey.
usageIf 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.
prefixIf 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().

◆ generateUsageLine()

char * generateUsageLine ( const char *  progname,
const Key *  command,
const Key *  commandArgs 
)

Generate usage line for help message from optionsSpec.

Returns
a newly allocated string, must be freed with elektraFree()
kdbGet
int kdbGet(KDB *handle, KeySet *ks, Key *parentKey)
Retrieve keys in an atomic and universal way.
Definition: kdb.c:1024
elektraGetOptsHelpMessage
char * elektraGetOptsHelpMessage(Key *errorKey, const char *usage, const char *prefix)
Extracts the help message from the errorKey used in elektraGetOpts().
Definition: opts.c:316
kdbOpen
KDB * kdbOpen(Key *errorKey)
Opens the session with the Key database.
Definition: kdb.c:290
ksNew
KeySet * ksNew(size_t alloc,...)
Allocate, initialize and return a new KeySet object.
Definition: keyset.c:225
kdb
This is the main namespace for the C++ binding and libraries.
Definition: backend.hpp:30
keyString
const char * keyString(const Key *key)
Get the c-string representing the value.
Definition: keyvalue.c:193
keyGetMeta
const Key * keyGetMeta(const Key *key, const char *metaName)
Returns the value of a meta-information given by name.
Definition: keymeta.c:414
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 envir...
Definition: opts.c:133
KS_END
#define KS_END
End of a list of keys.
Definition: kdbenum.c:88
keyDel
int keyDel(Key *key)
A destructor for Key objects.
Definition: key.c:568
ksDel
int ksDel(KeySet *ks)
A destructor for KeySet objects.
Definition: keyset.c:437
elektraFree
void elektraFree(void *ptr)
Free memory of Elektra or its backends.
Definition: internal.c:304