diff options
Diffstat (limited to 'MCServer/Plugins')
| -rw-r--r-- | MCServer/Plugins/APIDump/APIDesc.lua | 34 | ||||
| -rw-r--r-- | MCServer/Plugins/APIDump/main.lua | 129 |
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 + + + + |