; docformat = 'rst'

;+
; MG_LOG is a procedural interface to the logging framework.
;
; MG_LOG is a convenience routine so that the MGffLogger object does not need
; to be explicitly stored. If more than one logger is required, then create
; and use the logger objects explicitly instead of using this routine.
;
; The error levels are: none (level 0), debug (level 1), informational (level 
; 2), warning (level 3), error (level 4), critial (level 5). Only log messages 
; with a level equal or higher to the current logger level are actually 
; recorded.
; 
; :Examples:
;    Use the LOGGER keyword to retrieve the logger object in order to set the
;    level or filename of output::
;
;       IDL> mg_log, logger=logger
;       IDL> logger->setProperty, level=3
;       IDL> mg_log, 'Warning message', /warning
;-


;+
; Messages are logged via this routine. Also, the LOGGER keyword returns the
; logging object which is used to configure the logging.
;
; :Params:
;    msg : in, optional, type=string
;       message to log, if present
;
; :Keywords:
;    debug : in, optional, type=boolean
;       set to specify the message as debug
;    informational : in, optional, type=boolean
;       set to specify the message as informational
;    warning : in, optional, type=boolean
;       set to specify the message as a warning
;    error : in, optional, type=boolean
;       set to specify the message as an error
;    critical : in, optional, type=boolean
;       set to specify the message as critical
;    last_error : in, optional, type=boolean
;       set to place a stack trace for the last error in the log
;    logger : out, optional, type=object
;       MGlogInfo object
;    quit : in, optional, type=boolean
;       set to quit logging
;-
pro mg_log, msg, debug=debug, informational=informational, $
            warning=warning, error=error, critical=critical, $
            last_error=lastError, $
            logger=logger, quit=quit
  compile_opt strictarr
  @mg_log_common
  
  if (~obj_valid(mgLogger)) then begin
    mgLogger = obj_new('MGffLogger')
  endif

  if (arg_present(logger)) then begin
    logger = mgLogger
  endif
  
  if (keyword_set(quit)) then begin
    obj_destroy, mgLogger
  endif

  if (keyword_set(lastError)) then begin
    mgLogger->insertLastError
  endif
  
  if (n_params() gt 0L && obj_valid(mgLogger)) then begin
    levels = [keyword_set(debug), keyword_set(informational), $
              keyword_set(warning), keyword_set(error), keyword_set(critical)]
    level = max(levels * (lindgen(5) + 1L))
    mgLogger->print, msg, level=level
  endif
end


; Main-level example program

mg_log, logger=logger

logger->setProperty, level=3

mg_log, 'Debugging message', /debug              ; won't show up since LEVEL=3
mg_log, 'Informational message', /informational  ; won't show up since LEVEL=3
mg_log, 'Warning message', /warning
mg_log, 'Error message', /error
mg_log, 'Critical message', /critical

mg_log, /quit

end