summaryrefslogtreecommitdiffstats
path: root/src/Bindings/BindingsProcessor.lua
diff options
context:
space:
mode:
Diffstat (limited to 'src/Bindings/BindingsProcessor.lua')
-rw-r--r--src/Bindings/BindingsProcessor.lua205
1 files changed, 187 insertions, 18 deletions
diff --git a/src/Bindings/BindingsProcessor.lua b/src/Bindings/BindingsProcessor.lua
index e71684cdc..7f8a4caf0 100644
--- a/src/Bindings/BindingsProcessor.lua
+++ b/src/Bindings/BindingsProcessor.lua
@@ -15,6 +15,17 @@ The transformations implemented:
- 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
--]]
@@ -48,7 +59,12 @@ end
-local access = {public = 0, protected = 1, private = 2}
+local access =
+{
+ public = 0,
+ protected = 1,
+ private = 2
+}
@@ -65,20 +81,71 @@ 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))]
+ 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
@@ -334,7 +401,7 @@ local function outputClassVariableDocs(a_File, a_Class, a_Variables)
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\tDesc = ", string.format("%q", v.Desc.DoxyComment or ""), ",\n")
a_File:write("\t\t\t},\n")
end
a_File:write("\t\t},\n")
@@ -373,7 +440,7 @@ local function outputClassConstantDocs(a_File, a_Class, a_Constants, a_IgnoredCo
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\tDesc = ", string.format("%q", con.Desc.DoxyComment or ""), ",\n")
a_File:write("\t\t\t},\n")
end
a_File:write("\t\t},\n")
@@ -441,7 +508,7 @@ local function outputClassDocs(a_Class, a_Functions, a_Variables, a_Constants, a
-- 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")
+ f:write("\t\tDesc = ", string.format("%q", a_Class.DoxyComment or ""), ",\n")
-- If the class inherits from anything, output it here:
local ignoredConstants = {}
@@ -483,7 +550,39 @@ 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
+ print("Applying forward DoxyComment for " .. (a_Container[i].name or a_Container[i].cname or a_Container[i].lname or "<unknown name>"))
+ 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 = {}
@@ -650,6 +749,34 @@ 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
@@ -658,13 +785,17 @@ 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:
- classPackage.genDocs = genPackageDocs
- classClass.genDocs = genClassDocs
- classFunction.genMemberDocs = genFunctionMemberDocs
- classVariable.genMemberDocs = genVariableMemberDocs
- a_Package:genDocs()
+ 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
@@ -673,6 +804,44 @@ 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:
+ local f = assert(io.open("code_in.cpp", "wb"))
+ f:write(a_Package.code)
+ f:close()
+ a_Package.code = a_Package.code
+ :gsub("/%*%*%s*(.-)%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"
+ end
+ )
+ f = assert(io.open("code_out.cpp", "wb"))
+ f:write(a_Package.code)
+ f:close()
+end
+
+
+
+
+
if not(TOLUA_VERSION) then
-- BindingsProcessor has been called standalone, invoke the entire ToLua++ machinery:
print("Generating Lua bindings and docs...")