diff options
author | Karl Berry <karl@freefriends.org> | 2021-07-23 20:09:36 +0000 |
---|---|---|
committer | Karl Berry <karl@freefriends.org> | 2021-07-23 20:09:36 +0000 |
commit | 39d6f8916f43870a04b061a79eccba138e2731f8 (patch) | |
tree | 173d0975492a3d2e76dc932d3a8b0de9629b914f /Master/texmf-dist/doc/luatex/luaxml | |
parent | ab48fdef29562d4609a9abac3425b4de89110c46 (diff) |
luaxml (23jul21)
git-svn-id: svn://tug.org/texlive/trunk@60030 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/doc/luatex/luaxml')
-rw-r--r-- | Master/texmf-dist/doc/luatex/luaxml/README | 2 | ||||
-rw-r--r-- | Master/texmf-dist/doc/luatex/luaxml/luaxml.pdf | bin | 107935 -> 118190 bytes | |||
-rw-r--r-- | Master/texmf-dist/doc/luatex/luaxml/luaxml.tex | 260 |
3 files changed, 257 insertions, 5 deletions
diff --git a/Master/texmf-dist/doc/luatex/luaxml/README b/Master/texmf-dist/doc/luatex/luaxml/README index 9ac304ea1de..e41f3100ea2 100644 --- a/Master/texmf-dist/doc/luatex/luaxml/README +++ b/Master/texmf-dist/doc/luatex/luaxml/README @@ -28,7 +28,7 @@ Author ------ Michal Hoftich Email: michal.h21@gmail.com -Version: v0.1n, 2020-12-20 +Version: v0.1o, 2021-07-23 Original authors: Paul Chakravarti and Manoel Campos (http://manoelcampos.com) diff --git a/Master/texmf-dist/doc/luatex/luaxml/luaxml.pdf b/Master/texmf-dist/doc/luatex/luaxml/luaxml.pdf Binary files differindex 405a7b311b3..ee611396446 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 8857458a0f8..1030422db9d 100644 --- a/Master/texmf-dist/doc/luatex/luaxml/luaxml.tex +++ b/Master/texmf-dist/doc/luatex/luaxml/luaxml.tex @@ -7,7 +7,7 @@ \usepackage{framed} % Version is defined in the makefile, use default values when compiled directly \ifdefined\version\else -\def\version{v0.1n} +\def\version{v0.1o} \let\gitdate\date \fi \newcommand\modulename[1]{\subsection{#1}\label{sec:#1}} @@ -170,7 +170,7 @@ end It supports also |XML| namespaces, using \verb_namespace|element_ syntax. -\subsubsection{Supported CSS selectors} +\subsubsection{Supported CSS selectors}\label{sec:css_selectors} The \verb|query_selector| method supports following CSS selectors: @@ -296,6 +296,7 @@ body:replace_node(oldbody) \section{The \texttt{CssQuery} library} +\label{sec:cssquery_library} This library serves mainly as a support for the \texttt{DOM\_Object:query\_selector} function. It also supports adding @@ -385,9 +386,260 @@ repository\footnote{\url{https://github.com/michal-h21/LuaXML/blob/master/exampl \section{The \texttt{luaxml-transform} library} This library is still a bit experimental. It enables XML transformation based -on CSS selector templates. It is better to use XSLT in general, but it may -succeed for simpler tasks\footnote{See this example: \url{https://tex.stackexchange.com/a/574004/2891}}. +on CSS selector templates. +It isn't nearly as powerful as XSLT, but it may suffice for simpler tasks. + +\subsection{Basic example} + +\begin{verbatim} +local transform = require "luaxml-transform" + +local transformer = transform.new() +local xml_text = [[<section>hello <b>world</b></section>]] + +-- transformatio rules +transformer:add_action("section", "\\section{@<.>}") +transformer:add_action("b", "\\textbf{@<.>}") + +-- transform and print the result to the document +local result = transformer:parse_xml(xml_text) +transform.print_tex("\\verb|" .. result .. "|") +\end{verbatim} +\begin{framed} +\begin{luacode*} +local transform = require "luaxml-transform" + +local transformer = transform.new() +local xml_text = [[<section>hello <b>world</b></section>]] + +-- transformatio rules +transformer:add_action("section", "\\section{@<.>}") +transformer:add_action("b", "\\textbf{@<.>}") + +-- transform and print the result to the document +local result = transformer:parse_xml(xml_text) +transform.print_tex("\\verb|" .. result .. "|") +\end{luacode*} +\end{framed} + +\subsection{The Transform object } + +The \texttt{luaxml-transform} library provides several functions. +Most important of them is \verb|new()|. It returns a Transform object, +that can be used for the transformations. It is possible to transform +XML using text templates, or Lua functions. In both cases, actions for +elements are selected using CSS selectors. If there is no action for +an element, it's text content and text from transformed child elements, +is placed to the output string. + +There are two methods for action specification, \verb|add_action| for +text templates, and \verb|add_custom_action| for Lua functions. + +\subsubsection{Transforming using templates} + +Template actions can be added using the \verb|add_action| method: + +\begin{verbatim} +transformer:add_action("CSS selector", "template", {parameters table}) +\end{verbatim} + +For details about CSS selectors, see the \texttt{CssQuery} library +(see page~\pageref{sec:cssquery_library}). Templates can contain +arbitrary text, with special instructions that can insert transformed +text contents of the element, contents of specific element, or element's +attributes. + + +\noindent\textbf{Instruction syntax:} + +\begin{description} + \item[\verb|@\{attribute name\}|] insert value of an attribute + \item[\verb|@<.>|] insert transformed content of the element + \item[\verb|@<number>|] insert transformed content of the child element + selected by it's number in the list of children + \item[\verb|@<element name>|] insert transformed content of the named child element +\end{description} + +\noindent\textbf{Parameters} + +The parameters table can hold following values: + +\begin{description} + \item[verbatim] -- by default, spaces are collapsed. This is useful in general, but you may want to + keep spaces, for example in program listings. Set \texttt{verbatim=true} in this case. + \item[separator] -- when you select element by names (\verb|@<element name>|), you can use this parameter + set the separator between possible multiple instances of the child element. +\end{description} + +\noindent\textbf{Examples:} + +\noindent\textbf{Process children} + +\begin{verbatim} +local transformer = transform.new() +transformer:add_action("a", "@<.>") +-- ignore element <b> +transformer:add_action("b", "") +local result = transformer:parse_xml("<x><a>hello</a><b>, world</b></x>") +transform.print_tex(result) +\end{verbatim} +\begin{framed} +\begin{luacode*} + +local transform = require "luaxml-transform" + +local transformer = transform.new() +transformer:add_action("a", "@<.>") +-- ignore element <b> +transformer:add_action("b", "") +local result = transformer:parse_xml("<x><a>hello</a><b>, world</b></x>") +transform.print_tex(result) +\end{luacode*} +\end{framed} + +\noindent\textbf{Select elements by their position} + +\begin{verbatim} +local transformer = transform.new() +-- swap child elements +transformer:add_action("x", "@<2>, @<1>") +local result = transformer:parse_xml("<x><a>world</a>, <b>hello</b></x>") +transform.print_tex(result) +\end{verbatim} + +\begin{framed} +\begin{luacode*} + +local transform = require "luaxml-transform" + +local transformer = transform.new() +transformer:add_action("x", "@<2>, @<1>") +local result = transformer:parse_xml("<x><a>world</a>, <b>hello</b></x>") +transform.print_tex(result) +\end{luacode*} +\end{framed} + + +\noindent\textbf{Select elements by name} +\begin{verbatim} +local transformer = transform.new() +transformer:add_action("x", "@<a>") +local result = transformer:parse_xml("<x><a>hello</a><b>, world</b></x>") +transform.print_tex(result) +\end{verbatim} +\begin{framed} +\begin{luacode*} + +local transform = require "luaxml-transform" +local transformer = transform.new() +transformer:add_action("x", "@<a>") +local result = transformer:parse_xml("<x><a>hello</a><b>, world</b></x>") +transform.print_tex(result) +\end{luacode*} +\end{framed} + +\noindent\textbf{Select attributes} +\begin{verbatim} +local transformer = transform.new() +transformer:add_action("b", "\\textbf{@<.>}") +-- this will select only <b> elements with "style" attribute +transformer:add_action("b[style]", "\\textcolor{@{style}}{\\textbf{@<.>}}") +local text = '<x><b>hello</b> <b style="red">world</b></x>' +local result = transformer:parse_xml(text) +transform.print_tex(result) +\end{verbatim} +\begin{framed} +\begin{luacode*} + +local transform = require "luaxml-transform" +local transformer = transform.new() +transformer:add_action("b", "\\textbf{@<.>}") +-- this will select only <b> elements with "style" attribute +transformer:add_action("b[style]", "\\textcolor{@{style}}{\\textbf{@<.>}}") +local text = '<x><b>hello</b> <b style="red">world</b></x>' +local result = transformer:parse_xml(text) +transform.print_tex("\\verb|" .. result .. "|") +\end{luacode*} +\end{framed} + +\subsubsection{Transforming using Lua functions} + +You can use Lua functions for more complex transformations where simple templates don't suffice. + +\begin{verbatim} +transformer:add_custom_action("CSS selector", function) +\end{verbatim} + + +\noindent\textbf{Example} +\begin{verbatim} +local transformer = transform.new() +local xml_text = "<x><a>world</a><b>hello, </b></x>" +-- load helper functions +local get_child_element = transform.get_child_element +local process_children = transform.process_children +-- define custom action +transformer:add_custom_action("x", function(el) + -- it basically just swaps child elements, + -- like in the template @<2>@<1> + local first = process_children(get_child_element(el, 1)) + local second = process_children(get_child_element(el, 2)) + return second .. first +end) +local result = transformer:parse_xml(xml_text) +transform.print_tex(result) +\end{verbatim} + +\begin{framed} +\begin{luacode*} + +local transform = require "luaxml-transform" +local transformer = transform.new() +local xml_text = "<x><a>world</a><b>hello, </b></x>" +-- load helper functions +local get_child_element = transform.get_child_element +local process_children = transform.process_children +-- define custom action +transformer:add_custom_action("x", function(el) + -- it basically just swaps child elements, + -- like in the template @<2>@<1> + local first = process_children(get_child_element(el, 1)) + local second = process_children(get_child_element(el, 2)) + return second .. first +end) +local result = transformer:parse_xml(xml_text) +transform.print_tex(result) +\end{luacode*} +\end{framed} + +\subsubsection{Character handling} + +You may want to escape certain characters, or replace them with +\LaTeX\ commands. You can use the \texttt{unicodes} table contained +in the Transform object: + + +\begin{verbatim} +local transformer = transform.new() +-- you must use the Unicode character code +transformer.unicodes[124] = "\\textbar" +local text = '<x>|</x>' +local result = transformer:parse_xml(text) +transform.print_tex(result) +\end{verbatim} + +\begin{framed} +\begin{luacode*} +local transform = require "luaxml-transform" +local transformer = transform.new() +-- you must use the Unicode character code +transformer.unicodes[124] = "\\textbar" +local text = '<x>|</x>' +local result = transformer:parse_xml(text) +transform.print_tex("\\verb|" .. result .. "|") +\end{luacode*} +\end{framed} \section{The API documentation} |