Provides a logging framework for Lazarus applications.

LazLogger.pas provides logging facilities to write message to a file or stdout device. Messages can be logged plain, or enclosed in begin/end like blocks, adding indent to all messages between to points (blocks can be nested). It also has the ability to filter groups of messages.

It can read the command line and environment to find the desired filename. By default it looks for a --debug-log= argument on the command line or "appname"_debuglog in the system environment.

If no log name is found StdOut is used.

The easiest method is to use the unit and put "DebugLn"/ "DbgOut" / "DebugLnEnter"/ "DebugLnExit" in your code. This works without any further setup.

This file is part of the LazUtils package.

Alias for the PLazLoggerLogGroup type in the LazLoggerBase unit.
Writes a message to the log.
Writes a message to the log.

Writes the text to the log. Does not append a new line. The Argument can be:

- One or more string(s)
- An open array of const: All values are converted to string and joined
- A single string and open array of const: Will be passed to Format
- Any of the above with a PLazLoggerLogGroup as filter

This is a forwarder to the log TLazLogger object. See there for details.

GetDebugLogger SetDebugLogger
Writes a message to the log.

Writes the text to the log. Does append a new line.

The Argument can be:

- One or more string
- An open array of const: All values are converted to string and joined
- A single string and open array of const: Will be passed to Format
- Any of the above with a PLazLoggerLogGroup as filter

This is a forwarder to the log TLazLogger object. See there for details.

GetDebugLogger SetDebugLogger
Writes a message to the log.

Writes the text to the log. Does append a new line. Increases the current intend.

The Argument can be:

- One or more string
- An open array of const: All values are converted to string and joined
- A single string and open array of const: Will be passed to Format
- Any of the above with a PLazLoggerLogGroup as filter

This is a forwarder to the log TLazLogger object. See there for details.

GetDebugLogger SetDebugLogger
Writes a message to the log.

Writes the text to the log. Does append a new line. Increases the current indentation level.

The Argument can be:

- One or more string
- An open array of const: All values are converted to string and joined
- A single string and open array of const: Will be passed to Format
- Any of the above with a PLazLoggerLogGroup as filter
- This is a forwarder to the log TLazLogger object. See there for details.

GetDebugLogger SetDebugLogger
Create a text representation for the specified value.

Create a text representation for the specified value. Does not produce a log output.

Represents a file or device handle for a logger class instance.

Provides functionality to write messages to a log file. The file is represented by a Text member stored internally. TLazLoggerFileHandle allows filtering and changing indent level.

TLazLoggerFileHandle can parse options from command line for log filename and filter settings.

An application can subclass the logger handle to provide additional functionality.

Used in the implementation of the TLazLoggerFile class.

Constructor for the class instance.
Create sets the default values for members and properties in the class instance.
Destructor for the class instance.

Calls the inherited destructor on entry. Ensures that the Text handle to LogName is closed when it is in use. Sets the value in ActiveLogText to Nil.

Opens the output handle for the logger when CloseLogFileBetweenWrites is False.

Calls a private method to ensure that a Text handle is allocated for the output destination. No actions are performed when:

- ActiveLogText has already been assigned.
- Previous access to the output handle has failed.
- LogName is an empty string ('') and UseStdOut is set to False.

To use an output file, set LogName to a valid file path and name which allows write access prior to calling OpenFile.

To use the stdout device, set LogName to an empty string and UseStdOut to True prior to calling OpenFile.

RTL routines like Assign, Append, or Rewrite are called to associate the Text handle for the logger and to establish the FileMode for write access. On successful completion of the method, ActiveLogText is updated with the TextRec for the file name or stdout device in Output. If an exception occurs, it is caught and an error message is written to the stdout device.

Closes the output handle for the logger.
Resets the value in WriteFailedCount to 0 (zero).
Writes the specified log message to the output handle for the class instance.

WriteToFile ensures that the OnWidgetsetDbgOut routine is signalled (when assigned for the unit) to perform the write operation. If the message is handled in OnWidgetsetDbgOut, no additional actions are performed in the method.

Otherwise, the output handle is opened when not already assigned. If ActiveLogText is unassigned after trying to open the output handle, no additional actions are performed in the method.

The RTL Write routine is called to write the value in S to the output handle for the TextRec. The Flush routine is called when needed for the platform.

When CloseLogFileBetweenWrites is set to True, the output handle is closed and released.

If an exception occurs during output to the handle, it is caught and the values in WriteFailedCount and LastWriteFailed are updated to reflect the error condition.

Log message written in the method.
Logger class instance passed to the OnWidgetsetDbgOut handler.
Writes the specified log message to the output handle for the class instance.

WriteLnToFile ensures that the OnWidgetSetDebugLn routine is signalled (when assigned for the unit) to perform the write operation. If the message is handled in OnWidgetSetDebugLn, no additional actions are performed in the method.

Otherwise, the output handle is opened when not already assigned. If ActiveLogText is unassigned after trying to open the output handle, no additional actions are performed in the method.

The RTL WriteLn routine is called to write the value in S to the output handle for the TextRec.

When CloseLogFileBetweenWrites is set to True, the output handle is closed and released.

If an exception occurs during output to the handle, it is caught and the values in WriteFailedCount and LastWriteFailed are updated to reflect the error condition.

Log message written in the method.
Logger class instance passed to the OnWidgetSetDebugLn handler.
The name of the log file.
This can be set by the application. Alternatively it can be determined according to ParamForLogFileName and EnvironmentForLogFileName
Enables writing to STDOUT, if LogName is not set.
Enable opening and closing the log for each write.
Indicates whether logger output is directed to a File or the STDOUT device.

The property contains a value from the TLazLoggerWriteTarget enumeration.

lwtNone
  A handle or output destination has not been or cannot be determined.
lwtTextFile
  The output destination is a Text instance representing the file in LogName.
lwtStdOut
  The output destination is the STDOUT device.

Contains the Text instance for the output destination, or Nil when unassigned.
Indicates the cumulative number of failed write operations for the output handle.

WriteFailedCount is updated in methods which perform write operations to the output handle, such WriteToFile and WriteLnToFile. Its value is reset using the ResetWriteFailedCounter method.

Indicates if the last write attempt encountered an exception or otherwise failed.

The value is updated in methods which perform write operations to the output handle, like WriteToFile and WriteLnToFIle.

Performs file operations using a critical section.

TLazLoggerFileHandleThreadSave is a TLazLoggerFileHandle descendant which implements a threaded file logger. TLazLoggerFileHandleThreadSave uses a TRTLCriticalSection class instance to lock the log file during file output operations. Requires that DoOpenFile is called by the main application thread. Otherwise the filehandle may get closed.

Constructor for the class instance.

Initializes the critical section used to protect write access to the handle for the class instance. Calls the inherited constructor prior to exiting from the method.

Destructor for the class instance.

Finalizes the critical section used to protect write access to the handle for the class instance. Calls the inherited destructor prior to exiting from the method.

Re-implements the method to use a critical section to protect write access to the handle for the class instance.
Re-implements the method to use a critical section to protect write access to the handle for the class instance.
Represents a File handle for logger operations queued in the main thread.

TLazLoggerFileHandleMainThread is a TLazLoggerFileHandle descendant which implements a file-based logger which queues file operations for the main thread in an application.

Constructor for the class instance.

Initializes the critical section used to protect write access to the handle for the class instance. Calls the inherited constructor prior to exiting from the method.

Destructor for the class instance.

Ensures the event handler used to write log messages in the main thread is removed from the thread manager. Calls the inherited destructor, and finalizes the critical section used to protect write access to the handle for the class instance.

Re-implements the method used to write log messages in the main thread for the application.
Re-implements the method used to write log messages in the main thread for the application.
Implements a logger which uses a file or the STDOUT device as the destination for log messages.

TLazLoggerFile is a TLazLoggerWithGroupParam descendant. It provides properties and methods needed to implement the handle-based logger class. It also provides event handlers used to perform DbgOut and DebugLn write events (when assigned).

TLazLoggerFileHandle provides a FileHandle property (TLazLoggerFileHandle instance) to represent the handle for the output device or file.

Various methods from ancestor classes are overridden to perform actions needed to format log messages for the destination.

Use LogName to specify a file name where log messages are stored.

Use the UseStdOut property to indicate that the STDOUT device is used (instead of a file name) to output the log messages for the class instance. Set LogName to an empty string ('') to ensure that STDOUT is used.

Use CloseLogFileBetweenWrites to force the output handle to be closed and released when a write operation is completed. This is the default behavior for the WinCE platform.

Performs actions to initialize the file-based logger class instance.
Performs actions to finalize the file-based logger class instance.
Increases the indentation (nesting) level for messages written using the logger.
Decreases the indentation (nesting) level for messages written using the logger.
Performs actions needed to create an indentation spacing string for the current nesting level.

Calls CreateIndent to prepare the string prefix inserted at the start of a log message.

Creates a string with spaces characters used as the prefix for log messages.
Gets the value for the indexed BlockHandler property.
Value for the indexed BlockHandler property.
Ordinal position for the TLazLoggerBlockHandler value in the property.
Removes all block handlers for the logger class created using AddBlockHandler.

Calls RemoveBlockHandler to remove each of the block handlers from the internal list of handlers, and releases the references to the block handler class instances.

Performs actions needed to implement the DbgOut method for the logger class type.

DoDbgOut is overridden in TLazLoggerFile to ensure that log message formatting and event handlers are used when the DbgOut method is called. Space characters are inserted at the start of the log message to reflect the current nesting level for the logger class. For multi-threaded usage, an internal critical section is used to protect the current nesting level while preparing the indentation spaces for the message.

The OnDbgOut event handler is signalled (when assigned) to allow user-specified actions to be performed when writing the log message. If the write operation is handled in the event handler, no additional actions are performed in the method. Otherwise, the WriteToFile method in FileHandle is called to write the log message to the device or file.

Log message formatted and written in the method.
Performs actions needed to implement the DebugLn method for the logger class type.
TLazLoggerFileHandle instance representing the file or device where log messages are written.

Resources are allocated for the member when the FileHandle property is accessed. At run-time, a TLazLoggerFileHandleMainThread instance is created and assigned to the member for the property.

Read and write access to some property values in the logger class instance are re-directed to the corresponding properties in FileHandle, including:

- LogName
- UseStdOut
- CloseLogFileBetweenWrites

Methods in TLazLoggerFile may call the corresponding methods in FileHandle which implement the methods, including:

- DoInit
- DoFinish
- DoDbgOut
- DoDebugLn
- DoDebugLnStack

Constructor for the class instance.

Creates allocates and initializes resources for the block handler list and a critical section used in the class instance. The default value for CurrentIndentLevel is set to 0.

Create ensures that ParamForLogFileName and EnvironmentForLogFileName are set to the default values for the platform or widgetset. For WinCE, that requires the properties to be set empty strings ('').

Destructor for the class instance.

Destroy is the overridden destructor for the class instance. It ensures that all block handlers assigned to the class instance are removed from the internal list and released. The inherited destructor is called to finalize the logger class instance.

Destory frees resources allocated for the FileHandle property, the internal list used for block handlers, and the critical section used to protect access to the current nesting level.

Implements object persistence for the TLazLoggerFile class type.

Assign is an overridden method used to implement object persistence for the TLazLoggerFile class type.

Src is the TLazLogger instance with the values copied into the current class instance. The inherited method is called to handle group parameters and block handlers assigned in Src.

When Src is derived from TLazLoggerFile, the following property values are also copied:

- CloseLogFileBetweenWrites
- EnvironmentForLogFileName
- LogName
- ParamForLogFileName
- UseStdOut
- OnDbgOut
- OnDebugLn

These property values are not copied when Src is not derived from TLazLoggerFile.

TLazLogger instance with values copies in the method.
Gets the current indentation (nesting) level for messages written using the logger.

Indicates the number of space characters prepended to a message to format the output for the logger class.

Current nesting level for the logger class instance.
Name of the command line parameter that has the log file name for the class instance.

ParamForLogFileName is a command line parameter that may contain the name for the log file (if not already set). For example: --debug-log=/path/to/filename.ext.

If LogName is empty and ParamForLogFileName has been assigned, the command line will be checked for a parameter with the specified name. LogName will be set to the file name in the parameter, if found. The default value for the property is '--debug-log='. Please note that the dashes and equal sign must be present.

Name of the environment variable with the log file name for the class instance.

If LogName is empty and con not be found from ParamForLogFileName, then the environment variable specified will be checked. LogName will be set, if found.

An * character will be replaced with the value from param(0) (the name for the application).

The default value for the property is: '*_debuglog'.

Event handler signalled to write a full line in the log (DebugLn, DebugLnEnter or DebugLnExit).

OnDebugLn allows user-specified actions to be performed when writing a log message. Arguments passed to the event handler identify the log message and the logger class instance used for the operation. A Handled variable parameter is also provided that can be set to True to prevent the default action (writing to log) from being performed in the DoDebugLn method.

Event handler signalled to write a log message (DbgOut).

OnDbgOut allows user-specified actions to be performed when writing a log message. Arguments passed to the event handler identify the log message and the logger class instance used for the operation. A Handled variable parameter is also provided that can be set to True to prevent the default action (writing to log) from being performed in the DoDbgOut method.

Adds the specified block handler to the internal list of block handlers for the logger.
Block handler added to the internal list of block handlers.
Removes the specified block handler from the internal list of block handlers.
Block handler removed from the internal list of block handlers.
Gets the number of block handlers in the internal list.
Number of block handler instances in the internal list.
The qualified name for the log file where log messages are written.

The property value can be set by the application. Alternatively, it can be determined using ParamForLogFileName or EnvironmentForLogFileName.

Enables writing to STDOUT when LogName has not been assigned.
Enables opening and closing the output handle for the logger following each write operation.
Gets the value for the DebugLogger property.
Value for the DebugLogger property.
Sets the value for the DebugLogger property.
New value for the DebugLogger property.
Contains the class instance for the file-based logger.

DebugLogger is a TLazLoggerFile property with the class instance for the logger used to write its output to a file.