Merge remote-tracking branch 'upstream/master' into playerxp

MCServer/Plugins/APIDump/APIDesc.lua

@@ -2478,6 +2478,112 @@ end
 			},
 		},  -- ItemCategory
 		
+		lxp =
+		{
+			Desc = [[
+				This class provides an interface to the XML parser,
+				{{http://matthewwild.co.uk/projects/luaexpat/|LuaExpat}}. It provides a SAX interface with an
+				incremental XML parser.</p>
+				<p>
+				With an event-based API like SAX the XML document can be fed to the parser in chunks, and the
+				parsing begins as soon as the parser receives the first document chunk. LuaExpat reports parsing
+				events (such as the start and end of elements) directly to the application through callbacks. The
+				parsing of huge documents can benefit from this piecemeal operation.</p>
+				<p>
+				See the online
+				{{http://matthewwild.co.uk/projects/luaexpat/manual.html#parser|LuaExpat documentation}} for details
+				on how to work with this parser. The code examples below should provide some basic help, too.
+			]],
+			Functions =
+			{
+				new = {Params = "CallbacksTable, [SeparatorChar]", Return = "XMLParser object", Notes = "Creates a new XML parser object, with the specified callbacks table and optional separator character."},
+			},
+			Constants =
+			{
+				_COPYRIGHT = { Notes = "" },
+				_DESCRIPTION = { Notes = "" },
+				_VERSION = { Notes = "" },
+			},
+			AdditionalInfo =
+			{
+				{
+					Header = "Parser callbacks",
+					Contents = [[
+						The callbacks table passed to the new() function specifies the Lua functions that the parser
+						calls upon various events. The following table lists the most common functions used, for a
+						complete list see the online
+						{{http://matthewwild.co.uk/projects/luaexpat/manual.html#parser|LuaExpat documentation}}.</p>
+						<table>
+						<tr><th>Function name</th><th>Parameters</th><th>Notes</th></tr>
+						<tr><td>CharacterData</td><td>Parser, string</td><td>Called when the parser recognizes a raw string inside the element</td></tr>
+						<tr><td>EndElement</td><td>Parser, ElementName</td><td>Called when the parser detects the ending of an XML element</td></tr>
+						<tr><td>StartElement</td><td>Parser, ElementName, AttributesTable</td><td>Called when the parser detects the start of an XML element. The AttributesTable is a Lua table containing all the element's attributes, both in the array section (in the order received) and in the dictionary section.</td></tr>
+						</table>
+					]],
+				},
+				{
+					Header = "XMLParser object",
+					Contents = [[
+						The XMLParser object returned by lxp.new provides the functions needed to parse the XML. The
+						following list provides the most commonly used ones, for a complete list see the online
+						{{http://matthewwild.co.uk/projects/luaexpat/manual.html#parser|LuaExpat documentation}}.
+						<ul>
+							<li>close() - closes the parser, freeing all memory used by it.</li>
+							<li>getCallbacks() - returns the callbacks table for this parser.</li>
+							<li>parse(string) - parses more document data. the string contains the next part (or possibly all) of the document. Returns non-nil for success or nil, msg, line, col, pos for error.</li>
+							<li>stop() - aborts parsing (can be called from within the parser callbacks).</li>
+						</ul>
+					]],
+				},
+				{
+					Header = "Code example",
+					Contents = [[
+						The following code reads an entire XML file and outputs its logical structure into the console:
+<pre class="prettyprint lang-lua">
+local Depth = 0;
+
+-- Define the callbacks:
+local Callbacks = {
+	CharacterData = function(a_Parser, a_String)
+		LOG(string.rep(" ", Depth) .. "* " .. a_String);
+	end
+	
+	EndElement = function(a_Parser, a_ElementName)
+		Depth = Depth - 1;
+		LOG(string.rep(" ", Depth) .. "- " .. a_ElementName);
+	end
+
+	StartElement = function(a_Parser, a_ElementName, a_Attribs)
+		LOG(string.rep(" ", Depth) .. "+ " .. a_ElementName);
+		Depth = Depth + 1;
+	end
+}
+
+-- Create the parser:
+local Parser = lxp.new(Callbacks);
+
+-- Parse the XML file:
+local f = io.open("file.xml", "rb");
+while (true) do
+	local block = f:read(128 * 1024);  -- Use a 128KiB buffer for reading
+	if (block == nil) then
+		-- End of file
+		break;
+	end
+	Parser:parse(block);
+end
+
+-- Signalize to the parser that no more data is coming
+Parser:parse();
+
+-- Close the parser:
+Parser:close();
+</pre>
+					]],
+				},
+			},  -- AdditionalInfo
+		},  -- lxp
+		
 		TakeDamageInfo =
 		{
 			Desc = [[

MCServer/Plugins/APIDump/main.lua

@@ -373,13 +373,18 @@ function ReadDescriptions(a_API)
 		return false;
 	end
 	
-	-- Returns true if the function (specified by its fully qualified name) is to be ignored
+	-- Returns true if the function is to be ignored
-	local function IsFunctionIgnored(a_FnName)
+	local function IsFunctionIgnored(a_ClassName, a_FnName)
 		if (g_APIDesc.IgnoreFunctions == nil) then
 			return false;
 		end
+		if (((g_APIDesc.Classes[a_ClassName] or {}).Functions or {})[a_FnName] ~= nil) then
+			-- The function is documented, don't ignore
+			return false;
+		end
+		local FnName = a_ClassName .. "." .. a_FnName;
 		for i, name in ipairs(g_APIDesc.IgnoreFunctions) do
-			if (a_FnName:match(name)) then
+			if (FnName:match(name)) then
 				return true;
 			end
 		end
@@ -482,7 +487,7 @@ function ReadDescriptions(a_API)
 					if (FnDesc == nil) then
 						-- No description for this API function
 						AddFunction(func.Name);
-						if not(IsFunctionIgnored(cls.Name .. "." .. FnName)) then
+						if not(IsFunctionIgnored(cls.Name, FnName)) then
 							table.insert(cls.UndocumentedFunctions, FnName);
 						end
 					else
@@ -505,7 +510,7 @@ function ReadDescriptions(a_API)
 			else  -- if (APIDesc.Functions ~= nil)
 				for j, func in ipairs(cls.Functions) do
 					local FnName = func.DocID or func.Name;
-					if not(IsFunctionIgnored(cls.Name .. "." .. FnName)) then
+					if not(IsFunctionIgnored(cls.Name, FnName)) then
 						table.insert(cls.UndocumentedFunctions, FnName);
 					end
 				end
@@ -567,7 +572,7 @@ function ReadDescriptions(a_API)
 			g_Stats.NumUndocumentedClasses = g_Stats.NumUndocumentedClasses + 1;
 			for j, func in ipairs(cls.Functions) do
 				local FnName = func.DocID or func.Name;
-				if not(IsFunctionIgnored(cls.Name .. "." .. FnName)) then
+				if not(IsFunctionIgnored(cls.Name, FnName)) then
 					table.insert(cls.UndocumentedFunctions, FnName);
 				end
 			end  -- for j, func - cls.Functions[]
@@ -586,7 +591,7 @@ function ReadDescriptions(a_API)
 		-- Remove ignored functions:
 		local NewFunctions = {};
 		for j, fn in ipairs(cls.Functions) do
-			if (not(IsFunctionIgnored(cls.Name .. "." .. fn.Name))) then
+			if (not(IsFunctionIgnored(cls.Name, fn.Name))) then
 				table.insert(NewFunctions, fn);
 			end
 		end  -- for j, fn