-- main.lua
-- Implements the plugin entrypoint (in this case the entire plugin)
-- Global variables:
g_Plugin = nil;
function Initialize(Plugin)
g_Plugin = Plugin;
Plugin:SetName("APIDump");
Plugin:SetVersion(1);
LOG("Initialized " .. Plugin:GetName() .. " v." .. Plugin:GetVersion())
-- dump all available API functions and objects:
-- DumpAPITxt();
-- DEBUG: Convert the wiki dump into APIDesc
ConvertWikiToDesc();
-- Dump all available API object in HTML format into a subfolder:
DumpAPIHtml();
return true
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()
--[[
We want an API table of the following shape:
local API = {
{
Name = "cCuboid",
Functions = {
{Name = "Sort"},
{Name = "IsInside"}
},
Constants = {
}
}},
{
Name = "cBlockArea",
Functions = {
{Name = "Clear"},
{Name = "CopyFrom"},
...
}
Constants = {
{Name = "baTypes", Value = 0},
{Name = "baMetas", Value = 1},
...
}
...
}}
};
local Globals = {
Functions = {
...
},
Constants = {
...
}
};
--]]
local Globals = {Functions = {}, Constants = {}};
local API = {};
local function Add(a_APIContainer, a_ClassName, a_ClassObj)
if (type(a_ClassObj) == "function") then
table.insert(a_APIContainer.Functions, {Name = a_ClassName});
elseif (type(a_ClassObj) == "number") then
table.insert(a_APIContainer.Constants, {Name = a_ClassName, Value = a_ClassObj});
end
end
local function SortClass(a_ClassAPI)
-- Sort the function list and constant lists:
table.sort(a_ClassAPI.Functions,
function(f1, f2)
return (f1.Name < f2.Name);
end
);
table.sort(a_ClassAPI.Constants,
function(c1, c2)
return (c1.Name < c2.Name);
end
);
end;
local function ParseClass(a_ClassName, a_ClassObj)
local res = {Name = a_ClassName, Functions = {}, Constants = {}};
for i, v in pairs(a_ClassObj) do
Add(res, i, v);
end
SortClass(res);
return res;
end
for i, v in pairs(_G) do
if (type(v) == "table") then
-- It is a table - probably a class
local StartLetter = GetChar(i, 0);
if (StartLetter == "c") then
-- Starts with a "c", handle it as a MCS API class
table.insert(API, ParseClass(i, v));
end
else
Add(Globals, i, v);
end
end
SortClass(Globals);
table.sort(API,
function(c1, c2)
return (c1.Name < c2.Name);
end
);
return API, Globals;
end
function DumpAPIHtml()
LOG("Dumping all available functions and constants to API subfolder...");
local API, Globals = CreateAPITables();
Globals.Name = "Globals";
table.insert(API, Globals);
-- Read in the descriptions:
ReadDescriptions(API);
-- Create a "class index" file, write each class as a link to that file,
-- then dump class contents into class-specific file
local f = io.open("API/index.html", "w");
if (f == nil) then
-- Create the output folder
os.execute("mkdir API");
local err;
f, err = io.open("API/index.html", "w");
if (f == nil) then
LOGINFO("Cannot output HTML API: " .. err);
return;
end
end
f:write([[<html><head><title>MCServer API - class index</title>
<link rel="stylesheet" type="text/css" href="main.css" />
</head><body>
<ul>
]]);
for i, cls in ipairs(API) do
f:write("<li><a href=\"" .. cls.Name .. ".html\">" .. cls.Name .. "</a></li>\n");
WriteHtmlClass(cls);
end
f:write("</ul></body></html>");
f:close();
LOG("API subfolder written");
end
function ReadDescriptions(a_API)
local UnexportedDocumented = {}; -- List of API objects that are documented but not exported, simply a list of names
for i, cls in ipairs(a_API) do
local APIDesc = g_APIDesc.Classes[cls.Name];
if (APIDesc ~= nil) then
cls.Desc = APIDesc.Desc;
if (APIDesc.Functions ~= nil) then
-- Assign function descriptions:
for j, func in ipairs(cls.Functions) do
-- func is {"FuncName"}, add Parameters, Return and Notes from g_APIDesc
local FnDesc = APIDesc.Functions[func.Name];
if (FnDesc ~= nil) then
func.Params = FnDesc.Params;
func.Return = FnDesc.Return;
func.Notes = FnDesc.Notes;
FnDesc.IsExported = true;
end
end -- for j, func
-- Add all non-exported function descriptions to UnexportedDocumented:
for j, func in pairs(APIDesc.Functions) do
-- TODO
end
end -- if (APIDesc.Functions ~= nil)
if (APIDesc.Constants ~= nil) then
-- Assign constant descriptions:
for j, cons in ipairs(cls.Constants) do
local CnDesc = APIDesc.Constants[cons.Name];
if (CnDesc ~= nil) then
cons.Notes = CnDesc.Notes;
CnDesc.IsExported = true;
end
end -- for j, cons
-- Add all non-exported constant descriptions to UnexportedDocumented:
for j, cons in pairs(APIDesc.Constants) do
-- TODO
end
end -- if (APIDesc.Constants ~= nil)
end
end -- for i, class
end
function WriteHtmlClass(a_ClassAPI)
local cf, err = io.open("API/" .. a_ClassAPI.Name .. ".html", "w");
if (cf == nil) then
return;
end
local function LinkifyString(a_String)
-- TODO: Make a link out of anything with the special linkifying syntax {{link|title}}
-- a_String:gsub("{{([^|]*)|[^}]*}}", "<a href=\"%1\">%2</a>");
return a_String;
end
cf:write([[<html><head><title>MCServer API - ]] .. a_ClassAPI.Name .. [[</title>
<link rel="stylesheet" type="text/css" href="main.css" />
</head><body>
<h1>Contents</h1>
<ul>
]]);
-- Write the table of contents:
if (#a_ClassAPI.Constants > 0) then
cf:write("<li><a href=\"#constants\">Constants</a></li>\n");
end
if (#a_ClassAPI.Functions > 0) then
cf:write("<li><a href=\"#functions\">Functions</a></li>\n");
end
cf:write("</ul>");
-- Write the class description:
cf:write("<a name=\"desc\"><h1>" .. a_ClassAPI.Name .. "</h1></a>\n");
if (a_ClassAPI.Desc ~= nil) then
cf:write("<p>");
cf:write(a_ClassAPI.Desc);
cf:write("</p>\n");
end;
-- Write the constants:
if (#a_ClassAPI.Constants > 0) then
cf:write("<a name=\"constants\"><h1>Constants</h1></a>\n");
cf:write("<table><tr><th>Name</th><th>Value</th><th>Notes</th></tr>\n");
for i, cons in ipairs(a_ClassAPI.Constants) do
cf:write("<tr><td>" .. cons.Name .. "</td>");
cf:write("<td>" .. cons.Value .. "</td>");
cf:write("<td>" .. LinkifyString(cons.Notes or "") .. "</td></tr>\n");
end
cf:write("</table>\n");
end
-- Write the functions:
if (#a_ClassAPI.Functions > 0) then
cf:write("<a name=\"functions\"><h1>Functions</h1></a>\n");
cf:write("<table><tr><th>Name</th><th>Parameters</th><th>Return value</th><th>Notes</th></tr>\n");
for i, func in ipairs(a_ClassAPI.Functions) do
cf:write("<tr><td>" .. func.Name .. "</td>");
cf:write("<td>" .. LinkifyString(func.Params or "").. "</td>");
cf:write("<td>" .. LinkifyString(func.Return or "").. "</td>");
cf:write("<td>" .. LinkifyString(func.Notes or "") .. "</td></tr>\n");
end
cf:write("</table>\n");
end
cf:write("</body></html>");
cf:close();
end
-- This function converts the wiki dump, as provided by FakeTruth, into the APIDesc format.
-- Dump available in forum: http://forum.mc-server.org/showthread.php?tid=1214&pid=9892#pid9892
-- The dump is expected unpacked as "wikipages/api/*.txt", in the executable folder
-- Only Windows-style paths are supported for now, since this is a one-time action
function ConvertWikiToDesc()
local fout = io.open("APIDesc.wiki.lua", "w");
fout:write("g_APIDesc =\n{\n\tClasses =\n\t{\n");
for filename in io.popen([[dir wikipages\\api\\*.txt /b]]):lines() do
-- Read file
local fin = io.open("wikipages\\api\\" .. filename, "r");
local ClassName = filename:match("[^\.]*");
local AddNextTime = "";
if (fin ~= nil) then
-- Read and parse the info from the file
local state = 0;
local Desc = "";
local Constants = {};
local Functions = {};
local ConstructorNumber = 1;
for line in fin:lines() do
-- Replace wiki-style markup:
line = line:gsub("%[%[.-:.-:(.-)|(.-)%]%]", "{{%1|%2}}"); -- Replaces [[API:Plugin:Hook|LinkText]]
line = line:gsub("%[%[.-:.-:(.-)%]%]", "{{%1|%1}}"); -- Replaces [[API:Plugin:Hook]]
line = line:gsub("%[%[.-:(.-)|(.-)%]%]", "{{%1|%2}}"); -- Replaces [[API:Class|LinkText]]
line = line:gsub("%[%[.-:(.-)%]%]", "{{%1|%1}}"); -- Replaces [[API:Class]]
line = line:gsub("%[%[(.-)|(.-)%]%]", "{{%1|%2}}"); -- Replaces [[Class|LinkText]]
line = line:gsub("%[%[(.-)%]%]", "{{%1|%1}}"); -- Replaces [[Class]]
if (line:find("======") ~= nil) then
state = 1; -- The following is the class description
ClassName = line:gsub("======", "");
ClassName = ClassName:match("%w+");
if (ClassName == nil) then
-- Reset to default
ClassName = filename:match("[^\.]*");
end
AddNextTime = "";
elseif (line:find("===== Constants") ~= nil) then
state = 2; -- The following is the constants description
elseif (line:find("===== Functions") ~= nil) then
state = 3; -- The following is the functions description
elseif (line:find("=====") ~= nil) then
state = 4; -- The following is an unknown text, skip it entirely
elseif (state == 1) then
-- Class description:
if (line == "") then
AddNextTime = "</p>\n\t\t<p>"; -- Replace empty lines with paragraph delimiters; add only when there's a followup text on next line
else
Desc = Desc .. AddNextTime .. line .. "\n";
AddNextTime = "";
end
elseif (state == 2) then
-- Constants:
line = line:gsub("| ", "\n");
local Split = StringSplitAndTrim(line, "\n");
if (#Split >= 3) then
-- Split[1] is always "", because the line starts with a "|"
local notes = Split[3] or "";
notes = notes:sub(1, notes:len() - 2); -- Remove the trailing " |"
table.insert(Constants, {Name = Split[2], Notes = notes});
end
elseif (state == 3) then
-- Functions:
line = string.gsub(line, "| ", "\n");
local Split = StringSplitAndTrim(line, "\n");
if (#Split >= 5) then
-- Split[1] is always "", because the line starts with a "|"
local notes = Split[5] or "";
notes = notes:sub(1, notes:len() - 2); -- Remove the trailing " |"
local name = (Split[2] or "");
if ((name == "( )") or (name == "()")) then
name = "constructor" .. ConstructorNumber; -- Special name is used for the constructor in the wiki
ConstructorNumber = ConstructorNumber + 1;
end
table.insert(Functions, {Name = name, Params = Split[3], Return = Split[4], Notes = notes});
end
end
end -- for line
fin:close();
-- Write the info into the output file:
fout:write("\t\t" .. ClassName .. " =\n\t\t{\n\t\t\tDesc = [[" .. Desc .. "]],\n\t\t\tFunctions =\n\t\t\t{\n");
for i, func in ipairs(Functions) do
fout:write(string.format("\t\t\t\t{ %s = { Params = %q, Return = %q, Notes = %q } },\n",
func.Name, func.Params, func.Return, func.Notes
));
end
fout:write("\t\t\t},\n\t\t\tConstants =\n\t\t\t{\n");
for i, cons in ipairs(Constants) do
fout:write(string.format("\t\t\t\t{ %s = { Notes = %q } },\n",
cons.Name, cons.Notes
));
end
fout:write("\t\t\t},\n\t\t},\n\n");
end -- if fin ~= nil
end -- for file
fout:write("\t}\n}\n\n\n\n\n\n");
fout:close();
end
