Utils.Class.Logger

Overview

The Utils.Class.Logger module is a Lua class designed to facilitate logging in Wezterm configurations. It provides a structured and flexible logging system that can output messages to Wezterm's debug overlay, making it easier to track and debug your configurations.

Whether logging is enabled or not is controlled by instance but, more importantly it is also controlled globally by the wezterm.GLOBAL.enable_logging variable. This is unset (nil) by default to allow the user to have more control. The use of the global variable makes it possible to disable/enable logging from the overlay.

The logging level is controlled globally with the wezterm.GLOBAL.log_level variable, also unset by default. There are four accepted log levels:

local levels = { DEBUG = 0, INFO = 1, WARN = 2, ERROR = 3 }

This means that setting wezterm.GLOBAL.log_level = "DEBUG" is the same thing as writing wezterm.GLOBAL.log_level = 0, etc.

Any DEBUG level logs will be logged with wezterm.log_info() since Wezterm does not support DEBUG level logging natively.

Usage

local Logger = require "utils.class.logger"
local log = Logger:new "ExampleLogger"

-- Logging messages with different levels
log:debug("This is a debug message: %s", "Debug details")
log:info("This is an info message: %s", "Info details")
log:warn("This is a warning message: %s", "Warning details")
log:error("This is an error message: %s", "Error details")

Features

• Flexible Logging Levels: Supports multiple logging levels (DEBUG, INFO, WARN, ERROR) to control the verbosity of the log output.
• Stringification: Automatically converts data types to strings for logging, making it easy to log complex objects.
• Conditional Logging: Allows enabling or disabling logging globally or per instance.
• Integration with Wezterm: Outputs logs directly to Wezterm's debug overlay.

Class Structure

The Utils.Class.Logger class provides a structured way to manage logging with different levels and formats, integrating seamlessly with Wezterm's debugging tools.

Log Levels

The class supports the following log levels:

• DEBUG: Detailed information, typically of interest only when diagnosing problems.
• INFO: Informational messages that highlight the progress of the application.
• WARN: Potentially harmful situations.
• ERROR: Error events that might still allow the application to continue running.

Methods

:new(identifier?, enabled?)

Creates a new Utils.Class.Logger instance.

Parameters:

• identifier [string] (optional): Identifier that will be printed in brackets before the message. Default is "Logger".
• enabled [boolean] (optional): Whether to enable logging or not. Defaults to true if not specified.

Returns:

• instance [Utils.Class.Logger] - new class instance.

Example:

local logger = Logger:new("MyLogger")

:log(level, message, ...)

Logs the given string to the Wezterm's debug overlay. The message can be either a simple string or a format string. The latter must only use %s placeholders since the function already takes care of stringifing any non-string value.

Parameters:

• level [string|integer] - Log level.
• message [string] - Log message or format string.
• ... [any] - additional arguments to format into the message.

Example:

log:log("INFO", "This is an informational message: %s", "Details here")

:debug(message, ...)

Logs a debug level message. The message can be either a simple string or a format string. The latter must only use %s placeholders since the function already takes care of stringifing any non-string value.

Parameters:

• message [string] - Log message or format string.
• ... [any] - additional arguments to format into the message.

Example:

log:debug("Debugging value: %s", some_value)

:info(message, ...)

Logs an informational level message. The message can be either a simple string or a format string. The latter must only use %s placeholders since the function already takes care of stringifing any non-string value.

Parameters:

• message [string] - Log message or format string.
• ... [any] - additional arguments to format into the message.

Example:

log:info("Information: %s", some_info)

:warn(message, ...)

Logs a warning level message. The message can be either a simple string or a format string. The latter must only use %s placeholders since the function already takes care of stringifing any non-string value.

Parameters:

• message [string] - Log message or format string.
• ... [any] - additional arguments to format into the message.

Example:

log:warn("Warning: %s", some_warning)

:error(message, ...)

Logs an error level message. The message can be either a simple string or a format string. The latter must only use %s placeholders since the function already takes care of stringifing any non-string value.

Parameters:

• message [string] - Log message or format string.
• ... [any] - additional arguments to format into the message.

Example:

log:error("Error occurred: %s", error_details)