logo

const class

sys::Log

sys::Obj
  sys::Log
   1  //
   2  // Copyright (c) 2006, Brian Frank and Andy Frank
   3  // Licensed under the Academic Free License version 3.0
   4  //
   5  // History:
   6  //   3 Jul 06  Brian Frank  Creation
   7  //  21 Dec 07  Brian Frank  Revamp
   8  //
   9  
  10  **
  11  ** Log provides a simple, but standardized mechanism for logging.
  12  ** See `docLang::Logging` for details.
  13  **
  14  const class Log
  15  {
  16  
  17  //////////////////////////////////////////////////////////////////////////
  18  // Factory
  19  //////////////////////////////////////////////////////////////////////////
  20  
  21    **
  22    ** Return a list of all the active logs which have
  23    ** been created since system startup.
  24    **
  25    static Log[] list()
  26  
  27    **
  28    ** Find a log by name.  If the log doesn't exist and
  29    ** checked is false then return null, otherwise throw Err.
  30    **
  31    static Log find(Str name, Bool checked := true)
  32  
  33    **
  34    ** Find an existing log by name or if not found then
  35    ** create a new Log instance with the given name.  Name
  36    ** must be valid according to `Uri.isName` otherwise
  37    ** NameErr is thrown.
  38    **
  39    static Log get(Str name)
  40  
  41    **
  42    ** Create a new log by name.  If a log has already been created
  43    ** for the specified name then throw ArgErr.  Name must be valid
  44    ** according to `Uri.isName` otherwise NameErr is thrown.
  45    **
  46    new make(Str name)
  47  
  48  //////////////////////////////////////////////////////////////////////////
  49  // Methods
  50  //////////////////////////////////////////////////////////////////////////
  51  
  52    **
  53    ** Return name of the log.
  54    **
  55    Str name()
  56  
  57    **
  58    ** Return name.
  59    **
  60    override Str toStr()
  61  
  62  //////////////////////////////////////////////////////////////////////////
  63  // Severity Level
  64  //////////////////////////////////////////////////////////////////////////
  65  
  66    **
  67    ** The log level field defines which log entries are reported
  68    ** versus ignored.  Anything which equals or is more severe than
  69    ** the log level is logged.  Anything less severe is ignored.
  70    ** If the level is set to silent, then logging is disabled.
  71    **
  72    LogLevel level()
  73  
  74    **
  75    ** Set the log `level` severity.
  76    **
  77    Void setLevel(LogLevel level)
  78  
  79    **
  80    ** Return if this log is enabled for the specified level.
  81    **
  82    Bool isEnabled(LogLevel level)
  83  
  84    **
  85    ** Return if error level is enabled.
  86    **
  87    Bool isError()
  88  
  89    **
  90    ** Return if warn level is enabled.
  91    **
  92    Bool isWarn()
  93  
  94    **
  95    ** Return if info level is enabled.
  96    **
  97    Bool isInfo()
  98  
  99    **
 100    ** Return if debug level is enabled.
 101    **
 102    Bool isDebug()
 103  
 104  //////////////////////////////////////////////////////////////////////////
 105  // Logging
 106  //////////////////////////////////////////////////////////////////////////
 107  
 108    **
 109    ** Generate a `LogLevel.error` log entry.
 110    **
 111    Void error(Str message, Err err := null)
 112  
 113    **
 114    ** Generate a `LogLevel.warn` log entry.
 115    **
 116    Void warn(Str message, Err err := null)
 117  
 118    **
 119    ** Generate a `LogLevel.info` log entry.
 120    **
 121    Void info(Str message, Err err := null)
 122  
 123    **
 124    ** Generate a `LogLevel.debug` log entry.
 125    **
 126    Void debug(Str message, Err err := null)
 127  
 128    **
 129    ** Publish a log entry.  The convenience methods `error`, `warn`
 130    ** `info`, and `debug` all route to this method for centralized
 131    ** handling.  The standard implementation is to call each of the
 132    ** installed `handlers` if the specified level is enabled.
 133    **
 134    virtual Void log(LogRecord rec)
 135  
 136  //////////////////////////////////////////////////////////////////////////
 137  // Handlers
 138  //////////////////////////////////////////////////////////////////////////
 139  
 140    **
 141    ** List all the handler functions installed to process log events.
 142    **
 143    static |LogRecord rec|[] handlers()
 144  
 145    **
 146    ** Install a handler to receive callbacks on logging events.
 147    ** If the handler func is not immutable, then throw NotImmutableErr.
 148    **
 149    static Void addHandler(|LogRecord rec| handler)
 150  
 151    **
 152    ** Uninstall a log handler.
 153    **
 154    static Void removeHandler(|LogRecord rec| handler)
 155  
 156  }