\hypertarget{md_doc_tutorials_command_line_options_autotoc_md3733}{}\doxysection{Introduction}\label{md_doc_tutorials_command_line_options_autotoc_md3733}
Many applications use command-\/line options and environment variables as a way to override configuration values. In Elektra this can be automated by providing a specification that maps command-\/line options and environment variables to keys in the KDB.

The recommended way to do this is via the {\ttfamily gopts} plugin. This plugin internally calls the actual parser {\ttfamily elektra\+Get\+Opts}. However, since there are some downsides to calling the parser manually, we cannot generally recommend doing so. If you think you have a use case for calling {\ttfamily elektra\+Get\+Opts} directly, take a look at the section \href{\#elektra-opts}{\texttt{ Advanced Use\+: Calling {\ttfamily elektra\+Get\+Opts} directly}} below.

The parser uses a specification together with {\ttfamily argc}/{\ttfamily argv} and a list of environment variables to create keys in the {\ttfamily proc\+:/} namespace. Because the keys are in the {\ttfamily proc\+:/} namespace, they will be preferred over all other namespaces in a standard cascading lookup. This allows us to use command-\/line options or environment variables to override standard configuration keys.\hypertarget{md_doc_tutorials_command_line_options_autotoc_md3734}{}\doxysection{Setup}\label{md_doc_tutorials_command_line_options_autotoc_md3734}
While you could manually mount and configure {\ttfamily gopts}, it is {\itshape not recommended} doing so. Instead, you should use {\ttfamily elektra\+GOpts\+Contract} to create a contract for use with {\ttfamily \mbox{\hyperlink{group__kdb_ga844e1299a84c3fbf1d3a905c5c893ba5}{kdb\+Open()}}}. This contract ensures that {\ttfamily gopts} is automatically mounted and correctly configured. To use {\ttfamily elektra\+GOpts\+Contract}, include {\ttfamily \mbox{\hyperlink{kdbgopts_8h}{kdbgopts.\+h}}}. This gives you access to these two functions\+:


\begin{DoxyCode}{0}
\DoxyCodeLine{\textcolor{keywordtype}{int} \mbox{\hyperlink{contracts_8c_af4f606fc2179e917a10c77dab576d648}{elektraGOptsContract}} (KeySet * contract, \textcolor{keywordtype}{int} argc, \textcolor{keyword}{const} \textcolor{keywordtype}{char} * \textcolor{keyword}{const} * argv, \textcolor{keyword}{const} \textcolor{keywordtype}{char} * \textcolor{keyword}{const} * envp, \textcolor{keyword}{const} Key * parentKey, KeySet * goptsConfig);}
\DoxyCodeLine{}
\DoxyCodeLine{\textcolor{keywordtype}{int} \mbox{\hyperlink{contracts_8c_ade81f23438c00b284247955e8b4b207d}{elektraGOptsContractFromStrings}} (KeySet * contract, \textcolor{keywordtype}{size\_t} argsSize, \textcolor{keyword}{const} \textcolor{keywordtype}{char} * args, \textcolor{keywordtype}{size\_t} envSize, \textcolor{keyword}{const} \textcolor{keywordtype}{char} * env, \textcolor{keyword}{const} Key * parentKey, KeySet * goptsConfig);}

\end{DoxyCode}


Whenever possible, we recommend that you use {\ttfamily elektra\+GOpts\+Contract} since it has less memory and processing overhead than {\ttfamily elektra\+GOpts\+Contract\+From\+Strings}. However, to use {\ttfamily elektra\+GOpts\+Contract} the pointers given for {\ttfamily argv} and {\ttfamily envp} must remain valid until after calling {\ttfamily \mbox{\hyperlink{group__kdb_gadb54dc9fda17ee07deb9444df745c96f}{kdb\+Close()}}}, because the {\ttfamily gopts} plugin will directly use these pointers. In the standard use case (i.\+e. using the {\ttfamily argv} from {\ttfamily \mbox{\hyperlink{testio__doc_8c_a3c04138a5bfe5d72780bb7e82a18e627}{main()}}} and the global {\ttfamily environ} for {\ttfamily envp}), this restriction is not a problem.

An example for using {\ttfamily elektra\+GOpts\+Contract} could look like this\+:


\begin{DoxyCode}{0}
\DoxyCodeLine{\textcolor{keyword}{extern} \textcolor{keywordtype}{char} ** environ;}
\DoxyCodeLine{}
\DoxyCodeLine{\textcolor{keywordtype}{int} \mbox{\hyperlink{testio__doc_8c_a3c04138a5bfe5d72780bb7e82a18e627}{main}} (\textcolor{keywordtype}{int} argc, \textcolor{keywordtype}{char} ** argv)}
\DoxyCodeLine{\{}
\DoxyCodeLine{  Key * parentKey = \mbox{\hyperlink{group__key_gad23c65b44bf48d773759e1f9a4d43b89}{keyNew}} (\textcolor{stringliteral}{"{}/sw/org/example/\#0/current"{}}, \mbox{\hyperlink{group__key_gga9b703ca49f48b482def322b77d3e6bc8aa8adb6fcb92dec58fb19410eacfdd403}{KEY\_END}});}
\DoxyCodeLine{}
\DoxyCodeLine{  KeySet * contract = \mbox{\hyperlink{group__keyset_ga671e1aaee3ae9dc13b4834a4ddbd2c3c}{ksNew}} (0, \mbox{\hyperlink{group__keyset_ga7a28fce3773b2c873c94ac80b8b4cd54}{KS\_END}});}
\DoxyCodeLine{  KeySet * goptsConfig = \mbox{\hyperlink{group__keyset_ga671e1aaee3ae9dc13b4834a4ddbd2c3c}{ksNew}} (0, \mbox{\hyperlink{group__keyset_ga7a28fce3773b2c873c94ac80b8b4cd54}{KS\_END}});}
\DoxyCodeLine{}
\DoxyCodeLine{  \textcolor{comment}{// error handling omitted for brevity}}
\DoxyCodeLine{  \mbox{\hyperlink{contracts_8c_af4f606fc2179e917a10c77dab576d648}{elektraGOptsContract}} (contract, argc, argv, environ, parentKey, goptsConfig);}
\DoxyCodeLine{}
\DoxyCodeLine{  KDB * \mbox{\hyperlink{namespacekdb}{kdb}} = \mbox{\hyperlink{group__kdb_ga844e1299a84c3fbf1d3a905c5c893ba5}{kdbOpen}} (contract, parentKey);}
\DoxyCodeLine{\}}

\end{DoxyCode}


If you cannot provide pointers that meet the requirements, you may use {\ttfamily elektra\+GOpts\+Contract\+From\+Strings}. This function copies its arguments {\ttfamily args} and {\ttfamily env} into separate memory, so the pointers need only be valid for the duration of the function call. This is mainly useful for language bindings, since in many programming languages manual memory management is not possible and there is no (easy) way to ensure the {\ttfamily argv} and {\ttfamily envp} pointers meet the necessary requirements.

The {\ttfamily gopts} plugin can also use operating system specific functions to retrieve the command-\/line arguments and environment variables internally. We recommend that you do not rely on this behavior whenever possible, since it can be a bit flaky (especially for command-\/line arguments). However, if for example you are writing a library or for some other reason do not have access to the necessary data, you can use this fallback.

If you pass {\ttfamily argc=0} {\bfseries{and}} {\ttfamily argv=NULL} to {\ttfamily elektra\+GOpts\+Contract} or {\ttfamily args\+Size=0} {\bfseries{and}} {\ttfamily args=NULL} to {\ttfamily elektra\+GOpts\+Contract\+From\+Strings}, {\ttfamily gopts} will fallback to the internal lookup of command-\/line options. Similarly, if you pass {\ttfamily envp=NULL} to {\ttfamily elektra\+GOpts\+Contract} or {\ttfamily env\+Size=0} {\bfseries{and}} {\ttfamily env=NULL} to {\ttfamily elektra\+GOpts\+Contract\+From\+Strings}, environment variables will be retrieved internally.

The other parameters are the same for both functions. The contract will be written into the {\ttfamily contract} Key\+Set. The {\ttfamily parent\+Key} indicates where to find the specification. The actual namespace that {\ttfamily parent\+Key} uses is irrelevant (we recommend a cascading key, so that it can be re-\/used for {\ttfamily \mbox{\hyperlink{group__kdb_ga28e385fd9cb7ccfe0b2f1ed2f62453a1}{kdb\+Get()}}}). The parser will use the keys below the {\ttfamily spec\+:/} namespace key equivalent to {\ttfamily parent\+Key} as the specification, and it will write keys to the equivalent key in {\ttfamily proc\+:/}.

The last parameter {\ttfamily gopts\+Config} can be used to provide additional configuration values to {\ttfamily gopts}. For example, this can be used to configure the auto-\/generated help message. The keys that {\ttfamily gopts} accepts in this Key\+Set will be explained throughout the document . A full list can be found in the \mbox{\hyperlink{md_src_plugins_gopts_README}{\`{}gopts\`{} README}}.\hypertarget{md_doc_tutorials_command_line_options_autotoc_md3735}{}\doxysection{Specification}\label{md_doc_tutorials_command_line_options_autotoc_md3735}
This section describes the specification used by the command-\/line option and environment variable parser.\hypertarget{md_doc_tutorials_command_line_options_autotoc_md3736}{}\doxysubsection{Options}\label{md_doc_tutorials_command_line_options_autotoc_md3736}
To define a command-\/line option either set the {\ttfamily opt} metakey to the short option you want to use, or set {\ttfamily opt/long} to the long option you want to use. For short options, only the first character of the given value will be used (\textquotesingle{}\textbackslash{}0\textquotesingle{} is ignored). Short and long options can be used simultaneously.

Additionally, a key can also be associated with multiple short/long options. To achieve this treat {\ttfamily opt} as an array. For example for two options {\ttfamily -\/a} and {\ttfamily -\/b} you would set {\ttfamily opt=\#1}, {\ttfamily opt/\#0=a} and {\ttfamily opt/\#1=b}. If not explicitly stated otherwise, you can replace {\ttfamily opt} with any {\ttfamily opt/\#} array element in all meta-\/keys mentioned in this document. This of course includes long options (i.\+e. {\ttfamily opt/\#0/long}, etc.).

While you can specify multiple options (or environment variables, see below) for a single key, only one of them can be used at the same time. Using two or more options (or variables) that are all linked to the same key, will result in an error.\hypertarget{md_doc_tutorials_command_line_options_autotoc_md3737}{}\doxysubsubsection{Option Arguments}\label{md_doc_tutorials_command_line_options_autotoc_md3737}
Per default an option is expected to have an argument. Arguments to short and long options are given in the same way as with {\ttfamily getopt\+\_\+long(3)} (i.\+e. {\ttfamily -\/oarg}, {\ttfamily -\/o arg}, {\ttfamily -\/-\/option arg} or {\ttfamily -\/-\/option=arg}).

To change whether an option expects an argument set {\ttfamily opt/arg} to either {\ttfamily \char`\"{}none\char`\"{}} or {\ttfamily \char`\"{}optional\char`\"{}} (the default is {\ttfamily \char`\"{}required\char`\"{}}).


\begin{DoxyItemize}
\item If you choose {\ttfamily \char`\"{}none\char`\"{}}, the corresponding key will be set to {\ttfamily \char`\"{}1\char`\"{}}, if the option is used This value can be changed by setting {\ttfamily opt/flagvalue}.
\item An option that is set to {\ttfamily \char`\"{}optional\char`\"{}} is treated the same as with {\ttfamily \char`\"{}none\char`\"{}}, except that you can also set the value with the long option form {\ttfamily -\/-\/option=value}. This also means that {\ttfamily opt/flagvalue} is used, if no argument is given. Contrary to {\ttfamily getopt\+\_\+long(3)} options with optional arguments can still have short forms. They just cannot have an argument in this form.
\end{DoxyItemize}\hypertarget{md_doc_tutorials_command_line_options_autotoc_md3738}{}\doxysubsection{Environment Variables}\label{md_doc_tutorials_command_line_options_autotoc_md3738}
Elektra also supports parsing environment variables in a similar manner. For these there are however, less configuration options. You can simply specify one or more environment variables for a key using the {\ttfamily env} metakey (or {\ttfamily env/\#} meta-\/array for multiple).\hypertarget{md_doc_tutorials_command_line_options_autotoc_md3739}{}\doxysubsection{Arrays}\label{md_doc_tutorials_command_line_options_autotoc_md3739}
Both options and environment variables expose special behavior, if used in combination with arrays.

If an option is specified on a key with basename {\ttfamily \#}, the option can be used repeatedly. All occurrences will be collected into the array.

Environment variables obviously cannot be repeated, instead a behavior similar that used for PATH is adopted. On Windows the variable will be split at each \textquotesingle{};\textquotesingle{} character. On all other systems \textquotesingle{}\+:\textquotesingle{} is used as a separator.\hypertarget{md_doc_tutorials_command_line_options_autotoc_md3740}{}\doxysubsection{Parameter Arguments}\label{md_doc_tutorials_command_line_options_autotoc_md3740}
All unused elements of {\ttfamily argv} are be collected into an array. You can access this array by specifying {\ttfamily args=remaining} on a key with basename {\ttfamily \#}. The array will be copied into this key. As is the case with getopt(3) processing of options will stop, if {\ttfamily -\/-\/} is encountered in {\ttfamily argv}.

If we parse command-\/line options like the POSIX version of getopt(3) does, then we would also stop processing options at the first non-\/option argument. This not the case by default, but we can enable this behavior. To do so, you need to pass a Key {\ttfamily /posixly} with value {\ttfamily 1} in the {\ttfamily gopts\+Config} Key\+Set of the {\ttfamily gopts} contract.

Additionally, there is {\ttfamily args=indexed}. If it is specified on a key, the key must also have the metakey {\ttfamily args/index=N} set to an integer {\ttfamily N}. Such a key will be set to the unused element at index {\ttfamily N}. If a key has {\ttfamily args=indexed} and {\ttfamily args/index=N}, then there must also be keys for all integers {\ttfamily 0 $<$= X $<$ N} with {\ttfamily args=indexed} and {\ttfamily args/index=N} set. For example, you cannot use {\ttfamily args/index=0} and {\ttfamily args/index=2} without {\ttfamily args/index=1}.

Combining {\ttfamily args=indexed} and {\ttfamily args=remaining} in the same specification (on different keys) is also possible. The key with {\ttfamily args=remaining} will only contain those elements not used via {\ttfamily args=indexed}. For example, if there are keys with {\ttfamily args/index=0} and {\ttfamily args/index=1} then the {\ttfamily args=remaining} array will start with the third (index 2) parameter argument. Note however, the {\ttfamily args=remaining} array {\bfseries{always}} starts with index {\ttfamily \#0}, even if it doesn\textquotesingle{}t contain the first parameter argument.\hypertarget{md_doc_tutorials_command_line_options_autotoc_md3741}{}\doxysubsubsection{Example}\label{md_doc_tutorials_command_line_options_autotoc_md3741}

\begin{DoxyCode}{0}
\DoxyCodeLine{[from]}
\DoxyCodeLine{args = indexed}
\DoxyCodeLine{args/index = 0}
\DoxyCodeLine{}
\DoxyCodeLine{[to]}
\DoxyCodeLine{args = indexed}
\DoxyCodeLine{args/index = 1}
\DoxyCodeLine{}
\DoxyCodeLine{[more/\#]}
\DoxyCodeLine{args = remaining}

\end{DoxyCode}


If an application {\ttfamily app} with the specification above is called as {\ttfamily ./app apple banana cherry date}, then the keys will be assigned as follows\+:


\begin{DoxyItemize}
\item {\ttfamily from = apple}
\item {\ttfamily to = banana}
\item {\ttfamily more/\#0 = cherry}
\item {\ttfamily more/\#1 = date}
\end{DoxyItemize}\hypertarget{md_doc_tutorials_command_line_options_autotoc_md3742}{}\doxysubsection{Sub-\/\+Commands}\label{md_doc_tutorials_command_line_options_autotoc_md3742}
The parser also supports sub-\/commands. Explaining sub-\/commands is easiest through the help of an example\+: {\ttfamily add} and {\ttfamily commit} are both sub-\/commands of {\ttfamily git}, since we can call {\ttfamily git add} and {\ttfamily git commit} and they do entirely different things. The most important impact of using sub-\/commands is their effect on option arguments. For example calling {\ttfamily git -\/p add} and {\ttfamily git add -\/p} result in different behavior, since the {\ttfamily -\/p} option is interpreted differently. The options that {\ttfamily git} understands are separate from the options that its sub-\/command {\ttfamily add} knows. However, the option {\ttfamily -\/p} is understood by both. In {\ttfamily git} it is short for {\ttfamily -\/-\/paginate} and in {\ttfamily add} it is short for {\ttfamily -\/-\/patch}.

An important thing to know about sub-\/commands is that they automatically turn on POSIX mode. This means {\bfseries{all}} options for a specific sub-\/command must be given before any non-\/option arguments (such as parameters or sub-\/commands). Otherwise, we couldn\textquotesingle{}t distinguish between {\ttfamily git -\/p add} and {\ttfamily git add -\/p}. In other words an option argument is always assigned to the first sub-\/command to its left. Any element of {\ttfamily argv} that is not the argument for an option argument, either switches to a new sub-\/command or is the start of the parameter arguments.

A sub-\/command is created by specifying {\ttfamily command} on a key. To enable sub-\/command processing the parent key of the whole specification must have {\ttfamily command} set to an empty string. All keys marked with {\ttfamily command} {\bfseries{directly}} below another key {\ttfamily K} marked with {\ttfamily command} (e.\+g. the parent key) are sub-\/commands of {\ttfamily K}. It is an error, if the immediate parent of a key {\ttfamily X} marked with {\ttfamily command} is not marked with {\ttfamily command} and {\ttfamily X} is not the parent of the whole specification.

To inform the application about the invoked sub-\/commands, the parser sets each {\ttfamily command} key to one of two values\+:


\begin{DoxyItemize}
\item The basename of the key, whose command was invoked.
\item An empty string otherwise.
\end{DoxyItemize}

For example consider {\ttfamily ./app add more}\+: The parent key will be set to the basename of whatever key {\ttfamily command=add} was specified on, the key for {\ttfamily add} will be set to the basename corresponding to {\ttfamily more} and the key for {\ttfamily more} is set to an empty string, because none of its sub-\/commands were invoked. A more detailed example is shown below.

Every key considered by the parser is assigned either to the root command, or a single sub-\/command. Specifically, each key is assigned to the command of its immediate parent. If sub-\/commands are used and the immediate parent of an {\ttfamily opt} or {\ttfamily args} key has no {\ttfamily command} metadata an error occurs. The value of a key will {\bfseries{only}} be set, if the corresponding sub-\/command was invoked.

Lastly, it is allowed to have keys with {\ttfamily args} and {\ttfamily command} below the same parent. If a matching sub-\/command is found among the {\ttfamily command} keys, processing will continue there. Otherwise, the {\ttfamily args} keys will be considered. This allows an application to implement dynamic commands (like {\ttfamily git} or {\ttfamily kdb}) by using the {\ttfamily args=remaining} array to invoke another application.

If an unknown sub-\/command is encountered without an {\ttfamily args} key, an error is returned.

All of this is best understood with an example\+:


\begin{DoxyCode}{0}
\DoxyCodeLine{[kdb]}
\DoxyCodeLine{command = "{}"{}}
\DoxyCodeLine{}
\DoxyCodeLine{[kdb/printversion]}
\DoxyCodeLine{description = "{}print version information and exit (ignoring all other options/commands/parameters)"{}}
\DoxyCodeLine{opt = v}
\DoxyCodeLine{opt/long = version}
\DoxyCodeLine{opt/arg = none}
\DoxyCodeLine{}
\DoxyCodeLine{[kdb/getter]}
\DoxyCodeLine{description = "{}get a key's value"{}}
\DoxyCodeLine{command = get}
\DoxyCodeLine{}
\DoxyCodeLine{[kdb/getter/verbose]}
\DoxyCodeLine{description = "{}print additional information about where the value comes from"{}}
\DoxyCodeLine{opt = v}
\DoxyCodeLine{opt/long = verbose}
\DoxyCodeLine{opt/arg = none}
\DoxyCodeLine{}
\DoxyCodeLine{[kdb/getter/keyname]}
\DoxyCodeLine{description = "{}name of the key to read"{}}
\DoxyCodeLine{args = indexed}
\DoxyCodeLine{args/index = 0}
\DoxyCodeLine{}
\DoxyCodeLine{[kdb/setter]}
\DoxyCodeLine{description = "{}print additional information about where the value will be stored"{}}
\DoxyCodeLine{command = set}
\DoxyCodeLine{}
\DoxyCodeLine{[kdb/setter/verbose]}
\DoxyCodeLine{description = "{}name of the key to write"{}}
\DoxyCodeLine{opt = v}
\DoxyCodeLine{opt/long = verbose}
\DoxyCodeLine{opt/arg = none}
\DoxyCodeLine{}
\DoxyCodeLine{[kdb/setter/keyname]}
\DoxyCodeLine{description = "{}name of the key to write"{}}
\DoxyCodeLine{args = indexed}
\DoxyCodeLine{args/index = 0}
\DoxyCodeLine{}
\DoxyCodeLine{[kdb/setter/value]}
\DoxyCodeLine{description = "{}value to be written"{}}
\DoxyCodeLine{args = indexed}
\DoxyCodeLine{args/index = 1}
\DoxyCodeLine{}
\DoxyCodeLine{[kdb/dynamic/\#]}
\DoxyCodeLine{description = "{}dynamically call a user-\/supplied command"{}}
\DoxyCodeLine{args = remaining}

\end{DoxyCode}



\begin{DoxyItemize}
\item If we invoke {\ttfamily kdb -\/v}, keys below {\ttfamily kdb/getter}, {\ttfamily kdb/setter} and {\ttfamily kdb/dynamic} are not touched. The result is\+:
\begin{DoxyItemize}
\item {\ttfamily kdb = \char`\"{}\char`\"{}}
\item {\ttfamily kdb/printversion = 1}
\item {\ttfamily kdb/getter = \char`\"{}\char`\"{}}
\item {\ttfamily kdb/setter = \char`\"{}\char`\"{}}
\end{DoxyItemize}
\item If we invoke {\ttfamily kdb get -\/v name}, keys below {\ttfamily kdb/setter} and {\ttfamily kdb/dynamic} are not touched. The result is\+:
\begin{DoxyItemize}
\item {\ttfamily kdb = getter}
\item {\ttfamily kdb/getter = \char`\"{}\char`\"{}}
\item {\ttfamily kdb/getter/verbose = 1}
\item {\ttfamily kdb/getter/keyname = name}
\item {\ttfamily kdb/setter = \char`\"{}\char`\"{}}
\end{DoxyItemize}
\item If we invoke {\ttfamily kdb -\/v set -\/v}, keys below {\ttfamily kdb/getter} and {\ttfamily kdb/dynamic} are not touched. The result is\+:
\begin{DoxyItemize}
\item {\ttfamily kdb = setter}
\item {\ttfamily kdb/printversion = 1}
\item {\ttfamily kdb/setter = \char`\"{}\char`\"{}}
\item {\ttfamily kdb/setter/verbose = 1}
\item {\ttfamily kdb/getter = \char`\"{}\char`\"{}}
\end{DoxyItemize}
\item If we invoke {\ttfamily kdb -\/v custom -\/v -\/x z}, keys below {\ttfamily kdb/getter} and {\ttfamily kdb/setter} are not touched. The result is\+:
\begin{DoxyItemize}
\item {\ttfamily kdb = \char`\"{}\char`\"{}}
\item {\ttfamily kdb/printversion = 1}
\item {\ttfamily kdb/getter = \char`\"{}\char`\"{}}
\item {\ttfamily kdb/setter = \char`\"{}\char`\"{}}
\item {\ttfamily kdb/dynamic/\#0 = custom}
\item {\ttfamily kdb/dynamic/\#1 = -\/v}
\item {\ttfamily kdb/dynamic/\#2 = -\/x}
\item {\ttfamily kdb/dynamic/\#3 = z}
\end{DoxyItemize}
\end{DoxyItemize}

To determine what code to execute, an application would just start with the parent key {\ttfamily kdb} in the example above. It would then repeatedly look at the current key\textquotesingle{}s value, append that to the current key and continue, until the current key\textquotesingle{}s value was the empty string {\ttfamily \char`\"{}\char`\"{}}. Each of the examined keys corresponds to one of the sub-\/commands in the invocation and the keys directly below those, contain the relevant options (and for the last sub-\/command also parameters).

The C code for this example is located in {\ttfamily examples/opts\+Commands.\+c}.\hypertarget{md_doc_tutorials_command_line_options_autotoc_md3743}{}\doxysubsection{Precedence}\label{md_doc_tutorials_command_line_options_autotoc_md3743}
The order of precedence is simple\+:


\begin{DoxyItemize}
\item If a short option for a key is found, it will always be used.
\item If none of the short options for a key are found, we look for long options.
\item If neither short nor long options are found, environment variables are considered.
\end{DoxyItemize}\hypertarget{md_doc_tutorials_command_line_options_autotoc_md3744}{}\doxysubsection{Limitations}\label{md_doc_tutorials_command_line_options_autotoc_md3744}

\begin{DoxyItemize}
\item Both options and environment variables can only be specified on a single key. If you need to have the value of one option/environment variable in multiple keys, you may use {\ttfamily fallback}s.
\item {\ttfamily -\/} cannot be used as a short option, because it would collide with, the \char`\"{}option end marker\char`\"{}.
\item {\ttfamily help} cannot be used as a long option, because it would collide with the help option.
\end{DoxyItemize}\hypertarget{md_doc_tutorials_command_line_options_autotoc_md3745}{}\doxysection{Help Message}\label{md_doc_tutorials_command_line_options_autotoc_md3745}
When the help option {\ttfamily -\/-\/help} is encountered in {\ttfamily argv}, the parser only reads the specification, but does not create any keys in the {\ttfamily proc\+:/} namespace. It will however, generate a standard help message that you can print.

To find you, whether {\ttfamily -\/-\/help} was encountered, check if the Key\+Set returned by {\ttfamily \mbox{\hyperlink{group__kdb_ga28e385fd9cb7ccfe0b2f1ed2f62453a1}{kdb\+Get()}}} contains the special key {\ttfamily proc\+:/elektra/gopts/help} with value {\ttfamily 1}. If it does, the auto-\/generated help message is stored in the key {\ttfamily proc\+:/elektra/gopts/help/message}.


\begin{DoxyCode}{0}
\DoxyCodeLine{\textcolor{keywordtype}{int} \mbox{\hyperlink{testio__doc_8c_a3c04138a5bfe5d72780bb7e82a18e627}{main}} (\textcolor{keywordtype}{int} argc, \textcolor{keywordtype}{char} ** argv)}
\DoxyCodeLine{\{}
\DoxyCodeLine{  \textcolor{comment}{// setup ommitted for brevity}}
\DoxyCodeLine{  KeySet * ks = \mbox{\hyperlink{group__keyset_ga671e1aaee3ae9dc13b4834a4ddbd2c3c}{ksNew}} (0, \mbox{\hyperlink{group__keyset_ga7a28fce3773b2c873c94ac80b8b4cd54}{KS\_END}});}
\DoxyCodeLine{}
\DoxyCodeLine{  \textcolor{comment}{// error handling ommitted for brevity}}
\DoxyCodeLine{  \mbox{\hyperlink{group__kdb_ga28e385fd9cb7ccfe0b2f1ed2f62453a1}{kdbGet}} (\mbox{\hyperlink{namespacekdb}{kdb}}, ks, parentKey);}
\DoxyCodeLine{}
\DoxyCodeLine{  Key * help = \mbox{\hyperlink{group__keyset_gad65d2cdcbb5381194a1688e169af8a83}{ksLookupByName}} (ks, \textcolor{stringliteral}{"{}proc:/elektra/gopts/help"{}});}
\DoxyCodeLine{  \textcolor{keywordflow}{if} (help != NULL \&\& strcmp (\mbox{\hyperlink{group__keyvalue_ga880936f2481d28e6e2acbe7486a21d05}{keyString}} (help), \textcolor{stringliteral}{"{}1"{}}) == 0)}
\DoxyCodeLine{  \{}
\DoxyCodeLine{    printf (\textcolor{stringliteral}{"{}\%s\(\backslash\)n"{}}, \mbox{\hyperlink{group__keyvalue_ga880936f2481d28e6e2acbe7486a21d05}{keyString}} (\mbox{\hyperlink{group__keyset_gad65d2cdcbb5381194a1688e169af8a83}{ksLookupByName}} (ks, \textcolor{stringliteral}{"{}proc:/elektra/gopts/help/message"{}})));}
\DoxyCodeLine{    \textcolor{comment}{// cleanup omitted for brevity}}
\DoxyCodeLine{    \textcolor{keywordflow}{return} 0;}
\DoxyCodeLine{  \}}
\DoxyCodeLine{\}}

\end{DoxyCode}


\begin{quote}
{\bfseries{Note}}\+: The key {\ttfamily proc\+:/elektra/gopts/help} will always be generated. Only if its value is set to {\ttfamily 1}, was the {\ttfamily -\/-\/help} option encountered. \end{quote}
\hypertarget{md_doc_tutorials_command_line_options_autotoc_md3746}{}\doxysubsection{Structure of the Help Message}\label{md_doc_tutorials_command_line_options_autotoc_md3746}
The help message consists of a usage line and an options list. The program name for the usage line is taken from {\ttfamily argv\mbox{[}0\mbox{]}}. If the value contains a slash ({\ttfamily /}) it will be considered a path and only the part after the last slash will be used.

The options list will contain exactly one entry for each key that has at least one option. Each entry has to parts. First all the options for the key are listed and then (possibly on the next line, if there are a lot of options), the description for the key is listed. The description is taken from the {\ttfamily opt/help} or alternatively the {\ttfamily description} metakey.

{\bfseries{Note\+:}} {\ttfamily opt/help} is specified {\itshape only once per key}. That means even if the key uses {\ttfamily opt/\#0}, {\ttfamily opt/\#1}, etc. (unlike most other metadata) the description will always be taken from {\ttfamily opt/help} directly, because there can only be one description. In general, we recommend using {\ttfamily description}, because it is used by other parts of Elektra as well. {\ttfamily opt/help} is intended to provide a less verbose description more suitable for the command-\/line.\hypertarget{md_doc_tutorials_command_line_options_autotoc_md3747}{}\doxysubsection{Sub-\/\+Commands}\label{md_doc_tutorials_command_line_options_autotoc_md3747}
If sub-\/commands are in use, the generated help message will apply to the invoked sub-\/command only. For example {\ttfamily ./app -\/-\/help} generates the general help message for {\ttfamily ./app} containing only options valid for the root command. But {\ttfamily ./app more -\/-\/help} generates the help message for the sub-\/command {\ttfamily more} and contains options valid to this sub-\/command.\hypertarget{md_doc_tutorials_command_line_options_autotoc_md3748}{}\doxysubsection{Modifying the Help Message}\label{md_doc_tutorials_command_line_options_autotoc_md3748}
The standard help message can be modified in a few different ways\+:


\begin{DoxyItemize}
\item The usage line can be replaced by a custom string (see below).
\item A custom string can be inserted between the usage line and the options list (see below).
\item An option can can be hidden from the help message by setting {\ttfamily opt/hidden} to {\ttfamily \char`\"{}1\char`\"{}}. This hides both the long and short form of the option. If you want to hide just one form, use an array of two options and hide just one index.
\item If the option has an {\ttfamily \char`\"{}optional\char`\"{}} or {\ttfamily \char`\"{}required\char`\"{}} argument, the string {\ttfamily ARG} will be used as a placeholder by default. You can change this, by setting {\ttfamily opt/arg/help} for the corresponding option.
\end{DoxyItemize}\hypertarget{md_doc_tutorials_command_line_options_autotoc_md3749}{}\doxysubsubsection{Custom Usage Line}\label{md_doc_tutorials_command_line_options_autotoc_md3749}
To use a custom usage line, you can either \href{\#manual-help-message}{\texttt{ manually generate the help message}} or you can pass the key {\ttfamily /help/usage} in the {\ttfamily gopts\+Config} Key\+Set. The value of {\ttfamily /help/usage} will be used to replace the default usage line.

Please note, that this will replace the whole usage line including the program name taken from {\ttfamily argv\mbox{[}0\mbox{]}}.\hypertarget{md_doc_tutorials_command_line_options_autotoc_md3750}{}\doxysubsubsection{Adding a Prefix Text}\label{md_doc_tutorials_command_line_options_autotoc_md3750}
If you just want to add information above the options list, but not replace the whole usage line, you can do so by adding a prefix text. This can be done by \href{\#manual-help-message}{\texttt{ manually generating the help message}} or by passing the key {\ttfamily /help/prefix} in the {\ttfamily gopts\+Config} Key\+Set. The value of {\ttfamily /help/prefix} will be inserted between the usage line and the options list.\hypertarget{md_doc_tutorials_command_line_options_autotoc_md3751}{}\doxysection{Examples}\label{md_doc_tutorials_command_line_options_autotoc_md3751}
The following specification describes a command line interface similar to the one used by {\ttfamily rm}. (It is based of {\ttfamily rm (GNU coreutils) 8.\+30}).


\begin{DoxyCode}{0}
\DoxyCodeLine{[force]}
\DoxyCodeLine{opt = f}
\DoxyCodeLine{opt/long = force}
\DoxyCodeLine{opt/arg = none}
\DoxyCodeLine{description = ignore nonexistent files and arguments, never prompt}
\DoxyCodeLine{}
\DoxyCodeLine{[interactive]}
\DoxyCodeLine{opt = \#1}
\DoxyCodeLine{opt/\#0 = i}
\DoxyCodeLine{opt/\#0/long = interactive}
\DoxyCodeLine{opt/\#0/arg = optional}
\DoxyCodeLine{opt/\#0/flagvalue = always}
\DoxyCodeLine{opt/\#1 = I}
\DoxyCodeLine{opt/\#1/flagvalue = once}
\DoxyCodeLine{opt/\#1/arg = none}
\DoxyCodeLine{opt/arg/name = WHEN}
\DoxyCodeLine{description = prompt according to WHEN: never, once (-\/I), or always (-\/i); without WHEN, prompt always}
\DoxyCodeLine{}
\DoxyCodeLine{[singlefs]}
\DoxyCodeLine{opt/long = one-\/file-\/system}
\DoxyCodeLine{opt/arg = none}
\DoxyCodeLine{description = when removing a hierarchy recursively, skip any directory that is on a file system different from that of the corresponding line argument}
\DoxyCodeLine{}
\DoxyCodeLine{[nopreserve]}
\DoxyCodeLine{opt/long = no-\/preserve-\/root}
\DoxyCodeLine{opt/arg = none}
\DoxyCodeLine{description = do not treat '/' specially}
\DoxyCodeLine{}
\DoxyCodeLine{[preserve]}
\DoxyCodeLine{opt/long = preserve-\/root}
\DoxyCodeLine{opt/arg = optional}
\DoxyCodeLine{opt/arg/name = all}
\DoxyCodeLine{opt/flagvalue = root}
\DoxyCodeLine{description = do not remove '/' (default); with 'all', reject any command line argument on a separate device from its parent}
\DoxyCodeLine{}
\DoxyCodeLine{[recursive]}
\DoxyCodeLine{opt = \#1}
\DoxyCodeLine{opt/\#0 = r}
\DoxyCodeLine{opt/\#0/long = recursive}
\DoxyCodeLine{opt/\#0/arg = none}
\DoxyCodeLine{opt/\#1 = R}
\DoxyCodeLine{opt/\#1/arg = none}
\DoxyCodeLine{description = remove directories and their contents recursively}
\DoxyCodeLine{}
\DoxyCodeLine{[emptydirs]}
\DoxyCodeLine{opt = d}
\DoxyCodeLine{opt/long = dir}
\DoxyCodeLine{opt/arg = none}
\DoxyCodeLine{description = remove empty directories}
\DoxyCodeLine{}
\DoxyCodeLine{[verbose]}
\DoxyCodeLine{opt = v}
\DoxyCodeLine{opt/long = verbose}
\DoxyCodeLine{opt/arg = none}
\DoxyCodeLine{env = VERBOSE}
\DoxyCodeLine{description = explain what is being done}
\DoxyCodeLine{}
\DoxyCodeLine{[showversion]}
\DoxyCodeLine{opt/long = version}
\DoxyCodeLine{opt/arg = none}
\DoxyCodeLine{description = output version information and exit}
\DoxyCodeLine{}
\DoxyCodeLine{[files/\#]}
\DoxyCodeLine{args = remaining}
\DoxyCodeLine{env = FILES}
\DoxyCodeLine{description = the files that shall be deleted}

\end{DoxyCode}


If this specification is used in a program called {\ttfamily erm} (for Elektra rm), which is called like this\+:


\begin{DoxyCode}{0}
\DoxyCodeLine{FILES="{}one.txt:other.log"{} VERBOSE=1 erm -\/fi -\/-\/recursive}

\end{DoxyCode}


The following keys will be created (assuming the specification is mounted at {\ttfamily spec\+:/sw/org/erm/\#0/current})\+:


\begin{DoxyItemize}
\item {\ttfamily proc\+:/sw/org/erm/\#0/current/force = \char`\"{}1\char`\"{}}
\item {\ttfamily proc\+:/sw/org/erm/\#0/current/interactive = \char`\"{}always\char`\"{}}
\item {\ttfamily proc\+:/sw/org/erm/\#0/current/recursive = \char`\"{}1\char`\"{}}
\item {\ttfamily proc\+:/sw/org/erm/\#0/current/verbose = \char`\"{}1\char`\"{}}
\item {\ttfamily proc\+:/sw/org/erm/\#0/current/files \mbox{[}array\mbox{]} = \char`\"{}\#1\char`\"{}}
\item {\ttfamily proc\+:/sw/org/erm/\#0/current/files/\#0 = \char`\"{}one.\+txt\char`\"{}}
\item {\ttfamily proc\+:/sw/org/erm/\#0/current/files/\#1 = \char`\"{}other.\+log\char`\"{}}
\end{DoxyItemize}

Calling {\ttfamily FILES=\char`\"{}abcd.\+txt\char`\"{} erm 123.\+txt 456.\+txt} meanwhile will result in\+:


\begin{DoxyItemize}
\item {\ttfamily proc\+:/sw/org/erm/\#0/current/files \mbox{[}array\mbox{]} = \char`\"{}\#1\char`\"{}}
\item {\ttfamily proc\+:/sw/org/erm/\#0/current/files/\#0 = \char`\"{}123.\+txt\char`\"{}}
\item {\ttfamily proc\+:/sw/org/erm/\#0/current/files/\#1 = \char`\"{}456.\+txt\char`\"{}}
\end{DoxyItemize}

NOTE\+: {\ttfamily proc\+:/sw/org/erm/\#0/current/files \mbox{[}array\mbox{]} = \char`\"{}\#1\char`\"{}} means the {\ttfamily array} metadata of {\ttfamily proc\+:/sw/org/erm/\#0/current/files} is {\ttfamily \#1}.

You can find a full working example \href{/examples/gopts.c}{\texttt{ here}}. However, it uses a hard coded specification which is a bit harder to read.

\label{_elektra-opts}%
\hypertarget{md_doc_tutorials_command_line_options_autotoc_md3752}{}\doxysection{Advanced Use\+: Calling $<$tt$>$elektra\+Get\+Opts$<$/tt$>$ directly}\label{md_doc_tutorials_command_line_options_autotoc_md3752}
The actual command line parser is implemented in {\ttfamily elektra\+Get\+Opts}.


\begin{DoxyCode}{0}
\DoxyCodeLine{\textcolor{keywordtype}{int} \mbox{\hyperlink{opts_8c_a9b60d56d97c918867960f19c19ab4058}{elektraGetOpts}} (KeySet * ks, \textcolor{keywordtype}{int} argc, \textcolor{keyword}{const} \textcolor{keywordtype}{char} ** argv, \textcolor{keyword}{const} \textcolor{keywordtype}{char} ** envp, Key * parentKey);}

\end{DoxyCode}


To access this function, you first need to link your application against {\ttfamily libelektra-\/opts} and then include the header {\ttfamily \mbox{\hyperlink{kdbopts_8h}{kdbopts.\+h}}}.

\begin{quote}
{\bfseries{Note\+:}} {\ttfamily libelektra-\/opts} is an internal library and {\ttfamily \mbox{\hyperlink{kdbopts_8h}{kdbopts.\+h}}} an internal header. We do not make and guarantees to the API stability of the functions declared in {\ttfamily \mbox{\hyperlink{kdbopts_8h}{kdbopts.\+h}}}. We will do our best to keep the API compatible, but the only way to have guaranteed API stability and backwards compatibility is be only using the parser via {\ttfamily gopts}. \end{quote}
Calling {\ttfamily elektra\+Get\+Opts} directly has some disadvantages. The main one being that there is no way to validate the values of command-\/line options. When you use {\ttfamily gopts}, you can for example add the metadata {\ttfamily type=long} to a key with a command-\/line option specification and the {\ttfamily type} plugin will validate that the value generated by the command-\/line option parser is actually of type {\ttfamily long}. But since {\ttfamily elektra\+Get\+Opts} has no way of delegating to plugins (as it is independent of {\ttfamily kdb\+Get}), you need to do all validation manually.

So why would you want to call {\ttfamily elektra\+Get\+Opts} directly? The advantage of calling {\ttfamily elektra\+Get\+Opts} directly is that you have more control over where the specification comes from. With {\ttfamily gopts} we need to mount the specification before starting our application (at least before calling {\ttfamily kdb\+Open}). But if we call {\ttfamily elektra\+Get\+Opts} directly, we can pass whatever Key\+Set we want. This can be useful, if you are writing a custom configuration tool (like the standard {\ttfamily kdb} tool, but specific to your use case). Such tools normally don\textquotesingle{}t need (or want) to be configured via persistent config files, but often have an advanced command-\/line interface. Using the fairly feature-\/rich parser implemented in {\ttfamily elektra\+Get\+Opts} could be a good option here.\hypertarget{md_doc_tutorials_command_line_options_autotoc_md3753}{}\doxysection{Advanced Use\+: Manually Generating the Help Message}\label{md_doc_tutorials_command_line_options_autotoc_md3753}
When using {\ttfamily gopts} you automatically get a generated help message via the key {\ttfamily proc\+:/elektra/gopts/help/message}, whenever the {\ttfamily -\/-\/help} option is used. But if you want to show the help message in another case, or you cannot use the auto-\/generated message for some reason (e.\+g. you want to add a prefix text, but the content of this text is not known before calling {\ttfamily \mbox{\hyperlink{group__kdb_ga844e1299a84c3fbf1d3a905c5c893ba5}{kdb\+Open()}}}), then you need to generate the help message manually.

If you are using {\ttfamily elektra\+Get\+Opts} directly, manually generating the help message is the only option.

The help message can be generated with {\ttfamily elektra\+Get\+Opts\+Help\+Message}.


\begin{DoxyCode}{0}
\DoxyCodeLine{\textcolor{keywordtype}{char} * \mbox{\hyperlink{opts_8c_ac289611a114f2b2a60b740b71313a965}{elektraGetOptsHelpMessage}} (Key * helpKey, \textcolor{keyword}{const} \textcolor{keywordtype}{char} * usage, \textcolor{keyword}{const} \textcolor{keywordtype}{char} * prefix);}

\end{DoxyCode}


To access this function, you first need to link your application against {\ttfamily libelektra-\/opts} and then include the header {\ttfamily \mbox{\hyperlink{kdbopts_8h}{kdbopts.\+h}}}.

\begin{quote}
{\bfseries{Note\+:}} {\ttfamily libelektra-\/opts} is an internal library and {\ttfamily \mbox{\hyperlink{kdbopts_8h}{kdbopts.\+h}}} an internal header. We do not make and guarantees to the API stability of the functions declared in {\ttfamily \mbox{\hyperlink{kdbopts_8h}{kdbopts.\+h}}}. We will do our best to keep the API compatible, but the only way to have guaranteed API stability and backwards compatibility is be only using the parser via {\ttfamily gopts}. \end{quote}
Calling {\ttfamily elektra\+Get\+Opts\+Help\+Message} allocates a new string that will contain the generated help message. You need to free the string with {\ttfamily elektra\+Free}, once you are done with it.

The parameter {\ttfamily help\+Key} has to be the same key as passed to {\ttfamily elektra\+Get\+Opts} as {\ttfamily parent\+Key}, if you called {\ttfamily elektra\+Get\+Opts} directly. If you used {\ttfamily gopts}, you should pass the key {\ttfamily proc\+:/elektra/gopts/help}.

The parameter {\ttfamily usage} is used to replace the default usage line, if it is not {\ttfamily NULL}. The string {\ttfamily prefix} is inserted between the usage line and the options list, if it is not {\ttfamily NULL}.

With {\ttfamily gopts} this could look something like this\+:


\begin{DoxyCode}{0}
\DoxyCodeLine{\textcolor{keywordtype}{int} \mbox{\hyperlink{testio__doc_8c_a3c04138a5bfe5d72780bb7e82a18e627}{main}} (\textcolor{keywordtype}{int} argc, \textcolor{keywordtype}{char} ** argv)}
\DoxyCodeLine{\{}
\DoxyCodeLine{  \textcolor{comment}{// setup omitted for brevity}}
\DoxyCodeLine{  \mbox{\hyperlink{group__kdb_ga28e385fd9cb7ccfe0b2f1ed2f62453a1}{kdbGet}} (\mbox{\hyperlink{namespacekdb}{kdb}}, ks, parentKey);}
\DoxyCodeLine{}
\DoxyCodeLine{  \textcolor{keywordflow}{if} (\textcolor{comment}{/* custom condition */})}
\DoxyCodeLine{  \{}
\DoxyCodeLine{    Key * help = \mbox{\hyperlink{group__keyset_gad65d2cdcbb5381194a1688e169af8a83}{ksLookupByName}} (ks, \textcolor{stringliteral}{"{}proc:/elektra/gopts/help"{}}, 0);}
\DoxyCodeLine{    \textcolor{keywordtype}{char} * helpMessage = \mbox{\hyperlink{opts_8c_ac289611a114f2b2a60b740b71313a965}{elektraGetOptsHelpMessage}} (help, \textcolor{stringliteral}{"{}custom usage"{}}, \textcolor{stringliteral}{"{}custom prefix"{}});}
\DoxyCodeLine{    printf (\textcolor{stringliteral}{"{}\%s\(\backslash\)n"{}}, helpMessage);}
\DoxyCodeLine{    \mbox{\hyperlink{internal_8c_a7f572149d2e0bfe18023a6ac969f195c}{elektraFree}} (helpMessage);}
\DoxyCodeLine{  \}}
\DoxyCodeLine{\}}

\end{DoxyCode}
 