Slredirect

From OpenEUO
Revision as of 16:49, 2 November 2010 by Ximan (Talk | contribs) (Usage Example)

(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search

Calling Convention

Call

local o = sl.redirect(flags[,filename[,callback]])

Args

flags is a string, valid members being 'c','i','n','p','r'
filename is a string, or nil
callback is a function

Results

o is a string, the old value of flags

Usage Example

local sl = dofile(getinstalldir()..'/lib/simplelib.lua')
local eh = function(eref)
  print('Script threw an error: '..sl.geterror(eref)._errmsg)
end
sl.redirect('pcr', 'myerrorlog.txt', eh)
local f  = function()
  local a = 'A'
  b = A * 3.14
end
local h  = function()
  error('This mightily suxxors.',1)
end
try(f, h)
--> Script threw an error: This mightily suxxors.

Description

Changes error message and exception handling for the entire library as well as user functions handled by the provided try method. By default, the library announces encountered errors in the script output window, and then reraises the error. Errors can also be recorded to log file (default is 'simpleliberr.txt' in the lib/ subdirectory of openeuo).

flag : effect
c      call user-supplied callback, trumps 'i'
i      inline an error tuple (in lieu of default reraise action)
n      if 'i' specified, return (nil,eref) instead of (ERR,eref)
p      print error message in script output window (default)
r      (also) record error information to log file

A 'c' flag causes errors to be redirected to the user supplied callback function. The function in which the error was caught will return whatever callback returns. The 'c' flag does not affect reporting either in the output window or to log file.

An 'i' flag causes errors to be inlined as the return result of the function where the error occurred. Said function will return an (ERR,eref) tuple, where eref is a number that can be supplied to the library function geterror. If 'n' is also specified, then the returned tuple takes the standard lua format of (nil,eref).

A 'p' flag causes error message text to be appended to the scripts output window. Clearing 'p' (removing it from the specified flags) silences this reporting mode.

A 'r' flag causes error message text to be logged to file. Clearing 'r' (removing it from the specified flags) silences this reporting mode. Stack tracing information will be added if verbosity has been set to 'high' (see slverbosity).

Callback Operation

The function specified by callback will receive all library errors if 'c' is specified anywhere in the flags, i.e. it trumps all other error handling modes. The callback should be defined to receive one argument, a number, eref. This can then be passed to geterror to retrieve an error record table.

Upon Error

Redirect fails silently. If 'c' is specified in flags, and a callback function wasn't specified, error will simply be reraised. If 'r' is specified, but the specified filename is invalid, an unhandled exception will raise when an attempt to write (open) the file occurs.

See Also