diff options
Diffstat (limited to 'Master/texmf-dist/scripts/lua2dox')
| -rwxr-xr-x | Master/texmf-dist/scripts/lua2dox/lua2dox.lua | 973 | ||||
| -rwxr-xr-x | Master/texmf-dist/scripts/lua2dox/lua2dox_filter (renamed from Master/texmf-dist/scripts/lua2dox/lua2dox_lua) | 0 |
2 files changed, 509 insertions, 464 deletions
diff --git a/Master/texmf-dist/scripts/lua2dox/lua2dox.lua b/Master/texmf-dist/scripts/lua2dox/lua2dox.lua index 9249baac9cd..7aaf75f795b 100755 --- a/Master/texmf-dist/scripts/lua2dox/lua2dox.lua +++ b/Master/texmf-dist/scripts/lua2dox/lua2dox.lua @@ -17,7 +17,6 @@ -- Free Software Foundation, Inc., -- -- 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. -- ----------------------------------------------------------------------------]] - --[[! \file \brief a hack lua2dox converter @@ -25,177 +24,220 @@ --[[! \mainpage - + + Introduction + ------------ A hack lua2dox converter - Version 0.1 + Version 0.2 This lets us make Doxygen output some documentation to let us develop this code. - - It is partially cribbed from the functionality of lua2dox + + It is partially cribbed from the functionality of lua2dox (http://search.cpan.org/~alec/Doxygen-Lua-0.02/lib/Doxygen/Lua.pm). Found on CPAN when looking for something else; kinda handy. - + Improved from lua2dox to make the doxygen output more friendly. Also it runs faster in lua rather than Perl. - + Because this Perl based system is called "lua2dox"., I have decided to add ".lua" to the name to keep the two separate. + + Running + ------- - 0. Ensure doxygen is installed on your system and that you are familiar with its use. - Best is to try to make and document some simple C/C++/PHP to see what it produces. - - 1. Run "lua2dox_lua -g" to create a default Doxyfile. - - Then alter it to let it recognise lua. Add the two following lines: - - FILE_PATTERNS = *.lua - + <ol> + <li> Ensure doxygen is installed on your system and that you are familiar with its use. + Best is to try to make and document some simple C/C++/PHP to see what it produces. + You can experiment with the enclosed example code. + + <li> Run "doxygen -g" to create a default Doxyfile. + + Then alter it to let it recognise lua. Add the two following lines: + + \code{.bash} + FILE_PATTERNS = *.lua + FILTER_PATTERNS = *.lua=lua2dox_filter + \endcode + + + Either add them to the end or find the appropriate entry in Doxyfile. - Either add them to the end or find the appropriate entry in Doxyfile. - - 2. When Doxyfile is edited run as "lua2dox_lua" - - When reading source with classes multiple passes are needed. - Each pass generates a list of member functions (as a file) that were found on this pass. - This list is read in on the next pass. - If the class+methods haven't changed this time then you only need to run it once, else run twice. - - The core function reads the input file (filename or stdin) and outputs some pseudo C-ish language. - It only has to be good enough for doxygen to see it as legal. - Therefore our lua interpreter is fairly limited, but "good enough". - - One limitation is that each line is treated separately (except for long comments). - The implication is that class and function declarations must be on the same line. - Some functions can have their parameter lists extended over multiple lines to make it look neat. - Managing this where there are also some comments is a bit more coding than I want to do at this stage, - so it will probably not document accurately if we do do this. - - However I have put in a hack that will insert the "missing" close paren. - The effect is that you will get the function documented, but not with the parameter list you might expect. - - Installation: + There are other lines that you might like to alter, but see futher documentation for details. + + <li> When Doxyfile is edited run "doxygen" + + The core function reads the input file (filename or stdin) and outputs some pseudo C-ish language. + It only has to be good enough for doxygen to see it as legal. + Therefore our lua interpreter is fairly limited, but "good enough". + + One limitation is that each line is treated separately (except for long comments). + The implication is that class and function declarations must be on the same line. + Some functions can have their parameter lists extended over multiple lines to make it look neat. + Managing this where there are also some comments is a bit more coding than I want to do at this stage, + so it will probably not document accurately if we do do this. + + However I have put in a hack that will insert the "missing" close paren. + The effect is that you will get the function documented, but not with the parameter list you might expect. + </ol> + Installation + ------------ + Here for linux or unix-like, for any other OS you need to refer to other documentation. + + This file is "lua2dox.lua". It gets called by "lua2dox_filter"(bash). + Somewhere in your path (e.g. "~/bin" or "/usr/local/bin") put a link to "lua2dox_filter". - This file is "lua2dox.lua". It gets called by "lua2dox_lua". - Somewhere in your path (e.g. "~/bin" or "/usr/local/bin") put two links to "lua2dox_lua". - Names to use are "lua2dox_lua" and "lua2dox_filter". + Documentation + ------------- - Call it as "lua2dox_lua" and the filter that gets called by doxygen is "lua2dox_filter". + Read the external documentation that should be part of this package. + For example look for the "README" and some .PDFs. ]] -- we won't use our library code, so this becomes more portable -local TConfig_config={ - ['LUA2DOX_COMMENTARY_FILE_IN']='./killme_lua2dox.methods' - ,['LUA2DOX_COMMENTARY_FILE_OUT']='./killme_lua2dox.methods.out' - } - ---! \brief Gets a config val -local function TConfig_get(Key,Default) - local val = TConfig_config[Key] - if not val then - val = Default +-- require 'elijah_fix_require' +-- require 'elijah_class' +-- +--! \brief ``declare'' as class +--! +--! use as: +--! \code{.lua} +--! TWibble = class() +--! function TWibble.init(this,Str) +--! this.str = Str +--! -- more stuff here +--! end +--! \endcode +--! +function class(BaseClass, ClassInitialiser) + 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 + newClass[i] = v + end + newClass._base = BaseClass end - return val + -- the class will be the metatable for all its newInstanceects, + -- and they will look up their methods in it. + newClass.__index = newClass + + -- expose a constructor which can be called by <classname>(<args>) + local classMetatable = {} + classMetatable.__call = + function(class_tbl, ...) + local newInstance = {} + setmetatable(newInstance,newClass) + --if init then + -- init(newInstance,...) + if class_tbl.init then + class_tbl.init(newInstance,...) + else + -- make sure that any stuff from the base class is initialized! + if BaseClass and BaseClass.init then + BaseClass.init(newInstance, ...) + end + end + return newInstance + end + newClass.init = ClassInitialiser + newClass.is_a = + function(this, klass) + local thisMetatable = getmetatable(this) + while thisMetatable do + if thisMetatable == klass then + return true + end + thisMetatable = thisMetatable._base + end + return false + end + setmetatable(newClass, classMetatable) + return newClass end ---! \brief sets a config val -local function TConfig_set(Key,Val) - TConfig_config[Key] = Val -end +-- require 'elijah_clock' ---! \brief write to stdout ---! ---! writes Str (if not nil) -local function TIO_write(Str) - if (Str) then - io.write(Str) - end -end +--! \class TCore_Clock +--! \brief a clock +TCore_Clock = class() ---! \brief write to stdout ---! ---! writelns Str (if not nil) and then an eoln. -local function TIO_writeln(Str) - if (Str) then - io.write(Str) +--! \brief get the current time +function TCore_Clock.GetTimeNow() + if os.gettimeofday then + return os.gettimeofday() + else + return os.time() end - io.write("\n") end ---! \brief show error to stdout ---! ---! writelns Str (if not nil) and then an eoln. -local function TIO_showError(Err,Str) - local err = Err - if not err then - err = 1 +--! \brief constructor +function TCore_Clock.init(this,T0) + if T0 then + this.t0 = T0 + else + this.t0 = TCore_Clock.GetTimeNow() end - - TIO_write('Error (' .. err .. '):') - TIO_writeln(Str) - return err end ---! \brief run system command -local function TOS_system(Cmd) - local errno,str - local rtn = os.execute(Cmd) - if not (rtn==0) then - errno = rtn - str = 'an error occured' +--! \brief get time string +function TCore_Clock.getTimeStamp(this,T0) + local t0 + if T0 then + t0 = T0 + else + t0 = this.t0 end - return errno,str + return os.date('%c %Z',t0) end ---! \brief does file exist? -local function TOS_fileExists(Filename) - local fh = io.open(Filename,'r') - if fh~=nil then - fh:close() - return true + +--require 'elijah_io' + +--! \class TCore_IO +--! \brief io to console +--! +--! pseudo class (no methods, just to keep documentation tidy) +TCore_IO = class() +-- +--! \brief write to stdout +function TCore_IO_write(Str) + if (Str) then + io.write(Str) end - return false end ---! \brief get the current time -local function TClock_GetTimeNow() - if os.gettimeofday then - return os.gettimeofday() - else - return os.time() +--! \brief write to stdout +function TCore_IO_writeln(Str) + if (Str) then + io.write(Str) end + io.write("\n") end ---! \brief get a timestamp ---! ---! not strictly necessary here but lets us put a timestamp on the end of the output stream. ---! Note that doxygen won't read this, and being off the end of the true file length (num lines), ---! it will have no effect. ---! However it lets us check the output file tail when debugging. ---! -local function TClock_getTimeStamp() - local now = TClock_GetTimeNow() - local fraction_secs = now - math.floor(now) - return os.date('%c %Z',now) .. ':' .. fraction_secs -end ---! \brief trims a string from both ends -local function TString_trim(Str) +--require 'elijah_string' + +--! \brief trims a string +function string_trim(Str) return Str:match("^%s*(.-)%s*$") end --! \brief split a string ---! +--! --! \param Str --! \param Pattern --! \returns table of string fragments -local function TString_split(Str, Pattern) +function string_split(Str, Pattern) local splitStr = {} local fpat = "(.-)" .. Pattern local last_end = 1 @@ -214,405 +256,408 @@ local function TString_split(Str, Pattern) return splitStr end ---! \brief trim comment off end of string ---! ---! If the string has a comment on the end, this trims it off. ---! -local function TString_removeCommentFromLine(Line) - local pos_comment = string.find(Line,'%-%-') - if pos_comment then - Line = string.sub(Line,1,pos_comment-1) - end - return Line -end - -local TClassList_methods = {} ---! \brief get methods -local function TClassList_method_get(Klass) - return TClassList_methods[Klass] -end - ---! \brief add a method to list of known methods -local function TClassList_method_add(Klass,Method) - local classRec = TClassList_methods[Klass] - if not classRec then - TClassList_methods[Klass] = {} - classRec = TClassList_methods[Klass] - end - table.insert(classRec,Method) -end +--require 'elijah_commandline' -local TCommentary_fh +--! \class TCore_Commandline +--! \brief reads/parses commandline +TCore_Commandline = class() ---! \brief write to output file -local function TCommentary_writeln(Str) - if TCommentary_fh then - TCommentary_fh:write(Str .. '\n') - end +--! \brief constructor +function TCore_Commandline.init(this) + this.argv = arg + this.parsed = {} + this.params = {} end -local TCommentary_fileID ---! \brief open the commentary save file -local function TCommentary_open(Filename,InputLuaFilename) - TCommentary_fileID = '"' .. InputLuaFilename .. '" : ' .. TClock_getTimeStamp() - TCommentary_fh = io.open(Filename,'a+') - if TCommentary_fh then - TCommentary_writeln('// opened:' .. TCommentary_fileID) +--! \brief get value +function TCore_Commandline.getRaw(this,Key,Default) + local val = this.argv[Key] + if not val then + val = Default end + return val end ---! \brief close the methods save file -local function TCommentary_close() - if TCommentary_fh then - TCommentary_writeln('// closed: ' .. TCommentary_fileID) - TCommentary_fh:close() - TCommentary_fh = nil - end -end ---! \brief read stuff from save file -local function TCommentary_readFileContents(Filename) - if TOS_fileExists(Filename) then - local klass,method,dot - local cmd,colon - local k,v,equals +--require 'elijah_debug' + +------------------------------- +--! \brief file buffer +--! +--! an input file buffer +TStream_Read = class() + +--! \brief get contents of file +--! +--! \param Filename name of file to read (or nil == stdin) +function TStream_Read.getContents(this,Filename) + -- get lines from file + local filecontents + if Filename then + -- syphon lines to our table + --TCore_Debug_show_var('Filename',Filename) + filecontents={} for line in io.lines(Filename) do - if string.sub(line,1,2)=='//' then - -- it's a comment - else - colon = string.find(line,':') - if colon then - cmd = string.sub(line,1,colon) - line = string.sub(line,colon+1) - else - cmd = nil - end - if (cmd == 'method:') then - dot = string.find(line,'%.') - klass = string.sub(line,1,dot-1) - method = string.sub(line,dot+1) - TClassList_method_add(klass,method) - elseif(cmd == 'set:') then - equals = string.find(line,'=') - if equals then - k = string.sub(line,1,equals-1) - v = string.sub(line,equals+1) - TConfig_set(k,v) - else - TConfig_set(line,true) - end - else -- ignore - TIO_write('/* bad command:"' .. line .. '" */') - end - end + table.insert(filecontents,line) end else - TIO_write('/* file "' .. Filename .. '" don\'t exist */') + -- get stuff from stdin as a long string (with crlfs etc) + filecontents=io.read('*a') + -- make it a table of lines + filecontents = TString_split(filecontents,'[\n]') -- note this only works for unix files. + Filename = 'stdin' + end + + if filecontents then + this.filecontents = filecontents + this.contentsLen = #filecontents + this.currentLineNo = 1 end + + return filecontents end ---! \brief method to save file -local function TCommentary_addMethod(Klass,Method) - if TCommentary_fh then - if Klass and Method then - if string.find(Klass,'%.') or string.find(Method,'%.') then - -- iffy, so we discard it - else - TCommentary_writeln('method:' .. Klass .. '.' .. Method) - end +--! \brief get lineno +function TStream_Read.getLineNo(this) + return this.currentLineNo +end + +--! \brief get a line +function TStream_Read.getLine(this) + local line + if this.currentLine then + line = this.currentLine + this.currentLine = nil + else + -- get line + if this.currentLineNo<=this.contentsLen then + line = this.filecontents[this.currentLineNo] + this.currentLineNo = this.currentLineNo + 1 + else + line = '' end end + return line end ---! \brief output line to stream ---! ---! Wraps IO_writeln() -local function TIO_out2stream(Line) - TIO_writeln(Line) +--! \brief save line fragment +function TStream_Read.ungetLine(this,LineFrag) + this.currentLine = LineFrag end ---! \brief suppress line -local function TIO_out2stream_commented(Line,Prefix,Suffix) - local line = Line - if (not Prefix) then - Prefix='' +--! \brief is it eof? +function TStream_Read.eof(this) + if this.currentLine or this.currentLineNo<=this.contentsLen then + return false end - line = Prefix .. ':' .. line - - if (Suffix) then - line = line .. Suffix - end - TIO_out2stream('// D' .. line) + return true +end + +--! \brief output stream +TStream_Write = class() + +--! \brief constructor +function TStream_Write.init(this) + this.tailLine = {} +end + +--! \brief write immediately +function TStream_Write.write(this,Str) + TCore_IO_write(Str) end +--! \brief write immediately +function TStream_Write.writeln(this,Str) + TCore_IO_writeln(Str) +end -TCommandline_argv = {} ---! \brief setup/parse the commandline -local function TCommandline_setup() - local argv1 =arg[1] - if not argv1 then - argv1 = 'base' +--! \brief write immediately +function TStream_Write.writelnComment(this,Str) + TCore_IO_write('// ZZ: ') + TCore_IO_writeln(Str) +end + +--! \brief write to tail +function TStream_Write.writelnTail(this,Line) + if not Line then + Line = '' end - TCommandline_argv_appname = argv1 - - local i=2 - local argvi=1 - while (argvi) do - argvi = arg[i] - if argvi then - TCommandline_argv[i-1] = argvi - i = i + 1 - end + table.insert(this.tailLine,Line) +end + +--! \brief outout tail lines +function TStream_Write.write_tailLines(this) + for k,line in ipairs(this.tailLine) do + TCore_IO_writeln(line) end + TCore_IO_write('// Lua2DoX new eof') +end + +--! \brief input filter +TLua2DoX_filter = class() + +--! \brief allow us to do errormessages +function TLua2DoX_filter.warning(this,Line,LineNo,Legend) + this.outStream:writelnTail( + '//! \todo warning! ' .. Legend .. ' (@' .. LineNo .. ')"' .. Line .. '"' + ) end ---! setup the commandline now -TCommandline_setup() ---! \brief get commandline args -local function TCommandline_getargv() - return TCommandline_argv +--! \brief trim comment off end of string +--! +--! 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 tailComment + if pos_comment then + Line = string.sub(Line,1,pos_comment-1) + tailComment = string.sub(Line,pos_comment) + end + return Line,tailComment end ---! \brief get appname -local function TApp_get_appname() - return TCommandline_argv_appname +--! \brief get directive from magic +local function getMagicDirective(Line) + local macro,tail + local 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+') + if space then + macro = string.sub(line,1,space-1) + tail = string_trim(string.sub(line,space+1)) + else + macro = line + tail = '' + end + end + return macro,tail end ---! \brief hack converter from lua to a pseudoC-ish language for doxygen ---! ---! This is a hack to make lua readable to doxygen. ---! ---! It works well enough to document functions/methods and classes, but not assignments. ---! Our pseudo-C gets confused if we allow assginments to be shown. ---! Because these are less interesting than class/functions/methods I have decided to ---! live with this limitation. ---! -local function TApp_lua2dox(FileContents) +--! \brief check comment for fn +local function checkComment4fn(Fn_magic,MagicLines) + local fn_magic = Fn_magic +-- TCore_IO_writeln('// checkComment4fn "' .. MagicLines .. '"') + + local magicLines = string_split(MagicLines,'\n') + + local macro,tail + + for k,line in ipairs(magicLines) do + macro,tail = getMagicDirective(line) + if macro == 'fn' then + fn_magic = tail + -- TCore_IO_writeln('// found fn "' .. fn_magic .. '"') + else + --TCore_IO_writeln('// not found fn "' .. line .. '"') + end + end + + return fn_magic +end +--! \brief run the filter +function TLua2DoX_filter.readfile(this,AppStamp,Filename) local err - local lines = FileContents - local maxi=#lines - local i = 1 - local line,head - while not err and (i<=maxi) do - line = TString_trim(lines[i]) - if #line==0 then - TIO_out2stream() - elseif string.sub(line,1,2)=='--' then - -- it's a comment of some kind - if string.sub(line,1,3)=='--!' then - -- it's a magic comment - TIO_out2stream('//!' .. string.sub(line,4)) - elseif string.sub(line,1,4)=='--[[' then - -- it's a multiline comment - -- read lines to end of comment - local hitend - local comment = '' - line = string.sub(line,5) --.. sep - while not err and (i<maxi) and not hitend do - comment = comment .. line .. '\n' - line = lines[i+1] - --if (string.sub(TString_trim(line),1,2)==']]') then - if (string.find(line,'\]\]')) then - local pos_close = string.find(line,'\]\]') - comment = comment .. string.sub(line,1,pos_close-1) - hitend=true + local inStream = TStream_Read() + local outStream = TStream_Write() + this.outStream = outStream -- save to this obj + + if (inStream:getContents(Filename)) then + -- output the file + local line + local fn_magic -- function name/def from magic comment + + outStream:writelnTail('// #######################') + outStream:writelnTail('// app run:' .. AppStamp) + outStream:writelnTail('// #######################') + outStream:writelnTail() + + while not (err or inStream:eof()) do + line = string_trim(inStream:getLine()) +-- TCore_Debug_show_var('inStream',inStream) +-- TCore_Debug_show_var('line',line ) + if string.sub(line,1,2)=='--' then -- its a comment + if string.sub(line,3,3)=='!' then -- it's a magic comment + local magic = string.sub(line,4) + outStream:writeln('//!' .. magic) + fn_magic = checkComment4fn(fn_magic,magic) + 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 err) and (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) + 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))) + end + comment = comment .. thisComment + end + if string.sub(comment,1,1)=='!' then -- it's a long magic comment + outStream:write('/*' .. comment .. '*/ ') + fn_magic = checkComment4fn(fn_magic,comment) + else -- discard + outStream:write('/* zz:' .. comment .. '*/ ') + fn_magic = nil end - i = i + 1 - end - -- got long comment - if string.sub(comment,1,1)=='!' then - TIO_out2stream('/*' .. comment .. '*/') else - TIO_out2stream('/* (longcomment):' .. comment .. '*/') + outStream:writeln('// zz:"' .. line .. '"') + fn_magic = nil end - else - -- it's a boring comment - TIO_out2stream_commented(line,'--') - end - elseif string.find(line,'^function%s') or string.find(line,'^local%s+function%s')then - -- "function wibble..." - -- it's a function declaration - -- ....v... - local pos_fn = string.find(line,'function') - if (pos_fn) then - local pos_local = string.find(line,'^local%s+function%s') - local fn = TString_removeCommentFromLine(TString_trim(string.sub(line,pos_fn+8))) - - if (string.sub(fn,1,1)=='(') then - -- anonymous function - TIO_out2stream_commented(line,'anon fn') - else - --[[ - we might have extracted a fn def with parameters on multilines - The hack is to insert a new close paren with a note to that effect. - ]] - - if not string.find(fn,'%)') then - fn = fn .. ' ___MissingCloseParenHere___)' + elseif string.find(line,'^function') or string.find(line,'^local%s+function') then + -- 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 ' + else + fn_type = '' end - - local plain_fn_str = 'function ' .. fn .. '{}' - if pos_local then - plain_fn_str = 'local ' .. plain_fn_str + local fn = TString_removeCommentFromLine(string_trim(string.sub(line,pos_fn+8))) + if fn_magic then + fn = fn_magic + fn_magic = nil end - - local dot = string.find(fn,'%.') - if dot then -- it's a method - local klass = string.sub(fn,1,dot-1) - local method = string.sub(fn,dot+1) - local method_str = klass .. '::' .. method .. '{}' - TCommentary_addMethod(klass,method) - TIO_out2stream(method_str) + + if string.sub(fn,1,1)=='(' then + -- it's an anonymous function + outStream:writelnComment(line) else - TIO_out2stream(plain_fn_str) + -- fn has a name, so is interesting + + -- want to fix for iffy declarations + local open_paren = string.find(fn,'[%({]') + local fn0 = fn + if open_paren then + fn0 = string.sub(fn,1,open_paren-1) + -- we might have a missing close paren + if not string.find(fn,'%)') then + fn = fn .. ' ___MissingCloseParenHere___)' + end + end + + local dot = string.find(fn0,'[%.:]') + if dot then -- it's a method + local klass = string.sub(fn,1,dot-1) + local method = string.sub(fn,dot+1) + --TCore_IO_writeln('function ' .. klass .. '::' .. method .. ftail .. '{}') + --TCore_IO_writeln(klass .. '::' .. method .. ftail .. '{}') + outStream:writeln( + '/*! \\memberof ' .. klass .. ' */ ' + .. method .. '{}' + ) + else + -- add vanilla function + + outStream:writeln(fn_type .. 'function ' .. fn .. '{}') + end end + else + this:warning(inStream:getLineNo(),'something weird here') end - end - elseif string.find(line,'=%s+class%(') then - -- it's a class definition - line = TString_removeCommentFromLine(line) - local klass,parent,pos_class - -- ....v... - pos_class = string.find(line,'=%s+class%(') - klass = TString_trim(string.sub(line,1,pos_class-1)) - parent = TString_trim(string.sub(line,pos_class+8)) - parent = string.sub(parent,1,-2) - - line = 'class ' .. klass - if (#parent>0) then - line = line .. ' :public ' .. parent - end - - -- need methods list - local methods = TClassList_method_get(klass) - local methods_str - if methods then - methods_str = 'public: ' - for k,v in pairs(methods) do - methods_str = methods_str .. v .. ';' + fn_magic = nil -- mustn't indavertently use it again + elseif string.find(line,'=%s*class%(') then + -- it's a class declaration + local tailComment + line,tailComment = TString_removeCommentFromLine(line) + local equals = string.find(line,'=') + local klass = string_trim(string.sub(line,1,equals-1)) + local tail = string_trim(string.sub(line,equals+1)) + -- class(wibble wibble) + -- ....v. + local parent = string.sub(tail,7,-2) + if #parent>0 then + parent = ' :public ' .. parent end + outStream:writeln('class ' .. klass .. parent .. '{};') else - methods_str = '/* no methods reported */' + -- we don't know what this line means, so we can probably just comment it out + if #line>0 then + outStream:writeln('// zz: ' .. line) + else + outStream:writeln() -- keep this line blank + end end - line = line .. '{' .. methods_str .. '}' - - TIO_out2stream(line .. ';',true) - else - -- we don't know what this line means, so we can probably just comment it out - TIO_out2stream_commented(line) end - i = i + 1 + -- output the tail + outStream:write_tailLines() + else + outStream:writeln('!empty file') end - return err end ---! \brief run the filter ---! ---! \param AppTimestamp application + timestamp for this run ---! \param Filename the filename or if nil stdin ---! \param CommentaryFiles names of commentary files ---! \return err or nil ---! -local function TApp_run_filter(AppTimestamp,Filename,CommentaryFiles) - local err - local filecontents - if Filename then - -- syphon lines to our table - filecontents={} - for line in io.lines(Filename) do - table.insert(filecontents,line) - end - else - -- get stuff from stdin as a long string (with crlfs etc) - filecontents=io.read('*a') - -- make it a table of lines - filecontents = TString_split(filecontents,'[\n]') -- note this only works for unix files. - Filename = 'stdin' - end - - if filecontents then - TCommentary_readFileContents(CommentaryFiles.infile) - TCommentary_open(CommentaryFiles.outfile,Filename) - - err = TApp_lua2dox(filecontents) - - TCommentary_close() - - TIO_writeln('// done (' .. AppTimestamp .. ')') - else - err = TIO_showError(1,'couldn\'t find any file contents') - end - return err +--! \brief this application +TApp = class() + +--! \brief constructor +function TApp.init(this) + local t0 = TCore_Clock() + this.timestamp = t0:getTimeStamp() + this.name = 'Lua2DoX' + this.version = '0.2 20130128' + this.copyright = 'Copyright (c) Simon Dales 2012-13' end ---! \brief run doxygen for one ---! ---! \param AppTimestamp application + timestamp for this run ---! \param Argv commandline for this run ---! \param CommentaryFiles names of commentary files ---! \return err or nil ---! -local function TApp_run_doxygen(AppTimestamp,Argv,CommentaryFiles) - local err - TIO_writeln('running: ' .. AppTimestamp) - - local argv1 = Argv[1] - if argv1=='--help' then - local appname = TApp_get_appname() - TIO_writeln('Syntax:') - TIO_writeln(' ' .. appname .. ' [[-g] [-s]] [<Doxyfile name>]|--help') - TIO_writeln(' --help show this text') - TIO_writeln(' -g: generate new Doxyfile') - TIO_writeln(' -s: generate new Doxyfile without comments') - TIO_writeln(' <Doxyfile name>: name of Doxyfile') - - TIO_writeln() - TIO_writeln(' For help on doxygen run its help system directly') - --! \todo more help here - else - local cl = 'doxygen' - for i,argv_i in ipairs(Argv) do - if i>=1 then -- don't want to use this app's name - cl = cl .. ' ' .. argv_i - end - end - - TIO_writeln('about to run "' .. cl .. '"') - err = TOS_system(cl) - - if not err then - -- cycle commentary files - local newComments=CommentaryFiles.outfile - local nextRunsComments=CommentaryFiles.infile - if TOS_fileExists(newComments) then - TIO_writeln('found outfile "' .. newComments .. '"') - os.remove(nextRunsComments) - TIO_writeln('mv "' .. newComments .. '"-> ' .. nextRunsComments .. '"') - os.rename(newComments,nextRunsComments) - end - end - end - return err +function TApp.getRunStamp(this) + return this.name .. ' (' .. this.version .. ') ' + .. this.timestamp +end + +function TApp.getVersion(this) + return this.name .. ' (' .. this.version .. ') ' end --- main -local timestamp = TClock_getTimeStamp() -local appname = TApp_get_appname() -local version = '0.1 20120704' -local appTimestamp = appname .. '(v' .. version .. ') :' .. timestamp -local commentary_files = { - infile=TConfig_get('LUA2DOX_COMMENTARY_FILE_IN') - ,outfile=TConfig_get('LUA2DOX_COMMENTARY_FILE_OUT') - } - -if appname == 'lua2dox_filter' then - err = TApp_run_filter(appTimestamp,TCommandline_getargv()[1],commentary_files) - TIO_writeln('// do filter') +function TApp.getCopyright(this) + return this.copyright +end + +local This_app = TApp() + +--main +local cl = TCore_Commandline() + +local argv1 = cl:getRaw(2) +if argv1 == '--help' then + TCore_IO_writeln(This_app:getVersion()) + TCore_IO_writeln(This_app:getCopyright()) + TCore_IO_writeln([[ +run as: +lua2dox_filter <param> +-------------- +Param: + <filename> : interprets filename + --version : show version/copyright info + --help : this help text]]) +elseif argv1 == '--version' then + TCore_IO_writeln(This_app:getVersion()) + TCore_IO_writeln(This_app:getCopyright()) else - err = TApp_run_doxygen(appTimestamp,TCommandline_getargv(),commentary_files) + -- it's a filter + local appStamp = This_app:getRunStamp() + local filename = argv1 + + local filter = TLua2DoX_filter() + filter:readfile(appStamp,filename) end + --eof
\ No newline at end of file diff --git a/Master/texmf-dist/scripts/lua2dox/lua2dox_lua b/Master/texmf-dist/scripts/lua2dox/lua2dox_filter index 822fed7bea1..822fed7bea1 100755 --- a/Master/texmf-dist/scripts/lua2dox/lua2dox_lua +++ b/Master/texmf-dist/scripts/lua2dox/lua2dox_filter |