Note.lua

-- Note.lua by Rouneq
-- Initially based on Write.lua by Knightly

-- Provides logging capabilities to both the MQ console and an external file

---@type OsTime
local time = require('OsTime')

--- The logging severity suppoted by Note
---@alias severityType
---| 'trace'
---| 'debug'
---| 'info'
---| 'warn'
---| 'error'
---| 'fatal'

local _newline = "\r\n"

--- Note Lua Binding
---@class Note
Note = {}

local _version = '1.0'

local logLevels = {
 ['trace'] = { level = 1, color = '\27[36m', mqcolor = '\at', abbreviation = 'TRACE', },
 ['debug'] = { level = 2, color = '\27[95m', mqcolor = '\am', abbreviation = 'DEBUG', },
 ['info'] = { level = 3, color = '\27[92m', mqcolor = '\ag', abbreviation = 'INFO' , },
 ['warn'] = { level = 4, color = '\27[93m', mqcolor = '\ay', abbreviation = 'WARN' , },
 ['error'] = { level = 5, color = '\27[31m', mqcolor = '\ao', abbreviation = 'ERROR', },
 ['fatal'] = { level = 6, color = '\27[91m', mqcolor = '\ar', abbreviation = 'FATAL', },
 ['help'] = { level = 7, color = '\27[97m', mqcolor = '\aw', abbreviation = 'HELP' , },
}

local luaReservedWords = {
 ['and'] = true,
 ['break'] = true,
 ['do'] = true,
 ['else'] = true,
 ['elseif'] = true,
 ['end'] = true,
 ['false'] = true,
 ['for'] = true,
 ['function'] = true,
 ['if'] = true,
 ['in'] = true,
 ['local'] = true,
 ['nil'] = true,
 ['not'] = true,
 ['or'] = true,
 ['repeat'] = true,
 ['return'] = true,
 ['then'] = true,
 ['true'] = true,
 ['until'] = true,
 ['while'] = true,
}

--- Indicates if log levels should be use colors
---@type boolean
Note.useColors = true
--- Indicates if a timestamp should be added to console output
---@type boolean
Note.useTimestampConsole = false
--- Indicates if a timestamp should be added to log output
---@type boolean
Note.useTimestampLog = true
--- The minimum level at which output is written to the console/log
---@type severityType
Note.logLevel = 'info'
--- A specific prefix added to each output
---@type string|function
Note.prefix = ''
--- Indicates if the output should be written to a log file
---@type boolean
Note.useOutfile = false
--- The path/name of the log file; if one is not defined it will be written to the default logs path for MQ with the name <server>_<character>.log
---@type string
Note.outfile = nil
--- Indicates if the log output should be appended to an existing file (if it exists) or a new file created
---@type boolean
Note.appendToOutfile = true
--- The minimum level at which caller info is included with the output
---@type severityType
Note.callerReportingLevel = 'trace'

local function terminate()
 local mq = package.loaded['mq']

 if mq then
 mq.exit()
 end

 os.exit()
end

local function getPath(filePath)
 if (not filePath or filePath == '') then
 return nil
 end

 return filePath:match("(.*[/\\])")
end

local function checkLogFile()
 local mq = package.loaded['mq']

 if (not Note.outfile or Note.outfile == '') then
 if (mq) then
 Note.outfile = string.format("%s\\%s_%s.log", mq.TLO.MacroQuest.Path('logs'), mq.TLO.EverQuest.Server(), mq.TLO.Me.CleanName())
 else
 Note.outfile = 'output.log'
 end
 else
 local path = getPath(Note.outfile)

 if (not path and mq) then
 Note.outfile = string.format("%s\\%s", mq.TLO.MacroQuest.Path('logs'), Note.outfile)
 end
 end
end

local function writeLog(data)
 local mode = "a"

 if (not Note.appendToOutfile) then
 mode = "w"
 end

 local file, err = io.open(Note.outfile, mode)

 if (file == nil) then
 Note.Raw('Error opening outfile: %s', err)

 return
 end

 file:write(data, "\n")
 file:close()
end

local function getColorStart(logLevel)
 if Note.useColors then
 if package.loaded['mq'] then return logLevels[logLevel].mqcolor end
 return logLevels[logLevel].color
 end

 return ''
end

local function getColorEnd()
 if Note.useColors then
 if package.loaded['mq'] then
 return '\ax'
 end

 return '\27[0m'
 end

 return ''
end

local function getCallerName()
 if (logLevels[Note.logLevel:lower()].level > logLevels[Note.callerReportingLevel].level) then
 return ''
 end

 local callName = 'unknown'
 local callerInfo = debug.getinfo(4,'Sl')

 if callerInfo and callerInfo.short_src ~= nil and callerInfo.short_src ~= '=[C]' then
 callName = string.format('%s::%s', callerInfo.short_src:match("[^\\^/]*.lua$"), callerInfo.currentline)
 end

 return string.format('(%s) ', callName)
end

local function exportstring(s)
 return string.format("%q", s)
end

local function tablePrint(data, indent)
 if not indent then indent = 0 end

 local output = "{" .. _newline
 indent = indent + 2

 for k, v in pairs(data) do
 output = output .. string.rep(" ", indent)

 if (type(k) == "number" or type(k) == "boolean") then
 output = output .. "[" .. tostring(k) .. "] = "
 elseif (type(k) == "string") then
 if (luaReservedWords[k] or tonumber(k)) then
 k = "["..exportstring(k).."]"
 end

 output = output .. k .. " = "
 end

 if (type(v) == "number" or type(v) == "boolean") then
 output = output .. tostring(v)
 elseif (type(v) == "string") then
 output = output .. "\"" .. v .. "\""
 elseif (type(v) == "table") then
 output = output .. tablePrint(v, indent + 2)
 else
 output = output .. "\"" .. tostring(v) .. "\""
 end

 output = output .. "," .. _newline
 end

 output = output .. string.rep(" ", indent - 2) .. "}"

 return output
end

local function normalizeValue(v)
 local output

 if (v == nil) then
 output = 'nil'
---@diagnostic disable-next-line: undefined-global
 elseif (v == NULL) then
 output = 'NULL'
 elseif (type(v) == "number" or type(v) == "string") then
 output = v
 elseif (type(v) == "table") then
 output = tablePrint(v)
 else
 output = tostring(v)
 end

 return output
end

local function normalizeArgs(...)
 local normalizedArgs = {}

 for i = 1, select('#', ...) do
 table.insert(normalizedArgs, normalizeValue((select(i, ...))))
 end

 return unpack(normalizedArgs)
end

local timestampPattern = "<%04d-%02d-%02d %02d:%02d:%02d.%03d> "

---@param useTimestamp boolean
local function getTimestamp(useTimestamp)
 if (useTimestamp) then
 local lt = time.GetLocalTime()

 return string.format(timestampPattern, lt.Year, lt.Month, lt.Day, lt.Hour, lt.Minute, lt.Second, lt.Milliseconds)
 end

 return ""
end

---@param prependNewline boolean
---@vararg ...
---@return string
local function formatVarargs(prependNewline, ...)
 local output = ''

 if (select('#', ...) > 0) then
 if (prependNewline) then
 output = _newline
 else
 output = ' '
 end

 output = output .. table.concat({...}, ' ')
 end

 return output
end

local function formatOutput(message, ...)
 local output

 if (type(message) == "string") then
 output = string.format(message, normalizeArgs(...))
 elseif (type(message) == "table") then
 output = tablePrint(message) .. formatVarargs(true, ...)
 else
 output = tostring(message) .. formatVarargs(false, ...)
 end

 return output
end

---@return string
local function formatHeader()
 local header = Note.prefix

 if (type(Note.prefix) == 'function') then
 header = Note.prefix()
 end

 return header --[[@as string]]
end

local function printf(format, ...)
 print(string.format(format, ...))
end

local function logf(format, ...)
 checkLogFile()

 local log = string.format(format, ...)

 writeLog(log)
end

local function writeOutput(logLevel, message, ...)
 if logLevels[Note.logLevel:lower()].level <= logLevels[logLevel].level then
 local output = formatOutput(message, ...)
 local header = formatHeader()
 local caller = getCallerName()

 printf('%s%s%s%s[%s]%s :: %s', getTimestamp(Note.useTimestampConsole), header, caller, getColorStart(logLevel), logLevels[logLevel].abbreviation, getColorEnd(), output)

 if (Note.useOutfile) then
 logf('%s%s%s[%s] :: %s', getTimestamp(Note.useTimestampLog), header, caller, logLevels[logLevel].abbreviation, output)
 end
 end
end

---Raw console output
---@param message any A message to display to the console (only); if a string, can contain formatting directives for further parameters
---@vararg any
function Note.Raw(message, ...)
 printf('%s', formatOutput(message, ...))
end

---Raw log output
---@param message any A message to display to the log (only); if a string, can contain formatting directives for further parameters
---@vararg any
function Note.RawLog(message, ...)
 logf('%s', formatOutput(message, ...))
end

---Trace-level output
---@param message any A message to display to the console (and log if configured) at a trace level; if a string, can contain formatting directives for further parameters
---@vararg any
function Note.Trace(message, ...)
 writeOutput('trace', message, ...)
end

---Debug-level output
---@param message any A message to display to the console (and log if configured) at a debug level; if a string, can contain formatting directives for further parameters
---@vararg any
function Note.Debug(message, ...)
 writeOutput('debug', message, ...)
end

---Information-level output
---@param message any A message to display to the console (and log if configured) at an informational level; if a string, can contain formatting directives for further parameters
---@vararg any
function Note.Info(message, ...)
 writeOutput('info', message, ...)
end

---Warning-level output
---@param message any A message to display to the console (and log if configured) at an warning level; if a string, can contain formatting directives for further parameters
---@vararg any
function Note.Warn(message, ...)
 writeOutput('warn', message, ...)
end

---Error-level output
---@param message any A message to display to the console (and log if configured) at an error level; if a string, can contain formatting directives for further parameters
---@vararg any
function Note.Error(message, ...)
 writeOutput('error', message, ...)
end

---Fatal-level output
---Script will terminate after writing the message
---@param message any A message to display to the console (and log if configured) at a fatal level; if a string, can contain formatting directives for further parameters
---@vararg any
function Note.Fatal(message, ...)
 writeOutput('fatal', message, ...)
 terminate()
end

---Log output
---@param message any A message to display to the log (only); if a string, can contain formatting directives for further parameters
---@vararg any
function Note.Log(message, ...)
 local header = formatHeader()
 local caller = getCallerName()

 logf('%s%s%s[%s] :: %s', getTimestamp(Note.useTimestampLog), header, caller, logLevels[Note.logLevel].abbreviation, formatOutput(message, ...))
end

return Note