diff --git a/scripts/lua2dox.lua b/scripts/lua2dox.lua index 674b42a699..562c3829c9 100644 --- a/scripts/lua2dox.lua +++ b/scripts/lua2dox.lua @@ -51,13 +51,13 @@ The effect is that you will get the function documented, but not with the parame ]] local function class(BaseClass, ClassInitialiser) - local newClass = {} -- a new class newClass + local newClass = {} -- a new class newClass if not ClassInitialiser and type(BaseClass) == 'function' then ClassInitialiser = BaseClass BaseClass = nil elseif type(BaseClass) == 'table' then -- our new class is a shallow copy of the base class! - for i,v in pairs(BaseClass) do + for i, v in pairs(BaseClass) do newClass[i] = v end newClass._base = BaseClass @@ -70,11 +70,11 @@ local function class(BaseClass, ClassInitialiser) local classMetatable = {} classMetatable.__call = function(class_tbl, ...) local newInstance = {} - setmetatable(newInstance,newClass) + setmetatable(newInstance, newClass) --if init then -- init(newInstance,...) if class_tbl.init then - class_tbl.init(newInstance,...) + class_tbl.init(newInstance, ...) else -- make sure that any stuff from the base class is initialized! if BaseClass and BaseClass.init then @@ -104,7 +104,7 @@ local TCore_Clock = class() --! \brief get the current time function TCore_Clock.GetTimeNow() - local gettimeofday = os.gettimeofday -- luacheck: ignore 143 Accessing an undefined field of a global variable. + local gettimeofday = os.gettimeofday -- luacheck: ignore 143 Accessing an undefined field of a global variable. if gettimeofday then return gettimeofday() else @@ -113,7 +113,7 @@ function TCore_Clock.GetTimeNow() end --! \brief constructor -function TCore_Clock.init(this,T0) +function TCore_Clock.init(this, T0) if T0 then this.t0 = T0 else @@ -122,36 +122,34 @@ function TCore_Clock.init(this,T0) end --! \brief get time string -function TCore_Clock.getTimeStamp(this,T0) +function TCore_Clock.getTimeStamp(this, T0) local t0 if T0 then t0 = T0 else t0 = this.t0 end - return os.date('%c %Z',t0) + return os.date('%c %Z', t0) end - --! \brief write to stdout local function TCore_IO_write(Str) - if (Str) then + if Str then io.write(Str) end end --! \brief write to stdout local function TCore_IO_writeln(Str) - if (Str) then + if Str then io.write(Str) end - io.write("\n") + io.write('\n') end - --! \brief trims a string local function string_trim(Str) - return Str:match("^%s*(.-)%s*$") + return Str:match('^%s*(.-)%s*$') end --! \brief split a string @@ -162,24 +160,23 @@ end ---@return string[] local function string_split(Str, Pattern) local splitStr = {} - local fpat = "(.-)" .. Pattern + local fpat = '(.-)' .. Pattern local last_end = 1 - local str, e, cap = string.find(Str,fpat, 1) + local str, e, cap = string.find(Str, fpat, 1) while str do - if str ~= 1 or cap ~= "" then - table.insert(splitStr,cap) + if str ~= 1 or cap ~= '' then + table.insert(splitStr, cap) end - last_end = e+1 - str, e, cap = string.find(Str,fpat, last_end) + last_end = e + 1 + str, e, cap = string.find(Str, fpat, last_end) end if last_end <= #Str then - cap = string.sub(Str,last_end) + cap = string.sub(Str, last_end) table.insert(splitStr, cap) end return splitStr end - --! \class TCore_Commandline --! \brief reads/parses commandline local TCore_Commandline = class() @@ -192,7 +189,7 @@ function TCore_Commandline.init(this) end --! \brief get value -function TCore_Commandline.getRaw(this,Key,Default) +function TCore_Commandline.getRaw(this, Key, Default) local val = this.argv[Key] if not val then val = Default @@ -209,14 +206,14 @@ local TStream_Read = class() --! \brief get contents of file --! --! \param Filename name of file to read (or nil == stdin) -function TStream_Read.getContents(this,Filename) +function TStream_Read.getContents(this, Filename) assert(Filename) -- get lines from file -- syphon lines to our table --TCore_Debug_show_var('Filename',Filename) - local filecontents={} + local filecontents = {} for line in io.lines(Filename) do - table.insert(filecontents,line) + table.insert(filecontents, line) end if filecontents then @@ -241,7 +238,7 @@ function TStream_Read.getLine(this) this.currentLine = nil else -- get line - if this.currentLineNo<=this.contentsLen then + if this.currentLineNo <= this.contentsLen then line = this.filecontents[this.currentLineNo] this.currentLineNo = this.currentLineNo + 1 else @@ -252,13 +249,13 @@ function TStream_Read.getLine(this) end --! \brief save line fragment -function TStream_Read.ungetLine(this,LineFrag) +function TStream_Read.ungetLine(this, LineFrag) this.currentLine = LineFrag end --! \brief is it eof? function TStream_Read.eof(this) - if this.currentLine or this.currentLineNo<=this.contentsLen then + if this.currentLine or this.currentLineNo <= this.contentsLen then return false end return true @@ -273,32 +270,32 @@ function TStream_Write.init(this) end --! \brief write immediately -function TStream_Write.write(_,Str) +function TStream_Write.write(_, Str) TCore_IO_write(Str) end --! \brief write immediately -function TStream_Write.writeln(_,Str) +function TStream_Write.writeln(_, Str) TCore_IO_writeln(Str) end --! \brief write immediately -function TStream_Write.writelnComment(_,Str) +function TStream_Write.writelnComment(_, Str) TCore_IO_write('// ZZ: ') TCore_IO_writeln(Str) end --! \brief write to tail -function TStream_Write.writelnTail(this,Line) +function TStream_Write.writelnTail(this, Line) if not Line then Line = '' end - table.insert(this.tailLine,Line) + table.insert(this.tailLine, Line) end --! \brief output tail lines function TStream_Write.write_tailLines(this) - for _,line in ipairs(this.tailLine) do + for _, line in ipairs(this.tailLine) do TCore_IO_writeln(line) end TCore_IO_write('// Lua2DoX new eof') @@ -308,9 +305,9 @@ end local TLua2DoX_filter = class() --! \brief allow us to do errormessages -function TLua2DoX_filter.warning(this,Line,LineNo,Legend) +function TLua2DoX_filter.warning(this, Line, LineNo, Legend) this.outStream:writelnTail( - '//! \todo warning! ' .. Legend .. ' (@' .. LineNo .. ')"' .. Line .. '"' + '//! \todo warning! ' .. Legend .. ' (@' .. LineNo .. ')"' .. Line .. '"' ) end @@ -319,47 +316,47 @@ end --! If the string has a comment on the end, this trims it off. --! local function TString_removeCommentFromLine(Line) - local pos_comment = string.find(Line,'%-%-') + local pos_comment = string.find(Line, '%-%-') local tailComment if pos_comment then - Line = string.sub(Line,1,pos_comment-1) - tailComment = string.sub(Line,pos_comment) + Line = string.sub(Line, 1, pos_comment - 1) + tailComment = string.sub(Line, pos_comment) end - return Line,tailComment + return Line, tailComment end --! \brief get directive from magic local function getMagicDirective(Line) - local macro,tail + local macro, tail local macroStr = '[\\@]' - local pos_macro = string.find(Line,macroStr) + local pos_macro = string.find(Line, macroStr) if pos_macro then --! ....\\ macro...stuff --! ....\@ macro...stuff - local line = string.sub(Line,pos_macro+1) - local space = string.find(line,'%s+') + local line = string.sub(Line, pos_macro + 1) + local space = string.find(line, '%s+') if space then - macro = string.sub(line,1,space-1) - tail = string_trim(string.sub(line,space+1)) + macro = string.sub(line, 1, space - 1) + tail = string_trim(string.sub(line, space + 1)) else macro = line - tail = '' + tail = '' end end - return macro,tail + return macro, tail end --! \brief check comment for fn -local function checkComment4fn(Fn_magic,MagicLines) +local function checkComment4fn(Fn_magic, MagicLines) local fn_magic = Fn_magic -- TCore_IO_writeln('// checkComment4fn "' .. MagicLines .. '"') - local magicLines = string_split(MagicLines,'\n') + local magicLines = string_split(MagicLines, '\n') - local macro,tail + local macro, tail for _, line in ipairs(magicLines) do - macro,tail = getMagicDirective(line) + macro, tail = getMagicDirective(line) if macro == 'fn' then fn_magic = tail -- TCore_IO_writeln('// found fn "' .. fn_magic .. '"') @@ -371,15 +368,15 @@ local function checkComment4fn(Fn_magic,MagicLines) return fn_magic end -local types = {"number", "string", "table", "list", "boolean", "function"} +local types = { 'number', 'string', 'table', 'list', 'boolean', 'function' } --! \brief run the filter -function TLua2DoX_filter.readfile(this,AppStamp,Filename) +function TLua2DoX_filter.readfile(this, AppStamp, Filename) local inStream = TStream_Read() local outStream = TStream_Write() this.outStream = outStream -- save to this obj - if (inStream:getContents(Filename)) then + if inStream:getContents(Filename) then -- output the file local line local fn_magic -- function name/def from magic comment @@ -389,7 +386,7 @@ function TLua2DoX_filter.readfile(this,AppStamp,Filename) outStream:writelnTail('// #######################') outStream:writelnTail() - local state = '' -- luacheck: ignore 231 variable is set but never accessed. + local state = '' -- luacheck: ignore 231 variable is set but never accessed. local offset = 0 local generic = {} local l = 0 @@ -398,7 +395,7 @@ function TLua2DoX_filter.readfile(this,AppStamp,Filename) -- TCore_Debug_show_var('inStream',inStream) -- TCore_Debug_show_var('line',line ) l = l + 1 - if string.sub(line,1,2) == '--' then -- it's a comment + if string.sub(line, 1, 2) == '--' then -- it's a comment -- Allow people to write style similar to EmmyLua (since they are basically the same) -- instead of silently skipping things that start with --- if string.sub(line, 3, 3) == '@' then -- it's a magic comment @@ -414,22 +411,23 @@ function TLua2DoX_filter.readfile(this,AppStamp,Filename) local magic_split = string_split(magic, ' ') if magic_split[1] == 'param' then for _, type in ipairs(types) do - magic = magic:gsub("^param%s+([a-zA-Z_?]+)%s+.*%((" .. type .. ")%)", "param %1 %2" ) - magic = magic:gsub("^param%s+([a-zA-Z_?]+)%s+.*%((" .. type .. "|nil)%)", "param %1 %2" ) + magic = magic:gsub('^param%s+([a-zA-Z_?]+)%s+.*%((' .. type .. ')%)', 'param %1 %2') + magic = + magic:gsub('^param%s+([a-zA-Z_?]+)%s+.*%((' .. type .. '|nil)%)', 'param %1 %2') end magic_split = string_split(magic, ' ') elseif magic_split[1] == 'return' then for _, type in ipairs(types) do - magic = magic:gsub("^return%s+.*%((" .. type .. ")%)", "return %1" ) - magic = magic:gsub("^return%s+.*%((" .. type .. "|nil)%)", "return %1" ) + magic = magic:gsub('^return%s+.*%((' .. type .. ')%)', 'return %1') + magic = magic:gsub('^return%s+.*%((' .. type .. '|nil)%)', 'return %1') end magic_split = string_split(magic, ' ') end - if magic_split[1] == "generic" then - local generic_name, generic_type = line:match("@generic%s*(%w+)%s*:?%s*(.*)") - if generic_type == "" then - generic_type = "any" + if magic_split[1] == 'generic' then + local generic_name, generic_type = line:match('@generic%s*(%w+)%s*:?%s*(.*)') + if generic_type == '' then + generic_type = 'any' end generic[generic_name] = generic_type else @@ -440,9 +438,9 @@ function TLua2DoX_filter.readfile(this,AppStamp,Filename) if magic_split[type_index] then -- fix optional parameters - if magic_split[type_index] and magic_split[2]:find("%?$") then - if not magic_split[type_index]:find("nil") then - magic_split[type_index] = magic_split[type_index] .. "|nil" + if magic_split[type_index] and magic_split[2]:find('%?$') then + if not magic_split[type_index]:find('nil') then + magic_split[type_index] = magic_split[type_index] .. '|nil' end magic_split[2] = magic_split[2]:sub(1, -2) end @@ -454,42 +452,44 @@ function TLua2DoX_filter.readfile(this,AppStamp,Filename) end -- surround some types by () for _, type in ipairs(types) do - magic_split[type_index] = magic_split[type_index]:gsub("^(" .. type .. "|nil):?$", "(%1)") - magic_split[type_index] = magic_split[type_index]:gsub("^(" .. type .. "):?$", "(%1)") + magic_split[type_index] = + magic_split[type_index]:gsub('^(' .. type .. '|nil):?$', '(%1)') + magic_split[type_index] = + magic_split[type_index]:gsub('^(' .. type .. '):?$', '(%1)') end end magic = table.concat(magic_split, ' ') outStream:writeln('/// @' .. magic) - fn_magic = checkComment4fn(fn_magic,magic) + fn_magic = checkComment4fn(fn_magic, magic) end - elseif string.sub(line,3,3)=='-' then -- it's a nonmagic doc comment - local comment = string.sub(line,4) - outStream:writeln('/// '.. comment) - elseif string.sub(line,3,4)=='[[' then -- it's a long comment - line = string.sub(line,5) -- nibble head + elseif string.sub(line, 3, 3) == '-' then -- it's a nonmagic doc comment + local comment = string.sub(line, 4) + outStream:writeln('/// ' .. comment) + elseif string.sub(line, 3, 4) == '[[' then -- it's a long comment + line = string.sub(line, 5) -- nibble head local comment = '' - local closeSquare,hitend,thisComment - while (not hitend) and (not inStream:eof()) do - closeSquare = string.find(line,']]') + local closeSquare, hitend, thisComment + while not hitend and (not inStream:eof()) do + closeSquare = string.find(line, ']]') if not closeSquare then -- need to look on another line thisComment = line .. '\n' line = inStream:getLine() else - thisComment = string.sub(line,1,closeSquare-1) + thisComment = string.sub(line, 1, closeSquare - 1) hitend = true -- unget the tail of the line -- in most cases it's empty. This may make us less efficient but -- easier to program - inStream:ungetLine(string_trim(string.sub(line,closeSquare+2))) + inStream:ungetLine(string_trim(string.sub(line, closeSquare + 2))) end comment = comment .. thisComment end - if string.sub(comment,1,1)=='@' then -- it's a long magic comment + if string.sub(comment, 1, 1) == '@' then -- it's a long magic comment outStream:write('/*' .. comment .. '*/ ') - fn_magic = checkComment4fn(fn_magic,comment) + fn_magic = checkComment4fn(fn_magic, comment) else -- discard outStream:write('/* zz:' .. comment .. '*/ ') fn_magic = nil @@ -504,64 +504,67 @@ function TLua2DoX_filter.readfile(this,AppStamp,Filename) end elseif string.find(line, '^function') or string.find(line, '^local%s+function') then generic = {} - state = 'in_function' -- it's a function - local pos_fn = string.find(line,'function') + state = 'in_function' -- it's a function + local pos_fn = string.find(line, 'function') -- function -- ....v... if pos_fn then -- we've got a function local fn_type - if string.find(line,'^local%s+') then - fn_type = ''--'static ' -- static functions seem to be excluded + if string.find(line, '^local%s+') then + fn_type = '' --'static ' -- static functions seem to be excluded else fn_type = '' end - local fn = TString_removeCommentFromLine(string_trim(string.sub(line,pos_fn+8))) + local fn = TString_removeCommentFromLine(string_trim(string.sub(line, pos_fn + 8))) if fn_magic then fn = fn_magic end - if string.sub(fn,1,1)=='(' then + if string.sub(fn, 1, 1) == '(' then -- it's an anonymous function outStream:writelnComment(line) else -- fn has a name, so is interesting -- want to fix for iffy declarations - local open_paren = string.find(fn,'[%({]') + local open_paren = string.find(fn, '[%({]') if open_paren then -- we might have a missing close paren - if not string.find(fn,'%)') then + if not string.find(fn, '%)') then fn = fn .. ' ___MissingCloseParenHere___)' end end -- Big hax - if string.find(fn, ":") then + if string.find(fn, ':') then -- TODO: We need to add a first parameter of "SELF" here -- local colon_place = string.find(fn, ":") -- local name = string.sub(fn, 1, colon_place) - fn = fn:gsub(":", ".", 1) - outStream:writeln("/// @param self") + fn = fn:gsub(':', '.', 1) + outStream:writeln('/// @param self') - local paren_start = string.find(fn, "(", 1, true) - local paren_finish = string.find(fn, ")", 1, true) + local paren_start = string.find(fn, '(', 1, true) + local paren_finish = string.find(fn, ')', 1, true) -- Nothing in between the parens local comma if paren_finish == paren_start + 1 then - comma = "" + comma = '' else - comma = ", " + comma = ', ' end - fn = string.sub(fn, 1, paren_start) .. "self" .. comma .. string.sub(fn, paren_start + 1) + fn = string.sub(fn, 1, paren_start) + .. 'self' + .. comma + .. string.sub(fn, paren_start + 1) end -- add vanilla function outStream:writeln(fn_type .. 'function ' .. fn .. '{}') end else - this:warning(inStream:getLineNo(),'something weird here') + this:warning(inStream:getLineNo(), 'something weird here') end fn_magic = nil -- mustn't indavertently use it again @@ -572,8 +575,8 @@ function TLua2DoX_filter.readfile(this,AppStamp,Filename) -- fn_magic = nil -- mustn't indavertently use it again else - state = '' -- unknown - if #line>0 then -- we don't know what this line means, so just comment it out + state = '' -- unknown + if #line > 0 then -- we don't know what this line means, so just comment it out outStream:writeln('// zz: ' .. line) else outStream:writeln() -- keep this line blank @@ -601,8 +604,7 @@ function TApp.init(this) end function TApp.getRunStamp(this) - return this.name .. ' (' .. this.version .. ') ' - .. this.timestamp + return this.name .. ' (' .. this.version .. ') ' .. this.timestamp end function TApp.getVersion(this) @@ -639,8 +641,7 @@ else local filename = argv1 local filter = TLua2DoX_filter() - filter:readfile(appStamp,filename) + filter:readfile(appStamp, filename) end - --eof