SUMMARY: MODULE | CLASS | TYPE | PROC | VAR | CONST | DETAIL: TYPE | PROC | VAR | CONST

# Logger

This module provides a very simple but still powerful abstraction for logging policy, log messages, and log targets.

It distingushes between two kinds of log messages:

Debug Messages | The target audience of debug messages are people who know about the inner workings of the program or library--that is, developers. As such, they are not for public consumption and developers have complete freedom where to output debug messages, and what to put into them.
Report Messages | Reports are intended for people who use or operate the application. Their intention is usually to report on progress of the application, provide information on interaction with the outside world, and, most importantly, to communicate failures and the cause of the problem. Report messages must be formulated in such a way that they can be understood and acted upon by non-developers.

Report logs and debug logs can be send to different targets. A typical setup might forward reports to a remote logging service, while debug logs are only written to local files. Examples for report messages: which config file is being read, whether the configuration has been processed successfully, or that an external database server has been connected to. All reports messages are duplicated into the debug log as well. This means, that access to the debug log provides all the log messages of the application, in the order in which they were generated by the application.

There are a number of issues that are not addressed by this module. The application designer has to create his own policy regarding the following issues:

Logging by Functional Units | This module does not provide and infrastructure to groups log messages by applications, components, modules, classes, or functions. By using different log handles with distinct prefix strings, the developer can group messages by functional units.
Severity Levels | Beyond the basic distinction between report and debug messages, no further message classification is build in. The reason for this is that there is no " one size fits all" severity classification. And even there is an agreed baseline, it is very hard to use it consistently across applications, third party software, different developers, and so on.
Usage of Log Handles | There is no predisposition on how log handles are used in applications, libraries, or modules. In some situations, a single log handle stored in a global public variable may be sufficient. Other designs may prefer to use separate handles for functional units.

### Import List

        IO
        Object
        Object

Class List
ChannelTarget |
Handle |
NullTarget |
Target |

Class Summary: ChannelTarget [Detail]
      +---Logger.Target
           |
           +--Logger.ChannelTarget
Inherited Fields
From Logger.Target: passOnDebug, passOnReport
Method Summary
INIT(BOOLEAN, BOOLEAN, ByteChannel)
Write(STRING, STRING)
Inherited Methods
From Logger.Target: INIT, Write

Class Summary: Handle [Detail]
      +--Logger.Handle
Field Summary
debugTarget-: Target
enableDebug-: BOOLEAN
enableReport-: BOOLEAN
prefix-: STRING
reportTarget-: Target
Method Summary
CloneTargets(STRING): Handle
Debug(STRING)
DebugBool(STRING, BOOLEAN)
DebugInt(STRING, LONGINT)
DebugLongReal(STRING, LONGREAL)
DebugObject(STRING, Object)
EnableDebug(BOOLEAN)
EnableReport(BOOLEAN)
INIT(Target, Target, STRING)
Report(STRING) Report messages are also duplicated into the debug log.
ReportBool(STRING, BOOLEAN)
ReportInt(STRING, LONGINT)
ReportLongReal(STRING, LONGREAL)
ReportObject(STRING, Object)

Class Summary: NullTarget [Detail]
      +---Logger.Target
           |
           +--Logger.NullTarget
Inherited Fields
From Logger.Target: passOnDebug, passOnReport
Method Summary
INIT()
Write(STRING, STRING)
Inherited Methods
From Logger.Target: INIT, Write

Class Summary: Target [Detail]
      +--Logger.Target
Field Summary
passOnDebug-: BOOLEAN Global flag to disable all debug output send to this target.
passOnReport-: BOOLEAN Global flag to disable all report output send to this target.
Method Summary
INIT(BOOLEAN, BOOLEAN)
Write(STRING, STRING)

Variable Summary
nullHandle-: Handle
nullTarget-: Target
stderrTarget-: Target
stdoutTarget-: Target

Constant Summary
timeStampFormat

Class Detail: ChannelTarget

Method Detail

### INIT

    PROCEDURE (lt: ChannelTarget) INIT(passOnReport: BOOLEAN;
                   passOnDebug: BOOLEAN;
                   ch: ByteChannel)

> Redefines: INIT

### Write

    PROCEDURE (lt: ChannelTarget) Write(prefix: STRING;
                    msg: STRING)

> Redefines: Write

Class Detail: Handle

Field Detail

### debugTarget

    FIELD debugTarget-: Target

### enableDebug

    FIELD enableDebug-: BOOLEAN

### enableReport

    FIELD enableReport-: BOOLEAN

### prefix

    FIELD prefix-: STRING

### reportTarget

    FIELD reportTarget-: Target

Method Detail

### CloneTargets

    PROCEDURE (lh: Handle) CloneTargets(newPrefix: STRING): Handle

### Debug

    PROCEDURE (lh: Handle) Debug(msg: STRING)

### DebugBool

    PROCEDURE (lh: Handle) DebugBool(msg: STRING;
                        x: BOOLEAN)

### DebugInt

    PROCEDURE (lh: Handle) DebugInt(msg: STRING;
                       x: LONGINT)

### DebugLongReal

    PROCEDURE (lh: Handle) DebugLongReal(msg: STRING;
                            x: LONGREAL)

### DebugObject

    PROCEDURE (lh: Handle) DebugObject(msg: STRING;
                          x: Object)

### EnableDebug

    PROCEDURE (lh: Handle) EnableDebug(enable: BOOLEAN)

### EnableReport

    PROCEDURE (lh: Handle) EnableReport(enable: BOOLEAN)

### INIT

    PROCEDURE (lh: Handle) INIT(reportTarget: Target;
                   debugTarget: Target;
                   prefix: STRING)

### Report

    PROCEDURE (lh: Handle) Report(msg: STRING)

> Report messages are also duplicated into the debug log.

### ReportBool

    PROCEDURE (lh: Handle) ReportBool(msg: STRING;
                         x: BOOLEAN)

### ReportInt

    PROCEDURE (lh: Handle) ReportInt(msg: STRING;
                        x: LONGINT)

### ReportLongReal

    PROCEDURE (lh: Handle) ReportLongReal(msg: STRING;
                             x: LONGREAL)

### ReportObject

    PROCEDURE (lh: Handle) ReportObject(msg: STRING;
                           x: Object)

Class Detail: NullTarget

Method Detail

### INIT

    PROCEDURE (lt: NullTarget) INIT()

> Redefines: INIT

### Write

    PROCEDURE (lt: NullTarget) Write(prefix: STRING;
                    msg: STRING)

> Redefines: Write

Class Detail: Target

Field Detail

### passOnDebug

    FIELD passOnDebug-: BOOLEAN

> Global flag to disable all debug output send to this target. The flag is tested by the Handle implementations.

### passOnReport

    FIELD passOnReport-: BOOLEAN

> Global flag to disable all report output send to this target. The flag is tested by the Handle implementations.

Method Detail

### INIT

    PROCEDURE (lt: Target) INIT(passOnReport: BOOLEAN;
                   passOnDebug: BOOLEAN)

### Write

    PROCEDURE (lt: Target) Write(prefix: STRING;
                    msg: STRING)

Variable Detail

### nullHandle

    VAR nullHandle-: Handle

### nullTarget

    VAR nullTarget-: Target

### stderrTarget

    VAR stderrTarget-: Target

### stdoutTarget

    VAR stdoutTarget-: Target

Constant Detail

### timeStampFormat

    CONST timeStampFormat