summaryrefslogtreecommitdiffstats
path: root/src
diff options
context:
space:
mode:
Diffstat (limited to 'src')
-rw-r--r--src/Bindings/.gitignore1
-rw-r--r--src/Bindings/BindingsProcessor.lua509
-rw-r--r--src/CMakeLists.txt3
3 files changed, 511 insertions, 2 deletions
diff --git a/src/Bindings/.gitignore b/src/Bindings/.gitignore
index 711ae9c3a..16f9db55d 100644
--- a/src/Bindings/.gitignore
+++ b/src/Bindings/.gitignore
@@ -1,3 +1,4 @@
+docs/
lua51.dll
LuaState_Declaration.inc
LuaState_Implementation.cpp
diff --git a/src/Bindings/BindingsProcessor.lua b/src/Bindings/BindingsProcessor.lua
index e7b909ded..e71684cdc 100644
--- a/src/Bindings/BindingsProcessor.lua
+++ b/src/Bindings/BindingsProcessor.lua
@@ -3,6 +3,47 @@
-- 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
+--]]
+
+
+
+
+
+--- 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
+
@@ -163,6 +204,452 @@ 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
+ a_File:write("\t\t\t", fn.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\t\t\t\t\tDesc = ", string.format("%q", desc.DoxyComment or ""), ",\n")
+ 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")
+ a_File:write("\t\t\t\tDesc = [[", v.Desc.DoxyComment or "", "]],\n")
+ 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")
+ a_File:write("\t\t\t\tDesc = [[", con.Desc.DoxyComment or "", "]],\n")
+ 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 = {}
+ local idx = 1
+ for _, valname in ipairs(enum.lnames) do
+ valnames[idx] = valname
+ idx = idx + 1
+ end
+ table.sort(valnames)
+ for _, valname in ipairs(valnames) do
+ a_File:write("\t\t\t\t\"", valname, "\",\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")
+ f:write("\t\tDesc = [[", a_Class.doxycomment or "", "]],\n")
+
+ -- 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
+
+
+
+
+
+local function genPackageDocs(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
+
+
+
+
+
function pre_output_hook(a_Package)
OutputLuaStateHelpers(a_Package)
end
@@ -171,8 +658,26 @@ end
-function post_output_hook()
- print("Bindings have been generated.")
+function post_output_hook(a_Package)
+ -- Generate the documentation:
+ classPackage.genDocs = genPackageDocs
+ classClass.genDocs = genClassDocs
+ classFunction.genMemberDocs = genFunctionMemberDocs
+ classVariable.genMemberDocs = genVariableMemberDocs
+ a_Package:genDocs()
+
+ print("Lua bindings and docs have been generated.")
+end
+
+
+
+
+
+if not(TOLUA_VERSION) then
+ -- BindingsProcessor has been called standalone, invoke the entire ToLua++ machinery:
+ print("Generating Lua bindings and docs...")
+ invokeToLua()
+ return
end
diff --git a/src/CMakeLists.txt b/src/CMakeLists.txt
index 76a18801d..5bf55c81f 100644
--- a/src/CMakeLists.txt
+++ b/src/CMakeLists.txt
@@ -378,3 +378,6 @@ if (${CMAKE_SYSTEM_NAME} STREQUAL "FreeBSD")
endif()
target_link_libraries(${EXECUTABLE} luaexpat jsoncpp_lib_static mbedtls zlib sqlite lua SQLiteCpp event_core event_extra)
+
+# Create a folder for Bindings' documentation:
+FILE(MAKE_DIRECTORY "Bindings/docs")