\documentclass{ltxdoc} \usepackage{tgschola,url} \usepackage[english]{babel} \begin{document} \title{The \textsc{LuaXML} library} \author{Paul Chakravarti \and Michal Hoftich} \date{Version 0.0.2\\May 25, 2013} \maketitle \tableofcontents \section*{Introduction} |LuaXML| is pure lua library for reading and serializing of the |xml| files. Current release is aimed mainly as support for the odsfile package. In first release it was included with the odsfile package, but as it is general library which can be used also with other packages, I decided to distribute it as separate library. \noindent Example of usage: \begin{verbatim} xml = require('luaxml-mod-xml') handler = require('luaxml-mod-handler') \end{verbatim} First load the libraries. In |luaxml-mod-xml|, there is xml parser and also serializer. In |luaxml-mod-handler|, there are various handlers for dealing with xml data. Handlers are objects with callback functions which are invoked for every type of content in the |xml| file. More information about handlers can be found in the original documentation, section \ref{sec:handlers}. \begin{verbatim} sample = [[ hello world. another ]] treehandler = handler.simpleTreeHandler() x = xml.xmlParser(treehandler) x:parse(sample) \end{verbatim} You have to create handler object, using |handler.simpleTreeHandler()| and xml parser object using |xml.xmlParser(handler object)|. |simpleTreehandler| creates simple table hierarchy, with top root node in |treehandler.root| \begin{verbatim} -- pretty printing function function printable(tb, level) level = level or 1 local spaces = string.rep(' ', level*2) for k,v in pairs(tb) do if type(v) ~= "table" then print(spaces .. k..'='..v) else print(spaces .. k) level = level + 1 printable(v, level) end end end -- print table printable(treehandler.root) -- print xml serialization of table print(xml.serialize(treehandler.root)) -- direct access to the element print(treehandler.root["a"]["b"][1]) -- output: -- a -- d=hello -- b -- 1=world. -- 2 -- 1=another -- _attr -- at=Hi -- -- -- hello -- world. -- -- another -- -- -- -- world. \end{verbatim} Note that |simpleTreeHandler| creates tables that can be easily accessed using standard lua functions, but in case of mixed content, like \begin{verbatim} hello world \end{verbatim} it produces wrong results. It is useful mostly for data |xml| files, not for text formats like |xhtml|. For complex xml documents with mixed content, |domHandler| is capable of representing any valid XML document: \begin{verbatim} -- dom-sample.lua -- next line enables scripts called with texlua to use luatex libraries kpse.set_program_name("luatex") function traverseDom(parser, current,level) local level = level or 0 local spaces = string.rep(" ",level) local root= current or parser._handler.root local name = root._name or "unnamed" local xtype = root._type or "untyped" local attributes = root._attr or {} if xtype == "TEXT" then print(spaces .."TEXT : " .. root._text) else print(spaces .. xtype .. " : " .. name) end for k, v in pairs(attributes) do print(spaces .. " ".. k.."="..v) end local children = root._children or {} for _, child in ipairs(children) do traverseDom(parser,child, level + 1) end end local xml = require('luaxml-mod-xml') local handler = require('luaxml-mod-handler') local x = '

hello world, how are you?

' local domHandler = handler.domHandler() local parser = xml.xmlParser(domHandler) parser:parse(x) traverseDom(parser) \end{verbatim} This produces after running with |texlua dom-sample.lua|: \begin{verbatim} ROOT : unnamed ELEMENT : p TEXT : hello ELEMENT : a href=http://world.com/ TEXT : world TEXT : , how are you? \end{verbatim} With \verb|domHandler|, you can process documents with mixed content, like \verb|xhtml|. Because at the moment it is intended mainly as support for the odsfile package, there is little documentation, what follows is the original documentation of |LuaXML|, which may be little bit obsolete now. \clearpage \noindent{\Huge Original documentation} \medskip \noindent This document was created automatically from original source code comments using Pandoc\footnote{\url{http://johnmacfarlane.net/pandoc/}} \section{Overview} This module provides a non-validating XML stream parser in Lua. \section{Features} \begin{itemize} \item Tokenises well-formed XML (relatively robustly) \item Flexible handler based event api (see below) \item Parses all XML Infoset elements - ie. \begin{itemize} \item Tags \item Text \item Comments \item CDATA \item XML Decl \item Processing Instructions \item DOCTYPE declarations \end{itemize} \item Provides limited well-formedness checking (checks for basic syntax \& balanced tags only) \item Flexible whitespace handling (selectable) \item Entity Handling (selectable) \end{itemize} \section{Limitations} \begin{itemize} \item Non-validating \item No charset handling \item No namespace support \item Shallow well-formedness checking only (fails to detect most semantic errors) \end{itemize} \section{API} The parser provides a partially object-oriented API with functionality split into tokeniser and hanlder components. The handler instance is passed to the tokeniser and receives callbacks for each XML element processed (if a suitable handler function is defined). The API is conceptually similar to the SAX API but implemented differently. The following events are generated by the tokeniser \begin{verbatim} handler:starttag - Start Tag handler:endtag - End Tag handler:text - Text handler:decl - XML Declaration handler:pi - Processing Instruction handler:comment - Comment handler:dtd - DOCTYPE definition handler:cdata - CDATA \end{verbatim} The function prototype for all the callback functions is \begin{verbatim} callback(val,attrs,start,end) \end{verbatim} where attrs is a table and val/attrs are overloaded for specific callbacks - ie. \begin{tabular}{llp{5cm}} Callback & val & attrs (table)\\ \hline starttag & name & |{ attributes (name=val).. }|\\ endtag & name & nil\\ text & || & nil\\ cdata & | | & nil\\ decl & "xml" & |{ attributes (name=val).. }|\\ pi & pi name & \begin{verbatim}{ attributes (if present).. _text = }\end{verbatim}\\ comment & || & nil\\ dtd & root element & \begin{verbatim}{ _root = , _type = SYSTEM|PUBLIC, _name = , _uri = , _internal = }\end{verbatim}\\ \end{tabular} (starttag \& endtag provide the character positions of the start/end of the element) XML data is passed to the parser instance through the `parse' method (Note: must be passed as single string currently) \section{Options} Parser options are controlled through the `self.options' table. Available options are - \begin{itemize} \item stripWS Strip non-significant whitespace (leading/trailing) and do not generate events for empty text elements \item expandEntities Expand entities (standard entities + single char numeric entities only currently - could be extended at runtime if suitable DTD parser added elements to table (see obj.\_ENTITIES). May also be possible to expand multibyre entities for UTF--8 only \item errorHandler Custom error handler function \end{itemize} NOTE: Boolean options must be set to `nil' not `0' \section{Usage} Create a handler instance - \begin{verbatim} h = { starttag = function(t,a,s,e) .... end, endtag = function(t,a,s,e) .... end, text = function(t,a,s,e) .... end, cdata = text } \end{verbatim} (or use predefined handler - see luaxml-mod-handler.lua) Create parser instance - \begin{verbatim} p = xmlParser(h) \end{verbatim} Set options - \begin{verbatim} p.options.xxxx = nil \end{verbatim} Parse XML data - \begin{verbatim} xmlParser:parse(", _type = ROOT|ELEMENT|TEXT|COMMENT|PI|DECL|DTD, _attr = { Node attributes - see callback API }, _parent = _children = { List of child nodes - ROOT/NODE only } } \end{verbatim} \subsubsection{simpleTreeHandler} simpleTreeHandler is a simplified handler which attempts to generate a more `natural' table based structure which supports many common XML formats. The XML tree structure is mapped directly into a recursive table structure with node names as keys and child elements as either a table of values or directly as a string value for text. Where there is only a single child element this is inserted as a named key - if there are multiple elements these are inserted as a vector (in some cases it may be preferable to always insert elements as a vector which can be specified on a per element basis in the options). Attributes are inserted as a child element with a key of `\_attr'. Only Tag/Text \& CDATA elements are processed - all others are ignored. This format has some limitations - primarily \begin{itemize} \item Mixed-Content behaves unpredictably - the relationship between text elements and embedded tags is lost and multiple levels of mixed content does not work \item If a leaf element has both a text element and attributes then the text must be accessed through a vector (to provide a container for the attribute) \end{itemize} In general however this format is relatively useful. \subsection{Options} \begin{verbatim} simpleTreeHandler.options.noReduce = { = bool,.. } - Nodes not to reduce children vector even if only one child domHandler.options.(comment|pi|dtd|decl)Node = bool - Include/exclude given node types \end{verbatim} \subsection{Usage} Pased as delegate in xmlParser constructor and called as callback by xmlParser:parse(xml) method. \section{History} This library is fork of LuaXML library originaly created by Paul Chakravarti. Its original version can be found at \url{http://manoelcampos.com/files/LuaXML--0.0.0-lua5.1.tgz}. Some files not needed for use with luatex were droped from the distribution. Documentation was converted from original comments in the source code. \section{License} This code is freely distributable under the terms of the Lua license (\url{http://www.lua.org/copyright.html}) \end{document}