Module:SimpleDebug: Difference between revisions

Module documentation[view] [edit] [history] [purge]

Contains a functions to help debug the lua modules. It allows to collect and view the values of several variables and/or points in your lua program, from a module (which is usual) or in several modules (which are required from the main module).

It is designed so that its functions are called from within the module that is to be debugged, calls that will have to be part of the code (of the module that you have designed, or that you want to improve or adapt) until you decide to delete them (when you already have determined the bug). Thus, you do not have to call any of its functions from an invoke.

Uses

One or several points to watch
Function abbreviations: w: where. n: names. v: variables. s: string.
Variables
Name	Default
tab.oneline	true	If it is false or it is true and contains nested tables, it will show a line for each item in the table and with an indent for each nested table. If it is true and it does not contain nested tables, it shows the table in a line.
tab.allidx	false	If it is true then also displays the numerical indexes of a table.
dec	-1	Spaces for the decimals: -1: It displays all required decimals. 0: No decimals. n: 1: one decimal, 2: two decimals, etc.
enabled	true	If it is false all calls to the below functions do nothing.
nohtml	false	In strings, it replaces < for ⪡ and > for ⪢.
plaintext	false	Deletes html format.
One point to watch
Functions
w (where)		where: point label.
v (...)		...: a number of variables = var1, var2...
wv (where, ...)		where: point label. ...: a number of variables = var1, var2...
nv (...)		...: a number of pairs of name-variable = name1, var1, name2, var2....
wnv (where, ...)		where: point label. ...: a number of pairs of name-variable = name1, var1, name2, var2....
Several points to watch
Variables
Name	Default
s		The string variable that holds the returned values from the next functions.
maxlines.num	100	The maxim number of lines (on calling the next functions).
maxlines.doerror	true	If it is true and maxlines.num is reached, error(s) is called.
counter	false	Adds an autoincremental number at the beginning of each call of a function.
Functions
breakline ()		Adds a break line in s.
wtos (where)		Equal to w, but the return string is stored in s.
vtos (...)		Equal to v, but the return string is stored in s.
wvtos (where, ...)		Equal to wv, but the return string is stored in s.
nvtos (...)		Equal to nv, but the return string is stored in s.
wnvtos (where, ...)		Igual a wnv, but the return string is stored in s.

Examples

One point to watch

Following the flow

local SD = require "Module:SimpleDebug"
return SD.v ('Here is reached')

returns:

Here is reached

Number of decimal places and value of a variable

local SD = require "Module:SimpleDebug"
SD.dec = 2
return SD.v (1/3)

returns:

0.33

Nohtml

local SD = require "Module:SimpleDebug"
SD.nohtml = true
return SD.v ("<b>bold</b>")

returns:

"⪡b⪢bold⪡/b⪢"

Plaintext

local SD = require "Module:SimpleDebug"
SD.plaintext = true
return SD.v ("<b>bold</b>")

returns:

"bold"

The value of several variables

local SD = require "Module:SimpleDebug"
local a = 12
local b = 'Hello'
return SD.v (a,b)

returns:

12  •  "Hello"

Non-assigned variable detection

local SD = require "Module:SimpleDebug"
local a = true
return SD.v (a,b)

returns:

true  •  nil

The value of a table

local SD = require "Module:SimpleDebug"
local a = {1, tab='a', 'b'}
return SD.v (a)

returns: { 1, "b", [tab]="a", }

local SD = require "Module:SimpleDebug"
local a = {{1,2,3},{4,5,6},{7,8,9}}
return SD.v (a)

returns:

{
  [1] = {1, 2, 3, },
  [2] = {4, 5, 6, },
  [3] = {7, 8, 9, },
} 

local SD = require "Module:SimpleDebug"
local a = {{First=1,2,3},{4,Second=5,6},{7,8,9}}
return SD.v (a)

returns:

{ 
 [1] = {2, 3, [First]=1, },
 [2] = {4, 6, [Second]=5, },
 [3] = {7, 8, 9, },
}

local SD = require "Module:SimpleDebug"
SD.tab.allidx = true
local a = {{1,2,3},{4,nil,6},{7,8,9}}
return SD.v (a)

returns:

{ 
  [1]={[1]=1, [2]=2, [3]=3, }, 
  [2]={[1]=4, [3]=6, }, 
  [3]={[1]=7, [2]=8, [3]=9, }, 
}

Usually, you implement these functions with error function:

local SD = require "Module:SimpleDebug"
local a = {{1,2,3},{4,5,6},{7,8,9}}
error (SD.v (a))

displays:

Lua error:Module:YourModule:Line:{

   [1] = {1, 2, 3, },
   [2] = {4, 5, 6, },
   [3] = {7, 8, 9, },
 }

All values of a table in multiline

local SD = require "Module:SimpleDebug"
SD.tab.oneline = false
local a = {{First=1,2,3},'Middle',{4,Second=5,6}}
return SD.v (a)

retorna:

{
 [1] = {
     [1] = 2,
     [2] = 3,
     ["First"] = 1,
   },
 [2] = "Middle",
 [3] = {
     [1] = 4,
     [2] = 6,
     ["Second"] = 5,
   },
}

The value of several variables with their name in a point

local SD = require "Module:SimpleDebug"
local a = 12
local b = 'Hello'
return SD.nv ('a',a,'b',b)

returns:

a: 12  •  b: "Hello"

Several points to watch

Following the flow

local SD = require "Module:SimpleDebug" 
local tab = {1,12,7}
function p.CheckValues ()
  local function LittleNum()
    SD.wtos ('little number')
  end
  local function BigNum(num)
    SD.wtos ('big='..num)
  end
  for i, num in ipairs(tab) do
    if num > 9 then
      BigNum(num)
    else
      LittleNum()
    end  
  end  
  error (SD.s)
end

returns:

Lua Error:Module:Your module:Line:

little number

big=12

little number.

With counter

local SD = require "Module:SimpleDebug" 
function Increm()
  local n = 0
  for i = 1, 3 do
    n = n + 2
    SD.vtos (n)
  end
end
SD.counter = true
Increm()
return SD.s

returns:

1  •  2

2  •  4

3  •  6

Monitoring of several variables

local SD = require "Module:SimpleDebug"
a = 12
b = 'Hello'
SD.vtos (1,a,b)
a = a + a
b = b..' world!'
SD.vtos ('Finally',a,b)
return SD.s

returns:

1 => 12  •  "Hello"

Finally => 24  •  "Hello world!"

local SD = require "Module:SimpleDebug"
SD.breakline ()
a = 12
b = 'Hello'
c = false
SD.nvtos (1,'a',a,'b',b,'c',c)
a = a + a
b = b..' world!'
SD.nvtos ('Finally','a',a,'b',b)
error (SD.s)

displays:

Lua error:Module:YourModule:Line:

1 => a: 12  •  b: "Hello"  •  c: false

Finally => a: 24  •  b: "Hello world!"

Variables and their presentation with conditions

local SD = require "Module:SimpleDebug"
SD.breakline()
SD.enabled = false
SD.maxlines.num = 3
local a = 'AA'
for i = 1, 10 do
  a = a + 'AA'
  if i == 3 then
    SD.enabled = true
  end
  SD.nvtos (i, string.len(a), a)
end

displays:

Lua error:Module:YourModule:Line:

3 => 8  •  "AAAAAAAA"

4 => 10  •  "AAAAAAAAAA"

5 => 12  •  "AAAAAAAAAAAA".

The above documentation is transcluded from Module:SimpleDebug/doc. (edit | history)
Editors can experiment in this module's sandbox (edit | diff) and testcases (create) pages.
Subpages of this module.

local p = {}

p.s = ''
p.tab = {
    oneline = true,
    allidx = false,
    }
p.dec = -1
p.maxlines = {
    num = 100,
    doerror = true,
    }
p.enabled = true
p.nowiki = false
p.nohtml = false
p.plaintext = false

local LinCount = 0
local vep = '  •  '

local function arrow()
    return ' => '
end

function p.breakline ()
    if p.s ~= '' then
        LinCount = LinCount + 1
    end    
    p.s = p.s..'\n\n'
    if (LinCount > p.maxlines.num) and p.maxlines.doerror then
        error (p.s,0)
    end    
end    --breakline

function CheckWhereName (wn, what)
    if wn == nil then
        return '"'..what..'" == nil'
    elseif (type(wn) == "table") then
        return 'Table as "'..what..'"!'
    else
        return wn    
    end    
end --CheckWhereName

function plain (text) --Modified from "Module:Plain text"
    if not text then return end
    text = mw.text.killMarkers(text)
        :gsub(' ', ' ') --replace nbsp spaces with regular spaces
        :gsub('<br ?/?>', ', ') --replace br with commas
        :gsub('<span.->(.-)</span>', '%1') --remove spans while keeping text inside
        :gsub('<b>(.-)</b>', '%1') --remove bold while keeping text inside
        :gsub('<i>(.-)</i>', '%1') --remove italic while keeping text inside
        :gsub('<sub>(.-)</sub>', '%1') --remove bold while keeping text inside
        :gsub('<sup>(.-)</sup>', '%1') --remove bold while keeping text inside
        :gsub('<.->.-<.->', '') --strip out remaining tags and the text inside
        :gsub('<.->', '') --remove any other tag markup
        :gsub('%[%[%s*[Ff]ile%s*:.-%]%]', '') --strip out files
        :gsub('%[%[%s*[Ii]mage%s*:.-%]%]', '') --strip out use of image:
        :gsub('%[%[%s*[Cc]ategory%s*:.-%]%]', '') --strip out categories
        :gsub('%[%[[^%]]-|', '') --strip out piped link text
        :gsub('[%[%]]', '') --then strip out remaining [ and ]
        :gsub("'''''", "") --strip out bold italic markup
        :gsub("'''?", "") --not stripping out '''' gives correct output for bolded text in quotes
        :gsub('----', '') --remove ---- lines
        :gsub("^%s+", "") --strip leading
        :gsub("%s+$", "") --and trailing spaces
        :gsub("%s+", " ") --strip redundant spaces
    return text
end --plain

function totext (text)
    if p.plaintext then
        return plain (text)
    else
        return text
    end    
end --totext

function NumToStr (N)        
    if (p.dec == -1) or (N == math.floor(N)) then
        return tostring(N)
    else
        return tostring (math.floor ((N*10^p.dec)+0.5) / (10^p.dec))
    end    
end    --NumToStr

local iniTab1Line = true
function p.containsTab (avar)
    result = false
    for k,v in pairs(avar) do
        if type(v) == 'table' then
            result = true
            break
        end    
    end
    return result
end --containsTab

function DumTab (tbl, indent)
    if not indent then indent = 1 end
    local toprint = " {\r\n"
    indent = indent + 2
    for k, v in pairs(tbl) do
        toprint = toprint..string.rep(" ", indent)
        local id = k
        if (type(k) == "string") then
            k = '"'..k..'"'
        end
        toprint = toprint.."["..k.."] = "
        if (type(v) == "number") then
            toprint = toprint..NumToStr(v)..",\r\n"
        elseif (type(v) == "string") then
            toprint = toprint.."\""..totext(v).."\",\r\n"
        elseif (type(v) == "table") then
            if iniTab1Line and (not p.containsTab (v)) then
                local wds = '{'
                for kk,vv in pairs(v) do
                    if (p.tab.allidx == true) or (type(kk) ~= 'number')  then
                        wds = wds..'['..kk..']='..var(vv)..', '
                    else    
                        wds = wds..var(vv)..', '
                    end
                end
                toprint = toprint..wds.."},\r\n"
            else    
                toprint = toprint..DumTab(v, indent + 2)..",\r\n"
            end
        else
            toprint = toprint.."\""..tostring(v).."\",\r\n"
        end
    end
    toprint = toprint..string.rep(" ", indent-2).."}"
    return toprint
end --DumTab

function var (avar)
    local EndStr = ''
    if type(avar) == 'table' then
        if #avar > 0 then
            p.s = p.s..'\r\n'
        end    
        if p.tab.oneline then
            local wds = '{ '
            for k,v in pairs(avar) do
                if (p.tab.allidx == true) or (type(k) ~= 'number')  then
                    wds = wds..'['..k..']='..var(v)..', '
                else    
                    wds = wds..var(v)..', '
                end
            end
            EndStr = wds .. '} '
        else
            EndStr = DumTab (avar)
        end    
    elseif type(avar) == 'number' then
        EndStr = NumToStr (avar)
    elseif type(avar) == 'boolean' then
        if avar == true then
            EndStr = 'true'
        else
            EndStr = 'false'
        end    
    elseif avar == nil then    
        EndStr = 'nil'
    else
        avar = totext (tostring(avar))
        if p.nohtml then
            avar = string.gsub (avar, "<", "⪡")
            avar = string.gsub (avar, ">", "⪢")
        end    
        EndStr = '"'..avar..'"'
    end
    return EndStr
end --var

function p.w (where)
    if p.enabled then
        return CheckWhereName (where, 'w')
    end    
end --w

function varx (avar)
    iniTab1Line = p.tab.oneline
    if p.tab.oneline and (type(avar) == 'table') then
        p.tab.oneline = not p.containsTab(avar)
    end
    local ss = var(avar)
    p.tab.oneline = iniTab1Line
    return ss
end --varx

function p.v (...)
    if p.enabled then
        local str = ''
        for i = 1, #arg do
            if str ~= '' then
                str = str..vep
            end    
            str = str..varx(arg[i])
        end    
        return str
    end    
end    --v

function p.wv (where, ...)
    if p.enabled then
        return CheckWhereName(where,'w')..arrow()..p.v(unpack(arg))
    end    
end    --wv

function p.nv (...)
    if p.enabled then
        if math.mod(#arg,2) ~= 0 then    
            EndStr = 'Any parameter has not a name or variable'
        else
            local s = ''
            local IsName = true
            function Concat(wds)
                if s ~= '' then
                    if IsName then
                        s = s..vep
                    else    
                        s = s..': '
                    end    
                end
                s = s..wds
            end
            for i = 1, #arg do
                if IsName then
                    Concat (CheckWhereName(arg[i],'n'))
                    IsName = false
                else    
                    Concat (varx(arg[i]))
                    IsName = true
                end    
            end
            EndStr = s
        end
        return EndStr
    end    
end --nv

function p.wnv (where, ...)
    if p.enabled then
        return CheckWhereName(where,'w')..arrow()..p.nv (unpack(arg))
    end    
end

----------

local function EnabAndBl ()
    if p.enabled and (LinCount < p.maxlines.num) then
        if p.s ~= '' then
            p.breakline ()
        end    
        return true
    else
        return false
    end
end --EnabAndBl

function p.wtos (where)
    if EnabAndBl () then
        p.s = p.s..p.w (where)
    end    
end --wtos

function p.vtos (...)
    if EnabAndBl () then
        p.s = p.s..p.v (unpack(arg))
    end    
end --vtos

function p.wvtos (where, ...)
    if EnabAndBl () then
        p.s = p.s..p.wv (where,unpack(arg))
    end    
end --wvtos

function p.nvtos (...)
    if EnabAndBl () then
        p.s = p.s..p.nv (unpack(arg))
    end    
end --nvtos

function p.wnvtos (where, ...)
    if EnabAndBl () then
        p.s = p.s..p.wnv (where, unpack(arg))
    end    
end --wnvtos

return p