Class OptionContext

java.lang.Object
org.javagi.base.ProxyInstance
org.gnome.glib.OptionContext
All Implemented Interfaces:
Proxy
@Generated("org.javagi.JavaGI") public class OptionContext extends ProxyInstance
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.

  • Constructor Summary

    Constructors
    Constructor
    Description
    OptionContext(MemorySegment address)
    Create a OptionContext proxy instance for the provided memory address.

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    addGroup(OptionGroup group)
    Adds a GOptionGroup to the context, so that parsing with this OptionContext will recognize the options in the group.
    void
    addMainEntries(@Nullable OptionEntry @Nullable [] entries, @Nullable String translationDomain)
    A convenience function which creates a main group if it doesn't exist, adds the entries to it and sets the translation domain.
    void
    free()
    Frees context and all the groups which have been added to it.
    String
    getDescription()
    Returns the description.
    String
    getHelp(boolean mainHelp, @Nullable OptionGroup group)
    Returns a formatted, translated help text for the given context.
    boolean
    getHelpEnabled()
    Returns whether automatic --help generation is turned on for context. See g_option_context_set_help_enabled().
    boolean
    getIgnoreUnknownOptions()
    Returns whether unknown options are ignored or not.
    OptionGroup
    getMainGroup()
    Returns a pointer to the main group of context.
    static MemoryLayout
    getMemoryLayout()
    The memory layout of the native struct.
    boolean
    getStrictPosix()
    Returns whether strict POSIX code is enabled.
    String
    getSummary()
    Returns the summary.
    static OptionContext
    new_(@Nullable String parameterString)
    Creates a new option context.
    boolean
    parse(@Nullable Out<String[]> argv)
    Parses the command line arguments, recognizing options which have been added to context. A side-effect of calling this function is that g_set_prgname() will be called.
    boolean
    parseStrv(@Nullable Out<String[]> arguments)
    Parses the command line arguments.
    void
    setDescription(@Nullable String description)
    Adds a string to be displayed in --help output after the list of options.
    void
    setHelpEnabled(boolean helpEnabled)
    Enables or disables automatic generation of --help output.
    void
    setIgnoreUnknownOptions(boolean ignoreUnknown)
    Sets whether to ignore unknown options or not.
    void
    setMainGroup(OptionGroup group)
    Sets a GOptionGroup as main group of the context. This has the same effect as calling g_option_context_add_group(), the only difference is that the options in the main group are treated differently when generating --help output.
    void
    setStrictPosix(boolean strictPosix)
    Sets strict POSIX mode.
    void
    setSummary(@Nullable String summary)
    Adds a string to be displayed in --help output before the list of options.
    void
    setTranslateFunc(@Nullable TranslateFunc func)
    Sets the function which is used to translate the contexts user-visible strings, for --help output.
    void
    setTranslationDomain(String domain)
    A convenience function to use gettext() for translating user-visible strings.

    Methods inherited from class ProxyInstance

    equals, handle, hashCode

    Methods inherited from class Object

    clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait

  • Constructor Details

    • OptionContext

      public OptionContext(MemorySegment address)
      Create a OptionContext proxy instance for the provided memory address.
      Parameters:
      address - the memory address of the native object

  • Method Details

    • getMemoryLayout

      public static MemoryLayout getMemoryLayout()
      The memory layout of the native struct.
      Returns:
      the memory layout

    • new_

      public static OptionContext new_(@Nullable String parameterString)

      Creates a new option context.

      The parameterString can serve multiple purposes. It can be used to add descriptions for "rest" arguments, which are not parsed by the GOptionContext, typically something like "FILES" or "FILE1 FILE2...". If you are using G_OPTION_REMAINING for collecting "rest" arguments, GLib handles this automatically by using the argDescription of the corresponding GOptionEntry in the usage summary.

      Another usage is to give a short summary of the program functionality, like " - frob the strings", which will be displayed in the same line as the usage. For a longer description of the program functionality that should be displayed as a paragraph below the usage line, use g_option_context_set_summary().

      Note that the parameterString is translated using the function set with g_option_context_set_translate_func(), so it should normally be passed untranslated.

      Parameters:
      parameterString - a string which is displayed in the first line of --help output, after the usage summary programname [OPTION...]
      Returns:
      a newly created GOptionContext, which must be freed with g_option_context_free() after use.
      Since:
      2.6

    • addGroup

      public void addGroup(OptionGroup group)
      Adds a GOptionGroup to the context, so that parsing with this OptionContext will recognize the options in the group. Note that this will take ownership of the group and thus the group should not be freed.
      Parameters:
      group - the group to add
      Since:
      2.6

    • addMainEntries

      public void addMainEntries(@Nullable OptionEntry @Nullable [] entries, @Nullable String translationDomain)
      A convenience function which creates a main group if it doesn't exist, adds the entries to it and sets the translation domain.
      Parameters:
      entries - a null-terminated array of GOptionEntrys
      translationDomain - a translation domain to use for translating the --help output for the options in entries with gettext(), or null
      Since:
      2.6

    • free

      public void free()

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

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

      Since:
      2.6

    • getDescription

      public String getDescription()
      Returns the description. See g_option_context_set_description().
      Returns:
      the description
      Since:
      2.12

    • getHelp

      public String getHelp(boolean mainHelp, @Nullable OptionGroup group)
      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).
      Parameters:
      mainHelp - if true, only include the main group
      group - the GOptionGroup to create help for, or null
      Returns:
      A newly allocated string containing the help text
      Since:
      2.14

    • getHelpEnabled

      public boolean getHelpEnabled()
      Returns whether automatic --help generation is turned on for context. See g_option_context_set_help_enabled().
      Returns:
      true if automatic help generation is turned on.
      Since:
      2.6

    • getIgnoreUnknownOptions

      public boolean getIgnoreUnknownOptions()
      Returns whether unknown options are ignored or not. See g_option_context_set_ignore_unknown_options().
      Returns:
      true if unknown options are ignored.
      Since:
      2.6

    • getMainGroup

      public OptionGroup getMainGroup()
      Returns a pointer to the main group of context.
      Returns:
      the main group of context, or null if this OptionContext doesn't have a main group. Note that group belongs to this OptionContext and should not be modified or freed.
      Since:
      2.6

    • getStrictPosix

      public boolean getStrictPosix()

      Returns whether strict POSIX code is enabled.

      See g_option_context_set_strict_posix() for more information.

      Returns:
      true if strict POSIX is enabled, false otherwise.
      Since:
      2.44

    • getSummary

      public String getSummary()
      Returns the summary. See g_option_context_set_summary().
      Returns:
      the summary
      Since:
      2.12

    • parse

      public boolean parse(@Nullable Out<String[]> argv) throws GErrorException

      Parses the command line arguments, recognizing options which have been added to context. A side-effect of calling this function is that g_set_prgname() 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 g_option_context_set_help_enabled()), 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 for automatic character set conversion of string and filename arguments.

      Parameters:
      argv - a pointer to the array of command line arguments
      Returns:
      true if the parsing was successful, false if an error occurred
      Throws:
      GErrorException - see GError
      Since:
      2.6

    • parseStrv

      public boolean parseStrv(@Nullable Out<String[]> arguments) throws GErrorException

      Parses the command line arguments.

      This function is similar to g_option_context_parse() 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 g_free().

      On Windows, the strings are expected to be in UTF-8. This is in contrast to g_option_context_parse() 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 GOptionContext with GApplication.

      Parameters:
      arguments - a pointer to the command line arguments (which must be in UTF-8 on Windows). Starting with GLib 2.62, arguments can be null, which matches g_option_context_parse().
      Returns:
      true if the parsing was successful, false if an error occurred
      Throws:
      GErrorException - see GError
      Since:
      2.40

    • setDescription

      public void setDescription(@Nullable String description)

      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 g_option_context_set_translate_func()).

      Parameters:
      description - a string to be shown in --help output after the list of options, or null
      Since:
      2.12

    • setHelpEnabled

      public void setHelpEnabled(boolean helpEnabled)
      Enables or disables automatic generation of --help output. By default, g_option_context_parse() recognizes --help, -h, -?, --help-all and --help-groupname and creates suitable output to stdout.
      Parameters:
      helpEnabled - true to enable --help, false to disable it
      Since:
      2.6

    • setIgnoreUnknownOptions

      public void setIgnoreUnknownOptions(boolean ignoreUnknown)

      Sets whether to ignore unknown options or not. If an argument is ignored, it is left in the argv array after parsing. By default, g_option_context_parse() 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.

      Parameters:
      ignoreUnknown - true to ignore unknown options, false to produce an error when unknown options are met
      Since:
      2.6

    • setMainGroup

      public void setMainGroup(OptionGroup group)
      Sets a GOptionGroup as main group of the context. This has the same effect as calling g_option_context_add_group(), the only difference is that the options in the main group are treated differently when generating --help output.
      Parameters:
      group - the group to set as main group
      Since:
      2.6

    • setStrictPosix

      public void setStrictPosix(boolean strictPosix)

      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).

      Parameters:
      strictPosix - the new value
      Since:
      2.44

    • setSummary

      public void setSummary(@Nullable String summary)

      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 g_option_context_set_translate_func() and g_option_context_set_translation_domain()).

      Parameters:
      summary - a string to be shown in --help output before the list of options, or null
      Since:
      2.12

    • setTranslateFunc

      public void setTranslateFunc(@Nullable TranslateFunc func)

      Sets the function which is used to translate the contexts user-visible strings, for --help output. If func is null, 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 g_option_context_set_summary()) and the description (see g_option_context_set_description()).

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

      Parameters:
      func - the GTranslateFunc, or null
      Since:
      2.12

    • setTranslationDomain

      public void setTranslationDomain(String domain)
      A convenience function to use gettext() for translating user-visible strings.
      Parameters:
      domain - the domain to use
      Since:
      2.12