Commandline parsing with getopt

Wirbel's implementation of getopt

getopt is a well known library for parsing command lines. It can handle short options, GNU-style long options, options with optional arguments and many other details.

Wirbel has it's own implementation of getopt, which offers a modern API that makes use of Wirbel's functional programming features. It will take the programmer's burden of doing everything right and conforming to standards:

• One-letter short options like -a and -X can be combined to -aX.
• But if a short option requires an argument, it can be appended to the option. Instead of -I ../lib the user may write -I../lib.
• Long options like --debug can take arguments, too. Their options can even be optional. The user can specify an optional argument to a long option with --debug=most.
• The user can place the special argument -- to mark an explicit end of options.
• A single dash '-' is not considered to be an option but a normal argument (which the application might interpret as stdin or stdout)0.

How to use getopt

Defining the options

The first step for using getopt in your application is to define a table describing all options your programm understands. You need list of six-tuples:

options = [
  ( 'v',  "verbose",  `no_argument,       `verbose,      [],              null ),
  ( 'V',  "version",  `no_argument,       null,          [],              lambda w,x,y,z: print_version() ),
  ( 'h',  "help",     `no_argument,       null,          [],              lambda w,x,y,z: print_usage() ),
  ( 'o',  "output",   `required_argument, null,          [],              set_output_file ),
  ( null, "debug",    `optional_argument, null,          [],              null ),
  ( 'c',  null,       `no_argument,       `dont_compile, [`optimize],     null ),
  ( 'O',  "optimize", `no_argument,       `optimize,     [`dont_compile], null ),
]

These are the columns:

• char: Short option (might be null if there is only a long version of this option)
• string: Long option (might be null if there is only a short version of this option)
• enum: Specifies wether this option takes an argument. Three values are allowed: `no_argument, `optional_argument and `required_argument.
• enum: If the option is seen in the commandline it sets this flags for you. May be null if no flag should be set.
• list(enum): A list of the flags of other options that this option conflicts with.
• function(string, string, list(enum), list(string)): An optional function that handles this option. If getopt sees the option, it will call this function for you with four arguments:
  • The actual option (this makes it possible to use one generic function for a set of similar options)
  • The options' argument or null of no argument was supplied by the user
  • The list of all flags seen in the entire command line
  • The list of all non-option arguments seen in the entire command line

Please note that all option handlers will not be called before the entire command line has been parsed and been declared as correct. That way the user might use flags at any position in the command line. Nevertheless the order of execution of the handler functions resembles the order of options in the commandline.

Calling getopt

getopt takes to argument: the list of actual command line arguments (without argv[0]) and your option table. It will return a list of all seen flags and a list of all non-option arguments. If a syntax error in the commandline is detected then an exception of type getopt will be raised. Its reason-text which will explain the error to the user.

try:
    seen_flags, arguments = getopt(argv[1:], options)
except getopt:
    print(reason)
    exit(1)

Handler functions Option handler function might either take

immediate action and execute the option, or store values for later execution in global variables. The following example function is called whenever the option -o or --output is seen:

def set_output_file(opt, opt_arg, seen_flags, arguments):
    print("Ouputfile (Option %s) is %s" % opt % opt_arg)
    if `verbose in seen_flags:
	print("Verbose output...")
    print("Non-option arguments: %s" % arguments)

If you handler function does not take all four parameters you can help yourself with the lambda construct as seen in the upper example. The follo function print_version does not take any parameter:

def print_version():
    print("Getopt demo 1.0.17, Copyright Mathias Kettner")
    exit(1)

It is entered in the option table as lambda w,x,y,z: print_version().