-------------------------------------------------------------------------------

--

--	tek.lib.debug

--	Written by Timm S. Mueller <tmueller at schulze-mueller.de>

--	See copyright notice in COPYRIGHT

--

--	OVERVIEW::

--	Debug library - implements debug output and debug levels:

--

--	2  || TRACE || used for tracking bugs

--	4  || INFO  || informational messages

--	5  || WARN  || something unexpected happened

--	10 || ERROR || something went wrong, e.g. resource unavailable

--	20 || FAIL  || something went wrong that can't be coped with

--

--	The default debug level is 10 {{ERROR}}. To set the debug level

--	globally, e.g.:

--			db = require "tek.lib.debug"

--			db.level = db.INFO

--

--	The default debug output stream is {{stderr}}.

--	To override it globally, e.g.:

--			db = require "tek.lib.debug"

--			db.out = io.open("logfile", "w")

--

--	FUNCTIONS::

--		- debug.console() - Enter debug console

--		- debug.dump() - Dump a table recursively

--		- debug.error() - Print a text in the {{ERROR}} debug level

--		- debug.execute() - Execute a function in the specified debug level

--		- debug.fail() - Print a text in the {{FAIL}} debug level

--		- debug.info() - Print a text in the {{INFO}} debug level

--		- debug.print() - Print a text in the specified debug level

--		- debug.stacktrace() - Print a stacktrace in the specified debug level

--		- debug.trace() - Print a text in the {{TRACE}} debug level

--		- debug.warn() - Print a text in the {{WARN}} debug level

--

-------------------------------------------------------------------------------

local debug = require "debug"

local getinfo = debug.getinfo

local stderr = io.stderr

local pairs = pairs

local select = select

local time = os.time

local tonumber = tonumber

local tostring = tostring

local traceback = debug.traceback

local type = type

local unpack = unpack

module "tek.lib.debug"

_VERSION = "Debug 4.1"

-- symbolic:

TRACE = 2

INFO = 4

WARN = 5

ERROR = 10

FAIL = 20

-- global defaults:

level = INFO

out = stderr

wrout = function(...) out:write(...) end

-------------------------------------------------------------------------------

--	print(lvl, msg, ...): Prints formatted text if the global debug level

--	is less or equal the specified level.

-------------------------------------------------------------------------------

function print(lvl, msg, ...)

	if level and lvl >= level then

		local t = getinfo(3, "lS")

		local arg = { }

		for i = 1, select('#', ...) do

			local v = select(i, ...)

			arg[i] = v and type(v) ~= "number" and tostring(v) or v or 0

		end

		wrout(("(%02d %d %s:%d) " .. msg):format(lvl,

			time(), t.short_src, t.currentline, unpack(arg)) .. "\n")

	end

end

-------------------------------------------------------------------------------

--	execute(lvl, func, ...): Executes the specified function if the global

--	debug library is less or equal the specified level.

-------------------------------------------------------------------------------

function execute(lvl, func, ...)

	if level and lvl >= level then

		return func(...)

	end

end

-------------------------------------------------------------------------------

--	trace(msg, ...): Prints formatted debug info with {{TRACE}} level

-------------------------------------------------------------------------------

function trace(msg, ...) print(2, msg, ...) end

-------------------------------------------------------------------------------

--	info(msg, ...): Prints formatted debug info with {{INFO}} level

-------------------------------------------------------------------------------

function info(msg, ...) print(4, msg, ...) end

-------------------------------------------------------------------------------

--	warn(msg, ...): Prints formatted debug info with {{WARN}} level

-------------------------------------------------------------------------------

function warn(msg, ...) print(5, msg, ...) end

-------------------------------------------------------------------------------

--	error(msg, ...): Prints formatted debug info with {{ERROR}} level

-------------------------------------------------------------------------------

function error(msg, ...) print(10, msg, ...) end

-------------------------------------------------------------------------------

--	fail(msg, ...): Prints formatted debug info with {{FAIL}} level

-------------------------------------------------------------------------------

function fail(msg, ...) print(20, msg, ...) end

-------------------------------------------------------------------------------

--	stacktrace(debuglevel, stacklevel): Prints a stacktrace starting at

--	the function of the given {{level}} on the stack (excluding the

--	{{stracktrace}} function itself) if the global debug level is less

--	or equal the specified {{debuglevel}}.

-------------------------------------------------------------------------------

function stacktrace(lvl, level)

	print(lvl, traceback("", level or 1 + 1))

end

-------------------------------------------------------------------------------

--	console(): Enter the debug console.

-------------------------------------------------------------------------------

function console()

	stderr:write('Entering the debug console.\n')

	stderr:write('To redirect the output, e.g.:\n')

	stderr:write('  tek.lib.debug.out = io.open("logfile", "w")\n')

	stderr:write('To dump a table, e.g.:\n')

	stderr:write('  tek.lib.debug.dump(app)\n')

	stderr:write('Use "cont" to continue.\n')

	debug.debug()

end

-------------------------------------------------------------------------------

--	dump(table): Dump a table as Lua source using {{out}} as the output

--	stream. Cyclic references are silently dropped.

-------------------------------------------------------------------------------

local function encodenonascii(c)

	return ("\\%03d"):format(c:byte())

end

local function encode(s)

	return s:gsub('([%z\001-\031\092"])', encodenonascii)

end

local function dumpr(tab, indent, outfunc, saved)

	saved[tab] = tab

	local is = ("\t"):rep(indent)

	for key, val in pairs(tab) do

		if not saved[val] then

			outfunc(is)

			local t = type(key)

			if t == "number" or t == "boolean" then

				outfunc('[' .. tostring(key) .. '] = ')

			elseif t == "string" then

				if key:match("[^%a_]") then

					outfunc('["' .. encode(key) .. '"] = ')

				else

					outfunc(key .. ' = ')

				end

			else

				outfunc('["' .. tostring(key) .. '"] = ')

			end

			t = type(val)

			if t == "table" then

				outfunc('{\n')

				dumpr(val, indent + 1, outfunc, saved)

				outfunc(is .. '},\n')

			elseif t == "string" then

				outfunc('"' .. encode(val) .. '",\n')

			elseif t == "number" or t == "boolean" then

				outfunc(tostring(val) .. ',\n')

			else

				outfunc('"' .. tostring(val) .. '",\n')

			end

		end

	end

end

function dump(tab, outf)

	dumpr(tab, 0, outf or wrout, { })

end