diff options
author | Karl Berry <karl@freefriends.org> | 2018-02-09 00:16:06 +0000 |
---|---|---|
committer | Karl Berry <karl@freefriends.org> | 2018-02-09 00:16:06 +0000 |
commit | b2153506a41b9f934841bc0eb31dd9c3946b407b (patch) | |
tree | debea85a21708749fafa1748c894ab25b0e125e8 /Master/texmf-dist/doc | |
parent | e6304d3f0b0d72c2f38350d3ae4b4fa6bd862793 (diff) |
luaxml (8feb18)
git-svn-id: svn://tug.org/texlive/trunk@46570 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/doc')
-rw-r--r-- | Master/texmf-dist/doc/luatex/luaxml/README | 10 | ||||
-rw-r--r-- | Master/texmf-dist/doc/luatex/luaxml/luaxml.pdf | bin | 114519 -> 98163 bytes | |||
-rw-r--r-- | Master/texmf-dist/doc/luatex/luaxml/luaxml.tex | 434 |
3 files changed, 399 insertions, 45 deletions
diff --git a/Master/texmf-dist/doc/luatex/luaxml/README b/Master/texmf-dist/doc/luatex/luaxml/README index cb48cbab9bd..0ebf891e74b 100644 --- a/Master/texmf-dist/doc/luatex/luaxml/README +++ b/Master/texmf-dist/doc/luatex/luaxml/README @@ -7,6 +7,16 @@ In this version, some files not useful for luaTeX were droped. Original files ca http://manoelcampos.com/files/LuaXML--0.0.0-lua5.1.tgz +Install +======= + +LuaXML is installed in TeX distributions, so you don't need to install it yourself. If you want to try the development version, +then clone this repository and run + + make install + +Please note that you will need [LDoc](http://stevedonovan.github.io/ldoc/manual/doc.md.html#Processing_Single_Modules) installed +on your system. License: ======== diff --git a/Master/texmf-dist/doc/luatex/luaxml/luaxml.pdf b/Master/texmf-dist/doc/luatex/luaxml/luaxml.pdf Binary files differindex 3a6967c9c66..07ec3244c70 100644 --- a/Master/texmf-dist/doc/luatex/luaxml/luaxml.pdf +++ 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 index 4dcff6a51a1..88ab450a50e 100644 --- a/Master/texmf-dist/doc/luatex/luaxml/luaxml.tex +++ b/Master/texmf-dist/doc/luatex/luaxml/luaxml.tex @@ -1,28 +1,347 @@ \documentclass{ltxdoc} -\usepackage{tgschola,url} +% \usepackage{tgschola,url} +\usepackage{url} \usepackage[english]{babel} +\usepackage{hyperref} +\usepackage{luacode} +\usepackage{framed} +% Version is defined in the makefile, use default values when compiled directly +\ifdefined\version\else +\def\version{0} +\let\gitdate\date +\fi +\newcommand\modulename[1]{\subsection{#1}\label{sec:#1}} +\newcommand\modulesummary[1]{#1\\} +\newcommand\moduleclass[1]{\subsubsection{Class: #1}} +\newcommand\functionname[2]{\par\noindent\textbf{#1(#2)}\\} +\newcommand\functionsummary[1]{#1\\\textbf{Parameters:}\\} +\newcommand\functionparam[2]{\texttt{#1}: #2\\} +\newcommand\functionreturn[1]{\textbf{Return: }\\#1\\} + \begin{document} \title{The \textsc{LuaXML} library} \author{Paul Chakravarti \and Michal Hoftich} - \date{Version 0.0.2\\May 25, 2013} + \date{Version \version\\\gitdate} \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. +\section{Introduction} + +|LuaXML| is pure lua library for processing and serializing of the |xml| files. +The base code code has been written by Paul Chakravarti, with minor changes +which brings Lua 5.3 or HTML 5 support. On top of that, new modules for +accessing the |xml| files using |DOM| like methods or |CSS| +selectors\footnote{Thanks to Leaf Corcoran for |CSS selector| parsing code.} +have been added. + +The documentation is divided to three parts -- first part deals with the |DOM| +library, second part describes the low-level libraries and the third part is +original documentation by Paul Chakravarti. +% 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. + +\section{The \texttt{DOM\_Object} library} + +This library can process a |xml| sources using |DOM| like functions. To load +it, you need to require |luaxml-domobject.lua| file. The |parse| function +provided by the library creates \texttt{DOM\_Object} object, which provides several +methods for processing the |xml| tree. + +\begin{verbatim} +local dom = require "luaxml-domobject" +local document = [[ +<html> +<head><title>sample</title></head> +<body> +<h1>test</h1> +<p>hello</p> +</body> +</html> + ]] + +-- dom.parse returns the DOM_Object +local obj = dom.parse(document) +-- it is possible to call methods on the object +local root_node = obj:root_node() +for _, x in ipairs(root_node:get_children()) do + print(x:get_element_name()) +end +\end{verbatim} + +The details about available methods can be found in the API docs, section +\ref{sec:luaxml-domobject}. The above code will load a |xml| document, it will +get the ROOT element and print all it's children element names. The +\verb|DOM_Object:get_children| function returns Lua table, so it is possible to +loop over it using standard table functions. + +\begin{framed} +\begin{luacode*} +dom = require "luaxml-domobject" +local document = [[ +<html> +<head><title>sample</title></head> +<body> +<h1>test</h1> +<p>hello</p> +</body> +</html> + ]] + +-- dom.parse returns the DOM_Object +obj = dom.parse(document) +-- it is possible to call methods on the object +local root_node = obj:root_node() +for _, x in ipairs(root_node:get_children()) do + tex.print(x:get_element_name().. "\\par") +end +\end{luacode*} +\end{framed} + +\subsection{Node selection methods} +There are some other methods for element retrieving. + +\subsubsection{The \texttt{DOM\_Object:get\_path} method} +If you want to print text content of all child elements of the body element, you can use \verb|DOM_Object:get_path|: + +\begin{verbatim} +local path = obj:get_path("html body") +for _, el in ipairs(path[1]:get_children()) do + print(el:get_text()) +end +\end{verbatim} + +The \verb|DOM_Object:get_path| function always return array with all elements +which match the requested path, even it there is only one such element. In this +case, it is possible to use standard Lua table indexing to get the first and +only one matched element and get it's children using +\verb|DOM_Object:get_children| method. It the children node is an element, it's +text content is printed using \verb|DOM_Object:get_text|. + + + +\begin{framed} + \begin{luacode*} +local path = obj:get_path("html body") + +for _, el in ipairs(path[1]:get_children()) do + if el:is_element() then + tex.print(el:get_text().."\\par") + end +end + \end{luacode*} +\end{framed} + +\subsubsection{The \texttt{DOM\_Object:query\_selector} method} + +This method uses |CSS selector| syntax to select elements, similarly to JavaScript \textit{jQuery} library. + +\begin{verbatim} +for _, el in ipairs(obj:query_selector("h1,p")) do + print(el:get_text()) +end +\end{verbatim} + + +\begin{framed} + \begin{luacode*} +for _, el in ipairs(obj:query_selector("h1,p")) do + tex.print(el:get_text().."\\par") +end + \end{luacode*} +\end{framed} + +\subsection{Element traversing} + +\subsubsection{The \texttt{DOM\_Object:traverse\_elements} method} + +It may be useful to traverse over all elements and apply a function on all of them. + +\begin{verbatim} +obj:traverse_elements(function(node) + print(node:get_text()) +end) +\end{verbatim} + +\begin{framed} + \begin{luacode*} +obj:traverse_elements(function(node) + tex.print(node:get_text().."\\par") +end) + \end{luacode*} +\end{framed} + +The \verb|get_text| method gets text from all children elements, so the first +line shows all text contained in the \verb|<html>| element, the second one in +\verb|<head>| element and so on. + +\subsection{DOM modifications} + +It is possible to add new elements, text nodes, or to remove them. -\noindent Example of usage: +\begin{verbatim} +local headers = obj:query_selector("h1") +for _, header in ipairs(headers) do + header:remove_node() +end +-- query selector returns array, we must retrieve the first element +-- to get the actual body element +local body = obj:query_selector("body")[1] +local paragraph = body:create_element("p", {}) +body:add_child_node(paragraph) +paragraph:add_child_node(paragraph:create_text_node("This is a second paragraph")) + +for _, el in ipairs(body:get_children()) do + if el:is_element() then + print(el:get_element_name().. ": ".. el:get_text()) + end +end +\end{verbatim} + +In this example, \verb|<h1>| element is being removed from the sample document, and new +paragraph is added. Two paragraphs should be shown in the output: + +\begin{framed} + \begin{luacode*} +local headers = obj:query_selector("h1") +-- query selector returns array, we must retrieve the first element +-- to get the actual body element +local body = obj:query_selector("body")[1] +local oldbody = body:copy_node() +for _, header in ipairs(headers) do + header:remove_node() +end +local paragraph = body:create_element("p", {}) +body:add_child_node(paragraph) +paragraph:add_child_node(paragraph:create_text_node("This is a second paragraph")) + +for _, el in ipairs(body:get_children()) do +if el:is_element() then + tex.print(el:get_element_name().. ": ".. el:get_text() .. "\\par") +end +end + +body:replace_node(oldbody) + \end{luacode*} +\end{framed} + + +\section{The \texttt{CssQuery} library} + +This library serves mainly as a support for the +\texttt{DOM\_Object:query\_selector} function. It also supports adding +information to the DOM tree. + +\subsection{Example usage} + +\begin{verbatim} +local cssobj = require "luaxml-cssquery" +local domobj = require "luaxml-domobject" + +local xmltext = [[ +<html> +<body> +<h1>Header</h1> +<p>Some text, <i>italics</i></p> +</body> +</html> +]] + +local dom = domobj.parse(xmltext) +local css = cssobj() + +css:add_selector("h1", function(obj) + print("header found: " .. obj:get_text()) +end) + +css:add_selector("p", function(obj) + print("paragraph found: " .. obj:get_text()) +end) + +css:add_selector("i", function(obj) + print("found italics: " .. obj:get_text()) +end) + +dom:traverse_elements(function(el) + -- find selectors that match the current element + local querylist = css:match_querylist(el) + -- add templates to the element + css:apply_querylist(el,querylist) +end) +\end{verbatim} + +\begin{framed} + \begin{luacode*} +local cssobj = require "luaxml-cssquery" +local domobj = require "luaxml-domobject" +local print = function(s) tex.print(s .. "\\par") end + +local xmltext = [[ +<html> +<body> +<h1>Header</h1> +<p>Some text, <i>italics</i></p> +</body> +</html> +]] + +local dom = domobj.parse(xmltext) +local css = cssobj() + +css:add_selector("h1", function(obj) + print("header found: " .. obj:get_text()) +end) + +css:add_selector("p", function(obj) + print("paragraph found: " .. obj:get_text()) +end) + +css:add_selector("i", function(obj) + print("found italics: " .. obj:get_text()) +end) + +dom:traverse_elements(function(el) + -- find selectors that match the current element + local querylist = css:match_querylist(el) + -- add templates to the element + css:apply_querylist(el,querylist) +end) + \end{luacode*} +\end{framed} + +More complete example may be found in the \texttt{examples} directory in the +\texttt{LuaXML} source code +repository\footnote{\url{https://github.com/michal-h21/LuaXML/blob/master/examples/xmltotex.lua}}. + +\section{The API documentation} + +\input{doc/api.tex} + +\section{Low-level functions usage} + +% The processing is done with several handlers, their usage will be shown in the +% following section. Full description of handlers is given in the original +% documentation in section \ref{sec:handlers}. + +% \subsection{Usage examples} + +The original |LuaXML| library provides some low-level functions for |XML| handling. +First of all, we need to load the libraries: \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}. + +The |luaxml-mod-xml| file contains the xml parser and also the serializer. In +|luaxml-mod-handler|, various handlers for dealing with xml data are defined. +Handlers transforms the |xml| file to data structures which can be handled from +the Lua code. More information about handlers can be found in the original +documentation, section \ref{sec:handlers}. + +\subsection{The simpleTreeHandler} \begin{verbatim} sample = [[ <a> @@ -35,7 +354,10 @@ 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| +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) @@ -58,46 +380,63 @@ printable(treehandler.root) print(xml.serialize(treehandler.root)) -- direct access to the element print(treehandler.root["a"]["b"][1]) +\end{verbatim} --- 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. +This code produces the following output: + +\begin{verbatim} + 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 +First part is pretty-printed dump of Lua table structure contained in the handler, the second +part is |xml| serialized from that table and the last part demonstrates direct access to particular +elements. + +Note that |simpleTreeHandler| creates tables that can be easily accessed using +standard lua functions, but if the xml document is of mixed-content type\footnote{% +This means that element may contain both children elements and text.}: + \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|. -For complex xml documents with mixed content, |domHandler| is capable of representing any valid XML document: +\noindent then it produces wrong results. It is useful mostly for data |xml| files, not for +text formats like |xhtml|. + +\subsection{The domHandler} + +% For complex xml documents with mixed content, |domHandler| is capable of representing any valid XML document: +For complex xml documents, it is best to use the |domHandler|, which creates object which contains all information +from the |xml| document. \begin{verbatim} --- dom-sample.lua +-- file dom-sample.lua -- next line enables scripts called with texlua to use luatex libraries -kpse.set_program_name("luatex") -function traverseDom(parser, current,level) +--kpse.set_program_name("luatex") +function traverseDom(current,level) local level = level or 0 local spaces = string.rep(" ",level) - local root= current or parser._handler.root + local root= current or current.root local name = root._name or "unnamed" local xtype = root._type or "untyped" local attributes = root._attr or {} @@ -111,7 +450,7 @@ function traverseDom(parser, current,level) end local children = root._children or {} for _, child in ipairs(children) do - traverseDom(parser,child, level + 1) + traverseDom(child, level + 1) end end @@ -121,10 +460,16 @@ local x = '<p>hello <a href="http://world.com/">world</a>, how are you?</p>' local domHandler = handler.domHandler() local parser = xml.xmlParser(domHandler) parser:parse(x) -traverseDom(parser) +traverseDom(domHandler.root) \end{verbatim} -This produces after running with |texlua dom-sample.lua|: +The ROOT element is stored in |domHandler.root| table, it's child nodes are stored in |_children| +tables. Node type is saved in |_type| field, if the node type is |ELEMENT|, then |_name| field contains +element name, |_attr| table contains element attributes. |TEXT| node contains text content in |_text| +field. + +The previous code produces following output in the terminal: % after command +% |texlua dom-sample.lua| running: \begin{verbatim} ROOT : unnamed @@ -136,16 +481,15 @@ ROOT : unnamed TEXT : , how are you? \end{verbatim} -With \verb|domHandler|, you can process documents with mixed content, like \verb|xhtml|. +% With \verb|domHandler|, you can process documents with mixed content, like +% \verb|xhtml|, so it is a most powerful handler. -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} +\part{Original \texttt{LuaXML} documentation by Paul Chakravarti} \medskip -\noindent This document was created automatically from original source code comments using Pandoc\footnote{\url{http://johnmacfarlane.net/pandoc/}} +\noindent This document was created automatically from the original source code comments using Pandoc\footnote{\url{http://johnmacfarlane.net/pandoc/}} \section{Overview} |