Library oops

Useful error stack objects

Many NSE library functions return a boolean status and an optional error message. The Oops library consists of several simple functions to accumulate these errors and pass them up the stack, resulting in a useful and verbose error message when debugging.

Author:

• Daniel Miller

Copyright © Same as Nmap--See https://nmap.org/book/man-legal.html

Source: https://svn.nmap.org/nmap/nselib/oops.lua

Functions

err (message, previous)

Add an error message to a stack of errors

output (status, message)

Report an error or return a good value

raise (message, status, previous, ...)

Report a status and error or return values

Functions

err (message, previous)

Add an error message to a stack of errors

Parameters

message

The error message to add to the stack.

previous

(Optional) Any error reported by other functions that failed.

Return value:

An Oops object representing the error stack.

output (status, message)

Report an error or return a good value

If the status is true, just return the message. If it's false, return the message as an Oops object. This can be easily used as the final return value of a script.

Parameters

status

The return status of the script.

message

The output of the script, or an error message if status is false.

Return value:

The message if status is true, or an error message if it is false.

raise (message, status, previous, ...)

Report a status and error or return values

This is intended to wrap a function that returns a status and either an error or some value. If the status is false, the message is added to the stack of errors. Instead of this code:

local status, value_or_error, value = somefunction(args)
if not status then
  return status, "somefunction failed for some reason"
end

with this instead:

local status, value_or_error, value = oops.raise("somefunction failed", somefunction(args))
if not status then
  return status, value_or_error
end

but instead of just the one error, you get a stack of errors from somefunction with your own message at the top.

Parameters

message

The error message to report if status is false.

status

The first return value of the function. Treated as boolean, but returned unmodified.

previous

The second return value of the function, or error.

...

 

Return values:

1. The same status that was input.
2. The rest of the return values, but on error, the message will be added to the stack.