summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/luatex
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2018-02-09 00:16:06 +0000
committerKarl Berry <karl@freefriends.org>2018-02-09 00:16:06 +0000
commitb2153506a41b9f934841bc0eb31dd9c3946b407b (patch)
treedebea85a21708749fafa1748c894ab25b0e125e8 /Master/texmf-dist/doc/luatex
parente6304d3f0b0d72c2f38350d3ae4b4fa6bd862793 (diff)
luaxml (8feb18)
git-svn-id: svn://tug.org/texlive/trunk@46570 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/doc/luatex')
-rw-r--r--Master/texmf-dist/doc/luatex/luaxml/README10
-rw-r--r--Master/texmf-dist/doc/luatex/luaxml/luaxml.pdfbin114519 -> 98163 bytes
-rw-r--r--Master/texmf-dist/doc/luatex/luaxml/luaxml.tex434
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
index 3a6967c9c66..07ec3244c70 100644
--- a/Master/texmf-dist/doc/luatex/luaxml/luaxml.pdf
+++ b/Master/texmf-dist/doc/luatex/luaxml/luaxml.pdf
Binary files differ
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}