diff options
Diffstat (limited to 'src/Bindings/BindingsProcessor.lua')
| -rw-r--r-- | src/Bindings/BindingsProcessor.lua | 205 |
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...") |