summaryrefslogtreecommitdiffstats
path: root/src/Bindings/BindingsProcessor.lua
diff options
context:
space:
mode:
authorMattes D <github@xoft.cz>2016-07-19 10:15:49 +0200
committerGitHub <noreply@github.com>2016-07-19 10:15:49 +0200
commitc54691a3e578c0c33f0e196959a4c224883b1c93 (patch)
treebb258a4eb246e062e3ad9b3cfa2119411bb1d4ac /src/Bindings/BindingsProcessor.lua
parentFixes for boat entities (#3265) (diff)
parentCMake: Silenced CMP0054 policy warning. (diff)
downloadcuberite-c54691a3e578c0c33f0e196959a4c224883b1c93.tar
cuberite-c54691a3e578c0c33f0e196959a4c224883b1c93.tar.gz
cuberite-c54691a3e578c0c33f0e196959a4c224883b1c93.tar.bz2
cuberite-c54691a3e578c0c33f0e196959a4c224883b1c93.tar.lz
cuberite-c54691a3e578c0c33f0e196959a4c224883b1c93.tar.xz
cuberite-c54691a3e578c0c33f0e196959a4c224883b1c93.tar.zst
cuberite-c54691a3e578c0c33f0e196959a4c224883b1c93.zip
Diffstat (limited to '')
-rw-r--r--src/Bindings/BindingsProcessor.lua843
1 files changed, 831 insertions, 12 deletions
diff --git a/src/Bindings/BindingsProcessor.lua b/src/Bindings/BindingsProcessor.lua
index e7b909ded..28a6a053c 100644
--- a/src/Bindings/BindingsProcessor.lua
+++ b/src/Bindings/BindingsProcessor.lua
@@ -3,11 +3,68 @@
-- 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}
+local access =
+{
+ public = 0,
+ protected = 1,
+ private = 2
+}
@@ -24,20 +81,73 @@ local g_HasCustomPushImplementation =
-function parser_hook(s)
- local container = classContainer.curr -- get the current container
+--- 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,
+}
+
+
+
+
- -- process access-specifying labels (public, private, etc)
+--- 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(s, "^%s*(%w*)%s*:[^:]") -- we need to check for [^:], otherwise it would match 'namespace::type'
+ 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 from the global 'access' table
+ -- Found a label, get the new access value for it:
if access[label] then
- container.curr_member_access = access[label]
+ classContainer.curr.curr_member_access = access[label]
end -- else ?
-
- return strsub(s, e) -- normally we would use 'e+1', but we need to preserve the [^:]
+ 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))]
+ else
+ curr.first_child_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
@@ -163,16 +273,725 @@ 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.IsStatic) then
+ a_File:write("\t\t\t\t\tIsStatic = true,\n")
+ end
+ 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, and first_child_DoxyComment to first child item in the container.
+-- a_Container is the ToLua++'s table potentially containing children as its array members
+local function applyNextDoxyComments(a_Container)
+ -- Apply the DoxyComment to the first child, if appropriate:
+ if (a_Container[1] and a_Container.first_child_DoxyComment) then
+ a_Container[1].DoxyComment = a_Container.first_child_DoxyComment
+ end
+
+ -- Apply each child's next_DoxyComment to the actual next child:
+ 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]:check_public_access() and -- Do not export private and protected members
+ 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]:check_public_access() and -- Don't export private and protected members
+ 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),
+ }
+ local _, _, hasStatic = string.find(a_Self.mod, "^%s*(static)")
+ if (hasStatic) then
+ desc.IsStatic = true
+ end
+ 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 (string.find(a_Self.type,'const%s+') or string.find(a_Self.mod, 'tolua_readonly') or string.find(a_Self.mod, 'tolua_inherits')) then
+ a_Constants[a_Self.lname] = desc
+ else
+ a_Variables[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)
+
+ -- Generate the documentation:
+ -- (must generate documentation before ToLua++ writes the bindings, because "static" information is lost at that point)
+ local isSuccess, msg = generateDocs(a_Package)
+ if not(isSuccess) then
+ print("API docs haven't been generated due to an error: " .. (msg or "<no message>"))
+ else
+ print("API docs have been generated.");
+ end
+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)
+ print("Lua bindings 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
+ ) -- Replace ///< comments with an ID into a lookup table wrapped in DC3 and DC4
+ 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
-function post_output_hook()
- print("Bindings have been generated.")
+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