The GOption command line parser is intended to be a simpler replacement for the popt library. It supports short and long command line options, as shown in the following example:

testtreemodel -r 1 --max-size 20 --rand --display=:1.0 -vb -- file1 file2  

The example demonstrates a number of features of the GOption command line parser:

• Options can be single letters, prefixed by a single dash.
• Multiple short options can be grouped behind a single dash.
• Long options are prefixed by two consecutive dashes.
• Options can have an extra argument, which can be a number, a string or a filename. For long options, the extra argument can be appended with an equals sign after the option name, which is useful if the extra argument starts with a dash, which would otherwise cause it to be interpreted as another option.
• Non-option arguments are returned to the application as rest arguments.
• An argument consisting solely of two dashes turns off further parsing, any remaining arguments, even those starting with a dash, are returned to the application as rest arguments.

Another important feature of GOption is that it can automatically generate nicely formatted help output. Unless it is explicitly turned off with the g-option-context-help-enabled function, GOption will recognize the --help, -?, --help-all and --help-groupname options, where groupname is the name of a g-option-group instance, and write a text similar to the one shown in the following example.

Usage:
  testtreemodel [OPTION...] - test tree model performance


Help Options:
  -h, --help               Show help options
  --help-all               Show all help options
  --help-gtk               Show GTK+ Options


Application Options:
  -r, --repeats=N          Average over N repetitions
  -m, --max-size=M         Test up to 2^M items
  --display=DISPLAY        X display to use
  -v, --verbose            Be verbose
  -b, --beep               Beep when done
  --rand                   Randomize the data  

GOption groups options in a g-option-group instance, which makes it easy to incorporate options from multiple sources. The intended use for this is to let applications collect option groups from the libraries it uses, add them to their g-option-context instance, and parse all options by a single call to the g-option-context-parse function. See the gtk-option-group function for an example.

If an option is declared to be of type string or filename, GOption takes care of converting it to the right encoding. Strings are returned in UTF-8, filenames are returned in the GLib filename encoding. Note that this only works if the setlocale() function has been called before the g-option-context-parse function.

Here is a complete example of setting up GOption to parse the example command line above and produce the example help output.

(defvar repeats (cffi:foreign-alloc :int :initial-element 2))
(defvar max-size (cffi:foreign-alloc :int :initial-element 0))
(defvar verbose (cffi:foreign-alloc :boolean :initial-element nil))
(defvar beep (cffi:foreign-alloc :boolean :initial-element nil))
(defvar randomize (cffi:foreign-alloc :boolean :initial-element nil))


(defun main (&rest argv)
  (let ((entries '(("repeats"                        ; long-name
                    #\r                              ; short-name
                    :none                            ; flags
                    :int                             ; arg
                    repeats                          ; arg-data
                    "Average over N repetitions"     ; description
                    "N")                             ; arg-description
                   ("max-size"
                    #\m
                    0
                    :int
                    max-size
                    "Test up to 2^M items"
                    "M")
                   ("verbose"
                    #\v
                    0
                    :none
                    verbose
                    "Be verbose"
                    nil)
                   ("beep"
                    #\b
                    0
                    :none
                    beep
                    "Beep when done"
                    nil)
                   ("rand"
                    #\Nul
                    0
                    :none
                    randomize
                    "Randomize the data"
                    nil)))
         (context (g-option-context-new "- test tree model performance")))


    (g-option-context-add-main-entries context entries nil)
    (g-option-context-add-group context (gtk-option-group t))


    (if (g-option-context-parse context argv)
        (progn
          (format t "Option parsing failed.~%")
          ;; Print the Help Usage
          (format t "~&~%~a~%" (g-option-context-help context t)))
        (progn
          ;; Print the parsed arguments
          (format t "~&Parsed arguments~%")
          (format t "   repeats : ~a~%" (mem-ref repeats :int))
          (format t "  max-size : ~a~%" (mem-ref max-size :int))
          (format t "   verbose : ~a~%" (mem-ref verbose :boolean))
          (format t "      beep : ~a~%" (mem-ref beep :boolean))
          (format t " randomize : ~a~%" (mem-ref randomize :boolean))))
  ... ))  

On UNIX systems, the argv argument that is passed to the main function has no particular encoding, even to the extent that different parts of it may have different encodings. In general, normal arguments and flags will be in the current locale and filenames should be considered to be opaque byte strings. Proper use of the :filename versus :string option arguments is therefore important.

Note that on Windows, filenames do have an encoding, but using a g-option-context instance with the argv argument as passed to the main function will result in a program that can only accept command line arguments with characters from the system codepage. This can cause problems when attempting to deal with filenames containing Unicode characters that fall outside of the codepage.

A solution to this is to use the g_win32_get_command_line() and g-option-context-parse-strv functions which will properly handle full Unicode filenames. If you are using a g-application instance, this is done automatically for you.