logo

const class

sys::Log

sys::Obj
  sys::Log
//
// Copyright (c) 2006, Brian Frank and Andy Frank
// Licensed under the Academic Free License version 3.0
//
// History:
//   3 Jul 06  Brian Frank  Creation
//  21 Dec 07  Brian Frank  Revamp
//

**
** Log provides a simple, but standardized mechanism for logging.
**
** See `docLang::Logging` for details.
** See `docCookbook::Logging` for coding examples.
**
const class Log
{

//////////////////////////////////////////////////////////////////////////
// Factory
//////////////////////////////////////////////////////////////////////////

  **
  ** Return a list of all the active logs which have
  ** been created since system startup.
  **
  static Log[] list()

  **
  ** Find a log by name.  If the log doesn't exist and
  ** checked is false then return null, otherwise throw Err.
  **
  static Log find(Str name, Bool checked := true)

  **
  ** Find an existing log by name or if not found then
  ** create a new Log instance with the given name.  Name
  ** must be valid according to `Uri.isName` otherwise
  ** NameErr is thrown.
  **
  static Log get(Str name)

  **
  ** Create a new log by name.  If a log has already been created
  ** for the specified name then throw ArgErr.  Name must be valid
  ** according to `Uri.isName` otherwise NameErr is thrown.
  **
  new make(Str name)

//////////////////////////////////////////////////////////////////////////
// Methods
//////////////////////////////////////////////////////////////////////////

  **
  ** Return name of the log.
  **
  Str name()

  **
  ** Return name.
  **
  override Str toStr()

//////////////////////////////////////////////////////////////////////////
// Severity Level
//////////////////////////////////////////////////////////////////////////

  **
  ** The log level field defines which log entries are reported
  ** versus ignored.  Anything which equals or is more severe than
  ** the log level is logged.  Anything less severe is ignored.
  ** If the level is set to silent, then logging is disabled.
  **
  LogLevel level()

  **
  ** Set the log `level` severity.
  **
  Void setLevel(LogLevel level)

  **
  ** Return if this log is enabled for the specified level.
  **
  Bool isEnabled(LogLevel level)

  **
  ** Return if error level is enabled.
  **
  Bool isError()

  **
  ** Return if warn level is enabled.
  **
  Bool isWarn()

  **
  ** Return if info level is enabled.
  **
  Bool isInfo()

  **
  ** Return if debug level is enabled.
  **
  Bool isDebug()

//////////////////////////////////////////////////////////////////////////
// Logging
//////////////////////////////////////////////////////////////////////////

  **
  ** Generate a `LogLevel.error` log entry.
  **
  Void error(Str message, Err err := null)

  **
  ** Generate a `LogLevel.warn` log entry.
  **
  Void warn(Str message, Err err := null)

  **
  ** Generate a `LogLevel.info` log entry.
  **
  Void info(Str message, Err err := null)

  **
  ** Generate a `LogLevel.debug` log entry.
  **
  Void debug(Str message, Err err := null)

  **
  ** Publish a log entry.  The convenience methods `error`, `warn`
  ** `info`, and `debug` all route to this method for centralized
  ** handling.  The standard implementation is to call each of the
  ** installed `handlers` if the specified level is enabled.
  **
  virtual Void log(LogRecord rec)

//////////////////////////////////////////////////////////////////////////
// Handlers
//////////////////////////////////////////////////////////////////////////

  **
  ** List all the handler functions installed to process log events.
  **
  static |LogRecord rec|[] handlers()

  **
  ** Install a handler to receive callbacks on logging events.
  ** If the handler func is not immutable, then throw NotImmutableErr.
  **
  static Void addHandler(|LogRecord rec| handler)

  **
  ** Uninstall a log handler.
  **
  static Void removeHandler(|LogRecord rec| handler)

}