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
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.
- newtype OptionContext = OptionContext (ManagedPtr OptionContext)
- noOptionContext :: Maybe OptionContext
- data OptionContextAddGroupMethodInfo
- optionContextAddGroup :: (HasCallStack, MonadIO m) => OptionContext -> OptionGroup -> m ()
- data OptionContextAddMainEntriesMethodInfo
- optionContextAddMainEntries :: (HasCallStack, MonadIO m) => OptionContext -> OptionEntry -> Maybe Text -> m ()
- data OptionContextFreeMethodInfo
- optionContextFree :: (HasCallStack, MonadIO m) => OptionContext -> m ()
- data OptionContextGetDescriptionMethodInfo
- optionContextGetDescription :: (HasCallStack, MonadIO m) => OptionContext -> m Text
- data OptionContextGetHelpMethodInfo
- optionContextGetHelp :: (HasCallStack, MonadIO m) => OptionContext -> Bool -> Maybe OptionGroup -> m Text
- data OptionContextGetHelpEnabledMethodInfo
- optionContextGetHelpEnabled :: (HasCallStack, MonadIO m) => OptionContext -> m Bool
- data OptionContextGetIgnoreUnknownOptionsMethodInfo
- optionContextGetIgnoreUnknownOptions :: (HasCallStack, MonadIO m) => OptionContext -> m Bool
- data OptionContextGetMainGroupMethodInfo
- optionContextGetMainGroup :: (HasCallStack, MonadIO m) => OptionContext -> m OptionGroup
- data OptionContextGetStrictPosixMethodInfo
- optionContextGetStrictPosix :: (HasCallStack, MonadIO m) => OptionContext -> m Bool
- data OptionContextGetSummaryMethodInfo
- optionContextGetSummary :: (HasCallStack, MonadIO m) => OptionContext -> m Text
- data OptionContextParseMethodInfo
- optionContextParse :: (HasCallStack, MonadIO m) => OptionContext -> Maybe [Text] -> m (Maybe [Text])
- data OptionContextParseStrvMethodInfo
- optionContextParseStrv :: (HasCallStack, MonadIO m) => OptionContext -> Ptr CString -> m (Ptr CString)
- data OptionContextSetDescriptionMethodInfo
- optionContextSetDescription :: (HasCallStack, MonadIO m) => OptionContext -> Maybe Text -> m ()
- data OptionContextSetHelpEnabledMethodInfo
- optionContextSetHelpEnabled :: (HasCallStack, MonadIO m) => OptionContext -> Bool -> m ()
- data OptionContextSetIgnoreUnknownOptionsMethodInfo
- optionContextSetIgnoreUnknownOptions :: (HasCallStack, MonadIO m) => OptionContext -> Bool -> m ()
- data OptionContextSetMainGroupMethodInfo
- optionContextSetMainGroup :: (HasCallStack, MonadIO m) => OptionContext -> OptionGroup -> m ()
- data OptionContextSetStrictPosixMethodInfo
- optionContextSetStrictPosix :: (HasCallStack, MonadIO m) => OptionContext -> Bool -> m ()
- data OptionContextSetSummaryMethodInfo
- optionContextSetSummary :: (HasCallStack, MonadIO m) => OptionContext -> Maybe Text -> m ()
- data OptionContextSetTranslateFuncMethodInfo
- optionContextSetTranslateFunc :: (HasCallStack, MonadIO m) => OptionContext -> Maybe TranslateFunc -> m ()
- data OptionContextSetTranslationDomainMethodInfo
- optionContextSetTranslationDomain :: (HasCallStack, MonadIO m) => OptionContext -> Text -> m ()
Exported types
newtype OptionContext #
Constructors
OptionContext (ManagedPtr OptionContext) |
Instances
Methods
addGroup
data OptionContextAddGroupMethodInfo #
Instances
((~) * signature (OptionGroup -> m ()), MonadIO m) => MethodInfo * OptionContextAddGroupMethodInfo OptionContext signature # | |
Arguments
:: (HasCallStack, MonadIO m) | |
=> OptionContext |
|
-> OptionGroup |
|
-> 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
data OptionContextAddMainEntriesMethodInfo #
Instances
((~) * signature (OptionEntry -> Maybe Text -> m ()), MonadIO m) => MethodInfo * OptionContextAddMainEntriesMethodInfo OptionContext signature # | |
Arguments
:: (HasCallStack, MonadIO m) | |
=> OptionContext |
|
-> OptionEntry |
|
-> Maybe Text |
|
-> 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
data OptionContextFreeMethodInfo #
Instances
((~) * signature (m ()), MonadIO m) => MethodInfo * OptionContextFreeMethodInfo OptionContext signature # | |
Arguments
:: (HasCallStack, MonadIO m) | |
=> 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
data OptionContextGetDescriptionMethodInfo #
Instances
((~) * signature (m Text), MonadIO m) => MethodInfo * OptionContextGetDescriptionMethodInfo OptionContext signature # | |
Arguments
:: (HasCallStack, MonadIO m) | |
=> OptionContext |
|
-> m Text | Returns: the description |
Returns the description. See optionContextSetDescription
.
Since: 2.12
getHelp
data OptionContextGetHelpMethodInfo #
Instances
((~) * signature (Bool -> Maybe OptionGroup -> m Text), MonadIO m) => MethodInfo * OptionContextGetHelpMethodInfo OptionContext signature # | |
Arguments
:: (HasCallStack, MonadIO m) | |
=> OptionContext |
|
-> Bool |
|
-> Maybe OptionGroup |
|
-> 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
data OptionContextGetHelpEnabledMethodInfo #
Instances
((~) * signature (m Bool), MonadIO m) => MethodInfo * OptionContextGetHelpEnabledMethodInfo OptionContext signature # | |
Arguments
:: (HasCallStack, MonadIO m) | |
=> OptionContext |
|
-> m Bool | Returns: |
Returns whether automatic --help
generation
is turned on for context
. See optionContextSetHelpEnabled
.
Since: 2.6
getIgnoreUnknownOptions
data OptionContextGetIgnoreUnknownOptionsMethodInfo #
Instances
((~) * signature (m Bool), MonadIO m) => MethodInfo * OptionContextGetIgnoreUnknownOptionsMethodInfo OptionContext signature # | |
optionContextGetIgnoreUnknownOptions #
Arguments
:: (HasCallStack, MonadIO m) | |
=> OptionContext |
|
-> m Bool | Returns: |
Returns whether unknown options are ignored or not. See
optionContextSetIgnoreUnknownOptions
.
Since: 2.6
getMainGroup
data OptionContextGetMainGroupMethodInfo #
Instances
((~) * signature (m OptionGroup), MonadIO m) => MethodInfo * OptionContextGetMainGroupMethodInfo OptionContext signature # | |
Arguments
:: (HasCallStack, MonadIO m) | |
=> OptionContext |
|
-> m OptionGroup | Returns: the main group of |
Returns a pointer to the main group of context
.
Since: 2.6
getStrictPosix
data OptionContextGetStrictPosixMethodInfo #
Instances
((~) * signature (m Bool), MonadIO m) => MethodInfo * OptionContextGetStrictPosixMethodInfo OptionContext signature # | |
Arguments
:: (HasCallStack, MonadIO m) | |
=> OptionContext |
|
-> m Bool |
Returns whether strict POSIX code is enabled.
See optionContextSetStrictPosix
for more information.
Since: 2.44
getSummary
data OptionContextGetSummaryMethodInfo #
Instances
((~) * signature (m Text), MonadIO m) => MethodInfo * OptionContextGetSummaryMethodInfo OptionContext signature # | |
Arguments
:: (HasCallStack, MonadIO m) | |
=> OptionContext |
|
-> m Text | Returns: the summary |
Returns the summary. See optionContextSetSummary
.
Since: 2.12
parse
data OptionContextParseMethodInfo #
Instances
((~) * signature (Maybe [Text] -> m (Maybe [Text])), MonadIO m) => MethodInfo * OptionContextParseMethodInfo OptionContext signature # | |
Arguments
:: (HasCallStack, MonadIO m) | |
=> OptionContext |
|
-> Maybe [Text] |
|
-> m (Maybe [Text]) | (Can throw |
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
data OptionContextParseStrvMethodInfo #
Instances
((~) * signature (Ptr CString -> m (Ptr CString)), MonadIO m) => MethodInfo * OptionContextParseStrvMethodInfo OptionContext signature # | |
Arguments
:: (HasCallStack, MonadIO m) | |
=> OptionContext |
|
-> Ptr CString |
|
-> m (Ptr CString) | (Can throw |
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
data OptionContextSetDescriptionMethodInfo #
Instances
((~) * signature (Maybe Text -> m ()), MonadIO m) => MethodInfo * OptionContextSetDescriptionMethodInfo OptionContext signature # | |
Arguments
:: (HasCallStack, MonadIO m) | |
=> OptionContext |
|
-> Maybe Text |
|
-> 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
data OptionContextSetHelpEnabledMethodInfo #
Instances
((~) * signature (Bool -> m ()), MonadIO m) => MethodInfo * OptionContextSetHelpEnabledMethodInfo OptionContext signature # | |
Arguments
:: (HasCallStack, MonadIO m) | |
=> OptionContext |
|
-> Bool | |
-> 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
data OptionContextSetIgnoreUnknownOptionsMethodInfo #
Instances
((~) * signature (Bool -> m ()), MonadIO m) => MethodInfo * OptionContextSetIgnoreUnknownOptionsMethodInfo OptionContext signature # | |
optionContextSetIgnoreUnknownOptions #
Arguments
:: (HasCallStack, MonadIO m) | |
=> OptionContext |
|
-> Bool |
|
-> 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
data OptionContextSetMainGroupMethodInfo #
Instances
((~) * signature (OptionGroup -> m ()), MonadIO m) => MethodInfo * OptionContextSetMainGroupMethodInfo OptionContext signature # | |
Arguments
:: (HasCallStack, MonadIO m) | |
=> OptionContext |
|
-> OptionGroup |
|
-> 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
data OptionContextSetStrictPosixMethodInfo #
Instances
((~) * signature (Bool -> m ()), MonadIO m) => MethodInfo * OptionContextSetStrictPosixMethodInfo OptionContext signature # | |
Arguments
:: (HasCallStack, MonadIO m) | |
=> OptionContext |
|
-> Bool |
|
-> 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
data OptionContextSetSummaryMethodInfo #
Instances
((~) * signature (Maybe Text -> m ()), MonadIO m) => MethodInfo * OptionContextSetSummaryMethodInfo OptionContext signature # | |
Arguments
:: (HasCallStack, MonadIO m) | |
=> OptionContext |
|
-> Maybe Text |
|
-> 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
data OptionContextSetTranslateFuncMethodInfo #
Instances
((~) * signature (Maybe TranslateFunc -> m ()), MonadIO m) => MethodInfo * OptionContextSetTranslateFuncMethodInfo OptionContext signature # | |
optionContextSetTranslateFunc #
Arguments
:: (HasCallStack, MonadIO m) | |
=> OptionContext |
|
-> Maybe TranslateFunc |
|
-> 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
data OptionContextSetTranslationDomainMethodInfo #
Instances
((~) * signature (Text -> m ()), MonadIO m) => MethodInfo * OptionContextSetTranslationDomainMethodInfo OptionContext signature # | |
optionContextSetTranslationDomain #
Arguments
:: (HasCallStack, MonadIO m) | |
=> OptionContext |
|
-> Text |
|
-> m () |
A convenience function to use gettext()
for translating
user-visible strings.
Since: 2.12