summaryrefslogtreecommitdiffstats
path: root/src/Bindings/BindingsProcessor.lua
blob: 417a8f48c0872b55759f4435ffd5e0bcb034a565 (plain) (blame)
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
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977

-- BindingsProcessor.lua

-- Implements additional processing that is done while generating the Lua bindings

--[[
The primary purpose of this file is to provide transformations for ToLua - it is loaded by ToLua++
before processing the C++ code.

This file can also be used as a standalone Lua program to actually generate the bindings, it invokes
ToLua++ if executed by a regular Lua interpreter

The transformations implemented:
	- Modify ToLua++ behavior so that it doesn't generate bindings for private and protected members
	- Export additional files to be included in cLuaState:
		- Forward declarations and typedefs for custom classes' pointers
		- Pushing and popping of bindings' classes

To parse DoxyComments, the preprocessor first replaces them with markers and then the parser uses
those markers to apply the DoxyComment to the next or previous item in the container, based on
the DoxyComment type.

Placeholders in use (i = internal ToLua++):
	- \1 and \2: (i) Embedded Lua code
	- \3 and \4: (i) Embedded C code ("<>")
	- \5 and \6: (i) Embedded C code ("{}")
	- \17 and \18: DoxyComment for next item ("/** ... */") via an ID lookup
	- \19 and \20: DocyComment for previous item ("///< ... \n") via an ID lookup
--]]





--- Invokes the ToLua++ parser
-- Called when this script detects it has been run outside of ToLua++'s processing
local function invokeToLua()
	-- The values used by ToLua scripts, normally filled from the cmdline params:
	flags =
	{
		L = "BindingsProcessor.lua",
		o = "Bindings.cpp",
		H = "Bindings.h",
		f = "AllToLua.pkg",
		-- P = true,  -- Prints the structure to stdout, doesn't generate cpp file
	}
	_extra_parameters = {}
	TOLUA_VERSION = "tolua++-1.0.92"
	TOLUA_LUA_VERSION = "Lua 5.1"

	-- Path to the ToLua scripts
	path = "../../lib/tolua++/src/bin/lua/"

	-- Run the ToLua processing:
	dofile(path .. "all.lua")
end





local access =
{
	public = 0,
	protected = 1,
	private = 2
}





--- Defines classes that have a custom manual Push() implementation and should not generate the automatic one
-- Map of classname -> true
local g_HasCustomPushImplementation =
{
	cEntity = true
}





--- Array-table of forward DoxyComments that are replaced in preprocess_hook() and substituted back in parser_hook()
-- We need to use a lookup table because the comments themselves may contain "//" which the preprocessor
-- would eliminate, thus breaking the code
-- The "n" member is a counter for faster insertion
local g_ForwardDoxyComments =
{
	n = 0
}


--- Array-table of backward DoxyComments that are replaced in preprocess_hook() and substituted back in parser_hook()
-- We need to use a lookup table because the comments themselves may contain "//" which the preprocessor
-- would eliminate, thus breaking the code
-- The "n" member is a counter for faster insertion
local g_BackwardDoxyComments =
{
	n = 0,
}





--- Provides extra parsing in addition to ToLua++'s own
-- Called by ToLua++ each time it extracts the next piece of code to parse
-- a_Code is the string representing the code to be parsed
-- The return value is the remaining code to be parsed in the next iteration
-- Processes the class access specifiers (public, protected, private), and doxycomments
function parser_hook(a_Code)
	-- Process access-specifying labels (public, private, etc)
	do
		local b, e, label = string.find(a_Code, "^%s*(%w*)%s*:[^:]") -- we need to check for [^:], otherwise it would match 'namespace::type'
		if b then
			-- Found a label, get the new access value for it:
			if access[label] then
				classContainer.curr.curr_member_access = access[label]
			end -- else ?
			return strsub(a_Code, e) -- normally we would use 'e + 1', but we need to preserve the [^:]
		end
	end
	
	-- Process forward DoxyComments:
	do
		local b, e, comment = a_Code:find("^%s*(%b\17\18)")
		if (b) then
			local curr = classContainer.curr
			if (curr.n and (curr.n > 0)) then
				curr[curr.n].next_DoxyComment = g_ForwardDoxyComments[tonumber(comment:sub(2, -2))]
			end
			return strsub(a_Code, e + 1)
		end
	end
	
	-- Process backward DoxyComments:
	do
		local b, e, comment = a_Code:find("^%s*(%b\19\20)")
		if (b) then
			comment = g_BackwardDoxyComments[tonumber(comment:sub(2, -2))]
			local currContainer = classContainer.curr
			if (currContainer.n > 0) then
				currContainer[currContainer.n].DoxyComment = comment
			else
				print("Backward DoxyComment lost in " .. (currContainer.name or currContainer.lname or currContainer.cname or "<no name>"))
			end
			return strsub(a_Code, e + 1)
		end
	end
end





--- Outputs the helper files supplementing the cLuaState class
-- Writes:
--   LuaState_Declaration.inc
--   LuaState_Implementation.cpp
--   LuaState_Typedefs.inc
local function OutputLuaStateHelpers(a_Package)
	-- Collect all class types from ToLua:
	local types = {}
	for idx, item in ipairs(a_Package) do
		local mt = getmetatable(item) or {}
		if (mt.classtype == "class") then
			table.insert(types, {name = item.name, lname = item.lname})
		end
	end
	table.sort(types,
		function(a_Item1, a_Item2)
			return (a_Item1.name:lower() < a_Item2.name:lower())
		end
	)

	-- Output the typedefs:
	do
		local f = assert(io.open("LuaState_Typedefs.inc", "w"))
		f:write("\n// LuaState_Typedefs.inc\n\n// This file is generated along with the Lua bindings by ToLua. Do not edit manually, do not commit to repo.\n")
		f:write("// Provides a forward declaration and a typedef for a pointer to each class exported to the Lua API.\n")
		f:write("\n\n\n\n\n")
		for _, item in ipairs(types) do
			if not(item.name:match(".*<.*")) then  -- Skip templates altogether
				-- Classes start with a "c", everything else is a struct:
				if (item.name:sub(1, 1) == "c") then
					f:write("class " .. item.name .. ";\n")
				else
					f:write("struct " .. item.name .. ";\n")
				end
			end
		end
		f:write("\n\n\n\n\n")
		for _, item in ipairs(types) do
			f:write("typedef " .. item.name .. " * Ptr" .. item.lname .. ";\n")
			f:write("typedef const " .. item.name .. " * ConstPtr" .. item.lname .. ";\n")
		end
		f:write("\n\n\n\n\n")
		f:close()
	end
	
	-- Output the Push() and GetStackValue() function declarations:
	do
		local f = assert(io.open("LuaState_Declaration.inc", "w"))
		f:write("\n// LuaState_Declaration.inc\n\n// This file is generated along with the Lua bindings by ToLua. Do not edit manually, do not commit to repo.\n")
		f:write("// Implements a Push() and GetStackValue() function for each class exported to the Lua API.\n")
		f:write("// This file expects to be included form inside the cLuaState class definition\n")
		f:write("\n\n\n\n\n")
		for _, item in ipairs(types) do
			if not(g_HasCustomPushImplementation[item.name]) then
				f:write("void Push(" .. item.name .. " * a_Value);\n")
			end
		end
		for _, item in ipairs(types) do
			f:write("bool GetStackValue(int a_StackPos, Ptr" .. item.lname .. " & a_ReturnedVal);\n")
			f:write("bool GetStackValue(int a_StackPos, ConstPtr" .. item.lname .. " & a_ReturnedVal);\n")
		end
		f:write("\n\n\n\n\n")
		f:close()
	end

	-- Output the Push() and GetStackValue() function implementations:
	do
		local f = assert(io.open("LuaState_Implementation.cpp", "w"))
		f:write("\n// LuaState_Implementation.cpp\n\n// This file is generated along with the Lua bindings by ToLua. Do not edit manually, do not commit to repo.\n")
		f:write("// Implements a Push() and GetStackValue() function for each class exported to the Lua API.\n")
		f:write("// This file expects to be compiled as a separate translation unit\n")
		f:write("\n\n\n\n\n")
		f:write("#include \"Globals.h\"\n#include \"LuaState.h\"\n#include \"tolua++/include/tolua++.h\"\n")
		f:write("\n\n\n\n\n")
		for _, item in ipairs(types) do
			if not(g_HasCustomPushImplementation[item.name]) then
				f:write("void cLuaState::Push(" .. item.name .. " * a_Value)\n{\n\tASSERT(IsValid());\n")
				f:write("\ttolua_pushusertype(m_LuaState, a_Value, \"" .. item.name .. "\");\n");
				f:write("\tm_NumCurrentFunctionArgs += 1;\n")
				f:write("}\n\n\n\n\n\n")
			end
		end
		for _, item in ipairs(types) do
			f:write("bool cLuaState::GetStackValue(int a_StackPos, Ptr" .. item.lname .. " & a_ReturnedVal)\n{\n\tASSERT(IsValid());\n")
			f:write("\tif (lua_isnil(m_LuaState, a_StackPos))\n\t{\n")
			f:write("\t\ta_ReturnedVal = nullptr;\n")
			f:write("\t\treturn false;\n\t}\n")
			f:write("\ttolua_Error err;\n")
			f:write("\tif (tolua_isusertype(m_LuaState, a_StackPos, \"" .. item.name .. "\", false, &err))\n")
			f:write("\t{\n")
			f:write("\t\ta_ReturnedVal = *(reinterpret_cast<" .. item.name .. " **>(lua_touserdata(m_LuaState, a_StackPos)));\n")
			f:write("\t\treturn true;\n");
			f:write("\t}\n")
			f:write("\treturn false;\n")
			f:write("}\n\n\n\n\n\n")

			f:write("bool cLuaState::GetStackValue(int a_StackPos, ConstPtr" .. item.lname .. " & a_ReturnedVal)\n{\n\tASSERT(IsValid());\n")
			f:write("\tif (lua_isnil(m_LuaState, a_StackPos))\n\t{\n")
			f:write("\t\ta_ReturnedVal = nullptr;\n")
			f:write("\t\treturn false;\n\t}\n")
			f:write("\ttolua_Error err;\n")
			f:write("\tif (tolua_isusertype(m_LuaState, a_StackPos, \"const " .. item.name .. "\", false, &err))\n")
			f:write("\t{\n")
			f:write("\t\ta_ReturnedVal = *(reinterpret_cast<const " .. item.name .. " **>(lua_touserdata(m_LuaState, a_StackPos)));\n")
			f:write("\t\treturn true;\n");
			f:write("\t}\n")
			f:write("\treturn false;\n")
			f:write("}\n\n\n\n\n\n")
		end
		f:close()
	end
end





local function FormatString(a_Str)
	local fmt = string.format("%q", a_Str)
	return (string.gsub(string.gsub(fmt, "\\\n", "\\n"), "\\\r\n", "\\r\\n"))
end





local function OutputTable(a_File, a_Table, a_Name, a_Indent, a_Visited, a_Metas)
	-- Check and update the "visited" status:
	if (a_Visited[a_Table]) then
		a_File:write(a_Indent .. "{ \"visited: " .. a_Visited[a_Table] .. "\", }")
		return
	end
	a_Visited[a_Table] = a_Name

	-- Output the table contents:
	a_File:write(a_Indent .. "{\n")
	local indent = a_Indent .. "\t"
	for k, v in pairs(a_Table) do
		if (type(k) == "string") then
			a_File:write(indent .. "[" .. FormatString(k) .. "] =")
		else
			a_File:write(indent .. "[" .. tostring(k) .. "] =")
		end
		local t = type(v)
		if (
			(t == "number") or
			(t == "boolean")
		) then
			a_File:write(" ", tostring(v))
		elseif (t == "string") then
			a_File:write(" ", FormatString(v))
		elseif (t == "table") then
			local metatab = getmetatable(v)
			if (metatab) then
				a_File:write("  -- meta: " .. tostring(metatab))
				a_Metas[metatab] = metatab
			end
			a_File:write("\n")
			OutputTable(a_File, v, a_Name .. "." .. tostring(k), indent, a_Visited, a_Metas)
		else
			print("Unhandled type: " .. t .. ": " .. tostring(v))
			a_File:write(" ", tostring(v))
		end
		a_File:write(",\n")
	end  -- for k, v - a_Table
	a_File:write(a_Indent .. "}")
end





--- Outputs the docs for all the functions in the specified class
-- a_File is the output file
-- a_Class is the ToLua's classClass object
-- a_Functions is a dictionary of function descriptions: "name" -> { {<description>}, ...}
local function outputClassFunctionDocs(a_File, a_Class, a_Functions)
	-- Sort the functions by name:
	local functions = {}
	for name, descs in pairs(a_Functions) do
		table.insert(functions, { Name = name, Descs = descs })
	end
	table.sort(functions,
		function (a_Fn1, a_Fn2)
			return (a_Fn1.Name < a_Fn2.Name)
		end
	)
	
	-- If there are no functions, bail out:
	if not(functions[1]) then
		return
	end
	
	-- Output the descriptions:
	a_File:write("\t\tFunctions =\n\t\t{\n")
	for _, fn in ipairs(functions) do
		local name = fn.Name
		if (name:sub(1, 1) == ".") then
			name = "[\"" .. name .. "\"]"
		end
		a_File:write("\t\t\t", name, " =\n\t\t\t{\n")
		for _, desc in ipairs(fn.Descs) do
			a_File:write("\t\t\t\t{\n\t\t\t\t\tParams =\n\t\t\t\t\t{\n")
			for _, param in ipairs(desc.Parameters) do
				a_File:write("\t\t\t\t\t\t{\n")
				a_File:write("\t\t\t\t\t\t\tType = \"", param.Type, "\",\n")
				a_File:write("\t\t\t\t\t\t\tName = \"", param.Name, "\",\n")
				a_File:write("\t\t\t\t\t\t},\n")
			end
			a_File:write("\t\t\t\t\t},\n\t\t\t\t\tReturns =\n\t\t\t\t\t{\n")
			for _, ret in ipairs(desc.Returns) do
				a_File:write("\t\t\t\t\t\t{\n\t\t\t\t\t\t\tType = \"", ret.Type, "\",\n\t\t\t\t\t\t},\n")
			end
			a_File:write("\t\t\t\t\t},\n")
			if (desc.DoxyComment) then
				a_File:write("\t\t\t\t\tDesc = ", string.format("%q", desc.DoxyComment), ",\n")
			end
			a_File:write("\t\t\t\t},\n")
		end
		a_File:write("\t\t\t},\n")
	end
	a_File:write("\t\t},\n")
end





--- Outputs the docs for all the member variables in the specified class
-- a_File is the output file
-- a_Class is the ToLua's classClass object
-- a_Variables is a dictionary of variable descriptions: "name" -> {<description>}
local function outputClassVariableDocs(a_File, a_Class, a_Variables)
	-- Sort the variables by name:
	local variables = {}
	for name, desc in pairs(a_Variables) do
		table.insert(variables, { Name = name, Desc = desc })
	end
	table.sort(variables,
		function (a_Var1, a_Var2)
			return (a_Var1.Name < a_Var2.Name)
		end
	)
	
	-- If there are no variables, bail out:
	if not(variables[1]) then
		return
	end
	
	-- Output the descriptions:
	a_File:write("\t\tVariables =\n\t\t{\n")
	for _, v in ipairs(variables) do
		a_File:write("\t\t\t", v.Name, " =\n\t\t\t{\n")
		a_File:write("\t\t\t\tType = \"", v.Desc.Type, "\",\n")
		if (v.Desc.DoxyComment) then
			a_File:write("\t\t\t\tDesc = ", string.format("%q", v.Desc.DoxyComment), ",\n")
		end
		a_File:write("\t\t\t},\n")
	end
	a_File:write("\t\t},\n")
end





--- Outputs the docs for all the member constants in the specified class
-- a_File is the output file
-- a_Class is the ToLua's classClass object
-- a_Constants is a dictionary of constant descriptions: "name" -> {<description>}
-- a_IgnoredConstants is a dictionary of constants not to be exported: "name" -> true (used for ToLua++'s multi-inheritance)
local function outputClassConstantDocs(a_File, a_Class, a_Constants, a_IgnoredConstants)
	-- Sort the constants by name:
	local constants = {}
	for name, desc in pairs(a_Constants) do
		if not(a_IgnoredConstants[name]) then
			table.insert(constants, { Name = name, Desc = desc })
		end
	end
	table.sort(constants,
		function (a_Var1, a_Var2)
			return (a_Var1.Name < a_Var2.Name)
		end
	)
	
	-- If there are no constants, bail out:
	if not(constants[1]) then
		return
	end
	
	-- Output the descriptions:
	a_File:write("\t\tConstants =\n\t\t{\n")
	for _, con in ipairs(constants) do
		a_File:write("\t\t\t", con.Name, " =\n\t\t\t{\n")
		a_File:write("\t\t\t\tType = \"", con.Desc.Type, "\",\n")
		if (con.Desc.DoxyComment) then
			a_File:write("\t\t\t\tDesc = ", string.format("%q", con.Desc.DoxyComment), ",\n")
		end
		a_File:write("\t\t\t},\n")
	end
	a_File:write("\t\t},\n")
end





--- Outputs the docs for all the member enums in the specified class
-- a_File is the output file
-- a_Class is the ToLua's classClass object
-- a_Enums is an array of ToLua's classEnum objects
local function outputClassEnumDocs(a_File, a_Class, a_Enums)
	-- If there are no enums, bail out:
	if (not(a_Enums) or not(a_Enums[1])) then
		return
	end
	
	-- Sort the enums by name:
	table.sort(a_Enums,
		function (a_Enum1, a_Enum2)
			return (a_Enum1.name < a_Enum2.name)
		end
	)
	
	-- Output the enums:
	a_File:write("\t\tEnums =\n\t\t{\n")
	for i, enum in ipairs(a_Enums) do
		local name = enum.name
		if (not(name) or (name == "")) then
			name = string.format("unnamedEnum_%d", i)
		end
		a_File:write("\t\t\t", name, " =\n\t\t\t{\n")
		local valnames = {}
		-- Make a copy of enum.lnames so that we can sort it:
		local idx = 1
		for i, valname in ipairs(enum.lnames) do
			valnames[idx] = { Name = valname, DoxyComment = enum.DoxyComments[i] }
			idx = idx + 1
		end
		table.sort(valnames,
			function (a_Val1, a_Val2)
				return (a_Val1.Name < a_Val2.Name)
			end
		)
		for _, valname in ipairs(valnames) do
			assert(not(valname.Name:find("\17")))
			assert(not(valname.Name:find("\18")))
			assert(not(valname.Name:find("\19")))
			assert(not(valname.Name:find("\20")))
			a_File:write("\t\t\t\t{\n")
			a_File:write("\t\t\t\t\tName = \"", valname.Name, "\",\n")
			if (valname.DoxyComment) then
				a_File:write("\t\t\t\t\tDesc = ", string.format("%q", valname.DoxyComment), ",\n")
			end
			a_File:write("\t\t\t\t},\n")
		end
		a_File:write("\t\t\t},\n")
	end
	a_File:write("\t\t},\n")
end





--- Outputs the docs for the specified class, which has been parsed for its functions, variables and constants
-- a_Class is the ToLua's classClass object
-- a_Functions is a dictionary of function descriptions: "name" -> { {<description>}, ...}
-- a_Variables is a dictionary of variable descriptions: "name" -> {<description>}
-- a_Constants is a dictionary of constant descriptions: "name" -> {<description>}
-- a_Filenames is an array into which the name of the docs file is to be appended
local function outputClassDocs(a_Class, a_Functions, a_Variables, a_Constants, a_Filenames)
	-- Add the output file to list of filenames:
	local fnam = a_Class.lname .. ".lua"
	table.insert(a_Filenames, fnam)

	-- Output the header:
	local f = assert(io.open("docs/" .. fnam, "w"))
	f:write("return\n{\n\t", a_Class.lname, " =\n\t{\n")
	if (a_Class.DoxyComment) then
		f:write("\t\tDesc = ", string.format("%q", a_Class.DoxyComment), ",\n")
	end
	
	-- If the class inherits from anything, output it here:
	local ignoredConstants = {}
	if (a_Class.base and (a_Class.base ~= "")) then
		local bases = {a_Class.base}
		local idx = 2
		for _, b in ipairs(a_Class.extra_bases or {}) do
			bases[idx] = b
			idx = idx + 1
			-- ToLua++ handles multiple inheritance by adding "constants" for the base types; ignore those:
			ignoredConstants["__" .. b .. "__"] = true
		end
		table.sort(bases)
		f:write("\t\tInherits =\n\t\t{\n")
		for _, b in ipairs(bases) do
			f:write("\t\t\t", string.format("%q", b), ",\n")
		end
		f:write("\t\t},\n")
	end
	
	-- Output the functions:
	outputClassFunctionDocs(f, a_Class, a_Functions)
	
	-- Output the variables:
	outputClassVariableDocs(f, a_Class, a_Variables)
	
	-- Output the constants:
	outputClassConstantDocs(f, a_Class, a_Constants, ignoredConstants)
	
	-- Output the enums:
	outputClassEnumDocs(f, a_Class, a_Class.enums)
	
	-- Output the footer:
	f:write("\t},\n}\n")
	f:close()
end





--- Recursively applies the next_DoxyComment member to the next item in the container
-- a_Container is the ToLua++'s table potentially containing children as its array members
local function applyNextDoxyComments(a_Container)
	local i = 1
	while (a_Container[i]) do
		if (a_Container[i].next_DoxyComment) then
			if (a_Container[i + 1]) then
				a_Container[i + 1].DoxyComment = a_Container[i].next_DoxyComment
			end
		end
		applyNextDoxyComments(a_Container[i])
		i = i + 1
	end
end





--- Generates documentation for a package.
local function genPackageDocs(a_Self)
	-- DEBUG: Output the raw package object:
	do
		local f = io.open("docs/_raw.lua", "w")
		if (f) then
			OutputTable(f, a_Self, "", "", {}, {})
			f:close()
		end
	end
	
	applyNextDoxyComments(a_Self)

	-- Generate docs for each member:
	local i = 1
	local filenames = {}
	while (a_Self[i]) do
		if (a_Self[i].genDocs) then
			a_Self[i]:genDocs(filenames)
		end
		i = i + 1
	end
	
	-- Output the globals' docs:
	local functions = {}
	local variables = {}
	local constants = {}
	while (a_Self[i]) do
		if (a_Self[i].genMemberDocs) then
			a_Self[i]:genMemberDocs(functions, variables, constants)
		end
		i = i + 1
	end
	local oldName = a_Self.lname
	a_Self.lname = "Globals"
	outputClassDocs(a_Self, functions, variables, constants, filenames)
	a_Self.lname = oldName
	
	-- Output the list of docs files:
	table.sort(filenames)
	local f = assert(io.open("docs/_files.lua", "w"))
	f:write("return\n{\n")
	for _, fnam in ipairs(filenames) do
		f:write("\t\"", fnam, "\",\n")
	end
	f:write("}\n")
	f:close()
end





local function genClassDocs(a_Self, a_Filenames)
	assert(a_Self.lname)
	assert(type(a_Filenames) == "table")
	--[[
	print("\n\nGenerating docs for class " .. a_Self.lname)
	local visited = {[a_Self.parent] = "<package>"}
	local metas = {}
	OutputTable(io.stdout, a_Self, a_Self.lname, "", visited, metas)
	--]]

	-- Collect the function, variable and constant docs:
	local i = 1
	local functions = {}
	local variables = {}
	local constants = {}
	while (a_Self[i]) do
		if (a_Self[i].genMemberDocs) then
			a_Self[i]:genMemberDocs(functions, variables, constants)
		end
		i = i + 1
	end
	
	-- Output the individual docs
	outputClassDocs(a_Self, functions, variables, constants, a_Filenames)
end





--- Parses the specified function's parameters and returns their description as a table
-- a_Function is the ToLua's classFunction object
local function parseFunctionParameters(a_Function)
	-- If the only param is a "void", then report no params:
	if (
		a_Function.args and                  -- The params are present
		(#(a_Function.args) == 1) and        -- There is exactly one param
		(a_Function.args[1].type == "void")  -- The param is a void
	) then
		return {}
	end
	
	local res = {}
	local idx = 1
	for _, param in ipairs(a_Function.args or {}) do
		local t = param.type
		t = t:gsub("^const ", "")  -- Remove the "const" keyword, if present
		res[idx] =
		{
			Name = param.name,
			Type = t,
			IsConst = (param.type:match("^const ") ~= nil),
		}
		idx = idx + 1
	end
	return res
end





--- Parses the specified function's return values and returns their description as a table
-- a_Function is the ToLua's classFunction object
local function parseFunctionReturns(a_Function)
	local res = {}
	local idx = 1
	if (a_Function.type and (a_Function.type ~= "void")) then
		res[idx] = { Type = a_Function.type }
		idx = idx + 1
	end
	for _, param in ipairs(a_Function.args or {}) do
		if ((param.mod == "&") or (param.ret == "&")) then
			res[idx] = { Type = param.type:gsub("^const ", "") }
			idx = idx + 1
		end
	end
	return res
end





local function genFunctionMemberDocs(a_Self, a_Functions, a_Variables, a_Constants)
	assert(a_Self.lname)
	
	local fn = a_Functions[a_Self.lname] or {}
	a_Functions[a_Self.lname] = fn

	local desc =
	{
		LuaName = a_Self.lname,
		CType = a_Self.type,
		DoxyComment = a_Self.DoxyComment,
		Parameters = parseFunctionParameters(a_Self),
		Returns = parseFunctionReturns(a_Self),
	}
	table.insert(fn, desc)
end





local function genVariableMemberDocs(a_Self, a_Functions, a_Variables, a_Constants)
	assert(a_Self.lname)
	
	local desc =
	{
		Name = a_Self.lname,
		Type = a_Self.type,
		DoxyComment = a_Self.DoxyComment,
	}
	
	if (a_Self.csetname) then
		a_Variables[a_Self.lname] = desc
	else
		a_Constants[a_Self.lname] = desc
	end
end





--- Generates the entire documentation for the API
-- a_Package is ToLua++'s classPackage object
-- Checks if the documentation folder is writable, if not, skips the docs generation
-- Returns true if documentation was generated, false and message if not
local function generateDocs(a_Package)
	-- Check if the docs folder is writable:
	local f, msg = io.open("docs/_files.lua", "w")
	if not(f) then
		return false, "Cannot access the docs folder: " .. msg
	end
	f:close()
	
	-- Generate the docs:
	classPackage.genDocs = genPackageDocs
	classClass.genDocs = genClassDocs
	classFunction.genMemberDocs = genFunctionMemberDocs
	classVariable.genMemberDocs = genVariableMemberDocs
	a_Package:genDocs()
	return true
end





--- Outputs the cLuaState helper files.
-- Called by ToLua++ before it starts outputting its generated files.
-- a_Package is ToLua++'s classPackage object
function pre_output_hook(a_Package)
	OutputLuaStateHelpers(a_Package)
end





--- Outputs the documentation files.
-- Called by ToLua++ after writing its generated files.
-- a_Package is ToLua++'s classPackage object
function post_output_hook(a_Package)
	-- Generate the documentation:
	local isSuccess, msg = generateDocs(a_Package)
	if not(isSuccess) then
		print("Lua bindings have been generated.")
		print("API docs haven't been generated due to an error: " .. (msg or "<no message>"))
		return
	end
	
	print("Lua bindings and docs have been generated.")
end





--- Provides DoxyComment processing while parsing the C++ code.
-- Called by ToLua++ parser before it starts parsing the code.
-- a_Package is the ToLua++'s classPackage object, currently unparsed
-- The C++ code to be parsed is in a_Packade.code
function preprocess_hook(a_Package)
	assert(a_Package)
	assert(type(a_Package.code) == "string")
	
	-- Replace all DoxyComments with placeholders so that they aren't erased later on:
	a_Package.code = a_Package.code
		:gsub("/%*%*%s*(.-)%s*%*/",
			function (a_Comment)
				local n = g_ForwardDoxyComments.n + 1
				g_ForwardDoxyComments[n] = a_Comment
				g_ForwardDoxyComments.n = n
				return "\17" .. n .."\18"
			end
		)  -- Replace /** ... */ with an ID into a lookup table wrapped in DC1 and DC2
		:gsub("///<%s*(.-)%s*\n%s*",
			function (a_Comment)
				local n = g_BackwardDoxyComments.n + 1
				g_BackwardDoxyComments[n] = a_Comment
				g_BackwardDoxyComments.n = n
				return "\19" .. n .."\20\n"
			end
		)
	local f = io.open("code_out.cpp", "wb")
	f:write(a_Package.code)
	f:close()
end





--- Chooses the smaller of the indices, and the number indicating whether it chose the first or the second
-- If one of the indices is nil, returns the other one
-- If both indices are nil, returns nil
local function chooseNextIndex(a_Index1, a_Index2)
	if not(a_Index1) then
		return a_Index2, 2
	end
	if not(a_Index2) then
		return a_Index1, 1
	end
	if (a_Index1 > a_Index2) then
		return a_Index2, 2
	else
		return a_Index1, 1
	end
end





--- Override for ToLua++'s own code extraction
-- Called for each "$cfile" and "$hfile" directive in the package file
-- a_FileName is the C++ header filename
-- a_Contents is the code contents of the header file
-- The function returns the code to be parsed by ToLua++
-- In addition to the original function, this override extracts all DoxyComments as well
-- This is needed when a function is marked with "// tolua_export" but its DoxyComment is not included
function extract_code(a_FileName, a_Contents)
	local code = '\n$#include "' .. a_FileName .. '"\n'
	a_Contents= "\n" .. a_Contents .. "\n" -- add blank lines as sentinels
	local _, e, c, t = strfind(a_Contents, "\n([^\n]-)[Tt][Oo][Ll][Uu][Aa]_([^%s]*)[^\n]*\n")
	local dcb, dce, dc = strfind(a_Contents, "/%*%*.-%*/")
	local nextEnd, whichOne = chooseNextIndex(e, dce)
	while (nextEnd) do
		if (whichOne == 2) then
			code = code .. a_Contents:sub(dcb, dce) .. "\n"
		else
			t = strlower(t)
			if (t == "begin") then
				_, nextEnd, c = strfind(a_Contents,"(.-)\n[^\n]*[Tt][Oo][Ll][Uu][Aa]_[Ee][Nn][Dd][^\n]*\n", e)
				if not(nextEnd) then
				 tolua_error("Unbalanced 'tolua_begin' directive in header file " .. a_FileName)
				end
			end
			code = code .. c .. "\n"
		end
		_, e, c, t = strfind(a_Contents, "\n([^\n]-)[Tt][Oo][Ll][Uu][Aa]_([^%s]*)[^\n]*\n", nextEnd)
		dcb, dce, dc = strfind(a_Contents, "/%*%*.-%*/", nextEnd)
		nextEnd, whichOne = chooseNextIndex(e, dce)
	end
	return code
end





--- Installs a hook that is called by ToLua++ for each instantiation of classEnumerate
-- The hook is used to fix DoxyComments in enums
local function installEnumHook()
	local oldEnumerate = Enumerate
	Enumerate = function (a_Name, a_Body, a_VarName)
		-- We need to remove the DoxyComment items from the enum
		-- otherwise ToLua++ parser would make an enum value out of them
		a_Body = string.gsub(a_Body, ",[%s\n]*}", "\n}") -- eliminate last ','
		local t = split(strsub(a_Body, 2, -2), ',') -- eliminate braces
		local doxyComments = {}
		local enumValues = {}
		local numEnumValues = 0
		for _, txt in ipairs(t) do
			txt = txt:gsub("(%b\17\18)",
				function (a_CommentID)
					doxyComments[numEnumValues + 1] = g_ForwardDoxyComments[tonumber(a_CommentID:sub(2, -2))]
					return ""
				end
			):gsub("(%b\19\20)",
				function (a_CommentID)
					doxyComments[numEnumValues] = g_BackwardDoxyComments[tonumber(a_CommentID:sub(2, -2))]
					return ""
				end
			)
			if (txt ~= "") then
				numEnumValues = numEnumValues + 1
				enumValues[numEnumValues] = txt
			end
		end
		local res = oldEnumerate(a_Name, "{" .. table.concat(enumValues, ",") .. "}", a_VarName)
		res.DoxyComments = doxyComments
		return res
	end
end





if not(TOLUA_VERSION) then
	-- BindingsProcessor has been called standalone, invoke the entire ToLua++ machinery:
	print("Generating Lua bindings and docs...")
	invokeToLua()
	return
else
	-- We're being executed from inside the ToLua++ parser. Install the needed hooks:
	installEnumHook()
end