getopts.lsp

Module index

source download

Module: getopts.lsp

Parse short and long command line options according to POSIX rules

Version: 1.0 initial release
Author: Ted Walther, July 2011


POSIX options come in 4 types; long and short, with or without an extra argument.

Short options are just a single letter with a - in front. -a -v -h are single options. Short options can be collapsed together. -a -v -h is the same thing as -avh

A short option that takes an argument can take the following two forms: -fmyletter.txt is the same as -f myletter.txt

Long options start with --. --quiet and --help are good examples.

A long option that takes an argument can be in the following two forms: --file=myletter.txt is the same as --file myletter.txt

Here is an example of how to use this module. It includes a bunch of standard options that every GNU program should support.

Example:

 (module "getopts.lsp")
 
 (setq version-string "Version: 1.0 (2011)")

 (shortopt "V" (getopts:die version-string) nil "Print version string")
 (shortopt "v" (++ verbosity) nil "Increase verbosity")
 (shortopt "q" (setq verbosity 0) nil "Quiet")
 (shortopt "?" (getopts:usage) nil "Print this help message")
 (shortopt "h" (getopts:usage) nil "Print this help message")
 (shortopt "o" (setq output-file getopts:arg) "file" "Output file")
 (longopt "help" (getopts:usage) nil "Print this help message")
 (longopt "quiet" (setq verbosity 0) nil "Quiet")
 (longopt "verbose" (++ verbosity) nil)
 (longopt "version" (getopts:die version-string) nil "Print version string")
 (longopt "output" (setq output-file getopts:arg) "file" "Output file")
 
 (println (main-args))
 (println (getopts (2 (main-args))))
 (println "Verbosity: " verbosity)
 (println "Output To: " output-file)
 (exit)

§

shortopt

syntax: (shortopt opt action arg? desc)
parameter: opt - The single letter option
parameter: action - The code to execute when the option is found
parameter: arg? - nil if the option doesn't take an argument, otherwise a string that describes the type of argument the option takes.
parameter: desc - A string that describes the option. This is used by the usage function.
Example:

 (shortopt "o" (setq output-file getopts:arg) "file" "Output file")
 ...
 $ ./myscript.lsp -ofoo.txt -q
 $ ./myscript.lsp -qofoo.txt
 $ ./myscript.lsp -o foo.txt -q
 $ ./myscript.lsp -qo foo.txt

§

longopt

syntax: (longopt opt action arg? desc)
parameter: opt - The long option
parameter: action - The code to execute when the option is found
parameter: arg? - nil if the option doesn't take an argument, otherwise a string that describes the type of argument the option takes.
parameter: desc - A string that describes the option. This is used by the usage function.
Example:

 (longopt "output" (setq output-file getopts:arg) "file" "Output file")
 ...
 $ ./myscript.lsp --output=foo.txt --quiet
 $ ./myscript.lsp --verbose --output foo.txt

§

getopts:arg

syntax: getopts:arg


The variable getopts:arg holds the argument to the option, for those options which take an argument. This is useful inside the action code, so you can make use of the argument. For instance, --prefix=/usr/bin on the command line, would leave the value /usr/bin in getopts:arg, and your action code could store the value or act on it in some other way.

§

getopts:usage

syntax: (getopts:usage)

return: Exits script with a value of 0

Prints out every command line option that has been registered with the getopts module.

Example:

 (shortopt "?" (getopts:usage) nil "Print this help message")
 ...
 $ ./myscript.lsp -?
 ==>
 Usage: ./myscript.lsp [options]
 	 -o file           	Output file
 	 -h                	Print this help message
 	 -?                	Print this help message
 	 -q                	Quiet
 	 -v                	Increase verbosity
 	--output file           	Output file
 	--verbose                	
 	--quiet                	Quiet
 	--help                	Print this help message

§

getopts:die

syntax: (getopts:die format-string [format options...])

return: Exits script with a value of 1

Prints an error message, then exits. Syntax is exactly the same as the format function.

§

getopts

syntax: (getopts arglist)
parameter: arglist - A list of strings, typically a subset of (main-args)

return: The list of all command line arguments that were NOT options.

After you have set up all the options using shortopt and longopt, call getopts to parse the commandline.

- ∂ -
generated with newLISP  and newLISPdoc