l0.DependencyControl.Logger¶

MoonScriptLua

Logger = require "l0.DependencyControl.Logger"

local Logger = require("l0.DependencyControl.Logger")

Logger ¶

Structured logger that writes to Aegisub's log window and optional log files.

Constructor ¶

MoonScriptLua

logger = Logger args

local logger = Logger(args)

Creates a logger, applying the given option overrides to the new instance.

param	type	description
args?	`table`	Field overrides copied onto the logger; a `usePrefix` key sets both the file and window prefix flags.

Instance methods¶

logEx ¶

MoonScriptLua

logger\logEx level, msg, insertLineFeed, prefix, indent, ...

logger:logEx(level, msg, insertLineFeed, prefix, indent, ...)

Writes a log message with explicit rendering options.

param	type	description
level?	`number`	Severity level (default: the logger's defaultLevel).
msg?	`string`\|`table`	Message, or a list of lines joined with newlines.
insertLineFeed?	`boolean`	Append a trailing newline (default true).
prefix?	`string`	Line prefix (default: the logger's prefix).
indent?	`number`	Indentation depth (default: the logger's indent).
...	`any`	Format arguments substituted into msg.

Returns:

written boolean — False if msg was empty, otherwise true.

format ¶

MoonScriptLua

logger\format msg, indent, ...

logger:format(msg, indent, ...)

Formats a message for display, substituting printf-style arguments and indenting each line after the first.

param	type	description
msg	`string`\|`table`	The message, or a list of lines joined with newlines.
indent	`number`	Indentation depth applied to every line after a line break.
...	`any`	Format arguments substituted into the message.

Returns:

msg string — The formatted message.

log ¶

MoonScriptLua

logger\log level, msg, ...

logger:log(level, msg, ...)

Logs a message at the given severity level.

param	type	description
level?	`number`\|`string`\|`table`	Severity level; when not a number, the value is taken as the message and logged at the default level.
msg?	`string`\|`table`	Message to log; taken as the first format argument when the level slot already holds the message.
...	`any`	Format arguments substituted into the message.

Returns:

written boolean — False when nothing was passed or the message was empty, otherwise true.

fatal ¶

MoonScriptLua

logger\fatal ...

logger:fatal(...)

Logs the given message at the fatal level (0).

param	type	description
...	`any`	Message and format arguments.

Returns:

written boolean — False when nothing was passed or the message was empty, otherwise true.

error ¶

MoonScriptLua

logger\error ...

logger:error(...)

Logs the given message at the error level (1).

param	type	description
...	`any`	Message and format arguments.

Returns:

written boolean — False when nothing was passed or the message was empty, otherwise true.

warn ¶

MoonScriptLua

logger\warn ...

logger:warn(...)

Logs the given message at the warning level (2).

param	type	description
...	`any`	Message and format arguments.

Returns:

written boolean — False when nothing was passed or the message was empty, otherwise true.

hint ¶

MoonScriptLua

logger\hint ...

logger:hint(...)

Logs the given message at the hint level (3).

param	type	description
...	`any`	Message and format arguments.

Returns:

written boolean — False when nothing was passed or the message was empty, otherwise true.

debug ¶

MoonScriptLua

logger\debug ...

logger:debug(...)

Logs the given message at the debug level (4).

param	type	description
...	`any`	Message and format arguments.

Returns:

written boolean — False when nothing was passed or the message was empty, otherwise true.

trace ¶

MoonScriptLua

logger\trace ...

logger:trace(...)

Logs the given message at the trace level (5).

param	type	description
...	`any`	Message and format arguments.

Returns:

written boolean — False when nothing was passed or the message was empty, otherwise true.

assert ¶

MoonScriptLua

logger\assert cond, ...

logger:assert(cond, ...)

Logs an error message when the given condition is falsy.

param	type	description
cond	`any`	Value to test for truthiness.
...	`any`	Error message and format arguments logged when cond is falsy.

Returns:

cond any — The condition and any trailing arguments, returned unchanged when truthy.

assertNotNil ¶

MoonScriptLua

logger\assertNotNil cond, ...

logger:assertNotNil(cond, ...)

Logs an error message when the given condition is nil.

param	type	description
cond	`any`	Value to test for nil.
...	`any`	Error message and format arguments logged when cond is nil.

Returns:

cond any — The condition and any trailing arguments, returned unchanged when not nil.

progress ¶

MoonScriptLua

logger\progress progress, msg, ...

logger:progress(progress, msg, ...)

Draws an in-place progress bar, filling it toward the given completion percentage.

param	type	description
progress?	`number`\|`boolean`	Completion percentage from 0 to 100; a falsy value closes the open bar and is the default.
msg?	`string`	Label drawn before the bar when it first opens (default: empty).
...	`any`	Format arguments substituted into the label.

dump ¶

MoonScriptLua

logger\dump item, ignore, level, maxDepth

logger:dump(item, ignore, level, maxDepth)

Logs a table dump (or scalar value) at the specified level.

param	type	description
item	`any`	Value to dump; tables are rendered recursively.
ignore?	`any`	Table key to omit from the dump.
level?	`number`	Log level (default: the logger's defaultLevel).
maxDepth?	`number`	Maximum table depth to recurse into.

dumpToString ¶

MoonScriptLua

logger\dumpToString item, ignore, maxDepth

logger:dumpToString(item, ignore, maxDepth)

Converts a table dump (or scalar value) to a readable string.

param	type	description
item	`any`	Value to render; tables are rendered recursively.
ignore?	`any`	Table key to omit from the dump.
maxDepth?	`number`	Maximum table depth to recurse into.

Returns:

string

trimFiles ¶

MoonScriptLua

logger\trimFiles doWipe, maxAge, maxSize, maxFiles

logger:trimFiles(doWipe, maxAge, maxSize, maxFiles)

Deletes log files that exceed the configured age, size, or count limits, keeping the newest.

param	type	description
doWipe	`boolean`	When true, delete every matching log file regardless of the limits.
maxAge?	`number`	Maximum file age in seconds before deletion (default: the logger's maxAge).
maxSize?	`number`	Maximum combined size in bytes before older files are deleted (default: the logger's maxSize).
maxFiles?	`number`	Maximum number of files to keep (default: the logger's maxFiles).

Returns:

deleted integer — Number of files removed (0 when the log directory does not exist yet).
deletedSize integer — Combined size in bytes of the removed files.
total integer — Total number of matching log files found.
totalSize integer — Combined size in bytes of all matching files.

Class methods¶

isAtLineStart ¶

MoonScriptLua

Logger.isAtLineStart!

Logger.isAtLineStart()

Whether the last message to the log stream ended with a line feed, or left the stream mid-line. Lets a caller decide whether its next output continues that open line or starts fresh.

Returns:

boolean

windowError ¶

MoonScriptLua

Logger.windowError errorMessage

Logger.windowError(errorMessage)

Displays the given error in a modal dialog with a Close button, then aborts the running script.

param	type	description
errorMessage	`string`	Message shown in the dialog.

describeType ¶

MoonScriptLua

Logger\describeType val

Logger:describeType(val)

Returns a human-readable type name for the given value.

param	type	description
val	`any`	Value whose type to describe.

Returns:

type string — The Lua type name, or " object" for a DependencyControl class instance.

Fields¶

field	type	description
defaultLevel	`integer`
maxToFileLevel	`integer`
fileBaseName	`string`
fileSubName	`string`
logDir	`string`
fileTemplate	`string`
fileMatchTemplate	`string`
prefix	`string`
toFile	`boolean`
toWindow	`boolean`
indent	`integer`
usePrefixFile	`boolean`
usePrefixWindow	`boolean`
indentStr	`string`
maxFiles	`integer`
maxAge	`integer`
maxSize	`number`