View source for Slredirect

== 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 ==

* [http://www.easyuo.com/openeuo/wiki/index.php/Simplelib simplelib]

* [[geterror]]

* [[try]]

* [[slverbosity]]