NAME

       ::log - Procedures to log messages of libraries and appli­
       cations.


SYNOPSIS

       package require log ?1.0?

       ::log::levels

       ::log::lv2longform level

       ::log::lv2color level

       ::log::lv2priority level

       ::log::lv2cmd level

       ::log::lv2channel level

       ::log::lvCompare level1 level2

       ::log::lvSuppress level {suppress 1}

       ::log::lvSuppressLE level {suppress 1}

       ::log::lvIsSuppressed level

       ::log::lvCmd level cmd

       ::log::lvCmdForall cmd

       ::log::lvChannel level chan

       ::log::lvChannelForall chan

       ::log::lvColor level color

       ::log::lvColorForall color

       ::log::log level text

       ::log::logMsg text

       ::log::logError text

       ::log::Puts level text

_________________________________________________________________


DESCRIPTION

       The ::log package provides commands that  allow  libraries
       and  applications  to  selectively  log  information about


       Each message given to the log facility is associated  with
       a  level  determining  the  importance of the message. The
       user can then select which levels to log, what commands to
       use for the logging of each level and the channel to write
       the message to. The latter is relevant only if  the  stan­
       dard  command  (::log::Puts)  to  log messages provided by
       ::log is used. Apprehending the usage of this facility  in
       graphical applications, i.e. tk-based ones, it also allows
       the user to associate colors with the message levels.

       The following commands are available:

       ::log::levels
              Returns the names of all known levels, in alphabet­
              ical order.

       ::log::lv2longform level
              Converts any unique abbreviation of a level name to
              the full level name.

       ::log::lv2color level
              Converts any level name including unique  abbrevia­
              tions to the corresponding color.

       ::log::lv2priority level
              Converts  any level name including unique abbrevia­
              tions to the corresponding priority.

       ::log::lv2cmd level
              Converts any level name including unique  abbrevia­
              tions  to the command prefix used to write messages
              with that level.

       ::log::lv2channel level
              Converts any level name including unique  abbrevia­
              tions  to  the channel used by ::log::Puts to write
              messages with that level.

       ::log::lvCompare level1 level2
              Compares two  levels  (including  unique  abbrevia­
              tions) with respect to their priority. This command
              can be used by the -command option  of  lsort.  The
              result  is  one of -1, 0 or 1 or an error. A result
              of -1 signals that level1 is of less priority  than
              level2.  0  signals  that both levels have the same
              priority. 1 signals that level1 has higher priority
              than level2.

       ::log::lvSuppress level {suppress 1}
              (Un)suppresses  the  output  of messages having the
              specified level. Unique abbreviations for the level
              are allowed here too.

              (Un)suppresses  the  output  of messages having the
              specified level or one of lesser  priority.  Unique
              abbreviations for the level are allowed here too.

       ::log::lvIsSuppressed level
              Asks  the  package  whether  the specified level is
              currently suppressed. Unique abbreviations of level
              names are allowed.

       ::log::lvCmd level cmd
              Defines  for the specified level with which command
              to write the messages  having  this  level.  Unique
              abbreviations  of level names are allowed. The com­
              mand is actually a command prefix and this facility
              will  append  2  arguments  before  calling it, the
              level of the message and  the  message  itself,  in
              this order.

       ::log::lvCmdForall cmd
              Defines  for all known levels with which command to
              write the messages having this level.  The  command
              is actually a command prefix and this facility will
              append 2 arguments before calling it, the level  of
              the  message and the message itself, in this order.

       ::log::lvChannel level chan
              Defines for the specified level into which  channel
              ::log::Puts  (the standard command) shall write the
              messages having this level. Unique abbreviations of
              level  names are allowed. The command is actually a
              command prefix and  this  facility  will  append  2
              arguments  before calling it, the level of the mes­
              sage and the message itself, in this order.

       ::log::lvChannelForall chan
              Defines for all known levels with which which chan­
              nel  ::log::Puts (the standard command) shall write
              the messages having  this  level.  The  command  is
              actually  a  command  prefix and this facility will
              append 2 arguments before calling it, the level  of
              the  message and the message itself, in this order.

       ::log::lvColor level color
              Defines for the specified level the color to return
              for  it in a call to ::log::lv2color. Unique abbre­
              viations of level names are allowed.

       ::log::lvColorForall color
              Defines for all known levels the  color  to  return
              for  it in a call to ::log::lv2color. Unique abbre­
              viations of level names are allowed.

              Log a message according to the  specifications  for
              commands, channels and suppression. In other words:
              The command will do nothing if the specified  level
              is  suppressed.  If it is not suppressed the actual
              logging is delegated to the specified  command.  If
              there  is  no  command  specified for the level the
              message  won't  be  logged.  The  standard  command
              ::log::Puts  will  write the message to the channel
              specified for the given level.  If  no  channel  is
              specified  for  the  level  the  message  won't  be
              logged. Unique abbreviations  of  level  names  are
              allowed.  Errors  in the actual logging command are
              not caught, but propagated to the caller,  as  they
              may  indicate misconfigurations of the log facility
              or errors in the callers code itself.

       ::log::logMsg text
              Convenience wrapper around  ::log::log.  Equivalent
              to ::log::log info text.

       ::log::logError text
              Convenience  wrapper  around ::log::log. Equivalent
              to ::log::log error text.

       ::log::Puts level text
              The standard log command, it  writes  messages  and
              their  levels  to  user-specified channels. Assumes
              that  the  suppression  checks  were  done  by  the
              caller. Expects full level names, abbreviations are
              not allowed.


SEE ALSO


KEYWORDS

       log, log level, message level, message


Man(1) output converted with man2html