gi-glib-2.0.17: GLib bindings

Copyright | Will Thompson Iñaki García Etxebarria and Jonas Platte
License | LGPL-2.1
Maintainer | Iñaki García Etxebarria (garetxe@gmail.com)
Safe Haskell | None
Language | Haskell2010

GI.GLib.Structs.OptionContext

Contents

- Exported types
- Methods
  - addGroup
  - addMainEntries
  - free
  - getDescription
  - getHelp
  - getHelpEnabled
  - getIgnoreUnknownOptions
  - getMainGroup
  - getStrictPosix
  - getSummary
  - parse
  - parseStrv
  - setDescription
  - setHelpEnabled
  - setIgnoreUnknownOptions
  - setMainGroup
  - setStrictPosix
  - setSummary
  - setTranslateFunc
  - setTranslationDomain

Description

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.

Synopsis

- newtype OptionContext = OptionContext (ManagedPtr OptionContext)
- noOptionContext :: Maybe OptionContext
- optionContextAddGroup :: (HasCallStack, MonadIO m) => OptionContext -> OptionGroup -> m ()
- optionContextAddMainEntries :: (HasCallStack, MonadIO m) => OptionContext -> OptionEntry -> Maybe Text -> m ()
- optionContextFree :: (HasCallStack, MonadIO m) => OptionContext -> m ()
- optionContextGetDescription :: (HasCallStack, MonadIO m) => OptionContext -> m Text
- optionContextGetHelp :: (HasCallStack, MonadIO m) => OptionContext -> Bool -> Maybe OptionGroup -> m Text
- optionContextGetHelpEnabled :: (HasCallStack, MonadIO m) => OptionContext -> m Bool
- optionContextGetIgnoreUnknownOptions :: (HasCallStack, MonadIO m) => OptionContext -> m Bool
- optionContextGetMainGroup :: (HasCallStack, MonadIO m) => OptionContext -> m OptionGroup
- optionContextGetStrictPosix :: (HasCallStack, MonadIO m) => OptionContext -> m Bool
- optionContextGetSummary :: (HasCallStack, MonadIO m) => OptionContext -> m Text
- optionContextParse :: (HasCallStack, MonadIO m) => OptionContext -> Maybe [Text] -> m (Maybe [Text])
- optionContextParseStrv :: (HasCallStack, MonadIO m) => OptionContext -> [Text] -> m [Text]
- optionContextSetDescription :: (HasCallStack, MonadIO m) => OptionContext -> Maybe Text -> m ()
- optionContextSetHelpEnabled :: (HasCallStack, MonadIO m) => OptionContext -> Bool -> m ()
- optionContextSetIgnoreUnknownOptions :: (HasCallStack, MonadIO m) => OptionContext -> Bool -> m ()
- optionContextSetMainGroup :: (HasCallStack, MonadIO m) => OptionContext -> OptionGroup -> m ()
- optionContextSetStrictPosix :: (HasCallStack, MonadIO m) => OptionContext -> Bool -> m ()
- optionContextSetSummary :: (HasCallStack, MonadIO m) => OptionContext -> Maybe Text -> m ()
- optionContextSetTranslateFunc :: (HasCallStack, MonadIO m) => OptionContext -> Maybe TranslateFunc -> m ()
- optionContextSetTranslationDomain :: (HasCallStack, MonadIO m) => OptionContext -> Text -> m ()

# Exported types

newtype OptionContext Source #

Memory-managed wrapper type.

Constructors

OptionContext (ManagedPtr OptionContext) |

Instances

WrappedPtr OptionContext Source # |
Instance details Defined in GI.GLib.Structs.OptionContext Methods wrappedPtrCalloc :: IO (Ptr OptionContext) Source # wrappedPtrCopy :: OptionContext -> IO OptionContext Source # wrappedPtrFree :: Maybe (FunPtr (Ptr OptionContext -> IO ())) Source #

noOptionContext :: Maybe OptionContext Source #

A convenience alias for `Nothing` :: `Maybe` `OptionContext`.

# Methods

## addGroup

optionContextAddGroup Source #

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 Source #

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 Source #

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 Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> OptionContext | `context`: a `OptionContext`
-> m Text | Returns: the description

Returns the description. See `optionContextSetDescription`.

Since: 2.12

## getHelp

optionContextGetHelp Source #

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 Source #

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 Source #

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 Source #

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 Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> OptionContext | `context`: a `OptionContext`
-> 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 Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> OptionContext | `context`: a `OptionContext`
-> m Text | Returns: the summary

Returns the summary. See `optionContextSetSummary`.

Since: 2.12

## parse

optionContextParse Source #

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 Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> OptionContext | `context`: a `OptionContext`
-> [Text] | `arguments`: a pointer to the command line arguments (which must be in UTF-8 on Windows)
-> m [Text] | (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 Source #

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 Source #

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 Source #

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 Source #

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 Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> OptionContext | `context`: a `OptionContext`
-> 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 Source #

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 Source #

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 Source #

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