GI.GLib.Structs.OptionContext

A GOptionContext struct defines which options are accepted by the commandline option parser. The struct has only private fields and should not be directly accessed.

Exported types

newtype OptionContext

Constructors

OptionContext (ManagedPtr OptionContext)

Instances

WrappedPtr OptionContext

Methods

wrappedPtrCalloc :: IO (Ptr OptionContext)

wrappedPtrCopy :: OptionContext -> IO OptionContext

wrappedPtrFree :: Maybe (FunPtr (Ptr OptionContext -> IO ()))

noOptionContext :: Maybe OptionContext

Methods

addGroup

optionContextAddGroup

Arguments

:: (HasCallStack, MonadIO m)

=> OptionContext

context: a OptionContext

-> OptionGroup

group: the group to add

-> m ()

Adds a OptionGroup to the context, so that parsing with context will recognize the options in the group. Note that this will take ownership of the group and thus the group should not be freed.

Since: 2.6

addMainEntries

optionContextAddMainEntries

Arguments

:: (HasCallStack, MonadIO m)

=> OptionContext

context: a OptionContext

-> OptionEntry

entries: a Nothing-terminated array of GOptionEntrys

-> Maybe Text

translationDomain: a translation domain to use for translating the --help output for the options in entries with gettext(), or Nothing

-> m ()

A convenience function which creates a main group if it doesn't exist, adds the entries to it and sets the translation domain.

Since: 2.6

free

optionContextFree

Arguments

:: (HasCallStack, MonadIO m)

=> OptionContext

context: a OptionContext

-> m ()

Frees context and all the groups which have been added to it.

Please note that parsed arguments need to be freed separately (see OptionEntry).

Since: 2.6

getDescription

optionContextGetDescription

Arguments

:: (HasCallStack, MonadIO m)

=> OptionContext

context: a OptionContext

-> m Text

Returns: the description

Returns the description. See optionContextSetDescription.

Since: 2.12

getHelp

optionContextGetHelp

Arguments

:: (HasCallStack, MonadIO m)

=> OptionContext

context: a OptionContext

-> Bool

mainHelp: if True, only include the main group

-> Maybe OptionGroup

group: the OptionGroup to create help for, or Nothing

-> m Text

Returns: A newly allocated string containing the help text

Returns a formatted, translated help text for the given context. To obtain the text produced by --help, call g_option_context_get_help (context, TRUE, NULL). To obtain the text produced by --help-all, call g_option_context_get_help (context, FALSE, NULL). To obtain the help text for an option group, call g_option_context_get_help (context, FALSE, group).

Since: 2.14

getHelpEnabled

optionContextGetHelpEnabled

Arguments

:: (HasCallStack, MonadIO m)

=> OptionContext

context: a OptionContext

-> m Bool

Returns: True if automatic help generation is turned on.

Returns whether automatic --help generation is turned on for context. See optionContextSetHelpEnabled.

Since: 2.6

getIgnoreUnknownOptions

optionContextGetIgnoreUnknownOptions

Arguments

:: (HasCallStack, MonadIO m)

=> OptionContext

context: a OptionContext

-> m Bool

Returns: True if unknown options are ignored.

Returns whether unknown options are ignored or not. See optionContextSetIgnoreUnknownOptions.

Since: 2.6

getMainGroup

optionContextGetMainGroup

Arguments

:: (HasCallStack, MonadIO m)

=> OptionContext

context: a OptionContext

-> m OptionGroup

Returns: the main group of context, or Nothing if context doesn't have a main group. Note that group belongs to context and should not be modified or freed.

Returns a pointer to the main group of context.

Since: 2.6

getStrictPosix

optionContextGetStrictPosix

Arguments

:: (HasCallStack, MonadIO m)

=> OptionContext

context: a GoptionContext

-> m Bool

Returns: True if strict POSIX is enabled, False otherwise.

Returns whether strict POSIX code is enabled.

See optionContextSetStrictPosix for more information.

Since: 2.44

getSummary

optionContextGetSummary

Arguments

:: (HasCallStack, MonadIO m)

=> OptionContext

context: a OptionContext

-> m Text

Returns: the summary

Returns the summary. See optionContextSetSummary.

Since: 2.12

parse

optionContextParse

Arguments

:: (HasCallStack, MonadIO m)

=> OptionContext

context: a OptionContext

-> Maybe [Text]

argv: a pointer to the array of command line arguments

-> m (Maybe [Text])

(Can throw GError)

Parses the command line arguments, recognizing options which have been added to context. A side-effect of calling this function is that setPrgname will be called.

If the parsing is successful, any parsed arguments are removed from the array and argc and argv are updated accordingly. A '--' option is stripped from argv unless there are unparsed options before and after it, or some of the options after it start with '-'. In case of an error, argc and argv are left unmodified.

If automatic --help support is enabled (see optionContextSetHelpEnabled), and the argv array contains one of the recognized help options, this function will produce help output to stdout and call exit (0).

Note that function depends on the [current locale][setlocale] for automatic character set conversion of string and filename arguments.

Since: 2.6

parseStrv

optionContextParseStrv

Arguments

:: (HasCallStack, MonadIO m)

=> OptionContext

context: a OptionContext

-> Ptr CString

arguments: a pointer to the command line arguments (which must be in UTF-8 on Windows)

-> m (Ptr CString)

(Can throw GError)

Parses the command line arguments.

This function is similar to optionContextParse except that it respects the normal memory rules when dealing with a strv instead of assuming that the passed-in array is the argv of the main function.

In particular, strings that are removed from the arguments list will be freed using free.

On Windows, the strings are expected to be in UTF-8. This is in contrast to optionContextParse which expects them to be in the system codepage, which is how they are passed as argv to main(). See g_win32_get_command_line() for a solution.

This function is useful if you are trying to use OptionContext with GApplication.

Since: 2.40

setDescription

optionContextSetDescription

Arguments

:: (HasCallStack, MonadIO m)

=> OptionContext

context: a OptionContext

-> Maybe Text

description: a string to be shown in --help output after the list of options, or Nothing

-> m ()

Adds a string to be displayed in --help output after the list of options. This text often includes a bug reporting address.

Note that the summary is translated (see optionContextSetTranslateFunc).

Since: 2.12

setHelpEnabled

optionContextSetHelpEnabled

Arguments

:: (HasCallStack, MonadIO m)

=> OptionContext

context: a OptionContext

-> Bool

helpEnabled: True to enable --help, False to disable it

-> m ()

Enables or disables automatic generation of --help output. By default, optionContextParse recognizes --help, -h, -?, --help-all and --help-groupname and creates suitable output to stdout.

Since: 2.6

setIgnoreUnknownOptions

optionContextSetIgnoreUnknownOptions

Arguments

:: (HasCallStack, MonadIO m)

=> OptionContext

context: a OptionContext

-> Bool

ignoreUnknown: True to ignore unknown options, False to produce an error when unknown options are met

-> m ()

Sets whether to ignore unknown options or not. If an argument is ignored, it is left in the argv array after parsing. By default, optionContextParse treats unknown options as error.

This setting does not affect non-option arguments (i.e. arguments which don't start with a dash). But note that GOption cannot reliably determine whether a non-option belongs to a preceding unknown option.

Since: 2.6

setMainGroup

optionContextSetMainGroup

Arguments

:: (HasCallStack, MonadIO m)

=> OptionContext

context: a OptionContext

-> OptionGroup

group: the group to set as main group

-> m ()

Sets a OptionGroup as main group of the context. This has the same effect as calling optionContextAddGroup, the only difference is that the options in the main group are treated differently when generating --help output.

Since: 2.6

setStrictPosix

optionContextSetStrictPosix

Arguments

:: (HasCallStack, MonadIO m)

=> OptionContext

context: a GoptionContext

-> Bool

strictPosix: the new value

-> m ()

Sets strict POSIX mode.

By default, this mode is disabled.

In strict POSIX mode, the first non-argument parameter encountered (eg: filename) terminates argument processing. Remaining arguments are treated as non-options and are not attempted to be parsed.

If strict POSIX mode is disabled then parsing is done in the GNU way where option arguments can be freely mixed with non-options.

As an example, consider "ls foo -l". With GNU style parsing, this will list "foo" in long mode. In strict POSIX style, this will list the files named "foo" and "-l".

It may be useful to force strict POSIX mode when creating "verb style" command line tools. For example, the "gsettings" command line tool supports the global option "--schemadir" as well as many subcommands ("get", "set", etc.) which each have their own set of arguments. Using strict POSIX mode will allow parsing the global options up to the verb name while leaving the remaining options to be parsed by the relevant subcommand (which can be determined by examining the verb name, which should be present in argv[1] after parsing).

Since: 2.44

setSummary

optionContextSetSummary

Arguments

:: (HasCallStack, MonadIO m)

=> OptionContext

context: a OptionContext

-> Maybe Text

summary: a string to be shown in --help output before the list of options, or Nothing

-> m ()

Adds a string to be displayed in --help output before the list of options. This is typically a summary of the program functionality.

Note that the summary is translated (see optionContextSetTranslateFunc and optionContextSetTranslationDomain).

Since: 2.12

setTranslateFunc

optionContextSetTranslateFunc

Arguments

:: (HasCallStack, MonadIO m)

=> OptionContext

context: a OptionContext

-> Maybe TranslateFunc

func: the TranslateFunc, or Nothing

-> m ()

Sets the function which is used to translate the contexts user-visible strings, for --help output. If func is Nothing, strings are not translated.

Note that option groups have their own translation functions, this function only affects the parameterString (see g_option_context_new()), the summary (see optionContextSetSummary) and the description (see optionContextSetDescription).

If you are using gettext(), you only need to set the translation domain, see optionContextSetTranslationDomain.

Since: 2.12

setTranslationDomain

optionContextSetTranslationDomain

Arguments

:: (HasCallStack, MonadIO m)

=> OptionContext

context: a OptionContext

-> Text

domain: the domain to use

-> m ()

A convenience function to use gettext() for translating user-visible strings.

Since: 2.12