summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/scripts/lua2dox/lua2dox.lua
blob: 9249baac9cd996da327ebee43972f2626531377a (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
--[[--------------------------------------------------------------------------
 --   Copyright (C) 2012 by Simon Dales   --
 --   simon@purrsoft.co.uk   --
 --                                                                         --
 --   This program is free software; you can redistribute it and/or modify  --
 --   it under the terms of the GNU General Public License as published by  --
 --   the Free Software Foundation; either version 2 of the License, or     --
 --   (at your option) any later version.                                   --
 --                                                                         --
 --   This program is distributed in the hope that it will be useful,       --
 --   but WITHOUT ANY WARRANTY; without even the implied warranty of        --
 --   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the         --
 --   GNU General Public License for more details.                          --
 --                                                                         --
 --   You should have received a copy of the GNU General Public License     --
 --   along with this program; if not, write to the                         --
 --   Free Software Foundation, Inc.,                                       --
 --   59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.             --
----------------------------------------------------------------------------]]

--[[!
	\file
	\brief a hack lua2dox converter
	]]

--[[!
	\mainpage
	
	
	A hack lua2dox converter
	Version 0.1

	This lets us make Doxygen output some documentation to let
	us develop this code.
	
	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.
	
	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
	
	FILTER_PATTERNS = *.lua=lua2dox_filter
	
	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:
	
	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_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".
	
	Call it as "lua2dox_lua" and the filter that gets called by doxygen is "lua2dox_filter".

	]]

-- 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
	end
	return val
end

--! \brief sets a config val
local function TConfig_set(Key,Val)
	TConfig_config[Key] = Val
end

--! \brief write to stdout
--! 
--! writes Str (if not nil)
local function TIO_write(Str)
	if (Str) then
		io.write(Str)
	end
end

--! \brief write to stdout
--! 
--! writelns Str (if not nil) and then an eoln.
local function TIO_writeln(Str)
	if (Str) then
		io.write(Str)
	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
	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'
	end
	return errno,str
end

--! \brief does file exist?
local function TOS_fileExists(Filename)
	local fh = io.open(Filename,'r')
	if fh~=nil then
		fh:close()
		return true
	end
	return false
end

--! \brief get the current time
local function TClock_GetTimeNow()
	if os.gettimeofday then
		return os.gettimeofday()
	else
		return os.time()
	end
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)
  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)
   local splitStr = {}
   local fpat = "(.-)" .. Pattern
   local last_end = 1
   local str, e, cap = string.find(Str,fpat, 1)
   while str do
      if str ~= 1 or cap ~= "" then
         table.insert(splitStr,cap)
      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)
      table.insert(splitStr, cap)
   end
   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


local TCommentary_fh

--! \brief write to output file
local function TCommentary_writeln(Str)
	if TCommentary_fh then
		TCommentary_fh:write(Str .. '\n')
	end
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)
	end
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
		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
		end
	else
		TIO_write('/* file "' .. Filename .. '" don\'t exist */')
	end
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
		end
	end
end

--! \brief output line to stream
--! 
--! Wraps IO_writeln()
local function TIO_out2stream(Line)
	TIO_writeln(Line)
end

--! \brief suppress line
local function TIO_out2stream_commented(Line,Prefix,Suffix)
	local line = Line
	if (not Prefix) then
		Prefix=''
	end
	line = Prefix .. ':' .. line
	
	if (Suffix) then
		line = line .. Suffix
	end
	TIO_out2stream('// D' .. line)
end


TCommandline_argv = {}
--! \brief setup/parse the commandline
local function TCommandline_setup()
	local argv1 =arg[1]
	if not argv1 then
		argv1 = 'base'
	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
	end
end
--! setup the commandline now
TCommandline_setup()

--! \brief get commandline args
local function TCommandline_getargv()
	return TCommandline_argv
end

--! \brief get appname
local function TApp_get_appname()
	return TCommandline_argv_appname
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)
	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
					end
					i = i + 1
				end
				-- got long comment
				if string.sub(comment,1,1)=='!' then
					TIO_out2stream('/*' .. comment .. '*/')
				else
					TIO_out2stream('/* (longcomment):' .. comment .. '*/')
				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___)'
					end
						
					local plain_fn_str = 'function ' .. fn .. '{}'
					if pos_local then
						plain_fn_str = 'local ' .. plain_fn_str
					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)
					else
						TIO_out2stream(plain_fn_str)
					end
				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 .. ';'
				end
			else
				methods_str = '/* no methods reported */'
			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
	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
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
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')
else
 	err = TApp_run_doxygen(appTimestamp,TCommandline_getargv(),commentary_files)
end

--eof