summaryrefslogtreecommitdiffstats
path: root/MCServer/Plugins/APIDump/main_APIDump.lua
diff options
context:
space:
mode:
authorHowaner <franzi.moos@googlemail.com>2014-04-03 22:03:18 +0200
committerHowaner <franzi.moos@googlemail.com>2014-04-03 22:03:18 +0200
commit32d054e8fdad1d486fd4edbb542daa3262220e5f (patch)
tree1094c471768b71e8cac1277c2fbea5a5d9f2caf9 /MCServer/Plugins/APIDump/main_APIDump.lua
parentRemove old function (diff)
parentAPIDump: Added angular specifics. (diff)
downloadcuberite-32d054e8fdad1d486fd4edbb542daa3262220e5f.tar
cuberite-32d054e8fdad1d486fd4edbb542daa3262220e5f.tar.gz
cuberite-32d054e8fdad1d486fd4edbb542daa3262220e5f.tar.bz2
cuberite-32d054e8fdad1d486fd4edbb542daa3262220e5f.tar.lz
cuberite-32d054e8fdad1d486fd4edbb542daa3262220e5f.tar.xz
cuberite-32d054e8fdad1d486fd4edbb542daa3262220e5f.tar.zst
cuberite-32d054e8fdad1d486fd4edbb542daa3262220e5f.zip
Diffstat (limited to 'MCServer/Plugins/APIDump/main_APIDump.lua')
-rw-r--r--MCServer/Plugins/APIDump/main_APIDump.lua966
1 files changed, 546 insertions, 420 deletions
diff --git a/MCServer/Plugins/APIDump/main_APIDump.lua b/MCServer/Plugins/APIDump/main_APIDump.lua
index bd509dcb6..52199740b 100644
--- a/MCServer/Plugins/APIDump/main_APIDump.lua
+++ b/MCServer/Plugins/APIDump/main_APIDump.lua
@@ -7,68 +7,22 @@
-- Global variables:
-g_Plugin = nil;
-g_PluginFolder = "";
-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,
-}
+local g_Plugin = nil
+local g_PluginFolder = ""
+local g_Stats = {}
+local g_TrackedPages = {}
-function Initialize(Plugin)
- g_Plugin = Plugin;
-
- Plugin:SetName("APIDump");
- Plugin:SetVersion(1);
-
- LOG("Initialising " .. Plugin:GetName() .. " v." .. Plugin:GetVersion())
-
- g_PluginFolder = Plugin:GetLocalFolder();
-
- -- Load the API descriptions from the Classes and Hooks subfolders:
- 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);
-
- -- dump all available API functions and objects:
- -- DumpAPITxt();
-
- -- Dump all available API object in HTML format into a subfolder:
- DumpAPIHtml();
-
- LOG("APIDump finished");
+local function LoadAPIFiles(a_Folder, a_DstTable)
+ assert(type(a_Folder) == "string")
+ assert(type(a_DstTable) == "table")
- return true
-end
-
-
-
-
-
-function LoadAPIFiles(a_Folder, a_DstTable)
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
@@ -89,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 = {
@@ -194,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 = ""});
@@ -235,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;
@@ -255,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
@@ -294,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");
@@ -314,162 +335,13 @@ end
-function DumpAPIHtml()
- LOG("Dumping all available functions and constants to API subfolder...");
-
- 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 the output folder
- if not(cFile:IsFolder("API")) then
- cFile:CreateFolder("API");
- end
-
- -- 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
@@ -487,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
@@ -500,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
@@ -513,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
@@ -523,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
@@ -533,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>";
@@ -570,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;
@@ -590,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
@@ -606,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
@@ -617,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);
@@ -627,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
@@ -640,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
@@ -649,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
@@ -664,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
@@ -682,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);
@@ -709,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
@@ -725,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
@@ -745,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
@@ -768,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
@@ -784,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
@@ -800,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);
@@ -813,7 +685,7 @@ end
-function ReadHooks(a_Hooks)
+local function ReadHooks(a_Hooks)
--[[
a_Hooks = {
{ Name = "HOOK_1"},
@@ -822,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
@@ -837,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
@@ -907,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");
@@ -918,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");
@@ -941,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));
@@ -961,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");
@@ -974,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");
@@ -1025,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);
@@ -1064,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");
@@ -1081,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;
@@ -1091,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
@@ -1101,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
@@ -1122,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
@@ -1194,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));
@@ -1216,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");
@@ -1225,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");
@@ -1234,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");
@@ -1282,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
@@ -1314,7 +1082,7 @@ end
-function ListMissingPages()
+local function ListMissingPages()
local MissingPages = {};
local NumLinks = 0;
for PageName, Referrers in pairs(g_TrackedPages) do
@@ -1344,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);
@@ -1360,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
@@ -1428,3 +1196,361 @@ end
+
+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_api.lua", "w")
+ if (f == nil) then
+ 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("-- 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
+ return
+ [[
+ <p>Pressing the button will generate the API dump on the server. Note that this can take some time.</p>
+ <form method="POST"><input type="submit" name="Dump" value="Dump the API"/></form>
+ ]]
+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
+
+
+
+
+