(define-module (my modules my-prog)
       #:autoload (scripts PROGRAM) (HVQC-MAIN)
       ...)

— Scheme Procedure: HVQC-MAIN args callback . config

Parse and handle args, a list of strings, for --help, --version, getopt-style command-line options processing and eventual application of callback, a procedure with one of two signatures (see below), all based on config, a list of zero or more key-value pairs for configuring the behavior of HVQC-MAIN. Recognized keys are: package, version, usage and option-spec.

Specifically, HVQC-MAIN does these actions:

• Check (cadr args) for --help. If found, display the help text to the current output port and exit successfully.

  The help text is by default "Usage: ~A [ARGS]" (followed by newline), where ~A is the basename of the program. You can specify more appropriate help text with a (usage . WHERE) element in the config list. WHERE can be:

  • the symbol commentary, which means to display the commentary
  • a string to use directly
  • a thunk which returns a string

  For the (usage . commentary) case, leading semicolons are removed from each line in the commentary automatically.

• If --help is not found, check (cadr args) for --version. If found, display the version text to the current output port and exit successfully.

  The version text is by default NAME VERSION (followed by newline), where NAME is the basename of the program, and VERSION is the result of calling the version procedure.

  You can specify an optional version string and an optional package affiliation string, using version and package configuration elements, respectively. When a package is specified, it appears in parentheses between the NAME and VERSION, like so: NAME (PACKAGE) VERSION.

• If --version is not found, check config for an option-spec key. If found, pass the associated option-spec along with the args to the getopt-long procedure as provided by module (ice-9 getopt-long). Use the result alist returned from getopt-long to make a qop (query-options procedure) and finally, pass this to the callback.

  The qop takes a key (a query of the parsed options) and an optional handler. If there is no associated parsed value for that key, qop returns #f. If a handler is specified, it is passed the associated (non-#f) value, and its return value is returned by qop. Otherwise, qop simply returns the associated (non-#f) value.

• If there is no option-spec in config, construct an argument list from args where the first argument has been passed through basename and the rest are unmodified. The invocation filename is available through an object property of the first arg named invocation-filename. Pass this arg list to callback.

  For example, this callback:

                 (define (callback args)
                   (simple-format #t "args: ~S~%" args)
                   (simple-format #t "invocation-filename: ~S~%"
                                  (object-property (car args) 'invocation-filename))
                   #t)
  

  for invocation /path/to/my-prog 1 2 3 displays:

                 args: ("my-prog" "1" "2" "3")
                 invocation-filename: "/path/to/my-prog"
  

  The rationale for passing this modified program argument list to callback instead of the unaltered original is that the program's basename is usually more appropriate for error messages and such, and so should be more easily accessible.

     $ guile-tools                    # to see a list of programs
     $ guile-tools PROGRAM --help     # to see PROGRAM's help
     $ guile-tools PROGRAM --version  # to see PROGRAM's version
     $ guile-tools --source PROGRAM   # to see PROGRAM's source