Moved lib/libLog.lua to lib/dtutils/log.lua. Rewrote most of it to make it more configurable and easier to use. Updated doc format to a fixed list of fields. Did away with the comment blocks and just relying on the libdoc comments. Update doc tools to use new formats. Moved dtutils/extensions.lua to dtutils/string.lua. Pulled dtutils/processor.lua back for now since there is no context for it. Removed unneeded functions and cleaned up others.
This commit is contained in:
Bill Ferguson
291
lib/dtutils/log.lua
Normal file
291
lib/dtutils/log.lua
Normal file
@@ -0,0 +1,291 @@
|
||||
|
||||
local dtutils_log = {}
|
||||
|
||||
dtutils_log.libdoc = {
|
||||
Name = [[dtutils.log]],
|
||||
Synopsis = [[darktable lua logging library]],
|
||||
Usage = [[local log = require "lib/dtutils.log"]],
|
||||
Description = [[log provides a multi-level logging solution for use with
|
||||
the darktable lua scripts. With this library you can leave log messages
|
||||
scattered through out your code and only turn them on as necessary.]],
|
||||
Return_Value = [[log - library - the darktable lua logging functions]],
|
||||
Limitations = [[]],
|
||||
Example = [[local log = require "lib/dtutils.log"
|
||||
|
||||
local cur_level = log.log_level()
|
||||
log.log_level(log.warn)
|
||||
|
||||
print out warning, error and success messages as code is running
|
||||
|
||||
log.log_level(debug)
|
||||
|
||||
print out debugging messages too because this isnt working
|
||||
|
||||
log.log_level(info)
|
||||
|
||||
I want to make sure this is working ok
|
||||
|
||||
log.log_level(cur_level)
|
||||
|
||||
reset the logging level back to normal]],
|
||||
See_Also = [[]],
|
||||
Reference = [[]],
|
||||
License = [[This program is free software: you can redistribute it and/or modify
|
||||
it under the terms of the GNU General Public License as published by
|
||||
the Free Software Foundation; either version 3 of the License, or
|
||||
(at your option) any later version.
|
||||
|
||||
This program is distributed in the hope that it will be useful,
|
||||
but WITHOUT ANY WARRANTY; without even the implied warranty of
|
||||
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
||||
GNU General Public License for more details.
|
||||
|
||||
You should have received a copy of the GNU General Public License
|
||||
along with this program. If not, see <http://www.gnu.org/licenses/>.]],
|
||||
Copyright = [[Copyright (C) 2016 Bill Ferguson <wpferguson@gmail.com>.]],
|
||||
functions = {}
|
||||
}
|
||||
|
||||
local dt = require "darktable"
|
||||
local dt_print_error = dt.print_error
|
||||
-- work around until dt.print_log()
|
||||
local dt_print_log = dt.print_error
|
||||
local dt_print = dt.print
|
||||
|
||||
-- set the default log levels
|
||||
|
||||
dtutils_log.debug = {
|
||||
label = "DEBUG:",
|
||||
enabled = false,
|
||||
engine = dt_print_log,
|
||||
level = 1,
|
||||
}
|
||||
dtutils_log.info = {
|
||||
label = "INFO:",
|
||||
enable = false,
|
||||
engine = dt_print_log,
|
||||
level = 2,
|
||||
}
|
||||
dtutils_log.warn = {
|
||||
label = "WARN:",
|
||||
enabled = false,
|
||||
engine = dt_print_log,
|
||||
level = 3,
|
||||
}
|
||||
dtutils_log.error = {
|
||||
label = "ERROR:",
|
||||
enabled = true,
|
||||
engine = dt_print_error,
|
||||
level = 4,
|
||||
}
|
||||
dtutils_log.success = {
|
||||
label = "SUCCESS:",
|
||||
enabled = true,
|
||||
engine = dt_print_log,
|
||||
level = 5,
|
||||
}
|
||||
dtutils_log.screen = {
|
||||
label = "",
|
||||
enabled = true,
|
||||
engine = dt_print,
|
||||
level = 9,
|
||||
}
|
||||
dtutils_log.always = {
|
||||
label = "",
|
||||
enabled = true,
|
||||
engine = dt_print_log,
|
||||
level = 9,
|
||||
}
|
||||
dtutils_log.critical = {
|
||||
label = "CRITICAL:",
|
||||
enabled = true,
|
||||
engine = print,
|
||||
level = 9,
|
||||
}
|
||||
|
||||
dtutils_log.libdoc.functions["caller"] = {
|
||||
Name = [[caller]],
|
||||
Synopsis = [[get the name and line number of the calling routine]],
|
||||
Usage = [[local log = require "lib/dtutils.log"
|
||||
|
||||
result = log.caller(level)
|
||||
level - number - the number of stack levels to go down to retrieve the caller routine information]],
|
||||
Description = [[caller gets the name and line number of the calling routine and returns it]],
|
||||
Return_Value = [[result - string - the name and line number of the calling function or 'callback: ' if the attempt to get the
|
||||
caller returns nil]],
|
||||
Limitations = [[]],
|
||||
Example = [[]],
|
||||
See_Also = [[]],
|
||||
Reference = [[]],
|
||||
License = [[]],
|
||||
Copyright = [[]],
|
||||
}
|
||||
|
||||
function dtutils_log.caller(level)
|
||||
local name = debug.getinfo(level).name
|
||||
local lineno = nil
|
||||
local source = nil
|
||||
if name then
|
||||
lineno = debug.getinfo(level).currentline
|
||||
-- returns the path to the file prefixed with @
|
||||
source = debug.getinfo(level).source
|
||||
-- we just need the filename, so grab it from the string
|
||||
-- Thanks, Tobias Jakobs :-)
|
||||
source = string.match(source, "@.-([^\\/]-%.?[^%.\\/]*)$")
|
||||
return name .. ": " .. source .. ": " .. lineno .. ":"
|
||||
else
|
||||
return "callback:"
|
||||
end
|
||||
end
|
||||
|
||||
dtutils_log.libdoc.functions["msg"] = {
|
||||
Name = [[msg]],
|
||||
Synopsis = [[print a log message]],
|
||||
Usage = [[local log = require "lib/log"
|
||||
|
||||
log.msg(level, ...)
|
||||
level - table - the type of message, one of:
|
||||
log.debug - debugging messages
|
||||
log.info - informational messages
|
||||
log.warn - warning messages
|
||||
log.error - error messages
|
||||
log.success - success messages
|
||||
log.always - an internal message for debugging
|
||||
log.screen - output 1 line of text to the screen
|
||||
log.critical - print a critical message to the console
|
||||
|
||||
... - string(s) - the message to print, which could be a comma separated set of strings]],
|
||||
Description = [[msg checks the level to see if it is enabled, then prints the level type and message if it is.
|
||||
Messages are output using the engine configured in each log level.]],
|
||||
Return_Value = [[]],
|
||||
Limitations = [[If you use log.msg in a callback, the name of the calling routine can't be determined. A solution
|
||||
is to include some means of reference such as the name of the callback as an argument, i.e.
|
||||
|
||||
log.msg(log.debug, "libPlugin.format_combobox:", "value is " .. self.value)
|
||||
|
||||
which would result in
|
||||
|
||||
DEBUG: callback: libPlugin.format_combobox: value is JPEG]],
|
||||
Example = [[]],
|
||||
See_Also = [[]],
|
||||
Reference = [[]],
|
||||
License = [[]],
|
||||
Copyright = [[]],
|
||||
}
|
||||
|
||||
function dtutils_log.msg(level, ...)
|
||||
if level.enabled then
|
||||
local args = {...}
|
||||
local call_level = 3
|
||||
if level == dtutils_log.always then
|
||||
call_level = args[1]
|
||||
table.remove(args, 1)
|
||||
end
|
||||
local log_msg = level.label
|
||||
if level.engine ~= dt_screen and call_level ~= 0 then
|
||||
log_msg = log_msg .. dtutils_log.caller(call_level) .. " "
|
||||
elseif log_msg:len() > 2 then
|
||||
log_msg = log_msg .. " "
|
||||
end
|
||||
for i = 1,#args do
|
||||
log_msg = log_msg .. tostring(args[i]) .. " "
|
||||
end
|
||||
level.engine(log_msg)
|
||||
end
|
||||
end
|
||||
|
||||
dtutils_log.libdoc.functions["log_level"] = {
|
||||
Name = [[log_level]],
|
||||
Synopsis = [[get or set the log level]],
|
||||
Usage = [[local log = require "lib/log"
|
||||
|
||||
local result = log.log_level(...)
|
||||
... - arguments - if none is supplied, then the current log level is returned as one of:
|
||||
log.debug, log.info, log.warn, log.error, log.success. If one of log.debug, log.info, log.warn,
|
||||
log.error, or log.success is supplied as the argument then the log level is set to that value. All
|
||||
log levels greater than or equal in value will be enabled. Any levels of lesser value will be disabled.]],
|
||||
Description = [[log_level gets and sets the logging level. When called with no arguments the current log level
|
||||
is returned as one of log.debug, log.info, log.warn, log.error, or log.success. When called with one of log.debug,
|
||||
log.info, log.warn, log.error or log.success then the log level is set. When setting the log level all levels
|
||||
equal or greater are enabled and any of lesser value are disabled. See the example.]],
|
||||
Return_Value = [[result - the log level, one of log.debug, log.info, log.warn, log.error or log.success]],
|
||||
Limitations = [[]],
|
||||
Example = [[Assume that the current log level is log.error. Calling log.log_level() will return log.error.
|
||||
Calling log.log_level(log.info) will leave log.debug disabled, and enable log.info, log.warn, log.error and
|
||||
log.success. log.info will be returned as the log_level.]],
|
||||
See_Also = [[]],
|
||||
Reference = [[]],
|
||||
License = [[]],
|
||||
Copyright = [[]],
|
||||
}
|
||||
|
||||
function dtutils_log.log_level(...)
|
||||
local levels = {"debug", "info", "warn", "error", "success"}
|
||||
local args = {...}
|
||||
local log_level = nil
|
||||
if #args > 0 then
|
||||
log_level = args[1]
|
||||
if log_level == dtutils_log.critical or
|
||||
log_level == dtutils_log.screen or
|
||||
log_level == dtutils_log.always then
|
||||
-- these aren't valid for setting levels
|
||||
return nil
|
||||
else
|
||||
for _,v in ipairs(levels) do
|
||||
if dtutils_log[v].level >= log_level.level then
|
||||
dtutils_log[v].enabled = true
|
||||
else
|
||||
dtutils_log[v].enabled = false
|
||||
end
|
||||
end
|
||||
end
|
||||
else
|
||||
for _,v in ipairs(levels) do
|
||||
if dtutils_log[v].enabled == true then
|
||||
log_level = dtutils_log[v]
|
||||
end
|
||||
end
|
||||
end
|
||||
return log_level
|
||||
end
|
||||
|
||||
dtutils_log.libdoc.functions["engine"] = {
|
||||
Name = [[engine]],
|
||||
Synopsis = [[get and set the output engine]],
|
||||
Usage = [[local log = require "lib/dtutils.log"
|
||||
|
||||
result = log.engine(level, ...)
|
||||
level - table - the log level to get or set the engine for, one of log.debug, log.info, log.warn, log.error
|
||||
log.success, log.always, log.screen, log.critical
|
||||
... - function - the output function, one of dt.print, dt.print_error, dt.print_log, print
|
||||
if not function is included, the current engine is returned for the specified log level]],
|
||||
Description = [[engine returns the output engine for the specified log level if a second argument is not
|
||||
supplied. If a function is supplied as the second argment, then the output engine for the specified log level
|
||||
is set to that.]],
|
||||
Return_Value = [[result - function - the current output engine]],
|
||||
Limitations = [[]],
|
||||
Example = [[]],
|
||||
See_Also = [[]],
|
||||
Reference = [[]],
|
||||
License = [[]],
|
||||
Copyright = [[]],
|
||||
}
|
||||
|
||||
function dtutils_log.print_engine(level, ...)
|
||||
local engines = {"dt_print", "dt_print_error", "dt_print_log", "print"}
|
||||
local args = {...}
|
||||
local cur_engine = ""
|
||||
if #args == 0 then
|
||||
cur_engine = level.engine
|
||||
else
|
||||
for _,v in ipairs(engines) do
|
||||
if args[1] == v then
|
||||
level.engine = args[1]
|
||||
cur_engine = level.engine
|
||||
end
|
||||
end
|
||||
end
|
||||
return cur_engine
|
||||
end
|
||||
|
||||
return dtutils_log
|
||||
Reference in New Issue
Block a user