From 0958e167e89d2b3289c01905ebb8897e6bc86c43 Mon Sep 17 00:00:00 2001 From: Julian Laubstein Date: Tue, 11 Aug 2015 22:48:55 +0200 Subject: Updated APIDump to follow the namechange --- MCServer/Plugins/APIDump/main_APIDump.lua | 229 +++++++++++++++--------------- 1 file changed, 112 insertions(+), 117 deletions(-) (limited to 'MCServer/Plugins/APIDump/main_APIDump.lua') diff --git a/MCServer/Plugins/APIDump/main_APIDump.lua b/MCServer/Plugins/APIDump/main_APIDump.lua index 543a299af..4892d477d 100644 --- a/MCServer/Plugins/APIDump/main_APIDump.lua +++ b/MCServer/Plugins/APIDump/main_APIDump.lua @@ -20,7 +20,7 @@ local g_TrackedPages = {} local function LoadAPIFiles(a_Folder, a_DstTable) assert(type(a_Folder) == "string") assert(type(a_DstTable) == "table") - + local Folder = g_PluginFolder .. a_Folder; for _, fnam in ipairs(cFile:GetFolderContents(Folder)) do local FileName = Folder .. fnam; @@ -79,7 +79,7 @@ local function CreateAPITables() }, ... }, - + cCuboid = {} -- Each array item also has the map item by its name }; local Globals = { @@ -94,7 +94,7 @@ local function CreateAPITables() local Globals = {Functions = {}, Constants = {}, Variables = {}, Descendants = {}}; local API = {}; - + local function Add(a_APIContainer, a_ObjName, a_ObjValue) if (type(a_ObjValue) == "function") then table.insert(a_APIContainer.Functions, {Name = a_ObjName}); @@ -105,14 +105,14 @@ local function CreateAPITables() table.insert(a_APIContainer.Constants, {Name = a_ObjName, Value = a_ObjValue}); end end - + local function ParseClass(a_ClassName, a_ClassObj) local res = {Name = a_ClassName, Functions = {}, Constants = {}, Variables = {}, Descendants = {}}; -- Add functions and constants: for i, v in pairs(a_ClassObj) do Add(res, i, v); end - + -- Member variables: local SetField = a_ClassObj[".set"] or {}; if ((a_ClassObj[".get"] ~= nil) and (type(a_ClassObj[".get"]) == "table")) then @@ -128,7 +128,7 @@ local function CreateAPITables() end return res; end - + for i, v in pairs(_G) do if ( (v ~= _G) and -- don't want the global namespace @@ -145,7 +145,7 @@ local function CreateAPITables() end end end - + return API, Globals; end @@ -196,14 +196,14 @@ end local function LinkifyString(a_String, a_Referrer) assert(a_Referrer ~= nil); assert(a_Referrer ~= ""); - + --- Adds a page to the list of tracked pages (to be checked for existence at the end) local function AddTrackedPage(a_PageName) local Pg = (g_TrackedPages[a_PageName] or {}); table.insert(Pg, a_Referrer); g_TrackedPages[a_PageName] = Pg; end - + --- Creates the HTML for the specified link and title local function CreateLink(Link, Title) if (Link:sub(1, 7) == "http://") then @@ -226,7 +226,7 @@ local function LinkifyString(a_String, a_Referrer) AddTrackedPage(Link); return "" .. Title .. ""; end - + -- Linkify the strings using the CreateLink() function: local txt = a_String:gsub("{{([^|}]*)|([^}]*)}}", CreateLink) -- {{link|title}} txt = txt:gsub("{{([^|}]*)}}", -- {{LinkAndTitle}} @@ -254,10 +254,10 @@ local function WriteHtmlHook(a_Hook, a_HookNav) return; end local HookName = a_Hook.DefaultFnName; - + f:write([[ - MCServer API - ]], HookName, [[ Hook + Cuberite API - ]], HookName, [[ Hook @@ -330,7 +330,7 @@ local function WriteHooks(f, a_Hooks, a_UndocumentedHooks, a_HookNav) A plugin can decide whether it will let the event pass through to the rest of the plugins, or hide it from them. This is determined by the return value from the hook callback function. If the function returns false or no value, the event is propagated further. If the function returns true, the processing - is stopped, no other plugin receives the notification (and possibly MCServer disables the default + is stopped, no other plugin receives the notification (and possibly Cuberite disables the default behavior for the event). See each hook's details to see the exact behavior.

@@ -371,7 +371,7 @@ local function ReadDescriptions(a_API) end return false; end - + -- Returns true if the function is to be ignored local function IsFunctionIgnored(a_ClassName, a_FnName) if (g_APIDesc.IgnoreFunctions == nil) then @@ -389,7 +389,7 @@ local function ReadDescriptions(a_API) end return false; end - + -- Returns true if the constant (specified by its fully qualified name) is to be ignored local function IsConstantIgnored(a_CnName) if (g_APIDesc.IgnoreConstants == nil) then @@ -402,7 +402,7 @@ local function ReadDescriptions(a_API) end return false; end - + -- Returns true if the member variable (specified by its fully qualified name) is to be ignored local function IsVariableIgnored(a_VarName) if (g_APIDesc.IgnoreVariables == nil) then @@ -415,7 +415,7 @@ local function ReadDescriptions(a_API) end return false; end - + -- Remove ignored classes from a_API: local APICopy = {}; for _, cls in ipairs(a_API) do @@ -433,7 +433,7 @@ local function ReadDescriptions(a_API) cls.ConstantGroups = {}; cls.NumConstantsInGroups = 0; cls.NumConstantsInGroupsForDescendants = 0; - + -- Rename special functions: for _, fn in ipairs(cls.Functions) do if (fn.Name == ".call") then @@ -456,13 +456,13 @@ local function ReadDescriptions(a_API) fn.Name = "operator =="; end end - + local APIDesc = g_APIDesc.Classes[cls.Name]; if (APIDesc ~= nil) then APIDesc.IsExported = true; cls.Desc = APIDesc.Desc; cls.AdditionalInfo = APIDesc.AdditionalInfo; - + -- Process inheritance: if (APIDesc.Inherits ~= nil) then for _, icls in ipairs(a_API) do @@ -476,13 +476,13 @@ local function ReadDescriptions(a_API) cls.UndocumentedFunctions = {}; -- This will contain names of all the functions that are not documented cls.UndocumentedConstants = {}; -- This will contain names of all the constants that are not documented cls.UndocumentedVariables = {}; -- This will contain names of all the variables that are not documented - + local DoxyFunctions = {}; -- This will contain all the API functions together with their documentation - + local function AddFunction(a_Name, a_Params, a_Return, a_Notes) table.insert(DoxyFunctions, {Name = a_Name, Params = a_Params, Return = a_Return, Notes = a_Notes}); end - + if (APIDesc.Functions ~= nil) then -- Assign function descriptions: for _, func in ipairs(cls.Functions) do @@ -508,7 +508,7 @@ local function ReadDescriptions(a_API) FnDesc.IsExported = true; end end -- for j, func - + -- Replace functions with their described and overload-expanded versions: cls.Functions = DoxyFunctions; else -- if (APIDesc.Functions ~= nil) @@ -519,7 +519,7 @@ local function ReadDescriptions(a_API) end end end -- if (APIDesc.Functions ~= nil) - + if (APIDesc.Constants ~= nil) then -- Assign constant descriptions: for _, cons in ipairs(cls.Constants) do @@ -541,7 +541,7 @@ local function ReadDescriptions(a_API) end end end -- else if (APIDesc.Constants ~= nil) - + -- Assign member variables' descriptions: if (APIDesc.Variables ~= nil) then for _, var in ipairs(cls.Variables) do @@ -565,7 +565,7 @@ local function ReadDescriptions(a_API) end end end -- else if (APIDesc.Variables ~= nil) - + if (APIDesc.ConstantGroups ~= nil) then -- Create links between the constants and the groups: local NumInGroups = 0; @@ -590,7 +590,7 @@ local function ReadDescriptions(a_API) if (group.ShowInDescendants) then NumInDescendantGroups = NumInDescendantGroups + NumInGroup; end - + -- Sort the constants: table.sort(group.Constants, function(c1, c2) @@ -601,7 +601,7 @@ local function ReadDescriptions(a_API) cls.ConstantGroups = APIDesc.ConstantGroups; cls.NumConstantsInGroups = NumInGroups; cls.NumConstantsInGroupsForDescendants = NumInDescendantGroups; - + -- Remove grouped constants from the normal list: local NewConstants = {}; for _, cons in ipairs(cls.Constants) do @@ -611,9 +611,9 @@ local function ReadDescriptions(a_API) end cls.Constants = NewConstants; end -- if (ConstantGroups ~= nil) - + else -- if (APIDesc ~= nil) - + -- Class is not documented at all, add all its members to Undocumented lists: cls.UndocumentedFunctions = {}; cls.UndocumentedConstants = {}; @@ -637,7 +637,7 @@ local function ReadDescriptions(a_API) end end -- for j, var - cls.Variables[] end -- else if (APIDesc ~= nil) - + -- Remove ignored functions: local NewFunctions = {}; for _, fn in ipairs(cls.Functions) do @@ -660,7 +660,7 @@ local function ReadDescriptions(a_API) return (f1.Name < f2.Name); end ); - + -- Remove ignored constants: local NewConstants = {}; for _, cn in ipairs(cls.Constants) do @@ -669,14 +669,14 @@ local function ReadDescriptions(a_API) end end -- for j, cn cls.Constants = NewConstants; - + -- Sort the constants: table.sort(cls.Constants, function(c1, c2) return (c1.Name < c2.Name); end ); - + -- Remove ignored member variables: local NewVariables = {}; for _, var in ipairs(cls.Variables) do @@ -685,7 +685,7 @@ local function ReadDescriptions(a_API) end end -- for j, var cls.Variables = NewVariables; - + -- Sort the member variables: table.sort(cls.Variables, function(v1, v2) @@ -693,7 +693,7 @@ local function ReadDescriptions(a_API) end ); end -- for i, cls - + -- Sort the descendants lists: for _, cls in ipairs(a_API) do table.sort(cls.Descendants, @@ -738,7 +738,7 @@ local function WriteHtmlClass(a_ClassAPI, a_ClassMenu) LOGINFO("Cannot write HTML API for class " .. a_ClassAPI.Name .. ": " .. err) return; end - + -- Writes a table containing all functions in the specified list, with an optional "inherited from" header when a_InheritedName is valid local function WriteFunctions(a_Functions, a_InheritedName) if (#a_Functions == 0) then @@ -757,7 +757,7 @@ local function WriteHtmlClass(a_ClassAPI, a_ClassMenu) end cf:write("
\n"); end - + local function WriteConstantTable(a_Constants, a_Source) cf:write("\n\n"); for _, cons in ipairs(a_Constants) do @@ -767,22 +767,22 @@ local function WriteHtmlClass(a_ClassAPI, a_ClassMenu) end cf:write("
NameValueNotes
\n\n"); end - + local function WriteConstants(a_Constants, a_ConstantGroups, a_NumConstantGroups, a_InheritedName) if ((#a_Constants == 0) and (a_NumConstantGroups == 0)) then return; end - + local Source = a_ClassAPI.Name if (a_InheritedName ~= nil) then cf:write("

Constants inherited from ", a_InheritedName, "

\n"); Source = a_InheritedName; end - + if (#a_Constants > 0) then WriteConstantTable(a_Constants, Source); end - + for _, group in pairs(a_ConstantGroups) do if ((a_InheritedName == nil) or group.ShowInDescendants) then cf:write("

"); @@ -792,16 +792,16 @@ local function WriteHtmlClass(a_ClassAPI, a_ClassMenu) end end end - + local function WriteVariables(a_Variables, a_InheritedName) if (#a_Variables == 0) then return; end - + if (a_InheritedName ~= nil) then cf:write("

Member variables inherited from ", a_InheritedName, "

\n"); end - + cf:write("\n"); for _, var in ipairs(a_Variables) do cf:write("\n"); @@ -810,7 +810,7 @@ local function WriteHtmlClass(a_ClassAPI, a_ClassMenu) end cf:write("
NameTypeNotes
", var.Name, "
\n\n"); end - + local function WriteDescendants(a_Descendants) if (#a_Descendants == 0) then return; @@ -823,7 +823,7 @@ local function WriteHtmlClass(a_ClassAPI, a_ClassMenu) end cf:write("\n"); end - + local ClassName = a_ClassAPI.Name; -- Build an array of inherited classes chain: @@ -833,10 +833,10 @@ local function WriteHtmlClass(a_ClassAPI, a_ClassMenu) table.insert(InheritanceChain, CurrInheritance); CurrInheritance = CurrInheritance.Inherits; end - + cf:write([[ - MCServer API - ]], a_ClassAPI.Name, [[ Class + Cuberite API - ]], a_ClassAPI.Name, [[ Class @@ -861,9 +861,9 @@ local function WriteHtmlClass(a_ClassAPI, a_ClassMenu)

Contents

\n"); - + -- Write the class description: cf:write("

", ClassName, " class

\n"); if (a_ClassAPI.Desc ~= nil) then @@ -900,7 +900,7 @@ local function WriteHtmlClass(a_ClassAPI, a_ClassMenu) cf:write(LinkifyString(a_ClassAPI.Desc, ClassName)); cf:write("

\n\n"); end; - + -- Write the inheritance, if available: if (HasInheritance) then cf:write("

Inheritance

\n"); @@ -917,7 +917,7 @@ local function WriteHtmlClass(a_ClassAPI, a_ClassMenu) cf:write("

\n\n"); end end - + -- Write the constants: if (HasConstants) then cf:write("

Constants

\n"); @@ -927,7 +927,7 @@ local function WriteHtmlClass(a_ClassAPI, a_ClassMenu) WriteConstants(cls.Constants, cls.ConstantGroups, cls.NumConstantsInGroupsForDescendants, cls.Name); end; end; - + -- Write the member variables: if (HasVariables) then cf:write("

Member variables

\n"); @@ -937,7 +937,7 @@ local function WriteHtmlClass(a_ClassAPI, a_ClassMenu) WriteVariables(cls.Variables, cls.Name); end; end - + -- Write the functions, including the inherited ones: if (HasFunctions) then cf:write("

Functions

\n"); @@ -947,7 +947,7 @@ local function WriteHtmlClass(a_ClassAPI, a_ClassMenu) WriteFunctions(cls.Functions, cls.Name); end end - + -- Write the additional infos: if (a_ClassAPI.AdditionalInfo ~= nil) then for i, additional in ipairs(a_ClassAPI.AdditionalInfo) do @@ -969,7 +969,7 @@ end local function WriteClasses(f, a_API, a_ClassMenu) f:write([[

Class index

 -

The following classes are available in the MCServer Lua scripting language: +

The following classes are available in the Cuberite Lua scripting language:

]]); - + WriteArticles(f); WriteClasses(f, a_API, ClassMenu); WriteHooks(f, Hooks, UndocumentedHooks, HookNav); - + -- Copy the static files to the output folder: local StaticFiles = { @@ -1328,7 +1328,7 @@ local function DumpAPIHtml(a_API) cFile:Delete("API/" .. fnam); cFile:Copy(g_Plugin:GetLocalFolder() .. "/" .. fnam, "API/" .. fnam); end - + -- List the documentation problems: LOG("Listing leftovers..."); ListUndocumentedObjects(a_API, UndocumentedHooks); @@ -1336,12 +1336,12 @@ local function DumpAPIHtml(a_API) ListMissingPages(); WriteStats(f); - + f:write([[]]) f:write(GetHtmlTimestamp()) f:write([[]]) f:close() - + LOG("API subfolder written"); end @@ -1354,16 +1354,16 @@ local function CleanUpDescription(a_Desc) -- Get rid of indent and newlines, normalize whitespace: local res = a_Desc:gsub("[\n\t]", "") res = a_Desc:gsub("%s%s+", " ") - + -- Replace paragraph marks with newlines: res = res:gsub("

", "\n") res = res:gsub("

", "") - + -- Replace list items with dashes: res = res:gsub("", "") res = res:gsub("
  • ", "\n - ") res = res:gsub("
    • ", "") - + return res end @@ -1405,21 +1405,21 @@ end ---- Writes one MCS class definition into the specified file in ZBS format +--- Writes one Cuberite class definition into the specified file in ZBS format local function WriteZBSClass(f, a_Class) assert(type(a_Class) == "table") - + -- Write class header: f:write("\t", a_Class.Name, " =\n\t{\n") f:write("\t\ttype = \"class\",\n") f:write("\t\tdescription = [[", CleanUpDescription(a_Class.Desc or ""), " ]],\n") f:write("\t\tchilds =\n") f:write("\t\t{\n") - + -- Export methods and constants: WriteZBSMethods(f, a_Class.Functions) WriteZBSConstants(f, a_Class.Constants) - + -- Finish the class definition: f:write("\t\t},\n") f:write("\t},\n\n") @@ -1437,12 +1437,12 @@ local function DumpAPIZBS(a_API) LOG("Cannot open mcserver_lua.lua for writing, ZBS API will not be dumped. " .. err) return end - + -- Write the file header: - f:write("-- This is a MCServer API file automatically generated by the APIDump plugin\n") + f:write("-- This is a Cuberite API file automatically generated by the APIDump plugin\n") f:write("-- Note that any manual changes will be overwritten by the next dump\n\n") f:write("return {\n") - + -- Export each class except Globals, store those aside: local Globals for _, cls in ipairs(a_API) do @@ -1452,13 +1452,13 @@ local function DumpAPIZBS(a_API) Globals = cls end end - + -- Export the globals: if (Globals) then WriteZBSMethods(f, Globals.Functions) WriteZBSConstants(f, Globals.Constants) end - + -- Finish the file: f:write("}\n") f:close() @@ -1480,21 +1480,21 @@ local function IsDeclaredDescendant(a_DescendantName, a_BaseName, a_API) end assert(type(a_API[a_BaseName]) == "table", "Not a class name: " .. a_BaseName) assert(type(a_API[a_BaseName].Descendants) == "table") - + -- Check direct inheritance: for _, desc in ipairs(a_API[a_BaseName].Descendants) do if (desc.Name == a_DescendantName) then return true end end -- for desc - a_BaseName's descendants - + -- Check indirect inheritance: for _, desc in ipairs(a_API[a_BaseName].Descendants) do if (IsDeclaredDescendant(a_DescendantName, desc.Name, a_API)) then return true end end -- for desc - a_BaseName's descendants - + return false end @@ -1509,7 +1509,7 @@ local function CheckClassInheritance(a_Class, a_API, a_Report) assert(type(a_Class) == "table") assert(type(a_API) == "table") assert(type(a_Report) == "table") - + -- Check that the declared descendants are really descendants: local registry = debug.getregistry() for _, desc in ipairs(a_Class.Descendants or {}) do @@ -1519,7 +1519,7 @@ local function CheckClassInheritance(a_Class, a_API, a_Report) table.insert(a_Report, desc.Name .. " is not a descendant of " .. a_Class.Name) end end -- for desc - a_Class.Descendants[] - + -- Check that all inheritance is listed for the class: local parents = registry["tolua_super"][_G[a_Class.Name]] -- map of "classname" -> true for each class that a_Class inherits for clsName, isParent in pairs(parents or {}) do @@ -1544,7 +1544,7 @@ local function CheckAPIDescendants(a_API) CheckClassInheritance(cls, a_API, report) end end - + -- If there's anything to report, output it to a file: if (report[1] ~= nil) then LOG("There are inheritance errors in the API description:") @@ -1568,7 +1568,7 @@ end local function DumpApi() LOG("Dumping the API...") - + -- Load the API descriptions from the Classes and Hooks subfolders: -- This needs to be done each time the command is invoked because the export modifies the tables' contents dofile(g_PluginFolder .. "/APIDesc.lua") @@ -1598,10 +1598,10 @@ local function DumpApi() NumTrackedLinks = 0, NumInvalidLinks = 0, } - + -- Create the API tables: local API, Globals = CreateAPITables(); - + -- Sort the classes by name: table.sort(API, function (c1, c2) @@ -1609,24 +1609,24 @@ local function DumpApi() end ); g_Stats.NumTotalClasses = #API; - + -- Add Globals into the API: Globals.Name = "Globals"; table.insert(API, Globals); - + -- Read in the descriptions: LOG("Reading descriptions..."); ReadDescriptions(API); -- Check that the API lists the inheritance properly, report any problems to a file: CheckAPIDescendants(API) - + -- Dump all available API objects in HTML format into a subfolder: DumpAPIHtml(API); - + -- Dump all available API objects in format used by ZeroBraneStudio API descriptions: DumpAPIZBS(API) - + LOG("APIDump finished"); return true end @@ -1671,20 +1671,15 @@ end function Initialize(Plugin) g_Plugin = Plugin; g_PluginFolder = Plugin:GetLocalFolder(); - + LOG("Initialising " .. Plugin:GetName() .. " v." .. Plugin:GetVersion()) - + -- Bind a console command to dump the API: cPluginManager:BindConsoleCommand("api", HandleCmdApi, "Dumps the Lua API docs into the API/ subfolder") cPluginManager:BindConsoleCommand("apishow", HandleCmdApiShow, "Runs the default browser to show the API docs") -- Add a WebAdmin tab that has a Dump button g_Plugin:AddWebTab("APIDump", HandleWebAdminDump) - + return true end - - - - - -- cgit v1.2.3