From 82834ee1ed17ba542049d583ad3ebde2ace22025 Mon Sep 17 00:00:00 2001 From: madmaxoft Date: Sat, 12 Oct 2013 18:31:55 +0200 Subject: APIDump: Added pretty-printing to code examples. --- MCServer/Plugins/APIDump/APIDesc.lua | 54 ++++++++++++++++++------------------ MCServer/Plugins/APIDump/main.lua | 11 ++++++-- 2 files changed, 35 insertions(+), 30 deletions(-) (limited to 'MCServer/Plugins') diff --git a/MCServer/Plugins/APIDump/APIDesc.lua b/MCServer/Plugins/APIDump/APIDesc.lua index 78ae4be1e..dc04d3e81 100644 --- a/MCServer/Plugins/APIDump/APIDesc.lua +++ b/MCServer/Plugins/APIDump/APIDesc.lua @@ -404,7 +404,7 @@ g_APIDesc = Contents = [[ The following example code sets the top-left item of each chest in the same chunk as Player to 64 * diamond: -
+
 -- Player is a {{cPlayer}} object instance
 local World = Player:GetWorld();
 World:ForEachChestInChunk(Player:GetChunkX(), Player:GetChunkZ(),
@@ -846,7 +846,7 @@ World:ForEachChestInChunk(Player:GetChunkX(), Player:GetChunkZ(),
 			Desc = [[
 				Provides helper functions for manipulating and querying the filesystem. Most functions are called
 				directly on the cFile class itself:
-
+
 cFile:Delete("/usr/bin/virus.exe");
 

]], @@ -1248,7 +1248,7 @@ aborted and Trace() returns false.

The following example is taken from the Debuggers plugin. It is a command handler function for the "/spidey" command that creates a line of cobweb blocks from the player's eyes up to 50 blocks away in the direction they're looking, but only through the air. -

+
 function HandleSpideyCmd(a_Split, a_Player)
 	local World = a_Player:GetWorld();
 
@@ -1315,7 +1315,7 @@ end
 					Header = "OnClosing Callback",
 					Contents = [[
 						This callback, settable via the SetOnClosing() function, will be called when the player tries to close the window, or the window is closed for any other reason (such as a player disconnecting).

-
+
 function OnWindowClosing(a_Window, a_Player, a_CanRefuse)
 

@@ -1326,7 +1326,7 @@ function OnWindowClosing(a_Window, a_Player, a_CanRefuse) Header = "OnSlotChanged Callback", Contents = [[ This callback, settable via the SetOnSlotChanged() function, will be called whenever the contents of any slot in the window's contents (i. e. NOT in the player inventory!) changes.

-
+
 function OnWindowSlotChanged(a_Window, a_SlotNum)
 

The a_Window parameter is the cLuaWindow object representing the window, a_SlotNum is the slot number. There is no reference to a {{cPlayer}}, because the slot change needn't originate from the player action. To get or set the slot, you'll need to retrieve a cPlayer object, for example by calling {{cWorld|cWorld}}:DoWithPlayer(). @@ -1338,7 +1338,7 @@ function OnWindowSlotChanged(a_Window, a_SlotNum) Header = "Example", Contents = [[ This example is taken from the Debuggers plugin, used to test the API functionality. It opens a window and refuse to close it 3 times. It also logs slot changes to the server console. -

+
 -- Callback that refuses to close the window twice, then allows:
 local Attempt = 1;
 local OnClosing = function(Window, Player, CanRefuse)
@@ -1494,7 +1494,7 @@ a_Player:OpenWindow(Window);
 				

Note that some functions are "static", that means that they are called using a dot operator instead of the colon operator. For example: -

+
 cPluginManager.AddHook(cPluginManager.HOOK_CHAT, OnChatMessage);
 

]], @@ -1520,8 +1520,8 @@ cPluginManager.AddHook(cPluginManager.HOOK_CHAT, OnChatMessage); ExecuteConsoleCommand = { Params = "CommandStr", Return = "bool", Notes = "Executes the command as if given on the server console. Returns true if executed." }, FindPlugins = { Params = "", Return = "", Notes = "Refreshes the list of plugins to include all folders inside the Plugins folder (potentially new disabled plugins)" }, ForceExecuteCommand = { Params = "{{cPlayer|Player}}, CommandStr", Return = "bool", Notes = "Same as ExecuteCommand, but doesn't check permissions" }, - ForEachCommand = { Params = "CallbackFn", Return = "bool", Notes = "Calls the CallbackFn function for each command that has been bound using BindCommand(). The CallbackFn has the following signature:
function(Command, Permission, HelpString)
. If the callback returns true, the enumeration is aborted and this API function returns false; if it returns false or no value, the enumeration continues with the next command, and the API function returns true." }, - ForEachConsoleCommand = { Params = "CallbackFn", Return = "bool", Notes = "Calls the CallbackFn function for each command that has been bound using BindConsoleCommand(). The CallbackFn has the following signature:
function (Command, HelpString)
. If the callback returns true, the enumeration is aborted and this API function returns false; if it returns false or no value, the enumeration continues with the next command, and the API function returns true." }, + ForEachCommand = { Params = "CallbackFn", Return = "bool", Notes = "Calls the CallbackFn function for each command that has been bound using BindCommand(). The CallbackFn has the following signature:
function(Command, Permission, HelpString)
. If the callback returns true, the enumeration is aborted and this API function returns false; if it returns false or no value, the enumeration continues with the next command, and the API function returns true." }, + ForEachConsoleCommand = { Params = "CallbackFn", Return = "bool", Notes = "Calls the CallbackFn function for each command that has been bound using BindConsoleCommand(). The CallbackFn has the following signature:
function (Command, HelpString)
. If the callback returns true, the enumeration is aborted and this API function returns false; if it returns false or no value, the enumeration continues with the next command, and the API function returns true." }, Get = { Params = "", Return = "cPluginManager", Notes = "Returns the single instance of the plugin manager" }, GetAllPlugins = { Params = "", Return = "table", Notes = "Returns a table (dictionary) of all plugins, [name => {{cPlugin}}] pairing." }, GetCommandPermission = { Params = "Command", Return = "Permission", Notes = "Returns the permission needed for executing the specified command" }, @@ -1605,8 +1605,8 @@ cPluginManager.AddHook(cPluginManager.HOOK_CHAT, OnChatMessage); Get = { Params = "", Return = "Root object", Notes = "This function returns the cRoot object." }, BroadcastChat = { Params = "Message", Return = "", Notes = "Broadcasts a message to every player in the server." }, FindAndDoWithPlayer = { Params = "PlayerName, CallbackFunction", Return = "", Notes = "Calls the given callback function for the given player." }, - ForEachPlayer = { Params = "CallbackFunction", Return = "", Notes = "Calls the given callback function for each player. The callback function has the following signature:
function Callback({{cPlayer|cPlayer}})
" }, - ForEachWorld = { Params = "CallbackFunction", Return = "", Notes = "Calls the given callback function for each world. The callback function has the following signature:
function Callback({{cWorld|cWorld}})
" }, + ForEachPlayer = { Params = "CallbackFunction", Return = "", Notes = "Calls the given callback function for each player. The callback function has the following signature:
function Callback({{cPlayer|cPlayer}})
" }, + ForEachWorld = { Params = "CallbackFunction", Return = "", Notes = "Calls the given callback function for each world. The callback function has the following signature:
function Callback({{cWorld|cWorld}})
" }, GetCraftingRecipes = { Params = "", Return = "{{cCraftingRecipe|cCraftingRecipe}}", Notes = "Returns the CraftingRecipes object" }, GetDefaultWorld = { Params = "", Return = "{{cWorld|cWorld}}", Notes = "Returns the world object from the default world." }, GetFurnaceRecipe = { Params = "", Return = "{{cFurnaceRecipe|cFurnaceRecipe}}", Notes = "Returns the cFurnaceRecipes object." }, @@ -1800,24 +1800,24 @@ Sign entities are saved and loaded from disk when the chunk they reside in is sa CreateProjectile = { Params = "X, Y, Z, {{cProjectile|ProjectileKind}}, {{cEntity|Creator}}, [{{Vector3d|Speed}}]", Return = "", Notes = "Creates a new projectile of the specified kind at the specified coords. The projectile's creator is set to Creator (may be nil). Optional speed indicates the initial speed for the projectile." }, DigBlock = { Params = "X, Y, Z", Return = "", Notes = "Replaces the specified block with air, without dropping the usual pickups for the block. Wakes up the simulators for the block and its neighbors." }, DoExplosionAt = { Params = "Force, X, Y, Z, CanCauseFire, Source, SourceData", Return = "", Notes = "Creates an explosion of the specified relative force in the specified position. If CanCauseFire is set, the explosion will set blocks on fire, too. The Source parameter specifies the source of the explosion, one of the esXXX constants. The SourceData parameter is specific to each source type, usually it provides more info about the source." }, - DoWithChestAt = { Params = "X, Y, Z, CallbackFunction, [CallbackData]", Return = "bool", Notes = "If there is a chest at the specified coords, calls the CallbackFunction with the {{cChestEntity}} parameter representing the chest. The CallbackFunction has the following signature:
function Callback({{cChestEntity|ChestEntity}}, [CallbackData])
The function returns false if there is no chest, or if there is, it returns the bool value that the callback has returned." }, - DoWithDispenserAt = { Params = "X, Y, Z, CallbackFunction, [CallbackData]", Return = "bool", Notes = "If there is a dispenser at the specified coords, calls the CallbackFunction with the {{cDispenserEntity}} parameter representing the dispenser. The CallbackFunction has the following signature:
function Callback({{cDispenserEntity|DispenserEntity}}, [CallbackData])
The function returns false if there is no dispenser, or if there is, it returns the bool value that the callback has returned." }, - DoWithDropSpenserAt = { Params = "X, Y, Z, CallbackFunction, [CallbackData]", Return = "bool", Notes = "If there is a dropper or a dispenser at the specified coords, calls the CallbackFunction with the {{cDropSpenserEntity}} parameter representing the dropper or dispenser. The CallbackFunction has the following signature:
function Callback({{cDropSpenserEntity|DropSpenserEntity}}, [CallbackData])
Note that this can be used to access both dispensers and droppers in a similar way. The function returns false if there is neither dispenser nor dropper, or if there is, it returns the bool value that the callback has returned." }, - DoWithDropperAt = { Params = "X, Y, Z, CallbackFunction, [CallbackData]", Return = "bool", Notes = "If there is a dropper at the specified coords, calls the CallbackFunction with the {{cDropperEntity}} parameter representing the dropper. The CallbackFunction has the following signature:
function Callback({{cDropperEntity|DropperEntity}}, [CallbackData])
The function returns false if there is no dropper, or if there is, it returns the bool value that the callback has returned." }, - DoWithEntityByID = { Params = "EntityID, CallbackFunction, [CallbackData]", Return = "bool", Notes = "If an entity with the specified ID exists, calls the callback with the {{cEntity}} parameter representing the entity. The CallbackFunction has the following signature:
function Callback({{cEntity|Entity}}, [CallbackData])
The function returns false if the entity was not found, and it returns the same bool value that the callback has returned if the entity was found." }, - DoWithFurnaceAt = { Params = "X, Y, Z, CallbackFunction, [CallbackData]", Return = "bool", Notes = "If there is a furnace at the specified coords, calls the CallbackFunction with the {{cFurnaceEntity}} parameter representing the furnace. The CallbackFunction has the following signature:
function Callback({{cFurnaceEntity|FurnaceEntity}}, [CallbackData])
The function returns false if there is no furnace, or if there is, it returns the bool value that the callback has returned." }, - DoWithPlayer = { Params = "PlayerName, CallbackFunction, [CallbackData]", Return = "bool", Notes = "If there is a player of the specified name (exact match), calls the CallbackFunction with the {{cPlayer}} parameter representing the player. The CallbackFunction has the following signature:
function Callback({{cPlayer|Player}}, [CallbackData])
The function returns false if the player was not found, or whatever bool value the callback returned if the player was found." }, + DoWithChestAt = { Params = "X, Y, Z, CallbackFunction, [CallbackData]", Return = "bool", Notes = "If there is a chest at the specified coords, calls the CallbackFunction with the {{cChestEntity}} parameter representing the chest. The CallbackFunction has the following signature:
function Callback({{cChestEntity|ChestEntity}}, [CallbackData])
The function returns false if there is no chest, or if there is, it returns the bool value that the callback has returned." }, + DoWithDispenserAt = { Params = "X, Y, Z, CallbackFunction, [CallbackData]", Return = "bool", Notes = "If there is a dispenser at the specified coords, calls the CallbackFunction with the {{cDispenserEntity}} parameter representing the dispenser. The CallbackFunction has the following signature:
function Callback({{cDispenserEntity|DispenserEntity}}, [CallbackData])
The function returns false if there is no dispenser, or if there is, it returns the bool value that the callback has returned." }, + DoWithDropSpenserAt = { Params = "X, Y, Z, CallbackFunction, [CallbackData]", Return = "bool", Notes = "If there is a dropper or a dispenser at the specified coords, calls the CallbackFunction with the {{cDropSpenserEntity}} parameter representing the dropper or dispenser. The CallbackFunction has the following signature:
function Callback({{cDropSpenserEntity|DropSpenserEntity}}, [CallbackData])
Note that this can be used to access both dispensers and droppers in a similar way. The function returns false if there is neither dispenser nor dropper, or if there is, it returns the bool value that the callback has returned." }, + DoWithDropperAt = { Params = "X, Y, Z, CallbackFunction, [CallbackData]", Return = "bool", Notes = "If there is a dropper at the specified coords, calls the CallbackFunction with the {{cDropperEntity}} parameter representing the dropper. The CallbackFunction has the following signature:
function Callback({{cDropperEntity|DropperEntity}}, [CallbackData])
The function returns false if there is no dropper, or if there is, it returns the bool value that the callback has returned." }, + DoWithEntityByID = { Params = "EntityID, CallbackFunction, [CallbackData]", Return = "bool", Notes = "If an entity with the specified ID exists, calls the callback with the {{cEntity}} parameter representing the entity. The CallbackFunction has the following signature:
function Callback({{cEntity|Entity}}, [CallbackData])
The function returns false if the entity was not found, and it returns the same bool value that the callback has returned if the entity was found." }, + DoWithFurnaceAt = { Params = "X, Y, Z, CallbackFunction, [CallbackData]", Return = "bool", Notes = "If there is a furnace at the specified coords, calls the CallbackFunction with the {{cFurnaceEntity}} parameter representing the furnace. The CallbackFunction has the following signature:
function Callback({{cFurnaceEntity|FurnaceEntity}}, [CallbackData])
The function returns false if there is no furnace, or if there is, it returns the bool value that the callback has returned." }, + DoWithPlayer = { Params = "PlayerName, CallbackFunction, [CallbackData]", Return = "bool", Notes = "If there is a player of the specified name (exact match), calls the CallbackFunction with the {{cPlayer}} parameter representing the player. The CallbackFunction has the following signature:
function Callback({{cPlayer|Player}}, [CallbackData])
The function returns false if the player was not found, or whatever bool value the callback returned if the player was found." }, FastSetBlock = { { Params = "X, Y, Z, BlockType, BlockMeta", Return = "", Notes = "Sets the block at the specified coords, without waking up the simulators or replacing the block entities for the previous block type. Do not use if the block being replaced has a block entity tied to it!" }, { Params = "{{Vector3i|BlockCoords}}, BlockType, BlockMeta", Return = "", Notes = "Sets the block at the specified coords, without waking up the simulators or replacing the block entities for the previous block type. Do not use if the block being replaced has a block entity tied to it!" }, }, - FindAndDoWithPlayer = { Params = "PlayerNameHint, CallbackFunction, [CallbackData]", Return = "bool", Notes = "If there is a player of a name similar to the specified name (weighted-match), calls the CallbackFunction with the {{cPlayer}} parameter representing the player. The CallbackFunction has the following signature:
function Callback({{cPlayer|Player}}, [CallbackData])
The function returns false if the player was not found, or whatever bool value the callback returned if the player was found. Note that the name matching is very loose, so it is a good idea to check the player name in the callback function." }, - ForEachChestInChunk = { Params = "ChunkX, ChunkZ, CallbackFunction, [CallbackData]", Return = "bool", Notes = "Calls the specified callback for each chest in the chunk. Returns true if all chests in the chunk have been processed (including when there are zero chests), or false if the callback has aborted the enumeration by returning true. The CallbackFunction has the following signature:
function Callback({{cChestEntity|ChestEntity}}, [CallbackData])
The callback should return false or no value to continue with the next chest, or true to abort the enumeration." }, - ForEachEntity = { Params = "CallbackFunction, [CallbackData]", Return = "bool", Notes = "Calls the specified callback for each entity in the loaded world. Returns true if all the entities have been processed (including when there are zero entities), or false if the callback function has aborted the enumeration by returning true. The callback function has the following signature:
function Callback({{cEntity|Entity}}, [CallbackData])
The callback should return false or no value to continue with the next entity, or true to abort the enumeration." }, - ForEachEntityInChunk = { Params = "ChunkX, ChunkZ, CallbackFunction, [CallbackData]", Return = "bool", Notes = "Calls the specified callback for each entity in the specified chunk. Returns true if all the entities have been processed (including when there are zero entities), or false if the chunk is not loaded or the callback function has aborted the enumeration by returning true. The callback function has the following signature:
function Callback({{cEntity|Entity}}, [CallbackData])
The callback should return false or no value to continue with the next entity, or true to abort the enumeration." }, - ForEachFurnaceInChunk = { Params = "ChunkX, ChunkZ, CallbackFunction, [CallbackData]", Return = "bool", Notes = "Calls the specified callback for each furnace in the chunk. Returns true if all furnaces in the chunk have been processed (including when there are zero furnaces), or false if the callback has aborted the enumeration by returning true. The CallbackFunction has the following signature:
function Callback({{cFurnaceEntity|FurnaceEntity}}, [CallbackData])
The callback should return false or no value to continue with the next furnace, or true to abort the enumeration." }, - ForEachPlayer = { Params = "CallbackFunction, [CallbackData]", Return = "bool", Notes = "Calls the specified callback for each player in the loaded world. Returns true if all the players have been processed (including when there are zero players), or false if the callback function has aborted the enumeration by returning true. The callback function has the following signature:
function Callback({{cPlayer|Player}}, [CallbackData])
The callback should return false or no value to continue with the next player, or true to abort the enumeration." }, + FindAndDoWithPlayer = { Params = "PlayerNameHint, CallbackFunction, [CallbackData]", Return = "bool", Notes = "If there is a player of a name similar to the specified name (weighted-match), calls the CallbackFunction with the {{cPlayer}} parameter representing the player. The CallbackFunction has the following signature:
function Callback({{cPlayer|Player}}, [CallbackData])
The function returns false if the player was not found, or whatever bool value the callback returned if the player was found. Note that the name matching is very loose, so it is a good idea to check the player name in the callback function." }, + ForEachChestInChunk = { Params = "ChunkX, ChunkZ, CallbackFunction, [CallbackData]", Return = "bool", Notes = "Calls the specified callback for each chest in the chunk. Returns true if all chests in the chunk have been processed (including when there are zero chests), or false if the callback has aborted the enumeration by returning true. The CallbackFunction has the following signature:
function Callback({{cChestEntity|ChestEntity}}, [CallbackData])
The callback should return false or no value to continue with the next chest, or true to abort the enumeration." }, + ForEachEntity = { Params = "CallbackFunction, [CallbackData]", Return = "bool", Notes = "Calls the specified callback for each entity in the loaded world. Returns true if all the entities have been processed (including when there are zero entities), or false if the callback function has aborted the enumeration by returning true. The callback function has the following signature:
function Callback({{cEntity|Entity}}, [CallbackData])
The callback should return false or no value to continue with the next entity, or true to abort the enumeration." }, + ForEachEntityInChunk = { Params = "ChunkX, ChunkZ, CallbackFunction, [CallbackData]", Return = "bool", Notes = "Calls the specified callback for each entity in the specified chunk. Returns true if all the entities have been processed (including when there are zero entities), or false if the chunk is not loaded or the callback function has aborted the enumeration by returning true. The callback function has the following signature:
function Callback({{cEntity|Entity}}, [CallbackData])
The callback should return false or no value to continue with the next entity, or true to abort the enumeration." }, + ForEachFurnaceInChunk = { Params = "ChunkX, ChunkZ, CallbackFunction, [CallbackData]", Return = "bool", Notes = "Calls the specified callback for each furnace in the chunk. Returns true if all furnaces in the chunk have been processed (including when there are zero furnaces), or false if the callback has aborted the enumeration by returning true. The CallbackFunction has the following signature:
function Callback({{cFurnaceEntity|FurnaceEntity}}, [CallbackData])
The callback should return false or no value to continue with the next furnace, or true to abort the enumeration." }, + ForEachPlayer = { Params = "CallbackFunction, [CallbackData]", Return = "bool", Notes = "Calls the specified callback for each player in the loaded world. Returns true if all the players have been processed (including when there are zero players), or false if the callback function has aborted the enumeration by returning true. The callback function has the following signature:
function Callback({{cPlayer|Player}}, [CallbackData])
The callback should return false or no value to continue with the next player, or true to abort the enumeration." }, GenerateChunk = { Params = "ChunkX, ChunkZ", Return = "", Notes = "Queues the specified chunk in the chunk generator. Ignored if the chunk is already generated (use RegenerateChunk() to force chunk re-generation)." }, GetBiomeAt = { Params = "BlockX, BlockZ", Return = "eBiome", Notes = "Returns the biome at the specified coords. Reads the biome from the chunk, if it is loaded, otherwise it uses the chunk generator to provide the biome value." }, GetBlock = @@ -1924,7 +1924,7 @@ Sign entities are saved and loaded from disk when the chunk they reside in is sa The following code examples show how to use the callbacks

This code teleports player Player to another player named ToName in the same world: -

+
 -- Player is a cPlayer object
 -- ToName is a string
 -- World is a cWorld object
@@ -1937,7 +1937,7 @@ World:ForEachPlayer(
 

This code fills each furnace in the chunk with 64 coals: -

+
 -- Player is a cPlayer object
 -- World is a cWorld object
 World:ForEachFurnaceInChunk(Player:GetChunkX(), Player:GetChunkZ(),
@@ -1948,7 +1948,7 @@ World:ForEachFurnaceInChunk(Player:GetChunkX(), Player:GetChunkZ(),
 

This code teleports all spiders up by 100 blocks: -

+
 -- World is a cWorld object
 World:ForEachEntity(
 	function (a_Entity)
diff --git a/MCServer/Plugins/APIDump/main.lua b/MCServer/Plugins/APIDump/main.lua
index 1ba9397f5..3827668e3 100644
--- a/MCServer/Plugins/APIDump/main.lua
+++ b/MCServer/Plugins/APIDump/main.lua
@@ -661,6 +661,8 @@ function WriteHtmlClass(a_ClassAPI, a_AllAPI)
 	
 	cf:write([[MCServer API - ]] .. a_ClassAPI.Name .. [[ class
 	
+	
+	
 	
 	

Contents

    @@ -748,13 +750,16 @@ function WriteHtmlHook(a_Hook) end f:write([[MCServer API - ]] .. a_Hook.DefaultFnName .. [[ hook + +

    ]] .. a_Hook.Name .. [[ hook

    ]]); f:write(LinkifyString(a_Hook.Desc)); f:write("

    Callback function

    The default name for the callback function is "); - f:write(a_Hook.DefaultFnName .. ". It has the following signature:

    function " .. a_Hook.DefaultFnName .. "(");
    +	f:write(a_Hook.DefaultFnName .. ". It has the following signature:");
    +	f:write("
    function " .. a_Hook.DefaultFnName .. "(");
     	if (a_Hook.Params == nil) then
     		a_Hook.Params = {};
     	end
    @@ -771,7 +776,7 @@ function WriteHtmlHook(a_Hook)
     	f:write("

    \n

    " .. (a_Hook.Returns or "") .. "

    \n"); f:write([[

    Code examples

    Registering the callback

    -
    +
     cPluginManager.AddHook(cPluginManager.]] .. a_Hook.Name .. ", My" .. a_Hook.DefaultFnName .. [[);
     
    ]]); @@ -779,7 +784,7 @@ cPluginManager.AddHook(cPluginManager.]] .. a_Hook.Name .. ", My" .. a_Hook.Defa for i, example in ipairs(Examples) do f:write("

    " .. example.Title .. "

    \n"); f:write("

    " .. example.Desc .. "

    \n"); - f:write("
    " .. example.Code .. "
    \n"); + f:write("
    " .. example.Code .. "
    \n"); end f:close(); end -- cgit v1.2.3