diff options
author | Karl Berry <karl@freefriends.org> | 2012-08-13 22:41:51 +0000 |
---|---|---|
committer | Karl Berry <karl@freefriends.org> | 2012-08-13 22:41:51 +0000 |
commit | 891d790aa1dafff5340c181e3dce3332526e4834 (patch) | |
tree | 049abb04059bc666a0ffa9c585547f5fee297a4c /Master/texmf-dist/doc/luatex/luaxml | |
parent | 99f6ebc940e504927ea38d6600f8ca9f893667bb (diff) |
new luatex package luaxml (13aug12)
git-svn-id: svn://tug.org/texlive/trunk@27394 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/doc/luatex/luaxml')
-rw-r--r-- | Master/texmf-dist/doc/luatex/luaxml/README | 27 | ||||
-rw-r--r-- | Master/texmf-dist/doc/luatex/luaxml/luaxml.pdf | bin | 0 -> 111453 bytes | |||
-rw-r--r-- | Master/texmf-dist/doc/luatex/luaxml/luaxml.tex | 355 |
3 files changed, 382 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/luatex/luaxml/README b/Master/texmf-dist/doc/luatex/luaxml/README new file mode 100644 index 00000000000..cb48cbab9bd --- /dev/null +++ b/Master/texmf-dist/doc/luatex/luaxml/README @@ -0,0 +1,27 @@ +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. The documentation was created by automatic conversion of original documentation in the source code. +In this version, some files not useful for luaTeX were droped. Original files can be found at + + http://manoelcampos.com/files/LuaXML--0.0.0-lua5.1.tgz + + +License: +======== + +This code is freely distributable under the terms of the Lua license + (http://www.lua.org/copyright.html) + + +Author +------ +Michal Hoftich +Email: michal.h21@gmail.com + +Original authors: Paul Chakravarti and Manoel Campos (http://manoelcampos.com) + +If you are interested in the process of development you may observe + + https://github.com/michal-h21/LuaXML
\ No newline at end of file diff --git a/Master/texmf-dist/doc/luatex/luaxml/luaxml.pdf b/Master/texmf-dist/doc/luatex/luaxml/luaxml.pdf Binary files differnew file mode 100644 index 00000000000..cddfdcdf5d9 --- /dev/null +++ b/Master/texmf-dist/doc/luatex/luaxml/luaxml.pdf diff --git a/Master/texmf-dist/doc/luatex/luaxml/luaxml.tex b/Master/texmf-dist/doc/luatex/luaxml/luaxml.tex new file mode 100644 index 00000000000..34363fbcf04 --- /dev/null +++ b/Master/texmf-dist/doc/luatex/luaxml/luaxml.tex @@ -0,0 +1,355 @@ +\documentclass{ltxdoc} +\usepackage{tgschola,url} +\usepackage[english]{babel} +\begin{document} + \title{The \textsc{LuaXML} library} + \author{Paul Chakravarti \and Michal Hoftich} + \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 = [[ +<a> + <d>hello</d> + <b>world.</b> + <b at="Hi">another</b> +</a>]] +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 +-- <?xml version="1.0" encoding="UTF-8"?> +-- <a> +-- <d>hello</d> +-- <b>world.</b> +-- <b at="Hi"> +-- another +-- </b> +-- </a> +-- +-- 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} +<a>hello + <b>world</b> +</a> +\end{verbatim} +it produces wrong results. It is useful mostly for data |xml| files, not for text formats like |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:start - Start Tag +handler:end - 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 +start & name & |{ attributes (name=val).. }|\\ +end & name & nil\\ +text & |<text>| & nil\\ +cdata & |<text> | & nil\\ +decl & "xml" & |{ attributes (name=val).. }|\\ +pi & pi name & \begin{verbatim}{ attributes (if present).. + _text = <PI Text> +}\end{verbatim}\\ +comment & |<text>| & nil\\ +dtd & root element & \begin{verbatim}{ _root = <Root Element>, + _type = SYSTEM|PUBLIC, + _name = <name>, + _uri = <uri>, + _internal = <internal dtd> +}\end{verbatim}\\ +\end{tabular} + +(start \& end provide the character positions of the start/end of the +element) + +XML data is passed to the parser instance through the `parse' method +(Nore: must be passed a 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 = { start = function(t,a,s,e) .... end, + end = 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("<?xml... ") +\end{verbatim} +\section{Handlers}\label{sec:handlers} + +\subsection{Overview} + +Standard XML event handler(s) for XML parser module (luaxml-mod-xml.lua) + +\subsection{Features} + +\begin{verbatim} +printHandler - Generate XML event trace +domHandler - Generate DOM-like node tree +simpleTreeHandler - Generate 'simple' node tree +simpleTeXhandler - SAX like handler with support for CSS selectros +\end{verbatim} +\subsection{API} + +Must be called as handler function from xmlParser and implement XML +event callbacks (see xmlParser.lua for callback API definition) + +\subsubsection{printHandler} + +printHandler prints event trace for debugging + +\subsubsection{domHandler} + +domHandler generates a DOM-like node tree structure with +a single ROOT node parent - each node is a table comprising +fields below. + +\begin{verbatim} +node = { _name = <Element Name>, + _type = ROOT|ELEMENT|TEXT|COMMENT|PI|DECL|DTD, + _attr = { Node attributes - see callback API }, + _parent = <Parent Node> + _children = { List of child nodes - ROOT/NODE only } + } + +\end{verbatim} +The dom structure is capable of representing any valid XML document +\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 = { <tag> = 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} |