summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authormadmaxoft <github@xoft.cz>2013-10-09 15:10:25 +0200
committermadmaxoft <github@xoft.cz>2013-10-09 15:10:25 +0200
commit9dafba50157086ff952bff9cbba774334caf190a (patch)
tree9129dd5f1674450655e068c78df6ce0a37654715
parentFixed cFile::CopyFile Linux compilation. (diff)
downloadcuberite-9dafba50157086ff952bff9cbba774334caf190a.tar
cuberite-9dafba50157086ff952bff9cbba774334caf190a.tar.gz
cuberite-9dafba50157086ff952bff9cbba774334caf190a.tar.bz2
cuberite-9dafba50157086ff952bff9cbba774334caf190a.tar.lz
cuberite-9dafba50157086ff952bff9cbba774334caf190a.tar.xz
cuberite-9dafba50157086ff952bff9cbba774334caf190a.tar.zst
cuberite-9dafba50157086ff952bff9cbba774334caf190a.zip
Diffstat (limited to '')
-rw-r--r--MCServer/Plugins/APIDump/APIDesc.lua34
-rw-r--r--MCServer/Plugins/APIDump/main.lua129
2 files changed, 152 insertions, 11 deletions
diff --git a/MCServer/Plugins/APIDump/APIDesc.lua b/MCServer/Plugins/APIDump/APIDesc.lua
index c41cac51b..33e1da976 100644
--- a/MCServer/Plugins/APIDump/APIDesc.lua
+++ b/MCServer/Plugins/APIDump/APIDesc.lua
@@ -2055,6 +2055,33 @@ World:ForEachEntity(
},
},
+
+ Hooks =
+ {
+ HOOK_CHAT =
+ {
+ CalledWhen = "Player sends a chat message",
+ DefaultFnName = "OnChat", -- also used as pagename
+ Desc = [[
+ A plugin may implement an OnChat() function and register it as a Hook to process chat messages from
+ the players. The function is then called for every in-game message sent from any player. Note that
+ commands are handled separately using a command framework API.
+ ]],
+ Params = {
+ { Name = "Player", Type = "{{cPlayer}}", Notes = "The player who sent the message" },
+ { Name = "Message", Type = "string", Notes = "The message" },
+ },
+ Returns = [[
+ The plugin may return 2 values. The first is a boolean specifying whether the hook handling is to be
+ stopped or not. If it is false, the message is broadcast to all players in the world. If it is true,
+ no message is broadcast and no further action is taken.</p>
+ <p>
+ The second value is specifies the message to broadcast. This way, plugins may modify the message. If
+ the second value is not provided, the original message is used.
+ ]],
+ }, -- HOOK_CHAT
+ }, -- Hooks[]
+
IgnoreClasses =
{
@@ -2080,12 +2107,15 @@ World:ForEachEntity(
"%a+.delete", -- AnyClass.delete
-- Functions global in the APIDump plugin:
- "Initialize",
- "DumpAPITxt",
"CreateAPITables",
"DumpAPIHtml",
+ "DumpAPITxt",
+ "Initialize",
+ "LinkifyString",
"ReadDescriptions",
+ "ReadHooks",
"WriteHtmlClass",
+ "WriteHtmlHook",
},
ExtraPages =
diff --git a/MCServer/Plugins/APIDump/main.lua b/MCServer/Plugins/APIDump/main.lua
index 5dd6c6f9e..6d4ac3d04 100644
--- a/MCServer/Plugins/APIDump/main.lua
+++ b/MCServer/Plugins/APIDump/main.lua
@@ -164,6 +164,8 @@ function DumpAPIHtml()
LOG("Dumping all available functions and constants to API subfolder...");
local API, Globals = CreateAPITables();
+ local Hooks = {};
+ local UndocumentedHooks = {};
-- Sort the classes by name:
table.sort(API,
@@ -176,8 +178,21 @@ function DumpAPIHtml()
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_.*")) then
+ table.insert(Hooks, { Name = name });
+ end
+ end
+ table.sort(Hooks,
+ function(Hook1, Hook2)
+ return (Hook1.Name < Hook2.Name);
+ end
+ );
+
-- Read in the descriptions:
ReadDescriptions(API);
+ ReadHooks(Hooks);
-- Create the output folder
if not(cFile:IsFolder("API")) then
@@ -220,7 +235,16 @@ function DumpAPIHtml()
for the event). See each hook's details to see the exact behavior.</p>
<table><tr><th>Hook name</th><th>Called when</th></tr>
]]);
- -- TODO: Write out the hooks into a table
+ for i, hook in ipairs(Hooks) do
+ if (hook.DefaultFnName == nil) then
+ -- The hook is not documented yet
+ f:write("<tr><td>" .. hook.Name .. "</td><td><i>(No documentation yet)</i></td></tr>\n");
+ table.insert(UndocumentedHooks, hook.Name);
+ else
+ f:write("<tr><td><a href=\"" .. hook.DefaultFnName .. ".html\">" .. hook.Name .. "</a></td><td>" .. hook.CalledWhen .. "</td></tr>\n");
+ WriteHtmlHook(hook);
+ end
+ end
f:write([[</table>
<a name="extra"><h2>Extra pages</h2></a>
<p>The following pages provide various extra information</p>
@@ -286,6 +310,24 @@ function DumpAPIHtml()
f:write("\t\t},\n\n");
end
end -- for i, cls - API[]
+ f:write("\t},\n");
+
+ if (#UndocumentedHooks > 0) then
+ f:write("\n\tHooks =\n\t{\n");
+ for i, hook in ipairs(UndocumentedHooks) do
+ if (i > 1) then
+ f:write("\n");
+ end
+ f:write("\t\t" .. hook .. " =\n\t\t{\n");
+ f:write("\t\t\tCalledWhen = \"\",\n");
+ f:write("\t\t\tDefaultFnName = \"On\", -- also used as pagename\n");
+ f:write("\t\t\tDesc = [[]],\n");
+ f:write("\t\t\tParams =\n\t\t\t{\n");
+ f:write("\t\t\t\t{ Name = \"\", Type = \"\", Notes = \"\" },\n\t\t\t},\n");
+ f:write("\t\t\tReturns = [[]],\n");
+ f:write("\t\t}, -- " .. hook .. "\n");
+ end
+ end
f:close();
end
@@ -531,19 +573,46 @@ end
+function ReadHooks(a_Hooks)
+ --[[
+ a_Hooks = {
+ { Name = "HOOK_1"},
+ { Name = "HOOK_2"},
+ ...
+ };
+ We want to add hook descriptions to each hook in this array
+ --]]
+ for i, hook in ipairs(a_Hooks) do
+ local HookDesc = g_APIDesc.Hooks[hook.Name];
+ if (HookDesc ~= nil) then
+ for key, val in pairs(HookDesc) do
+ hook[key] = val;
+ end
+ end
+ end -- for i, hook - a_Hooks[]
+end
+
+
+
+
+
+-- Make a link out of anything with the special linkifying syntax {{link|title}}
+function LinkifyString(a_String)
+ local txt = a_String:gsub("{{([^|}]*)|([^}]*)}}", "<a href=\"%1.html\">%2</a>") -- {{link|title}}
+ txt = txt:gsub("{{([^|}]*)}}", "<a href=\"%1.html\">%1</a>") -- {{LinkAndTitle}}
+ return txt;
+end
+
+
+
+
+
function WriteHtmlClass(a_ClassAPI, a_AllAPI)
local cf, err = io.open("API/" .. a_ClassAPI.Name .. ".html", "w");
if (cf == nil) then
return;
end
- -- Make a link out of anything with the special linkifying syntax {{link|title}}
- local function LinkifyString(a_String)
- local txt = a_String:gsub("{{([^|}]*)|([^}]*)}}", "<a href=\"%1.html\">%2</a>") -- {{link|title}}
- txt = txt:gsub("{{([^|}]*)}}", "<a href=\"%1.html\">%1</a>") -- {{LinkAndTitle}}
- return txt;
- end
-
-- Writes a table containing all functions in the specified list, with an optional "inherited from" header when a_InheritedName is valid
local function WriteFunctions(a_Functions, a_InheritedName)
if (#a_Functions == 0) then
@@ -584,7 +653,7 @@ function WriteHtmlClass(a_ClassAPI, a_AllAPI)
CurrInheritance = CurrInheritance.Inherits;
end
- cf:write([[<html><head><title>MCServer API - ]] .. a_ClassAPI.Name .. [[</title>
+ cf:write([[<html><head><title>MCServer API - ]] .. a_ClassAPI.Name .. [[ class</title>
<link rel="stylesheet" type="text/css" href="main.css" />
</head><body>
<h1>Contents</h1>
@@ -664,3 +733,45 @@ end
+function WriteHtmlHook(a_Hook)
+ 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
+ f:write([[<html><head><title>MCServer API - ]] .. a_Hook.DefaultFnName .. [[ hook</title>
+ <link rel="stylesheet" type="text/css" href="main.css" />
+ </head><body>
+ <h1>]] .. a_Hook.Name .. [[ hook</h1>
+ <p>
+ ]]);
+ f:write(LinkifyString(a_Hook.Desc));
+ f:write("</p><h1>Callback function</h1><pre>function " .. a_Hook.DefaultFnName .. "(");
+ 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><p>Parameters:\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) .. "</td><td>" .. LinkifyString(param.Notes) .. "</td></tr>\n");
+ end
+ f:write("</table></p>\n<p>" .. (a_Hook.Returns or "") .. "</p>\n");
+ f:write([[<h1>Code examples</h1>
+ <h2>Registering the callback</h2>
+<pre>
+cPluginManager.AddHook(cPluginManager.]] .. a_Hook.Name .. ", My" .. a_Hook.DefaultFnName .. [[);
+</pre>
+ ]]);
+ -- TODO: Other code examples
+ f:close();
+end
+
+
+
+