summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/scripts/lua2dox
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2013-02-08 00:38:37 +0000
committerKarl Berry <karl@freefriends.org>2013-02-08 00:38:37 +0000
commit532e95c1171566e596e733b2f12b60263d3773db (patch)
treea28c86920edec0518ca9d924a4dbe993099a0502 /Master/texmf-dist/scripts/lua2dox
parent26d5dc00f5d6880985f5ae779b786f5ea001bb2f (diff)
lua2dox 0.2 (7feb13)
git-svn-id: svn://tug.org/texlive/trunk@29053 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/scripts/lua2dox')
-rwxr-xr-xMaster/texmf-dist/scripts/lua2dox/lua2dox.lua973
-rwxr-xr-xMaster/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