summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorDaniel O'Brien <marmot.daniel@gmail.com>2013-11-16 07:30:19 +0100
committerDaniel O'Brien <marmot.daniel@gmail.com>2013-11-16 07:30:19 +0100
commitdf4aa6c86432732bd1ec398e7e3e95f079d2326a (patch)
treeb8a8628e0eca0ed358674499972f662c75e0f24a
parentalignment fixes :) (diff)
parentAPIDump: Documented lxp, the XML parser class. (diff)
downloadcuberite-df4aa6c86432732bd1ec398e7e3e95f079d2326a.tar
cuberite-df4aa6c86432732bd1ec398e7e3e95f079d2326a.tar.gz
cuberite-df4aa6c86432732bd1ec398e7e3e95f079d2326a.tar.bz2
cuberite-df4aa6c86432732bd1ec398e7e3e95f079d2326a.tar.lz
cuberite-df4aa6c86432732bd1ec398e7e3e95f079d2326a.tar.xz
cuberite-df4aa6c86432732bd1ec398e7e3e95f079d2326a.tar.zst
cuberite-df4aa6c86432732bd1ec398e7e3e95f079d2326a.zip
-rw-r--r--MCServer/Plugins/APIDump/APIDesc.lua106
-rw-r--r--MCServer/Plugins/APIDump/main.lua19
2 files changed, 118 insertions, 7 deletions
diff --git a/MCServer/Plugins/APIDump/APIDesc.lua b/MCServer/Plugins/APIDump/APIDesc.lua
index 741b912a6..cccc05ce2 100644
--- a/MCServer/Plugins/APIDump/APIDesc.lua
+++ b/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 = [[
diff --git a/MCServer/Plugins/APIDump/main.lua b/MCServer/Plugins/APIDump/main.lua
index d84926b53..ab154dc45 100644
--- a/MCServer/Plugins/APIDump/main.lua
+++ b/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
- local function IsFunctionIgnored(a_FnName)
+ -- Returns true if the function is to be ignored
+ 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