Callisto

• Index

Contents

• Functions

Modules

• cl
• environ
• extra
• fs
• json
• process

Module cl

Option parsing, and error formatting for the command line.

Functions

error (message, ...)	Prints a formatted error message to standard error.
mesg (message, ...)	Prints a formatted message to standard output.
panic ([code], message, ...)	Convenience function that calls cl.error to print a formatted error message to standard error, then terminates script execution and calls os.exit.
options (arg, optstring, fn)	Parses the command line argument list arg.

Functions

error (message, ...)

Prints a formatted error message to standard error. It looks like so:

progname: message

where progname is the name of the current script being executed and message is the message parameter.

The message parameter may optionally be followed by a variable number of arguments which are formatted using string.format.

Parameters:

• message string The message to print after the program's name. Supports string.format-style format specifiers.
• ... Any additional values specified by the format specifiers in the message parameter.

Usage:

local succeeded, err = io.open("file.txt")
if not succeeded then
	cl.error("could not open " .. err)
end

mesg (message, ...)

Prints a formatted message to standard output. It looks like so:

progname: message

where progname is the name of the current script being executed and message is the (optionally formatted) message parameter.

The message parameter may optionally be followed by a variable number of arguments which are formatted using string.format.

Parameters:

• message string The message to print after the program's name. Supports string.format-style format specifiers.
• ... Any additional values specified by the format specifiers in the message parameter.

Usage:

cl.mesg("message to stdout")

panic ([code], message, ...)

Convenience function that calls cl.error to print a formatted error message to standard error, then terminates script execution and calls os.exit.

For more information on the message parameter, see the cl.error function.

Parameters:

• code integer The exit code to return to the operating system. (optional)
• message string The message to print after the program's name. Supports string.format-style format specifiers.
• ... Any additional values specified by the format specifiers in the message parameter.

Usage:

local succeeded, err, code = io.open("file.txt")
if not succeeded then
	-- use a custom exit code:
	cl.panic(code, "could not open " .. err)
	-- use the default exit code (1):
	cl.panic("could not open " .. err)
end

options (arg, optstring, fn)

Parses the command line argument list arg. The string optstring may contain the following elements: individual characters, and characters followed by a colon. A character followed by a single colon indicates that an argument is to follow the option on the command line. For example, * an option string "x" permits a -x option, and an option string "x:" permits a -x option that must take an argument. An option * string of "x:yz" permits a -x option that takes an argument, and -y and -z options, which do not.

The function fn is run each time a new option of the argument list is processed. It takes the parameters opt, optarg, optindex, and opterror. - opt is a string containing the option used. It is set to the option the user specified on the command line. If the user specifies an unknown option (one that is not specified in optstring), the value of opt will be set to nil. If the user specifies an option that requires an argument, but does not specify its argument, the value of opt will be the string "*" (a single asterisk). - optarg, is a string containing the option argument (if applicable). - optindex is an integer that contains the index of the last command line argument processed. The last parameter, opterror, is set in case of an option error (if opt is nil or set to the string "*"), and is set to the option that caused an error (in the case of opt being nil, this will be the unknown option the user specified, or in the case of opt being the string "*", this will be the option that required an argument).

Parameters:

• arg table The argument table to parse.
• optstring string The option string, containing options that should be parsed.
• fn function The function to be run each time a new option is specified on the command line.

Usage:

cl.options(arg, "abc:", function(opt, optarg, optindex, opterror)
	if opt == 'a' then
		print("-a was used")
	elseif opt == 'b' then
		print("-b was used")
	elseif opt == 'c' then
		print("-c was used, with argument " .. optarg)
	elseif opt == '*' then
		print("missing argument for -" .. opterror)
	elseif opt == nil then -- or `if not opt`
		print("unknown option -" .. opterror)
	end
end)