diff options
| -rw-r--r-- | MCServer/Plugins/APIDump/main_APIDump.lua | 973 | ||||
| -rw-r--r-- | src/Bindings/LuaChunkStay.cpp | 3 | ||||
| -rw-r--r-- | src/Bindings/LuaState.cpp | 10 | ||||
| -rw-r--r-- | src/Bindings/LuaState.h | 4 |
4 files changed, 537 insertions, 453 deletions
diff --git a/MCServer/Plugins/APIDump/main_APIDump.lua b/MCServer/Plugins/APIDump/main_APIDump.lua index 4ed692b52..7455c3cd2 100644 --- a/MCServer/Plugins/APIDump/main_APIDump.lua +++ b/MCServer/Plugins/APIDump/main_APIDump.lua @@ -7,92 +7,22 @@ -- Global variables: -g_Plugin = nil; -g_PluginFolder = ""; +local g_Plugin = nil +local g_PluginFolder = "" +local g_Stats = {} +local g_TrackedPages = {} -function Initialize(Plugin) - g_Plugin = Plugin; - g_PluginFolder = Plugin:GetLocalFolder(); - - LOG("Initialising " .. Plugin:GetName() .. " v." .. Plugin:GetVersion()) - - cPluginManager:BindConsoleCommand("api", HandleCmdApi, "Dumps the Lua API docs into the API/ subfolder") - g_Plugin:AddWebTab("APIDump", HandleWebAdminDump) - -- TODO: Add a WebAdmin tab that has a Dump button - return true -end - - - - - -function HandleCmdApi(a_Split) - DumpApi() - return true -end - - - - - -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") - if (g_APIDesc.Classes == nil) then - g_APIDesc.Classes = {}; - end - if (g_APIDesc.Hooks == nil) then - g_APIDesc.Hooks = {}; - end - LoadAPIFiles("/Classes/", g_APIDesc.Classes); - LoadAPIFiles("/Hooks/", g_APIDesc.Hooks); - - -- Reset the stats: - g_TrackedPages = {}; -- List of tracked pages, to be checked later whether they exist. Each item is an array of referring pagenames. - g_Stats = -- Statistics about the documentation - { - NumTotalClasses = 0, - NumUndocumentedClasses = 0, - NumTotalFunctions = 0, - NumUndocumentedFunctions = 0, - NumTotalConstants = 0, - NumUndocumentedConstants = 0, - NumTotalVariables = 0, - NumUndocumentedVariables = 0, - NumTotalHooks = 0, - NumUndocumentedHooks = 0, - NumTrackedLinks = 0, - NumInvalidLinks = 0, - } - - -- dump all available API functions and objects: - -- DumpAPITxt(); - - -- Dump all available API object in HTML format into a subfolder: - DumpAPIHtml(); - - LOG("APIDump finished"); - return true -end - - - - - -function LoadAPIFiles(a_Folder, a_DstTable) +local function LoadAPIFiles(a_Folder, a_DstTable) assert(type(a_Folder) == "string") assert(type(a_DstTable) == "table") local Folder = g_PluginFolder .. a_Folder; - for idx, fnam in ipairs(cFile:GetFolderContents(Folder)) do + for _, fnam in ipairs(cFile:GetFolderContents(Folder)) do local FileName = Folder .. fnam; -- We only want .lua files from the folder: if (cFile:IsFile(FileName) and fnam:match(".*%.lua$")) then @@ -113,45 +43,7 @@ end -function DumpAPITxt() - LOG("Dumping all available functions to API.txt..."); - function dump (prefix, a, Output) - for i, v in pairs (a) do - if (type(v) == "table") then - if (GetChar(i, 1) ~= ".") then - if (v == _G) then - -- LOG(prefix .. i .. " == _G, CYCLE, ignoring"); - elseif (v == _G.package) then - -- LOG(prefix .. i .. " == _G.package, ignoring"); - else - dump(prefix .. i .. ".", v, Output) - end - end - elseif (type(v) == "function") then - if (string.sub(i, 1, 2) ~= "__") then - table.insert(Output, prefix .. i .. "()"); - end - end - end - end - - local Output = {}; - dump("", _G, Output); - - table.sort(Output); - local f = io.open("API.txt", "w"); - for i, n in ipairs(Output) do - f:write(n, "\n"); - end - f:close(); - LOG("API.txt written."); -end - - - - - -function CreateAPITables() +local function CreateAPITables() --[[ We want an API table of the following shape: local API = { @@ -218,7 +110,7 @@ function CreateAPITables() -- Member variables: local SetField = a_ClassObj[".set"] or {}; if ((a_ClassObj[".get"] ~= nil) and (type(a_ClassObj[".get"]) == "table")) then - for k, v in pairs(a_ClassObj[".get"]) do + for k in pairs(a_ClassObj[".get"]) do if (SetField[k] == nil) then -- It is a read-only variable, add it as a constant: table.insert(res.Constants, {Name = k, Value = ""}); @@ -259,7 +151,7 @@ local function WriteArticles(f) <p>The following articles provide various extra information on plugin development</p> <ul> ]]); - for i, extra in ipairs(g_APIDesc.ExtraPages) do + for _, extra in ipairs(g_APIDesc.ExtraPages) do local SrcFileName = g_PluginFolder .. "/" .. extra.FileName; if (cFile:Exists(SrcFileName)) then local DstFileName = "API/" .. extra.FileName; @@ -279,20 +171,125 @@ end -local function WriteClasses(f, a_API, a_ClassMenu) - f:write([[ - <a name="classes"><h2>Class index</h2></a> - <p>The following classes are available in the MCServer Lua scripting language: - <ul> - ]]); - for i, cls in ipairs(a_API) do - f:write("<li><a href=\"", cls.Name, ".html\">", cls.Name, "</a></li>\n"); - WriteHtmlClass(cls, a_API, a_ClassMenu); +-- Make a link out of anything with the special linkifying syntax {{link|title}} +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 - f:write([[ - </ul></p> + + --- Creates the HTML for the specified link and title + local function CreateLink(Link, Title) + if (Link:sub(1, 7) == "http://") then + -- The link is a full absolute URL, do not modify, do not track: + return "<a href=\"" .. Link .. "\">" .. Title .. "</a>"; + end + local idxHash = Link:find("#"); + if (idxHash ~= nil) then + -- The link contains an anchor: + if (idxHash == 1) then + -- Anchor in the current page, no need to track: + return "<a href=\"" .. Link .. "\">" .. Title .. "</a>"; + end + -- Anchor in another page: + local PageName = Link:sub(1, idxHash - 1); + AddTrackedPage(PageName); + return "<a href=\"" .. PageName .. ".html#" .. Link:sub(idxHash + 1) .. "\">" .. Title .. "</a>"; + end + -- Link without anchor: + AddTrackedPage(Link); + return "<a href=\"" .. Link .. ".html\">" .. Title .. "</a>"; + end + + -- Linkify the strings using the CreateLink() function: + local txt = a_String:gsub("{{([^|}]*)|([^}]*)}}", CreateLink) -- {{link|title}} + txt = txt:gsub("{{([^|}]*)}}", -- {{LinkAndTitle}} + function(LinkAndTitle) + local idxHash = LinkAndTitle:find("#"); + if (idxHash ~= nil) then + -- The LinkAndTitle contains a hash, remove the hashed part from the title: + return CreateLink(LinkAndTitle, LinkAndTitle:sub(1, idxHash - 1)); + end + return CreateLink(LinkAndTitle, LinkAndTitle); + end + ); + return txt; +end + + + + + +local function WriteHtmlHook(a_Hook, a_HookNav) + local fnam = "API/" .. a_Hook.DefaultFnName .. ".html"; + local f, error = io.open(fnam, "w"); + if (f == nil) then + LOG("Cannot write \"" .. fnam .. "\": \"" .. error .. "\"."); + return; + end + local HookName = a_Hook.DefaultFnName; + + f:write([[<!DOCTYPE html><html> + <head> + <title>MCServer API - ]], HookName, [[ Hook</title> + <link rel="stylesheet" type="text/css" href="main.css" /> + <link rel="stylesheet" type="text/css" href="prettify.css" /> + <script src="prettify.js"></script> + <script src="lang-lua.js"></script> + </head> + <body> + <div id="content"> + <header> + <h1>]], a_Hook.Name, [[</h1> <hr /> + </header> + <table><tr><td style="vertical-align: top;"> + Index:<br /> + <a href='index.html#articles'>Articles</a><br /> + <a href='index.html#classes'>Classes</a><br /> + <a href='index.html#hooks'>Hooks</a><br /> + <br /> + Quick navigation:<br /> + ]]); + f:write(a_HookNav); + f:write([[ + </td><td style="vertical-align: top;"><p> ]]); + f:write(LinkifyString(a_Hook.Desc, HookName)); + f:write("</p>\n<hr /><h1>Callback function</h1>\n<p>The default name for the callback function is "); + f:write(a_Hook.DefaultFnName, ". It has the following signature:\n"); + f:write("<pre class=\"prettyprint lang-lua\">function ", HookName, "("); + if (a_Hook.Params == nil) then + a_Hook.Params = {}; + end + for i, param in ipairs(a_Hook.Params) do + if (i > 1) then + f:write(", "); + end + f:write(param.Name); + end + f:write(")</pre>\n<hr /><h1>Parameters:</h1>\n<table><tr><th>Name</th><th>Type</th><th>Notes</th></tr>\n"); + for _, param in ipairs(a_Hook.Params) do + f:write("<tr><td>", param.Name, "</td><td>", LinkifyString(param.Type, HookName), "</td><td>", LinkifyString(param.Notes, HookName), "</td></tr>\n"); + end + f:write("</table>\n<p>" .. (a_Hook.Returns or "") .. "</p>\n\n"); + f:write([[<hr /><h1>Code examples</h1><h2>Registering the callback</h2>]]); + f:write("<pre class=\"prettyprint lang-lua\">\n"); + f:write([[cPluginManager:AddHook(cPluginManager.]] .. a_Hook.Name .. ", My" .. a_Hook.DefaultFnName .. [[);]]); + f:write("</pre>\n\n"); + local Examples = a_Hook.CodeExamples or {}; + for _, example in ipairs(Examples) do + f:write("<h2>", (example.Title or "<i>missing Title</i>"), "</h2>\n"); + f:write("<p>", (example.Desc or "<i>missing Desc</i>"), "</p>\n"); + f:write("<pre class=\"prettyprint lang-lua\">", (example.Code or "<i>missing Code</i>"), "\n</pre>\n\n"); + end + f:write([[</td></tr></table></div><script>prettyPrint();</script></body></html>]]); + f:close(); end @@ -318,7 +315,7 @@ local function WriteHooks(f, a_Hooks, a_UndocumentedHooks, a_HookNav) <th>Called when</th> </tr> ]]); - for i, hook in ipairs(a_Hooks) do + for _, hook in ipairs(a_Hooks) do if (hook.DefaultFnName == nil) then -- The hook is not documented yet f:write(" <tr>\n <td>" .. hook.Name .. "</td>\n <td><i>(No documentation yet)</i></td>\n </tr>\n"); @@ -338,162 +335,13 @@ end -function DumpAPIHtml() - LOG("Dumping all available functions and constants to API subfolder..."); - - -- Create the output folder - if not(cFile:IsFolder("API")) then - cFile:CreateFolder("API"); - end - - LOG("Copying static files.."); - cFile:CreateFolder("API/Static"); - local localFolder = g_Plugin:GetLocalFolder(); - for idx, fnam in ipairs(cFile:GetFolderContents(localFolder .. "/Static")) do - cFile:Delete("API/Static/" .. fnam); - cFile:Copy(localFolder .. "/Static/" .. fnam, "API/Static/" .. fnam); - end - - LOG("Creating API tables..."); - local API, Globals = CreateAPITables(); - local Hooks = {}; - local UndocumentedHooks = {}; - - -- Sort the classes by name: - LOG("Sorting..."); - table.sort(API, - function (c1, c2) - return (string.lower(c1.Name) < string.lower(c2.Name)); - end - ); - - g_Stats.NumTotalClasses = #API; - - -- Add Globals into the API: - Globals.Name = "Globals"; - table.insert(API, Globals); - - -- Extract hook constants: - for name, obj in pairs(cPluginManager) do - if ( - (type(obj) == "number") and - name:match("HOOK_.*") and - (name ~= "HOOK_MAX") and - (name ~= "HOOK_NUM_HOOKS") - ) then - table.insert(Hooks, { Name = name }); - end - end - table.sort(Hooks, - function(Hook1, Hook2) - return (Hook1.Name < Hook2.Name); - end - ); - - -- Read in the descriptions: - LOG("Reading descriptions..."); - ReadDescriptions(API); - ReadHooks(Hooks); - - -- Create a "class index" file, write each class as a link to that file, - -- then dump class contents into class-specific file - LOG("Writing HTML files..."); - local f = io.open("API/index.html", "w"); - if (f == nil) then - LOGINFO("Cannot output HTML API: " .. err); - return; - end - - -- Create a class navigation menu that will be inserted into each class file for faster navigation (#403) - local ClassMenuTab = {}; - for idx, cls in ipairs(API) do - table.insert(ClassMenuTab, "<a href='"); - table.insert(ClassMenuTab, cls.Name); - table.insert(ClassMenuTab, ".html'>"); - table.insert(ClassMenuTab, cls.Name); - table.insert(ClassMenuTab, "</a><br />"); - end - local ClassMenu = table.concat(ClassMenuTab, ""); - - -- Create a hook navigation menu that will be inserted into each hook file for faster navigation(#403) - local HookNavTab = {}; - for idx, hook in ipairs(Hooks) do - table.insert(HookNavTab, "<a href='"); - table.insert(HookNavTab, hook.DefaultFnName); - table.insert(HookNavTab, ".html'>"); - table.insert(HookNavTab, (hook.Name:gsub("^HOOK_", ""))); -- remove the "HOOK_" part of the name - table.insert(HookNavTab, "</a><br />"); - end - local HookNav = table.concat(HookNavTab, ""); - - -- Write the HTML file: - f:write([[<!DOCTYPE html> - <html> - <head> - <title>MCServer API - Index</title> - <link rel="stylesheet" type="text/css" href="main.css" /> - </head> - <body> - <div id="content"> - <header> - <h1>MCServer API - Index</h1> - <hr /> - </header> - <p>The API reference is divided into the following sections:</p> - <ul> - <li><a href="#articles">Articles</a></li> - <li><a href="#classes">Class index</a></li> - <li><a href="#hooks">Hooks</a></li> - <li><a href="#docstats">Documentation statistics</a></li> - </ul> - <hr /> - ]]); - - WriteArticles(f); - WriteClasses(f, API, ClassMenu); - WriteHooks(f, Hooks, UndocumentedHooks, HookNav); - - -- Copy the static files to the output folder: - local StaticFiles = - { - "main.css", - "prettify.js", - "prettify.css", - "lang-lua.js", - }; - for idx, fnam in ipairs(StaticFiles) do - cFile:Delete("API/" .. fnam); - cFile:Copy(g_Plugin:GetLocalFolder() .. "/" .. fnam, "API/" .. fnam); - end - - -- List the documentation problems: - LOG("Listing leftovers..."); - ListUndocumentedObjects(API, UndocumentedHooks); - ListUnexportedObjects(); - ListMissingPages(); - - WriteStats(f); - - f:write([[ </ul> - </div> - </body> -</html>]]); - f:close(); - - LOG("API subfolder written"); -end - - - - - -function ReadDescriptions(a_API) +local function ReadDescriptions(a_API) -- Returns true if the class of the specified name is to be ignored local function IsClassIgnored(a_ClsName) if (g_APIDesc.IgnoreClasses == nil) then return false; end - for i, name in ipairs(g_APIDesc.IgnoreClasses) do + for _, name in ipairs(g_APIDesc.IgnoreClasses) do if (a_ClsName:match(name)) then return true; end @@ -511,7 +359,7 @@ function ReadDescriptions(a_API) return false; end local FnName = a_ClassName .. "." .. a_FnName; - for i, name in ipairs(g_APIDesc.IgnoreFunctions) do + for _, name in ipairs(g_APIDesc.IgnoreFunctions) do if (FnName:match(name)) then return true; end @@ -524,7 +372,7 @@ function ReadDescriptions(a_API) if (g_APIDesc.IgnoreConstants == nil) then return false; end; - for i, name in ipairs(g_APIDesc.IgnoreConstants) do + for _, name in ipairs(g_APIDesc.IgnoreConstants) do if (a_CnName:match(name)) then return true; end @@ -537,7 +385,7 @@ function ReadDescriptions(a_API) if (g_APIDesc.IgnoreVariables == nil) then return false; end; - for i, name in ipairs(g_APIDesc.IgnoreVariables) do + for _, name in ipairs(g_APIDesc.IgnoreVariables) do if (a_VarName:match(name)) then return true; end @@ -547,7 +395,7 @@ function ReadDescriptions(a_API) -- Remove ignored classes from a_API: local APICopy = {}; - for i, cls in ipairs(a_API) do + for _, cls in ipairs(a_API) do if not(IsClassIgnored(cls.Name)) then table.insert(APICopy, cls); end @@ -557,14 +405,14 @@ function ReadDescriptions(a_API) end; -- Process the documentation for each class: - for i, cls in ipairs(a_API) do + for _, cls in ipairs(a_API) do -- Initialize default values for each class: cls.ConstantGroups = {}; cls.NumConstantsInGroups = 0; cls.NumConstantsInGroupsForDescendants = 0; -- Rename special functions: - for j, fn in ipairs(cls.Functions) do + for _, fn in ipairs(cls.Functions) do if (fn.Name == ".call") then fn.DocID = "constructor"; fn.Name = "() <i>(constructor)</i>"; @@ -594,7 +442,7 @@ function ReadDescriptions(a_API) -- Process inheritance: if (APIDesc.Inherits ~= nil) then - for j, icls in ipairs(a_API) do + for _, icls in ipairs(a_API) do if (icls.Name == APIDesc.Inherits) then table.insert(icls.Descendants, cls); cls.Inherits = icls; @@ -614,7 +462,7 @@ function ReadDescriptions(a_API) if (APIDesc.Functions ~= nil) then -- Assign function descriptions: - for j, func in ipairs(cls.Functions) do + for _, func in ipairs(cls.Functions) do local FnName = func.DocID or func.Name; local FnDesc = APIDesc.Functions[FnName]; if (FnDesc == nil) then @@ -630,7 +478,7 @@ function ReadDescriptions(a_API) AddFunction(func.Name, FnDesc.Params, FnDesc.Return, FnDesc.Notes); else -- Multiple function overloads - for k, desc in ipairs(FnDesc) do + for _, desc in ipairs(FnDesc) do AddFunction(func.Name, desc.Params, desc.Return, desc.Notes); end -- for k, desc - FnDesc[] end @@ -641,7 +489,7 @@ function ReadDescriptions(a_API) -- Replace functions with their described and overload-expanded versions: cls.Functions = DoxyFunctions; else -- if (APIDesc.Functions ~= nil) - for j, func in ipairs(cls.Functions) do + for _, func in ipairs(cls.Functions) do local FnName = func.DocID or func.Name; if not(IsFunctionIgnored(cls.Name, FnName)) then table.insert(cls.UndocumentedFunctions, FnName); @@ -651,7 +499,7 @@ function ReadDescriptions(a_API) if (APIDesc.Constants ~= nil) then -- Assign constant descriptions: - for j, cons in ipairs(cls.Constants) do + for _, cons in ipairs(cls.Constants) do local CnDesc = APIDesc.Constants[cons.Name]; if (CnDesc == nil) then -- Not documented @@ -664,7 +512,7 @@ function ReadDescriptions(a_API) end end -- for j, cons else -- if (APIDesc.Constants ~= nil) - for j, cons in ipairs(cls.Constants) do + for _, cons in ipairs(cls.Constants) do if not(IsConstantIgnored(cls.Name .. "." .. cons.Name)) then table.insert(cls.UndocumentedConstants, cons.Name); end @@ -673,7 +521,7 @@ function ReadDescriptions(a_API) -- Assign member variables' descriptions: if (APIDesc.Variables ~= nil) then - for j, var in ipairs(cls.Variables) do + for _, var in ipairs(cls.Variables) do local VarDesc = APIDesc.Variables[var.Name]; if (VarDesc == nil) then -- Not documented @@ -688,7 +536,7 @@ function ReadDescriptions(a_API) end end -- for j, var else -- if (APIDesc.Variables ~= nil) - for j, var in ipairs(cls.Variables) do + for _, var in ipairs(cls.Variables) do if not(IsVariableIgnored(cls.Name .. "." .. var.Name)) then table.insert(cls.UndocumentedVariables, var.Name); end @@ -706,8 +554,8 @@ function ReadDescriptions(a_API) group.Include = { group.Include }; end local NumInGroup = 0; - for idx, incl in ipairs(group.Include or {}) do - for cidx, cons in ipairs(cls.Constants) do + for _, incl in ipairs(group.Include or {}) do + for _, cons in ipairs(cls.Constants) do if ((cons.Group == nil) and cons.Name:match(incl)) then cons.Group = group; table.insert(group.Constants, cons); @@ -733,7 +581,7 @@ function ReadDescriptions(a_API) -- Remove grouped constants from the normal list: local NewConstants = {}; - for idx, cons in ipairs(cls.Constants) do + for _, cons in ipairs(cls.Constants) do if (cons.Group == nil) then table.insert(NewConstants, cons); end @@ -749,18 +597,18 @@ function ReadDescriptions(a_API) cls.UndocumentedVariables = {}; cls.Variables = cls.Variables or {}; g_Stats.NumUndocumentedClasses = g_Stats.NumUndocumentedClasses + 1; - for j, func in ipairs(cls.Functions) do + for _, func in ipairs(cls.Functions) do local FnName = func.DocID or func.Name; if not(IsFunctionIgnored(cls.Name, FnName)) then table.insert(cls.UndocumentedFunctions, FnName); end end -- for j, func - cls.Functions[] - for j, cons in ipairs(cls.Constants) do + for _, cons in ipairs(cls.Constants) do if not(IsConstantIgnored(cls.Name .. "." .. cons.Name)) then table.insert(cls.UndocumentedConstants, cons.Name); end end -- for j, cons - cls.Constants[] - for j, var in ipairs(cls.Variables) do + for _, var in ipairs(cls.Variables) do if not(IsConstantIgnored(cls.Name .. "." .. var.Name)) then table.insert(cls.UndocumentedVariables, var.Name); end @@ -769,7 +617,7 @@ function ReadDescriptions(a_API) -- Remove ignored functions: local NewFunctions = {}; - for j, fn in ipairs(cls.Functions) do + for _, fn in ipairs(cls.Functions) do if (not(IsFunctionIgnored(cls.Name, fn.Name))) then table.insert(NewFunctions, fn); end @@ -792,7 +640,7 @@ function ReadDescriptions(a_API) -- Remove ignored constants: local NewConstants = {}; - for j, cn in ipairs(cls.Constants) do + for _, cn in ipairs(cls.Constants) do if (not(IsFunctionIgnored(cls.Name, cn.Name))) then table.insert(NewConstants, cn); end @@ -808,7 +656,7 @@ function ReadDescriptions(a_API) -- Remove ignored member variables: local NewVariables = {}; - for j, var in ipairs(cls.Variables) do + for _, var in ipairs(cls.Variables) do if (not(IsVariableIgnored(cls.Name .. "." .. var.Name))) then table.insert(NewVariables, var); end @@ -824,7 +672,7 @@ function ReadDescriptions(a_API) end -- for i, cls -- Sort the descendants lists: - for i, cls in ipairs(a_API) do + for _, cls in ipairs(a_API) do table.sort(cls.Descendants, function(c1, c2) return (c1.Name < c2.Name); @@ -837,7 +685,7 @@ end -function ReadHooks(a_Hooks) +local function ReadHooks(a_Hooks) --[[ a_Hooks = { { Name = "HOOK_1"}, @@ -846,7 +694,7 @@ function ReadHooks(a_Hooks) }; We want to add hook descriptions to each hook in this array --]] - for i, hook in ipairs(a_Hooks) do + for _, hook in ipairs(a_Hooks) do local HookDesc = g_APIDesc.Hooks[hook.Name]; if (HookDesc ~= nil) then for key, val in pairs(HookDesc) do @@ -861,63 +709,10 @@ end --- Make a link out of anything with the special linkifying syntax {{link|title}} -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 - -- The link is a full absolute URL, do not modify, do not track: - return "<a href=\"" .. Link .. "\">" .. Title .. "</a>"; - end - local idxHash = Link:find("#"); - if (idxHash ~= nil) then - -- The link contains an anchor: - if (idxHash == 1) then - -- Anchor in the current page, no need to track: - return "<a href=\"" .. Link .. "\">" .. Title .. "</a>"; - end - -- Anchor in another page: - local PageName = Link:sub(1, idxHash - 1); - AddTrackedPage(PageName); - return "<a href=\"" .. PageName .. ".html#" .. Link:sub(idxHash + 1) .. "\">" .. Title .. "</a>"; - end - -- Link without anchor: - AddTrackedPage(Link); - return "<a href=\"" .. Link .. ".html\">" .. Title .. "</a>"; - end - - -- Linkify the strings using the CreateLink() function: - local txt = a_String:gsub("{{([^|}]*)|([^}]*)}}", CreateLink) -- {{link|title}} - txt = txt:gsub("{{([^|}]*)}}", -- {{LinkAndTitle}} - function(LinkAndTitle) - local idxHash = LinkAndTitle:find("#"); - if (idxHash ~= nil) then - -- The LinkAndTitle contains a hash, remove the hashed part from the title: - return CreateLink(LinkAndTitle, LinkAndTitle:sub(1, idxHash - 1)); - end - return CreateLink(LinkAndTitle, LinkAndTitle); - end - ); - return txt; -end - - - - - -function WriteHtmlClass(a_ClassAPI, a_AllAPI, a_ClassMenu) +local function WriteHtmlClass(a_ClassAPI, a_ClassMenu) local cf, err = io.open("API/" .. a_ClassAPI.Name .. ".html", "w"); if (cf == nil) then + LOGINFO("Cannot write HTML API for class " .. a_ClassAPI.Name .. ": " .. err) return; end @@ -931,7 +726,7 @@ function WriteHtmlClass(a_ClassAPI, a_AllAPI, a_ClassMenu) cf:write("<h2>Functions inherited from ", a_InheritedName, "</h2>\n"); end cf:write("<table>\n<tr><th>Name</th><th>Parameters</th><th>Return value</th><th>Notes</th></tr>\n"); - for i, func in ipairs(a_Functions) do + for _, func in ipairs(a_Functions) do cf:write("<tr><td>", func.Name, "</td>\n"); cf:write("<td>", LinkifyString(func.Params or "", (a_InheritedName or a_ClassAPI.Name)), "</td>\n"); cf:write("<td>", LinkifyString(func.Return or "", (a_InheritedName or a_ClassAPI.Name)), "</td>\n"); @@ -942,7 +737,7 @@ function WriteHtmlClass(a_ClassAPI, a_AllAPI, a_ClassMenu) local function WriteConstantTable(a_Constants, a_Source) cf:write("<table>\n<tr><th>Name</th><th>Value</th><th>Notes</th></tr>\n"); - for i, cons in ipairs(a_Constants) do + for _, cons in ipairs(a_Constants) do cf:write("<tr><td>", cons.Name, "</td>\n"); cf:write("<td>", cons.Value, "</td>\n"); cf:write("<td>", LinkifyString(cons.Notes or "", a_Source), "</td></tr>\n"); @@ -965,7 +760,7 @@ function WriteHtmlClass(a_ClassAPI, a_AllAPI, a_ClassMenu) WriteConstantTable(a_Constants, Source); end - for k, group in pairs(a_ConstantGroups) do + for _, group in pairs(a_ConstantGroups) do if ((a_InheritedName == nil) or group.ShowInDescendants) then cf:write("<a name='", group.Name, "'><p>"); cf:write(LinkifyString(group.TextBefore or "", Source)); @@ -985,7 +780,7 @@ function WriteHtmlClass(a_ClassAPI, a_AllAPI, a_ClassMenu) end cf:write("<table><tr><th>Name</th><th>Type</th><th>Notes</th></tr>\n"); - for i, var in ipairs(a_Variables) do + for _, var in ipairs(a_Variables) do cf:write("<tr><td>", var.Name, "</td>\n"); cf:write("<td>", LinkifyString(var.Type or "<i>(undocumented)</i>", a_InheritedName or a_ClassAPI.Name), "</td>\n"); cf:write("<td>", LinkifyString(var.Notes or "", a_InheritedName or a_ClassAPI.Name), "</td>\n </tr>\n"); @@ -998,7 +793,7 @@ function WriteHtmlClass(a_ClassAPI, a_AllAPI, a_ClassMenu) return; end cf:write("<ul>"); - for i, desc in ipairs(a_Descendants) do + for _, desc in ipairs(a_Descendants) do cf:write("<li><a href=\"", desc.Name, ".html\">", desc.Name, "</a>"); WriteDescendants(desc.Descendants); cf:write("</li>\n"); @@ -1049,7 +844,7 @@ function WriteHtmlClass(a_ClassAPI, a_AllAPI, a_ClassMenu) local HasConstants = (#a_ClassAPI.Constants > 0) or (a_ClassAPI.NumConstantsInGroups > 0); local HasFunctions = (#a_ClassAPI.Functions > 0); local HasVariables = (#a_ClassAPI.Variables > 0); - for idx, cls in ipairs(InheritanceChain) do + for _, cls in ipairs(InheritanceChain) do HasConstants = HasConstants or (#cls.Constants > 0) or (cls.NumConstantsInGroupsForDescendants > 0); HasFunctions = HasFunctions or (#cls.Functions > 0); HasVariables = HasVariables or (#cls.Variables > 0); @@ -1088,7 +883,7 @@ function WriteHtmlClass(a_ClassAPI, a_AllAPI, a_ClassMenu) cf:write("<hr /><a name=\"inherits\"><h1>Inheritance</h1></a>\n"); if (#InheritanceChain > 0) then cf:write("<p>This class inherits from the following parent classes:<ul>\n"); - for i, cls in ipairs(InheritanceChain) do + for _, cls in ipairs(InheritanceChain) do cf:write("<li><a href=\"", cls.Name, ".html\">", cls.Name, "</a></li>\n"); end cf:write("</ul></p>\n"); @@ -1105,7 +900,7 @@ function WriteHtmlClass(a_ClassAPI, a_AllAPI, a_ClassMenu) cf:write("<a name=\"constants\"><hr /><h1>Constants</h1></a>\n"); WriteConstants(a_ClassAPI.Constants, a_ClassAPI.ConstantGroups, a_ClassAPI.NumConstantsInGroups, nil); g_Stats.NumTotalConstants = g_Stats.NumTotalConstants + #a_ClassAPI.Constants + (a_ClassAPI.NumConstantsInGroups or 0); - for i, cls in ipairs(InheritanceChain) do + for _, cls in ipairs(InheritanceChain) do WriteConstants(cls.Constants, cls.ConstantGroups, cls.NumConstantsInGroupsForDescendants, cls.Name); end; end; @@ -1115,7 +910,7 @@ function WriteHtmlClass(a_ClassAPI, a_AllAPI, a_ClassMenu) cf:write("<a name=\"variables\"><hr /><h1>Member variables</h1></a>\n"); WriteVariables(a_ClassAPI.Variables, nil); g_Stats.NumTotalVariables = g_Stats.NumTotalVariables + #a_ClassAPI.Variables; - for i, cls in ipairs(InheritanceChain) do + for _, cls in ipairs(InheritanceChain) do WriteVariables(cls.Variables, cls.Name); end; end @@ -1125,7 +920,7 @@ function WriteHtmlClass(a_ClassAPI, a_AllAPI, a_ClassMenu) cf:write("<a name=\"functions\"><hr /><h1>Functions</h1></a>\n"); WriteFunctions(a_ClassAPI.Functions, nil); g_Stats.NumTotalFunctions = g_Stats.NumTotalFunctions + #a_ClassAPI.Functions; - for i, cls in ipairs(InheritanceChain) do + for _, cls in ipairs(InheritanceChain) do WriteFunctions(cls.Functions, cls.Name); end end @@ -1146,71 +941,20 @@ end -function WriteHtmlHook(a_Hook, a_HookNav) - local fnam = "API/" .. a_Hook.DefaultFnName .. ".html"; - local f, error = io.open(fnam, "w"); - if (f == nil) then - LOG("Cannot write \"" .. fnam .. "\": \"" .. error .. "\"."); - return; - end - local HookName = a_Hook.DefaultFnName; - - f:write([[<!DOCTYPE html><html> - <head> - <title>MCServer API - ]], HookName, [[ Hook</title> - <link rel="stylesheet" type="text/css" href="main.css" /> - <link rel="stylesheet" type="text/css" href="prettify.css" /> - <script src="prettify.js"></script> - <script src="lang-lua.js"></script> - </head> - <body> - <div id="content"> - <header> - <h1>]], a_Hook.Name, [[</h1> - <hr /> - </header> - <table><tr><td style="vertical-align: top;"> - Index:<br /> - <a href='index.html#articles'>Articles</a><br /> - <a href='index.html#classes'>Classes</a><br /> - <a href='index.html#hooks'>Hooks</a><br /> - <br /> - Quick navigation:<br /> - ]]); - f:write(a_HookNav); +local function WriteClasses(f, a_API, a_ClassMenu) f:write([[ - </td><td style="vertical-align: top;"><p> + <a name="classes"><h2>Class index</h2></a> + <p>The following classes are available in the MCServer Lua scripting language: + <ul> ]]); - f:write(LinkifyString(a_Hook.Desc, HookName)); - f:write("</p>\n<hr /><h1>Callback function</h1>\n<p>The default name for the callback function is "); - f:write(a_Hook.DefaultFnName, ". It has the following signature:\n"); - f:write("<pre class=\"prettyprint lang-lua\">function ", HookName, "("); - if (a_Hook.Params == nil) then - a_Hook.Params = {}; - end - for i, param in ipairs(a_Hook.Params) do - if (i > 1) then - f:write(", "); - end - f:write(param.Name); - end - f:write(")</pre>\n<hr /><h1>Parameters:</h1>\n<table><tr><th>Name</th><th>Type</th><th>Notes</th></tr>\n"); - for i, param in ipairs(a_Hook.Params) do - f:write("<tr><td>", param.Name, "</td><td>", LinkifyString(param.Type, HookName), "</td><td>", LinkifyString(param.Notes, HookName), "</td></tr>\n"); - end - f:write("</table>\n<p>" .. (a_Hook.Returns or "") .. "</p>\n\n"); - f:write([[<hr /><h1>Code examples</h1><h2>Registering the callback</h2>]]); - f:write("<pre class=\"prettyprint lang-lua\">\n"); - f:write([[cPluginManager:AddHook(cPluginManager.]] .. a_Hook.Name .. ", My" .. a_Hook.DefaultFnName .. [[);]]); - f:write("</pre>\n\n"); - local Examples = a_Hook.CodeExamples or {}; - for i, example in ipairs(Examples) do - f:write("<h2>", (example.Title or "<i>missing Title</i>"), "</h2>\n"); - f:write("<p>", (example.Desc or "<i>missing Desc</i>"), "</p>\n"); - f:write("<pre class=\"prettyprint lang-lua\">", (example.Code or "<i>missing Code</i>"), "\n</pre>\n\n"); + for _, cls in ipairs(a_API) do + f:write("<li><a href=\"", cls.Name, ".html\">", cls.Name, "</a></li>\n"); + WriteHtmlClass(cls, a_ClassMenu); end - f:write([[</td></tr></table></div><script>prettyPrint();</script></body></html>]]); - f:close(); + f:write([[ + </ul></p> + <hr /> + ]]); end @@ -1218,12 +962,12 @@ end --- Writes a list of undocumented objects into a file -function ListUndocumentedObjects(API, UndocumentedHooks) +local function ListUndocumentedObjects(API, UndocumentedHooks) f = io.open("API/_undocumented.lua", "w"); if (f ~= nil) then f:write("\n-- This is the list of undocumented API objects, automatically generated by APIDump\n\n"); f:write("g_APIDesc =\n{\n\tClasses =\n\t{\n"); - for i, cls in ipairs(API) do + for _, cls in ipairs(API) do local HasFunctions = ((cls.UndocumentedFunctions ~= nil) and (#cls.UndocumentedFunctions > 0)); local HasConstants = ((cls.UndocumentedConstants ~= nil) and (#cls.UndocumentedConstants > 0)); local HasVariables = ((cls.UndocumentedVariables ~= nil) and (#cls.UndocumentedVariables > 0)); @@ -1240,7 +984,7 @@ function ListUndocumentedObjects(API, UndocumentedHooks) if (HasFunctions) then f:write("\t\t\tFunctions =\n\t\t\t{\n"); table.sort(cls.UndocumentedFunctions); - for j, fn in ipairs(cls.UndocumentedFunctions) do + for _, fn in ipairs(cls.UndocumentedFunctions) do f:write("\t\t\t\t" .. fn .. " = { Params = \"\", Return = \"\", Notes = \"\" },\n"); end -- for j, fn - cls.UndocumentedFunctions[] f:write("\t\t\t},\n\n"); @@ -1249,7 +993,7 @@ function ListUndocumentedObjects(API, UndocumentedHooks) if (HasConstants) then f:write("\t\t\tConstants =\n\t\t\t{\n"); table.sort(cls.UndocumentedConstants); - for j, cn in ipairs(cls.UndocumentedConstants) do + for _, cn in ipairs(cls.UndocumentedConstants) do f:write("\t\t\t\t" .. cn .. " = { Notes = \"\" },\n"); end -- for j, fn - cls.UndocumentedConstants[] f:write("\t\t\t},\n\n"); @@ -1258,7 +1002,7 @@ function ListUndocumentedObjects(API, UndocumentedHooks) if (HasVariables) then f:write("\t\t\tVariables =\n\t\t\t{\n"); table.sort(cls.UndocumentedVariables); - for j, vn in ipairs(cls.UndocumentedVariables) do + for _, vn in ipairs(cls.UndocumentedVariables) do f:write("\t\t\t\t" .. vn .. " = { Type = \"\", Notes = \"\" },\n"); end -- for j, fn - cls.UndocumentedVariables[] f:write("\t\t\t},\n\n"); @@ -1306,7 +1050,7 @@ end --- Lists the API objects that are documented but not available in the API: -function ListUnexportedObjects() +local function ListUnexportedObjects() f = io.open("API/_unexported-documented.txt", "w"); if (f ~= nil) then for clsname, cls in pairs(g_APIDesc.Classes) do @@ -1338,7 +1082,7 @@ end -function ListMissingPages() +local function ListMissingPages() local MissingPages = {}; local NumLinks = 0; for PageName, Referrers in pairs(g_TrackedPages) do @@ -1368,7 +1112,7 @@ function ListMissingPages() LOGWARNING("Cannot open _missingPages.txt for writing: '" .. err .. "'. There are " .. #MissingPages .. " pages missing."); return; end - for idx, pg in ipairs(MissingPages) do + for _, pg in ipairs(MissingPages) do f:write(pg.Name .. ":\n"); -- Sort and output the referrers: table.sort(pg.Refs); @@ -1384,7 +1128,7 @@ end --- Writes the documentation statistics (in g_Stats) into the given HTML file -function WriteStats(f) +local function WriteStats(f) local function ExportMeter(a_Percent) local Color; if (a_Percent > 99) then @@ -1453,7 +1197,321 @@ end -function HandleWebAdminDump(a_Request) +local function DumpAPIHtml(a_API) + LOG("Dumping all available functions and constants to API subfolder..."); + + -- Create the output folder + if not(cFile:IsFolder("API")) then + cFile:CreateFolder("API"); + end + + LOG("Copying static files.."); + cFile:CreateFolder("API/Static"); + local localFolder = g_Plugin:GetLocalFolder(); + for _, fnam in ipairs(cFile:GetFolderContents(localFolder .. "/Static")) do + cFile:Delete("API/Static/" .. fnam); + cFile:Copy(localFolder .. "/Static/" .. fnam, "API/Static/" .. fnam); + end + + -- Extract hook constants: + local Hooks = {}; + local UndocumentedHooks = {}; + for name, obj in pairs(cPluginManager) do + if ( + (type(obj) == "number") and + name:match("HOOK_.*") and + (name ~= "HOOK_MAX") and + (name ~= "HOOK_NUM_HOOKS") + ) then + table.insert(Hooks, { Name = name }); + end + end + table.sort(Hooks, + function(Hook1, Hook2) + return (Hook1.Name < Hook2.Name); + end + ); + ReadHooks(Hooks); + + -- Create a "class index" file, write each class as a link to that file, + -- then dump class contents into class-specific file + LOG("Writing HTML files..."); + local f, err = io.open("API/index.html", "w"); + if (f == nil) then + LOGINFO("Cannot output HTML API: " .. err); + return; + end + + -- Create a class navigation menu that will be inserted into each class file for faster navigation (#403) + local ClassMenuTab = {}; + for _, cls in ipairs(a_API) do + table.insert(ClassMenuTab, "<a href='"); + table.insert(ClassMenuTab, cls.Name); + table.insert(ClassMenuTab, ".html'>"); + table.insert(ClassMenuTab, cls.Name); + table.insert(ClassMenuTab, "</a><br />"); + end + local ClassMenu = table.concat(ClassMenuTab, ""); + + -- Create a hook navigation menu that will be inserted into each hook file for faster navigation(#403) + local HookNavTab = {}; + for _, hook in ipairs(Hooks) do + table.insert(HookNavTab, "<a href='"); + table.insert(HookNavTab, hook.DefaultFnName); + table.insert(HookNavTab, ".html'>"); + table.insert(HookNavTab, (hook.Name:gsub("^HOOK_", ""))); -- remove the "HOOK_" part of the name + table.insert(HookNavTab, "</a><br />"); + end + local HookNav = table.concat(HookNavTab, ""); + + -- Write the HTML file: + f:write([[<!DOCTYPE html> + <html> + <head> + <title>MCServer API - Index</title> + <link rel="stylesheet" type="text/css" href="main.css" /> + </head> + <body> + <div id="content"> + <header> + <h1>MCServer API - Index</h1> + <hr /> + </header> + <p>The API reference is divided into the following sections:</p> + <ul> + <li><a href="#articles">Articles</a></li> + <li><a href="#classes">Class index</a></li> + <li><a href="#hooks">Hooks</a></li> + <li><a href="#docstats">Documentation statistics</a></li> + </ul> + <hr /> + ]]); + + WriteArticles(f); + WriteClasses(f, a_API, ClassMenu); + WriteHooks(f, Hooks, UndocumentedHooks, HookNav); + + -- Copy the static files to the output folder: + local StaticFiles = + { + "main.css", + "prettify.js", + "prettify.css", + "lang-lua.js", + }; + for _, fnam in ipairs(StaticFiles) do + cFile:Delete("API/" .. fnam); + cFile:Copy(g_Plugin:GetLocalFolder() .. "/" .. fnam, "API/" .. fnam); + end + + -- List the documentation problems: + LOG("Listing leftovers..."); + ListUndocumentedObjects(a_API, UndocumentedHooks); + ListUnexportedObjects(); + ListMissingPages(); + + WriteStats(f); + + f:write([[ </ul> + </div> + </body> +</html>]]); + f:close(); + + LOG("API subfolder written"); +end + + + + + +--- Returns the string with extra tabs and CR/LFs removed +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("<p>", "\n") + res = res:gsub("</p>", "") + + -- Replace list items with dashes: + res = res:gsub("</?ul>", "") + res = res:gsub("<li>", "\n - ") + res = res:gsub("</li>", "") + + return res +end + + + + + +--- Writes a list of methods into the specified file in ZBS format +local function WriteZBSMethods(f, a_Methods) + for _, func in ipairs(a_Methods or {}) do + f:write("\t\t\t[\"", func.Name, "\"] =\n") + f:write("\t\t\t{\n") + f:write("\t\t\t\ttype = \"method\",\n") + if ((func.Notes ~= nil) and (func.Notes ~= "")) then + f:write("\t\t\t\tdescription = [[", CleanUpDescription(func.Notes or ""), " ]],\n") + end + f:write("\t\t\t},\n") + end +end + + + + + +--- Writes a list of constants into the specified file in ZBS format +local function WriteZBSConstants(f, a_Constants) + for _, cons in ipairs(a_Constants or {}) do + f:write("\t\t\t[\"", cons.Name, "\"] =\n") + f:write("\t\t\t{\n") + f:write("\t\t\t\ttype = \"value\",\n") + if ((cons.Desc ~= nil) and (cons.Desc ~= "")) then + f:write("\t\t\t\tdescription = [[", CleanUpDescription(cons.Desc or ""), " ]],\n") + end + f:write("\t\t\t},\n") + end +end + + + + + +--- Writes one MCS 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") +end + + + + + +--- Dumps the entire API table into a file in the ZBS format +local function DumpAPIZBS(a_API) + LOG("Dumping ZBS API description...") + local f, err = io.open("mcserver.lua", "w") + if (f == nil) then + LOG("Cannot open mcserver.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("-- 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 + if (cls.Name ~= "Globals") then + WriteZBSClass(f, cls) + else + 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() + LOG("ZBS API dumped...") +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") + if (g_APIDesc.Classes == nil) then + g_APIDesc.Classes = {}; + end + if (g_APIDesc.Hooks == nil) then + g_APIDesc.Hooks = {}; + end + LoadAPIFiles("/Classes/", g_APIDesc.Classes); + LoadAPIFiles("/Hooks/", g_APIDesc.Hooks); + + -- Reset the stats: + g_TrackedPages = {}; -- List of tracked pages, to be checked later whether they exist. Each item is an array of referring pagenames. + g_Stats = -- Statistics about the documentation + { + NumTotalClasses = 0, + NumUndocumentedClasses = 0, + NumTotalFunctions = 0, + NumUndocumentedFunctions = 0, + NumTotalConstants = 0, + NumUndocumentedConstants = 0, + NumTotalVariables = 0, + NumUndocumentedVariables = 0, + NumTotalHooks = 0, + NumUndocumentedHooks = 0, + NumTrackedLinks = 0, + NumInvalidLinks = 0, + } + + -- Create the API tables: + local API, Globals = CreateAPITables(); + + -- Sort the classes by name: + table.sort(API, + function (c1, c2) + return (string.lower(c1.Name) < string.lower(c2.Name)); + 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); + + -- 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 + + + + + +local function HandleWebAdminDump(a_Request) if (a_Request.PostParams["Dump"] ~= nil) then DumpApi() end @@ -1467,3 +1525,32 @@ end + +local function HandleCmdApi(a_Split) + DumpApi() + return true +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") + + -- Add a WebAdmin tab that has a Dump button + g_Plugin:AddWebTab("APIDump", HandleWebAdminDump) + + return true +end + + + + + diff --git a/src/Bindings/LuaChunkStay.cpp b/src/Bindings/LuaChunkStay.cpp index 0e982637f..db865cfa4 100644 --- a/src/Bindings/LuaChunkStay.cpp +++ b/src/Bindings/LuaChunkStay.cpp @@ -131,9 +131,6 @@ void cLuaChunkStay::Enable(cChunkMap & a_ChunkMap, int a_OnChunkAvailableStackPo void cLuaChunkStay::OnChunkAvailable(int a_ChunkX, int a_ChunkZ) { - // DEBUG: - LOGD("LuaChunkStay: Chunk [%d, %d] is now available, calling the callback...", a_ChunkX, a_ChunkZ); - cPluginLua::cOperation Op(m_Plugin); Op().Call((int)m_OnChunkAvailable, a_ChunkX, a_ChunkZ); } diff --git a/src/Bindings/LuaState.cpp b/src/Bindings/LuaState.cpp index f24e15c3b..0bb047873 100644 --- a/src/Bindings/LuaState.cpp +++ b/src/Bindings/LuaState.cpp @@ -1080,20 +1080,20 @@ bool cLuaState::ReportErrors(lua_State * a_LuaState, int a_Status) -void cLuaState::LogStackTrace(void) +void cLuaState::LogStackTrace(int a_StartingDepth) { - LogStackTrace(m_LuaState); + LogStackTrace(m_LuaState, a_StartingDepth); } -void cLuaState::LogStackTrace(lua_State * a_LuaState) +void cLuaState::LogStackTrace(lua_State * a_LuaState, int a_StartingDepth) { LOGWARNING("Stack trace:"); lua_Debug entry; - int depth = 0; + int depth = a_StartingDepth; while (lua_getstack(a_LuaState, depth, &entry)) { lua_getinfo(a_LuaState, "Sln", &entry); @@ -1312,7 +1312,7 @@ void cLuaState::LogStack(lua_State * a_LuaState, const char * a_Header) int cLuaState::ReportFnCallErrors(lua_State * a_LuaState) { LOGWARNING("LUA: %s", lua_tostring(a_LuaState, -1)); - LogStackTrace(a_LuaState); + LogStackTrace(a_LuaState, 1); return 1; // We left the error message on the stack as the return value } diff --git a/src/Bindings/LuaState.h b/src/Bindings/LuaState.h index f5cb8379d..356a284e0 100644 --- a/src/Bindings/LuaState.h +++ b/src/Bindings/LuaState.h @@ -868,10 +868,10 @@ public: static bool ReportErrors(lua_State * a_LuaState, int status); /** Logs all items in the current stack trace to the server console */ - void LogStackTrace(void); + void LogStackTrace(int a_StartingDepth = 0); /** Logs all items in the current stack trace to the server console */ - static void LogStackTrace(lua_State * a_LuaState); + static void LogStackTrace(lua_State * a_LuaState, int a_StartingDepth = 0); /** Returns the type of the item on the specified position in the stack */ AString GetTypeText(int a_StackPos); |