## log - Logging module

### Module Description

The log module implements a software logging and tracing module. The module uses 6 different log events, from low to high: trace, debug, info, warning, error and fatal. All log events will generate a log message. Only the fatal log event will do an abort. A log message shows the date and time, the log event and the actual message. The log events can be skipped during compilation and suppressed during execution. This is done by setting the log level with the log-level word. All log events that are equal or higher then this level will be compiled c.q. accepted. All events can be skipped by setting log.none to the log level. A log message can be sent to one of the four so called appenders. The default appender is the console. This appender is also used if one of the file appenders is not able to write to a file. The second appender is a normal text file. The third type appender is a rolling file appender. This appender writes a number of log messages to the first file, then moves to the next file and writes again a number of log messages, and so on, until the number of files is reached. Then the appender starts again with the first file. The calling word provides the base filename for the rolling filename. The logging module appends ".1", ".2" and so on for the different filenames. The last appender is the callback appender. With this appender the calling module can process the messages by its own. The stack notation for the callback word is: [ c-addr u -- ]

### Module Words

#### Log events

log.trace ( -- n )
  the trace event
log.debug ( -- n )
  the debug event
log.info ( -- n )
  the info event
log.warning ( -- n )
  the warning event
log.error ( -- n )
  the error event
log.fatal ( -- n )
  the fatal event
log.none ( -- n )
  disable all events

#### Appender words

log-to-rolling ( c-addr u n1 n2 -- )
  Start logging to rolling files, with names starting with c-addr u, maximum n1 files and n2 entries in one file
log-to-file ( fileid -- )
  Start logging to the file
log-to-callback ( xt -- )
  Start logging to the xt callback
log-to-console ( -- )
  Start logging to the console

#### Log settings words

log-from-level ( n -- )
  Skip and suppress all events below level n
log-stack-depth ( n -- )
  Append max n top stack elements to the log message
log-with-time&date ( flag -- )
  Set if the time&date should start the log message

#### Log word

do-log ( c-addr u n -- )
  Log the message c-addr u with event n

#### Parsing log words

fatal" ( "ccc<quote>" -- )
  Log a fatal message
error" ( "ccc<quote>" -- )
  Log an error message
warning" ( "ccc<quote>" -- )
  Log a warning message
info" ( "ccc<quote>" -- )
  Log an info message
debug" ( "ccc<quote>" -- )
  Log a debug message
trace" ( "ccc<quote>" -- )
  Log a trace message

### Examples

    include ffl/log.fs

    .( Logging to the console:) cr

    log-to-console

    warning" Warning message"

    log.error log-from-level          \ Log only errors and higher

    warning" Skip warning message"

    error" Error message"

    log.trace log-from-level          \ Log all events

    .( Logging to file "log.tmp" ) cr

    s" log.tmp" w/o create-file 0= [IF]
      dup log-to-file

      trace" Trace message"

      info" Info message"

      close-file drop
    [ELSE]
      drop
      .( Error: could not create "log.tmp" ) cr
    [THEN]

    .( Logging to rolling files: log.1 log.2 and log.3, 5 entries per file .." ) cr

    s" log" 3 5 log-to-rolling

    3 log-stack-depth            \ Log also the stack contents, maximum 3 values

    : do-18logs
      18 0 DO
        info" Infos message via rolling files"
      LOOP
    ;

    23 56                        \ Put some example values on the stack for the logger

    do-18logs                    \ Generate 18 log messages in the rolling files

    2drop

    .( Logging to callback ) cr

    : callback ( c-addr u -- )
      ." Logging:" type cr       \ Callback shows the message on the console
    ;

    ' callback log-to-callback

    0 log-stack-depth            \ Stop logging the stack contents

    error" Error message via callback"

    debug" Debug message via callback"

generated 03-Jun-2010 by ofcfrth-0.10.0