Collaboration diagram for Oyjl_args:

Macros
#define	OYJL_QUIET 0x100000
	be silent on error More...

#define	OYJL_SOURCE_CODE_C 0x01
	C programming language source code. More...

#define	OYJL_WITH_OYJL_ARGS_C 0x02
	Include oyjl_args.c . Skip libOyjlCore code. More...

#define	OYJL_NO_DEFAULT_OPTIONS 0x04
	omit automatic options generation for –help, –X export or –verbose More...

#define	OYJL_SUGGEST_VARIABLE_NAMES 0x08
	automatic suggestion of variable names for missing oyjlOption_s::o and oyjlOption_s::option members More...

#define	OYJL_WITH_OYJL_ARGS_BASE_API 0x10
	Restrict to oyjl_args_base.h API's. More...

#define	OYJL_COMPLETION_BASH 0x100
	bash completion source code More...

#define	OYJL_OPTION_FLAG_EDITABLE 0x001
	The oyjlOption_s choices are merely a hint. Let users fill other strings too: "prog --opt=arg\|...". More...

#define	OYJL_OPTION_FLAG_ACCEPT_NO_ARG 0x002
	Accept as well no arg: "prog --opt[=arg]". More...

#define	OYJL_OPTION_FLAG_NO_DASH 0x004
	No double dash '–' acceptance; single dash can be omitted by not specifying oyjlOption_s::o : "prog opt". More...

#define	OYJL_OPTION_FLAG_REPETITION 0x008
	Accept more than one occurence: "prog --opt=arg ...". More...

#define	OYJL_OPTION_FLAG_MAINTENANCE 0x100
	Maintenance option; can be invisible. More...

#define	OYJL_OPTION_FLAG_IMMEDIATE 0x200
	Apply instantly in UI; opposite to OYJL_GROUP_FLAG_EXPLICITE. More...

#define	OYJL_GROUP_FLAG_SUBCOMMAND 0x080
	This oyjlOptionGroup_s flag requires one single mandatory option with oyjlOPTIONTYPE_NONE. More...

#define	OYJL_GROUP_FLAG_EXPLICITE 0x100
	Apply explicitely in UI. More...

#define	OYJL_GROUP_FLAG_GENERAL_OPTS 0x200
	Hint for MAN page section. More...

Typedefs
typedef enum oyjlOPTIONTYPE_e	oyjlOPTIONTYPE_e
	Type of option. More...

typedef enum oyjlVARIABLETYPE_e	oyjlVARIABLE_e
	Types for oyjlVariable_u. More...

typedef struct oyjlOptionChoice_s	oyjlOptionChoice_s
	Choice item. More...

typedef union oyjlVariable_u	oyjlVariable_u
	abstract value More...

typedef union oyjlOption_u	oyjlOption_u
	abstract option More...

typedef struct oyjlOptionGroup_s	oyjlOptionGroup_s
	Info to compile a Syntax line and check missing arguments. More...

typedef struct oyjlUiHeaderSection_s	oyjlUiHeaderSection_s
	Header section. More...

typedef struct oyjlUi_s	oyjlUi_s
	Info for graphic UI's containing options, additional info sections and other bells and whistles. More...

Enumerations
enum	oyjlOBJECT_e { , oyjlOBJECT_OPTION = 1769433455, oyjlOBJECT_OPTION_GROUP = 1735879023, oyjlOBJECT_OPTIONS = 1937205615, oyjlOBJECT_UI_HEADER_SECTION = 1936222575, oyjlOBJECT_UI = 1769302383, oyjlOBJECT_TR = 1920231791, oyjlOBJECT_JSON = 1397385583 }
	Types of known objects. More...

enum	oyjlARGS_EXPORT_e { , oyjlARGS_EXPORT_HELP, oyjlARGS_EXPORT_JSON, oyjlARGS_EXPORT_MAN, oyjlARGS_EXPORT_MARKDOWN, oyjlARGS_EXPORT_EXPORT }

enum	oyjlARGS_EXPORT_e { , oyjlARGS_EXPORT_HELP, oyjlARGS_EXPORT_JSON, oyjlARGS_EXPORT_MAN, oyjlARGS_EXPORT_MARKDOWN, oyjlARGS_EXPORT_EXPORT }
	export type More...

enum	oyjlOPTIONTYPE_e { , oyjlOPTIONTYPE_CHOICE, oyjlOPTIONTYPE_FUNCTION, oyjlOPTIONTYPE_DOUBLE, oyjlOPTIONTYPE_NONE }
	Type of option. More...

enum	oyjlVARIABLETYPE_e { , oyjlNONE, oyjlSTRING, oyjlDOUBLE, oyjlINT }
	Types for oyjlVariable_u. More...

enum	oyjlOPTIONSTATE_e { , oyjlOPTION_NONE, oyjlOPTION_USER_CHANGED, oyjlOPTION_MISSING_VALUE, oyjlOPTION_UNEXPECTED_VALUE, oyjlOPTION_NOT_SUPPORTED, oyjlOPTION_DOUBLE_OCCURENCE, oyjlOPTIONS_MISSING, oyjlOPTION_NO_GROUP_FOUND, oyjlOPTION_SUBCOMMAND, oyjlOPTION_NOT_ALLOWED_AS_SUBCOMMAND }
	option state More...

enum	{ oyjlUI_STATE_NONE, oyjlUI_STATE_HELP, oyjlUI_STATE_VERBOSE = 2, oyjlUI_STATE_EXPORT = 4, oyjlUI_STATE_OPTION = 24, oyjlUI_STATE_NO_CHECKS = 0x1000, oyjlUI_STATE_NO_RELEASE = 0x2000 }

Functions
oyjl_val	oyjlOptionStringToJson (const char *opts)
	Convert separated string to result JSON. More...

void	oyjlUiJsonSetDefaults (oyjl_val root, oyjl_val defaults)
	Change Defaults. More...

int	oyjlArgsRender (int argc, const char *argv, const char json, const char commands, const char output, int debug, oyjlUi_s ui, int(callback)(int argc, const char **argv))
	Load renderer for graphical rendering options. More...

oyjl_val	oyjlUi_s::oyjlUiJsonSetOption (oyjl_val root, oyjl_val results, const char key, const char value, int current_group_id, int flags OYJL_UNUSED)
	Set interactive option and format cli args (libOyjlExtra) More...

char *	oyjlUi_s::oyjlUiExportToCode (oyjl_val root, int flags)
	Return a source code from a parsed source tree (libOyjlExtra) More...

void	oyjlOptionChoice_s::oyjlOptionChoice_Release (oyjlOptionChoice_s **choices)
	Release dynamic structure. More...

int	oyjlOptionChoice_s::oyjlOptionChoice_Count (oyjlOptionChoice_s *list)
	Return number of array elements. More...

int	oyjlOptions_s::oyjlOptions_Count (oyjlOptions_s *opts)
	Return number of "oiwi" array elements. More...

int	oyjlOptions_s::oyjlOptions_CountGroups (oyjlOptions_s *opts)
	Return number of "oiwi" groups elements. More...

oyjlOption_s *	oyjlOptions_s::oyjlOptions_GetOption (oyjlOptions_s opts, const char ol)
	Obtain the specified option from one letter member::o. More...

oyjlOption_s *	oyjlOptions_s::oyjlOptions_GetOptionL (oyjlOptions_s opts, const char ostring, int flags)
	Obtain the specified option from option string. More...

oyjlOPTIONSTATE_e	oyjlOptions_s::oyjlOptions_Parse (oyjlOptions_s *opts)
	Parse the options into a private data structure. More...

oyjlOPTIONSTATE_e	oyjlOptions_s::oyjlOptions_GetResult (oyjlOptions_s opts, const char opt, const char *result_string, double result_dbl, int *result_int)
	Obtain the parsed result. More...

char **	oyjlOptions_s::oyjlOptions_ResultsToList (oyjlOptions_s opts, const char oc, int *count)
	Convert the parsed content to a text list. More...

char *	oyjlOptions_s::oyjlOptions_ResultsToText (oyjlOptions_s *opts)
	Convert the parsed content to simple text. More...

char *	oyjlOption_s::oyjlOption_PropertiesGetValue (oyjlOption_s o, const char key)
	access the oyjlOption_s::properties by key More...

oyjlOptions_s *	oyjlOptions_s::oyjlOptions_New (int argc, const char **argv)
	Allocate a new options structure. More...

oyjlUi_s *	oyjlUi_s::oyjlUi_New (int argc, const char **argv)
	Allocate a new ui structure. More...

oyjlUi_s *	oyjlUi_s::oyjlUi_Copy (oyjlUi_s *src)
	Copy structure. More...

oyjlUi_s *	oyjlUi_s::oyjlUi_FromOptions (const char nick, const char name, const char description, const char logo, oyjlUiHeaderSection_s info, oyjlOptions_s opts, int *status)
	Create a new UI structure from options. More...

oyjlUi_s *	oyjlUi_s::oyjlUi_Create (int argc, const char *argv, const char nick, const char name, const char description, const char logo, oyjlUiHeaderSection_s info, oyjlOption_s options, oyjlOptionGroup_s groups, int *status)
	Create a new UI structure. More...

void	oyjlUi_s::oyjlUi_ReleaseArgs (oyjlUi_s **ui OYJL_UNUSED)
	Release "oiui". More...

int	oyjlUiHeaderSection_s::oyjlUiHeaderSection_Count (oyjlUiHeaderSection_s *sections)
	Return the number of sections of type "oihs". More...

oyjlUiHeaderSection_s *	oyjlUiHeaderSection_s::oyjlUiHeaderSection_Append (oyjlUiHeaderSection_s sections, const char nick, const char label, const char name, const char *description)
	Add new header section at end. More...

oyjlUiHeaderSection_s *	oyjlUi_s::oyjlUi_GetHeaderSection (oyjlUi_s ui, const char nick)
	Return the section which was specified by its nick name. More...

char *	oyjlUi_s::oyjlUi_ToMan (oyjlUi_s *ui, int flags OYJL_UNUSED)
	Return a MAN page from options. More...

char *	oyjlOptions_s::oyjlOptions_PrintHelp (oyjlOptions_s opts, oyjlUi_s ui, int verbose, FILE *out_file, const char motto_format,...)
	Print help text to stderr. More...

char *	oyjlUi_s::oyjlUi_ToMarkdown (oyjlUi_s *ui, int flags)
	Return markdown formated text from options. More...

Detailed Description

Macro Definition Documentation

◆ OYJL_COMPLETION_BASH

#define OYJL_COMPLETION_BASH 0x100

bash completion source code

◆ OYJL_GROUP_FLAG_EXPLICITE

#define OYJL_GROUP_FLAG_EXPLICITE 0x100

Apply explicitely in UI.

For per option exception see OYJL_OPTION_FLAG_IMMEDIATE . The flag is intended for e.g. costly processing.

◆ OYJL_GROUP_FLAG_GENERAL_OPTS

#define OYJL_GROUP_FLAG_GENERAL_OPTS 0x200

Hint for MAN page section.

Recommend to set a special section name "GENERAL OPTIONS". Usualy it follows the "OPTIONS" section.

◆ OYJL_GROUP_FLAG_SUBCOMMAND

#define OYJL_GROUP_FLAG_SUBCOMMAND 0x080

This oyjlOptionGroup_s flag requires one single mandatory option with oyjlOPTIONTYPE_NONE.

For a related flag see OYJL_OPTION_FLAG_NO_DASH

◆ OYJL_NO_DEFAULT_OPTIONS

#define OYJL_NO_DEFAULT_OPTIONS 0x04

omit automatic options generation for –help, –X export or –verbose

◆ OYJL_OPTION_FLAG_ACCEPT_NO_ARG

#define OYJL_OPTION_FLAG_ACCEPT_NO_ARG 0x002

Accept as well no arg: "prog --opt[=arg]".

◆ OYJL_OPTION_FLAG_EDITABLE

#define OYJL_OPTION_FLAG_EDITABLE 0x001

The oyjlOption_s choices are merely a hint. Let users fill other strings too: "prog --opt=arg|...".

◆ OYJL_OPTION_FLAG_IMMEDIATE

#define OYJL_OPTION_FLAG_IMMEDIATE 0x200

Apply instantly in UI; opposite to OYJL_GROUP_FLAG_EXPLICITE.

◆ OYJL_OPTION_FLAG_MAINTENANCE

#define OYJL_OPTION_FLAG_MAINTENANCE 0x100

Maintenance option; can be invisible.

◆ OYJL_OPTION_FLAG_NO_DASH

#define OYJL_OPTION_FLAG_NO_DASH 0x004

No double dash '–' acceptance; single dash can be omitted by not specifying oyjlOption_s::o : "prog opt".

◆ OYJL_OPTION_FLAG_REPETITION

#define OYJL_OPTION_FLAG_REPETITION 0x008

Accept more than one occurence: "prog --opt=arg ...".

◆ OYJL_QUIET

#define OYJL_QUIET 0x100000

be silent on error

◆ OYJL_SOURCE_CODE_C

#define OYJL_SOURCE_CODE_C 0x01

C programming language source code.

Referenced by oyjlUi_s::oyjlUiExportToCode().

◆ OYJL_SUGGEST_VARIABLE_NAMES

#define OYJL_SUGGEST_VARIABLE_NAMES 0x08

automatic suggestion of variable names for missing oyjlOption_s::o and oyjlOption_s::option members

◆ OYJL_WITH_OYJL_ARGS_BASE_API

#define OYJL_WITH_OYJL_ARGS_BASE_API 0x10

Restrict to oyjl_args_base.h API's.

◆ OYJL_WITH_OYJL_ARGS_C

#define OYJL_WITH_OYJL_ARGS_C 0x02

Include oyjl_args.c . Skip libOyjlCore code.

Typedef Documentation

◆ oyjlOption_u

typedef union oyjlOption_u oyjlOption_u

abstract option

The type is declared inside the oyjlOPTIONTYPE_e enum range.

◆ oyjlOptionChoice_s

typedef struct oyjlOptionChoice_s oyjlOptionChoice_s

Choice item.

◆ oyjlOptionGroup_s

typedef struct oyjlOptionGroup_s oyjlOptionGroup_s

Info to compile a Syntax line and check missing arguments.

Options listed in mandatory, optional and detail are comma(,) separated.

◆ oyjlOPTIONTYPE_e

typedef enum oyjlOPTIONTYPE_e oyjlOPTIONTYPE_e

Type of option.

◆ oyjlUi_s

typedef struct oyjlUi_s oyjlUi_s

Info for graphic UI's containing options, additional info sections and other bells and whistles.

◆ oyjlUiHeaderSection_s

typedef struct oyjlUiHeaderSection_s oyjlUiHeaderSection_s

Header section.

◆ oyjlVARIABLE_e

typedef enum oyjlVARIABLETYPE_e oyjlVARIABLE_e

Types for oyjlVariable_u.

type of result

◆ oyjlVariable_u

typedef union oyjlVariable_u oyjlVariable_u

abstract value

The type is declared inside the oyjlVARIABLE_e enum range.

Enumeration Type Documentation

◆ anonymous enum

anonymous enum

Enumerator
oyjlUI_STATE_NONE	nothing to report
oyjlUI_STATE_HELP	–help printed
oyjlUI_STATE_VERBOSE	–verbose option detected
oyjlUI_STATE_EXPORT	–export=XXX or other stuff printed
oyjlUI_STATE_OPTION	bit shift for detected error from option parser
oyjlUI_STATE_NO_CHECKS	skip any checks
oyjlUI_STATE_NO_RELEASE	skip any data release, e.g. for –help + freeing oyjlUi_s

◆ oyjlARGS_EXPORT_e [1/2]

enum oyjlARGS_EXPORT_e

export type

Enumerator
oyjlARGS_EXPORT_HELP	help text for command line
oyjlARGS_EXPORT_JSON	rendering data in JSON format
oyjlARGS_EXPORT_MAN	Unix Man page.
oyjlARGS_EXPORT_MARKDOWN	Markdown for conversion into HTML.
oyjlARGS_EXPORT_EXPORT	object data in JSON format

◆ oyjlARGS_EXPORT_e [2/2]

enum oyjlARGS_EXPORT_e

Enumerator
oyjlARGS_EXPORT_HELP	help text for command line
oyjlARGS_EXPORT_JSON	rendering data in JSON format
oyjlARGS_EXPORT_MAN	Unix Man page.
oyjlARGS_EXPORT_MARKDOWN	Markdown for conversion into HTML.
oyjlARGS_EXPORT_EXPORT	object data in JSON format

◆ oyjlOBJECT_e

enum oyjlOBJECT_e

Types of known objects.

Enumerator
oyjlOBJECT_OPTION	oyjlOption_s
oyjlOBJECT_OPTION_GROUP	oyjlOptionGroup_s
oyjlOBJECT_OPTIONS	oyjlOptions_s
oyjlOBJECT_UI_HEADER_SECTION	oyjlUiHeaderSection_s
oyjlOBJECT_UI	oyjlUi_s
oyjlOBJECT_TR	oyjlTranslation_s
oyjlOBJECT_JSON	oyjlNodes_s

◆ oyjlOPTIONSTATE_e

enum oyjlOPTIONSTATE_e

option state

Enumerator
oyjlOPTION_NONE	untouched
oyjlOPTION_USER_CHANGED	passed in by user
oyjlOPTION_MISSING_VALUE	user error
oyjlOPTION_UNEXPECTED_VALUE	user error
oyjlOPTION_NOT_SUPPORTED	user error
oyjlOPTION_DOUBLE_OCCURENCE	user error; except '@' is specified
oyjlOPTIONS_MISSING	user error; except '#' is specified
oyjlOPTION_NO_GROUP_FOUND	user error
oyjlOPTION_SUBCOMMAND	category
oyjlOPTION_NOT_ALLOWED_AS_SUBCOMMAND	user error

◆ oyjlOPTIONTYPE_e

enum oyjlOPTIONTYPE_e

Type of option.

Enumerator
oyjlOPTIONTYPE_CHOICE	list of choices
oyjlOPTIONTYPE_FUNCTION	computed list of choices
oyjlOPTIONTYPE_DOUBLE	IEEE floating point number with double precission
oyjlOPTIONTYPE_NONE	no value possible - the option is a flag like -v/–verbose

◆ oyjlVARIABLETYPE_e

enum oyjlVARIABLETYPE_e

Types for oyjlVariable_u.

Enumerator
oyjlNONE	no variable given, will be asked later with oyjlOptions_GetResult()
oyjlSTRING	pointer to a array of char
oyjlDOUBLE	IEEE floating point number with double precission
oyjlINT	integer number declared as int

Function Documentation

◆ oyjlArgsRender()

int oyjlArgsRender	(	int	argc,
		const char **	argv,
		const char *	json,
		const char *	commands,
		const char *	output,
		int	debug,
		oyjlUi_s *	ui,
		int()(int argc, const char *argv)	callback
	)

Load renderer for graphical rendering options.

link with libOyjlArgsWeb and use microhttps WWW renderer as library
link with libOyjlArgsQml and use Qt's QML to render in a GUI

See also: oyjlUi_ToJson()

The function version in libOyjlCore dynamicaly dlopen() s libOyjlArgsQml. The function version in liboyjl-core-static needs as well liboyjl-args-qml-static to work. You should check wich library is linked and possibly guard the according code in case no QML library is available:

#if !defined(NO_OYJL_ARGS_RENDER)
if(render && ui)
  // code with oyjlArgsRender() goes here
#endif

Parameters

[in]	argc	number of arguments from main()
[in]	argv	arguments from main()
[in]	json	JSON UI text; optional, can be generated from ui
[in]	commands	JSON commands/config text; optional, can be generated from ui or passed in as –render="XXX" option
[in]	output	write ui interaction results; optional
[in]	debug	set debug level
[in]	ui	user interface structure
[in,out]	callback	the function resembling main() to call into; It will be used to parse args, show help texts, all options handling and data processing

Returns: return value for main()

Version: Oyjl: 1.0.0

Date: 2020/03/05

Since: 2019/12/14 (Oyjl: 1.0.0)

◆ oyjlOption_PropertiesGetValue()

char * oyjlOption_PropertiesGetValue	(	oyjlOption_s *	o,
		const char *	key
	)

access the oyjlOption_s::properties by key

Version: Oyjl: 1.0.0

Date: 2022/06/23

Since: 2022/06/23 (Oyjl: 1.0.0)

References oyjlStringCopy(), oyjlStringListRelease(), and oyjlStringSplit2().

◆ oyjlOptionChoice_Count()

int oyjlOptionChoice_Count ( oyjlOptionChoice_s * list )

Return number of array elements.

Version: Oyjl: 1.0.0

Date: 2019/06/17

Since: 2019/06/17 (Oyjl: 1.0.0)

◆ oyjlOptionChoice_Release()

void oyjlOptionChoice_Release ( oyjlOptionChoice_s ** choices )

Release dynamic structure.

Version: Oyjl: 1.0.0

Date: 2018/08/14

Since: 2018/08/14 (OpenICC: 0.1.1)

◆ oyjlOptions_Count()

int oyjlOptions_Count ( oyjlOptions_s * opts )

Return number of "oiwi" array elements.

Version: Oyjl: 1.0.0

Date: 2018/08/14

Since: 2018/08/14 (OpenICC: 0.1.1)

References oyjlOBJECT_OPTION.

◆ oyjlOptions_CountGroups()

int oyjlOptions_CountGroups ( oyjlOptions_s * opts )

Return number of "oiwi" groups elements.

Version: Oyjl: 1.0.0

Date: 2018/08/14

Since: 2018/08/14 (OpenICC: 0.1.1)

References oyjlOBJECT_OPTION_GROUP.

◆ oyjlOptions_GetOption()

oyjlOption_s * oyjlOptions_GetOption	(	oyjlOptions_s *	opts,
		const char *	ol
	)

Obtain the specified option from one letter member::o.

Version: Oyjl: 1.0.0

Date: 2019/07/29

Since: 2018/08/14 (OpenICC: 0.1.1)

◆ oyjlOptions_GetOptionL()

oyjlOption_s * oyjlOptions_GetOptionL	(	oyjlOptions_s *	opts,
		const char *	ostring,
		int	flags
	)

Obtain the specified option from option string.

Version: Oyjl: 1.0.0

Date: 2021/03/04

Since: 2018/08/14 (OpenICC: 0.1.1)

Interprete "-o".

Interprete "--option"

Interprete "--option=arg" with arg

Interprete "--option.attr" with attribute

◆ oyjlOptions_GetResult()

oyjlOPTIONSTATE_e oyjlOptions_GetResult	(	oyjlOptions_s *	opts,
		const char *	opt,
		const char **	result_string,
		double *	result_dbl,
		int *	result_int
	)

Obtain the parsed result.

This function is only useful, if the results shall be obtained independently from oyjlOption_s::variable after oyjlOptions_Parse().

If the option was not specified the state oyjlOPTION_NONE will be returned and otherwise oyjlOPTION_USER_CHANGED. With result_int and a option type of oyjlOPTIONTYPE_NONE, the number of occurences is obtained, e.g. -vvv will give result_int = 3. A option type oyjlOPTIONTYPE_DOUBLE can ask for the floating point result with a result_dbl argument.

Version: Oyjl: 1.0.0

Date: 2019/08/04

Since: 2018/08/14 (OpenICC: 0.1.1)

References oyjlOPTION_NONE.

◆ oyjlOptions_New()

oyjlOptions_s * oyjlOptions_New	(	int	argc,
		const char **	argv
	)

Allocate a new options structure.

Version: Oyjl: 1.0.0

Date: 2019/03/24

Since: 2018/08/14 (OpenICC: 0.1.1)

◆ oyjlOptions_Parse()

oyjlOPTIONSTATE_e oyjlOptions_Parse ( oyjlOptions_s * opts )

Parse the options into a private data structure.

The returned status can be used to detect usage errors and hint them on the command line. In the usual case where the variable fields are set, the results will be set too.

Version: Oyjl: 1.0.0

Date: 2020/10/14

Since: 2018/08/14 (OpenICC: 0.1.1)

Put the count of found anonymous arguments into '@' options variable.i of variable_type oyjlINT.

References oyjlOPTION_NONE.

◆ oyjlOptions_PrintHelp()

char * oyjlOptions_PrintHelp	(	oyjlOptions_s *	opts,
		oyjlUi_s *	ui,
		int	verbose,
		FILE **	out_file,
		const char *	motto_format,
			...
	)

Print help text to stderr.

Parameters

opts	options to print
ui	more info for e.g. from the documentation section for the description block; optional
verbose	gives debug output -1 : print help only for detected group -2 : print only Synopsis -3 : print help only for detected group to stderr
out_file	recommended output file
motto_format	prints a customised intoduction line

Returns: help string for display on command line

Version: Oyjl: 1.0.0

Date: 2022/07/02

Since: 2018/08/14 (OpenICC: 0.1.1)

◆ oyjlOptions_ResultsToList()

char ** oyjlOptions_ResultsToList	(	oyjlOptions_s *	opts,
		const char *	oc,
		int *	count
	)

Convert the parsed content to a text list.

This function is part of libOyjlArgsBase.

Parameters

[in]	opts	the argument object
[in]	oc	a filter; use NULL to get all results; e.g. use "@" for all anonymous results
[out]	count	the number of matched results

Returns: a possibly filterd string list of results; Without a filter it contains the dash(es), the argument Id possibly followed by equal sign '=' and the result following. Building a command line call is easy. With oc filter it contains only results if apply and without Id. The memory is owned by caller.

Version: Oyjl: 1.0.0

Date: 2021/05/28

Since: 2019/03/25 (Oyjl: 1.0.0)

Keep the -@=XXX unbound option around in order to simplify interpreting the options. Thus sub commands like "prog opt" can be easily separated from "prog unbound.txt" . For a correct command line the "-@=" must be omitted.

◆ oyjlOptions_ResultsToText()

char * oyjlOptions_ResultsToText ( oyjlOptions_s * opts )

Convert the parsed content to simple text.

Version: Oyjl: 1.0.0

Date: 2021/05/29

Since: 2018/08/14 (OpenICC: 0.1.1)

◆ oyjlOptionStringToJson()

oyjl_val oyjlOptionStringToJson ( const char * opts )

Convert separated string to result JSON.

Parameters

opts	separate by colon ':' and omit leading dash '-' or '–'

Returns: result JSON

See also: oyjlOptions_ResultsToJson()

Version: Oyjl: 1.0.0

Date: 2023/05/22

Since: 2023/05/21 (Oyjl: 1.0.0)

References OYJL_CREATE_NEW, oyjlStringCopy(), oyjlStringListRelease(), oyjlStringSplit(), oyjlTreeGetValueF(), oyjlTreeNew(), oyjlValueCount(), and oyjlValueSetString().

◆ oyjlUi_Copy()

oyjlUi_s * oyjlUi_Copy ( oyjlUi_s * src )

Copy structure.

The oyjlUi_s string members are mostly references.

Version: Oyjl: 1.0.0

Date: 2020/07/31

Since: 2020/07/31 (Oyjl: 1.0.0)

References oyjlOBJECT_UI, and oyjlStringAppendN().

◆ oyjlUi_Create()

oyjlUi_s * oyjlUi_Create	(	int	argc,
		const char **	argv,
		const char *	nick,
		const char *	name,
		const char *	description,
		const char *	logo,
		oyjlUiHeaderSection_s *	info,
		oyjlOption_s *	options,
		oyjlOptionGroup_s *	groups,
		int *	status
	)

Create a new UI structure.

This is a high level convinience function. The returned oyjlUi_s is a comlete description of the UI and can be used instantly. The options are parsed, errors are printed, help text is printed for the boolean -h/–help option. Boolean -v/–verbose is handled too. The results are set to the declared variables. The app_type defaults to "tool", but it can be replaced if needed.

oyjlUi_s * ui = oyjlUi_Create( argc, argv,
                                     "myCl",
                                     _("My Command"),
                                     _("My Command line tool from Me"),
                                     "my_logo",
                                     info, options, groups, NULL )

Parameters

[in]	argc	number of command line arguments
[in]	argv	command line args from C/C++ main()
[in]	nick	four byte string; e.g. "myCl"
[in]	name	short name of the tool; i18n; e.g. _("My Command")
[in]	description	compact sentence starting with full name; i18n; e.g. _("My Command line tool from Me")
[in]	logo	icon name; This variable must contain the file name only, without ending. The icon needs to be installed in typical icon search path and will be detected there. e.g. "my_logo" points to "my_logo.{png\|svg}"
[in]	info	general information for rich UI's and for help text
[in,out]	options	the main option declaration, with syntax declaration and variable passing for setting results
[in]	groups	the option grouping declares dependencies of options and provides a UI layout
[in,out]	status	inform about processing oyjlUI_STATE_HELP : help was detected, printed and oyjlUi_s was released oyjlUI_STATE_EXPORT : export of json, man or markdown was detected, printed and oyjlUi_s was released oyjlUI_STATE_VERBOSE : verbose was detected oyjlUI_STATE_OPTION+ : error occured in option parser, message printed, oyjlOPTIONSTATE_e is placed in >> oyjlUI_STATE_OPTION and oyjlUi_s was released oyjlUI_STATE_NO_CHECKS : skip any checks during creation; Only useful if part of the passed in data is omitted or needs to be passed through.

Returns: UI object for later use

Version: Oyjl: 1.0.0

Date: 2020/04/05

Since: 2018/08/20 (OpenICC: 0.1.1)

◆ oyjlUi_FromOptions()

oyjlUi_s * oyjlUi_FromOptions	(	const char *	nick,
		const char *	name,
		const char *	description,
		const char *	logo,
		oyjlUiHeaderSection_s *	info,
		oyjlOptions_s *	opts,
		int *	status
	)

Create a new UI structure from options.

This function is part of libOyjlArgsBase.

This is a high level convinience function. The returned oyjlUi_s is a comlete description of the UI and can be used instantly. The options are parsed, errors are printed, help text is printed for the boolean -h/–help option. Boolean -v/–verbose is handled too. The results are set to the declared variables. The app_type defaults to "tool", but it can be replaced if needed.

oyjlUi_s * ui = oyjlUi_FromOptions ( "myCl",
                                     _("My Command"),
                                     _("My Command line tool from Me"),
                                     "my_logo",
                                     info, opts, NULL )

Parameters

[in]	nick	four byte string; e.g. "myCl"
[in]	name	short name of the tool; i18n; e.g. _("My Command")
[in]	description	compact sentence starting with full name; i18n; e.g. _("My Command line tool from Me")
[in]	logo	icon name; This variable must contain the file name only, without ending. The icon needs to be installed in typical icon search path and will be detected there. e.g. "my_logo" points to "my_logo.{png\|svg}"
[in]	info	general information for rich UI's and for help text
[in,out]	opts	The main option declaration, with syntax declaration and variable passing for setting results. The option grouping declares dependencies of options and provides a UI layout.
[in,out]	status	inform about processing oyjlUI_STATE_HELP : help was detected, printed and oyjlUi_s was released oyjlUI_STATE_EXPORT : export of json, man or markdown was detected, printed and oyjlUi_s was released oyjlUI_STATE_VERBOSE : verbose was detected oyjlUI_STATE_OPTION+ : error occured in option parser, message printed, oyjlOPTIONSTATE_e is placed in >> oyjlUI_STATE_OPTION and oyjlUi_s was released oyjlUI_STATE_NO_CHECKS : skip any checks during creation; Only useful if part of the passed in data is omitted or needs to be passed through.

Returns: UI object for later use

Version: Oyjl: 1.0.0

Date: 2020/10/13

Since: 2020/10/13 (Oyjl: 1.0.0)

◆ oyjlUi_GetHeaderSection()

oyjlUiHeaderSection_s * oyjlUi_GetHeaderSection	(	oyjlUi_s *	ui,
		const char *	nick
	)

Return the section which was specified by its nick name.

Version: Oyjl: 1.0.0

Date: 2018/08/14

Since: 2018/08/14 (OpenICC: 0.1.1)

◆ oyjlUi_New()

oyjlUi_s * oyjlUi_New	(	int	argc,
		const char **	argv
	)

Allocate a new ui structure.

The oyjlUi_s contains already options in the opts member.

Version: Oyjl: 1.0.0

Date: 2019/03/24

Since: 2018/08/14 (OpenICC: 0.1.1)

◆ oyjlUi_ReleaseArgs()

void oyjlUi_ReleaseArgs ( oyjlUi_s **ui OYJL_UNUSED )

Release "oiui".

Release oyjlUi_s::opts, oyjlUi_s::private_data and oyjlUi_s.

Version: Oyjl: 1.0.0

Date: 2018/08/14

Since: 2018/08/14 (OpenICC: 0.1.1)

References oyjlOBJECT_UI.

◆ oyjlUi_ToMan()

char * oyjlUi_ToMan	(	oyjlUi_s *	ui,
		int flags	OYJL_UNUSED
	)

Return a MAN page from options.

Some manual pages (MAN pages) might contain some additional sections. They are supported as options. To generate a custom MAN page section, add a blind option to your options list and set the oyjlOption_s::o char to something non interupting like, dot '.' or similar. The oyjlOption_s::option string contains "man-section_head", with "section_head" being adapted to your needs. The "man-" identifier part will be cut off and "section_head" will become uppercase and underline '_' become empty space, e.g.: "SECTION HEAD". Use oyjlOption_s::value_type=oyjlOPTIONTYPE_CHOICE and place your string list into oyjlOptionChoice_s by filling it's members. Each choice is shown as own subsection. oyjlOptionChoice_s::nick is handled as a subsection headline and oyjlOptionChoice_s::name is shown as link or normal text. A "man-see_also" section oyjlOptionChoice_s::nick is scanned for MAN page cross references, e.g: "oyjl(1) oyjl(args(1)" and links are created appropriately. Translated section heads are "EXAMPLES, "SEE AS WELL", "HISTORY", "ENVIRONMENT VARIABLES", "EXIT-STATE" and "FILES".

Version: Oyjl: 1.0.0

Date: 2020/04/15

Since: 2018/10/10 (OpenICC: 0.1.1)

◆ oyjlUi_ToMarkdown()

char * oyjlUi_ToMarkdown	(	oyjlUi_s *	ui,
		int	flags
	)

Return markdown formated text from options.

This function supports extra sections in MAN page style.

See also: oyjlUi_ToMan()

Version: Oyjl: 1.0.0

Date: 2019/08/02

Since: 2018/11/07 (OpenICC: 0.1.1)

◆ oyjlUiExportToCode()

char * oyjlUiExportToCode	(	oyjl_val	root,
		int	flags
	)

Return a source code from a parsed source tree (libOyjlExtra)

The input format is the JSON data from oyjlUi_ExportToJson().

Parameters

[in]	root	the parsed JSON tree to convert
[in]	flags	support; OYJL_SOURCE_CODE_C OYJL_WITH_OYJL_ARGS_C OYJL_WITH_OYJL_ARGS_BASE_API OYJL_SUGGEST_VARIABLE_NAMES OYJL_NO_DEFAULT_OPTIONS OYJL_COMPLETION_BASH

Version: Oyjl: 1.0.0

Date: 2023/03/10

Since: 2019/06/24 (Oyjl: 1.0.0)

References OYJL_SOURCE_CODE_C, oyjlStr_New(), and oyjlTreeGetValue().

◆ oyjlUiHeaderSection_Append()

oyjlUiHeaderSection_s * oyjlUiHeaderSection_Append	(	oyjlUiHeaderSection_s *	sections,
		const char *	nick,
		const char *	label,
		const char *	name,
		const char *	description
	)

Add new header section at end.

Version: Oyjl: 1.0.0

Date: 2020/07/16

Since: 2020/06/05 (Oyjl: 1.0.0)

◆ oyjlUiHeaderSection_Count()

int oyjlUiHeaderSection_Count ( oyjlUiHeaderSection_s * sections )

Return the number of sections of type "oihs".

Version: Oyjl: 1.0.0

Date: 2020/06/01

Since: 2018/08/14 (OpenICC: 0.1.1)

References oyjlOBJECT_UI_HEADER_SECTION.

◆ oyjlUiJsonSetDefaults()

void oyjlUiJsonSetDefaults	(	oyjl_val	root,
		oyjl_val	defaults
	)

Change Defaults.

Parameters

root	–export=json output
defaults	parsed oyjlOptionStringToJson() JSON

See also: oyjlOptions_ResultsToJson()

Version: Oyjl: 1.0.0

Date: 2023/05/21

Since: 2023/05/21 (Oyjl: 1.0.0)

References OYJL_KEY, oyjlTreeGetValue(), oyjlTreeToPaths(), and oyjlValueCount().

◆ oyjlUiJsonSetOption()

oyjl_val oyjlUiJsonSetOption	(	oyjl_val	root,
		oyjl_val	results,
		const char *	key,
		const char *	value,
		int	current_group_id,
		int flags	OYJL_UNUSED
	)

Set interactive option and format cli args (libOyjlExtra)

The input format is the JSON data from oyjlUi_ToJson().

Parameters

[in]	root	the parsed JSON tree to convert
[in,out]	results	the changed option and state
[in]	key	the option key to change
[in]	value	the option value to change
[in]	current_group_id	the group which was modified
[in]	flags	nothing

Returns: the list of command line args

Version: Oyjl: 1.0.0

Date: 2023/12/21

Since: 2023/12/21 (Oyjl: 1.0.0)

Macros

Typedefs

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ OYJL_COMPLETION_BASH

◆ OYJL_GROUP_FLAG_EXPLICITE

◆ OYJL_GROUP_FLAG_GENERAL_OPTS

◆ OYJL_GROUP_FLAG_SUBCOMMAND

◆ OYJL_NO_DEFAULT_OPTIONS

◆ OYJL_OPTION_FLAG_ACCEPT_NO_ARG

◆ OYJL_OPTION_FLAG_EDITABLE

◆ OYJL_OPTION_FLAG_IMMEDIATE

◆ OYJL_OPTION_FLAG_MAINTENANCE

◆ OYJL_OPTION_FLAG_NO_DASH

◆ OYJL_OPTION_FLAG_REPETITION

◆ OYJL_QUIET

◆ OYJL_SOURCE_CODE_C

◆ OYJL_SUGGEST_VARIABLE_NAMES

◆ OYJL_WITH_OYJL_ARGS_BASE_API

◆ OYJL_WITH_OYJL_ARGS_C

Typedef Documentation

◆ oyjlOption_u

◆ oyjlOptionChoice_s

◆ oyjlOptionGroup_s

◆ oyjlOPTIONTYPE_e

◆ oyjlUi_s

◆ oyjlUiHeaderSection_s

◆ oyjlVARIABLE_e

◆ oyjlVariable_u

Enumeration Type Documentation

◆ anonymous enum

◆ oyjlARGS_EXPORT_e [1/2]

◆ oyjlARGS_EXPORT_e [2/2]

◆ oyjlOBJECT_e

◆ oyjlOPTIONSTATE_e

◆ oyjlOPTIONTYPE_e

◆ oyjlVARIABLETYPE_e

Function Documentation

◆ oyjlArgsRender()

◆ oyjlOption_PropertiesGetValue()

◆ oyjlOptionChoice_Count()

◆ oyjlOptionChoice_Release()

◆ oyjlOptions_Count()

◆ oyjlOptions_CountGroups()

◆ oyjlOptions_GetOption()

◆ oyjlOptions_GetOptionL()

◆ oyjlOptions_GetResult()

◆ oyjlOptions_New()

◆ oyjlOptions_Parse()

◆ oyjlOptions_PrintHelp()

◆ oyjlOptions_ResultsToList()

◆ oyjlOptions_ResultsToText()

◆ oyjlOptionStringToJson()

◆ oyjlUi_Copy()

◆ oyjlUi_Create()

◆ oyjlUi_FromOptions()

◆ oyjlUi_GetHeaderSection()

◆ oyjlUi_New()

◆ oyjlUi_ReleaseArgs()

◆ oyjlUi_ToMan()

◆ oyjlUi_ToMarkdown()

◆ oyjlUiExportToCode()

◆ oyjlUiHeaderSection_Append()

◆ oyjlUiHeaderSection_Count()

◆ oyjlUiJsonSetDefaults()

◆ oyjlUiJsonSetOption()