123 lines
5.1 KiB
Lua
123 lines
5.1 KiB
Lua
--- For logging debug information to files.
|
|
-- @module Logger
|
|
-- @usage
|
|
-- local Logger = require('stdlib/log/logger')
|
|
-- -- or to create a logger directly:
|
|
-- local LOGGER = require('stdlib/log/logger').new(...)
|
|
-- -- and to use the same LOGGER in multiple require files make it global by removing 'local'.
|
|
|
|
local M = {_module_name = 'Logger'}
|
|
setmetatable(M, {__index = require('stdlib/core')})
|
|
|
|
local Is = require('stdlib/utils/is')
|
|
|
|
--- Creates a new logger object.
|
|
-- In debug mode, the logger writes to file immediately, otherwise the logger buffers the lines.
|
|
-- <p>The logger flushes the logged messages every 60 seconds since the last message.
|
|
-- <p>A table of @{options} may be specified when creating a logger.
|
|
-- @usage
|
|
--LOGGER = Logger.new('cool_mod_name')
|
|
--LOGGER.log("this msg will be logged!")
|
|
--
|
|
-- @usage
|
|
--LOGGER = Logger.new('cool_mod_name', 'test', true)
|
|
--LOGGER.log("this msg will be logged and written immediately in test.log!")
|
|
--
|
|
-- @usage
|
|
--LOGGER = Logger.new('cool_mod_name', 'test', true, { file_extension = data })
|
|
--LOGGER.log("this msg will be logged and written immediately in test.data!")
|
|
--
|
|
-- @tparam string mod_name [required] the name of the mod to create the logger for
|
|
-- @tparam[opt='main'] string log_name the name of the logger
|
|
-- @tparam[opt=false] boolean debug_mode toggles the debug state of logger
|
|
-- @tparam[opt={...}] options options a table with optional arguments
|
|
-- @return (<span class="types">@{Logger}</span>) the logger instance
|
|
function M.new(mod_name, log_name, debug_mode, options)
|
|
Is.Assert.String(mod_name, 'Logger must be given a mod_name as the first argument')
|
|
|
|
log_name = log_name or 'main'
|
|
options = options or {}
|
|
|
|
local Logger = {
|
|
mod_name = mod_name,
|
|
log_name = log_name,
|
|
debug_mode = debug_mode,
|
|
buffer = {},
|
|
last_written = 0,
|
|
ever_written = false
|
|
}
|
|
|
|
---
|
|
-- Used in the @{new} function for logging game ticks, specifying logfile extension, or forcing the logs to append to the end of the logfile.
|
|
-- @tfield[opt=false] boolean log_ticks whether to include the game tick timestamp in the logs
|
|
-- @tfield[opt="log"] string file_extension a string that overrides the default logfile extension
|
|
-- @tfield[opt=false] boolean force_append if true, every new message appends to the current logfile instead of creating a new one
|
|
-- @table Logger.options
|
|
Logger.options = {
|
|
log_ticks = options.log_ticks or false,
|
|
file_extension = options.file_extension or 'log',
|
|
force_append = options.force_append or false
|
|
}
|
|
|
|
Logger.file_name = Logger.mod_name .. '/' .. Logger.log_name .. '.' .. Logger.options.file_extension
|
|
Logger.ever_written = Logger.options.force_append
|
|
|
|
--- Logs a message.
|
|
-- @tparam string|table msg the message to log. @{table}s will be dumped using [serpent](https://github.com/pkulchenko/serpent) which is included in the official Factorio Lualib
|
|
-- @treturn boolean true if the message was written, false if it was queued for a later write
|
|
-- @see https://forums.factorio.com/viewtopic.php?f=25&t=23844 Debugging utilities built in to Factorio
|
|
function Logger.log(msg)
|
|
local format = string.format
|
|
if _G.game then
|
|
local tick = game.tick
|
|
local floor = math.floor
|
|
local time_s = floor(tick / 60)
|
|
local time_minutes = floor(time_s / 60)
|
|
local time_hours = floor(time_minutes / 60)
|
|
|
|
if type(msg) ~= 'string' then
|
|
msg = serpent.block(msg, {comment = false, nocode = true, sparse = true})
|
|
end
|
|
|
|
if Logger.options.log_ticks then
|
|
table.insert(Logger.buffer, format('%02d:%02d:%02d.%02d: %s\n', time_hours, time_minutes % 60, time_s % 60, tick - time_s * 60, msg))
|
|
else
|
|
table.insert(Logger.buffer, format('%02d:%02d:%02d: %s\n', time_hours, time_minutes % 60, time_s % 60, msg))
|
|
end
|
|
|
|
-- write the log every minute
|
|
if (Logger.debug_mode or (tick - Logger.last_written) > 3600) then
|
|
return Logger.write()
|
|
end
|
|
else
|
|
if _G.script then --buffer when a save is loaded but _G.game isn't available
|
|
if Logger.options.log_ticks then
|
|
table.insert(Logger.buffer, format('00:00:00:00: %s\n', msg))
|
|
else
|
|
table.insert(Logger.buffer, format('00:00:00: %s\n', msg))
|
|
end
|
|
else --log in data stage
|
|
log(format('%s/%s: %s', Logger.mod_name, Logger.log_name, msg))
|
|
end
|
|
end
|
|
return false
|
|
end
|
|
|
|
--- Writes out all buffered messages immediately.
|
|
-- @treturn boolean true if write was successful, false otherwise
|
|
function Logger.write()
|
|
if _G.game then
|
|
Logger.last_written = game.tick
|
|
game.write_file(Logger.file_name, table.concat(Logger.buffer), Logger.ever_written)
|
|
Logger.buffer = {}
|
|
Logger.ever_written = true
|
|
return true
|
|
end
|
|
return false
|
|
end
|
|
|
|
return Logger
|
|
end
|
|
|
|
return M
|