Debian Codegraph @

texmf-dist/doc/lualatex/luahttp/luahttp-doc.tex

raw
1 \documentclass[11pt]{article}
2 \usepackage[english]{babel}
3 \usepackage{listings}
4
5 \lstset{
6 frame=shadowbox,
7 numbers=left,
8 basicstyle=\ttfamily,
9 keywordstyle=\bfseries,
10 breakatwhitespace=false,
11 breaklines=true,
12 keepspaces=true,
13 }
14
15 % Document
16 \begin{document}
17
18 \setlength{\parindent}{0pt}
19 \setlength{\parskip}{5pt plus 2pt minus 1pt}
20
21 \title{The \textsf{LuaHTTP} package}
22 \author{Johannes Casaburi \\ \texttt{[email protected]}}
23 \date{\today\\Version 1.0.1}
24
25 \maketitle
26
27 \tableofcontents
28
29 \newpage
30
31 \section{Introduction}
32 This is a small package that is the result of a case study on Internet-Interactive \LaTeX\ PDF-documents. It provides five commands to make API calls, fetch data from the internet and insert that data into the PDF-document. This package depends on LuaTex, Lua and additional dependencies that need to be installed.
33
34 \section{Manual Installation}
35 First the required dependencies need to be installed:
36
37 \texttt{MacOS using Homebrew}
38 \begin{lstlisting}[language=bash]
39 brew install [email protected] luarocks expat openssl
40 \end{lstlisting}
41
42 \texttt{Arch}
43 \begin{lstlisting}[language=bash]
44 pacman -S lua53 luarocks expat openssl
45 \end{lstlisting}
46
47 \texttt{Debian}
48 \begin{lstlisting}[language=bash]
49 apt install liblua5.3-dev libssl-dev lua5.3 libexpat1-dev luarocks
50 \end{lstlisting}
51
52 Copy the \texttt{.sty} and \texttt{.lua} files in the directory where the \texttt{.tex} file is located.
53
54 In order to get the package working, a few dependencies first need to be installed. An easy way to do so, is by using \texttt{luarocks} which is the package manager for Lua modules which are called \texttt{rocks}.
55
56 To install the Lua rocks locally in the directory where the \lstinline{.tex} file(s) is located, execute the following commands. This will initialize a new Lua project and install the required dependencies (See below for MacOS):
57
58 \begin{lstlisting}[language=bash]
59 luarocks --lua-version=5.3 init
60 luarocks --lua-version=5.3 install dkjson
61 luarocks --lua-version=5.3 install luasec
62 luarocks --lua-version=5.3 install ltn12
63 luarocks --lua-version=5.3 install luaexpat
64 luarocks --lua-version=5.3 install feedparser
65 \end{lstlisting}
66
67 The Lua version may be changed if the Lua rocks support the version.
68
69 For \texttt{MacOS} you may need to add the Lua5.3 executable to your \texttt{\$PATH}.
70 \begin{lstlisting}[language=bash]
71 echo 'export PATH="/usr/local/opt/[email protected]/bin:$PATH"' >> ~/.zshrc
72 \end{lstlisting}
73
74 And it may also be necessary to install \texttt{luaexpat} and \texttt{luasec} using the commands below:
75 \begin{lstlisting}[language=bash]
76 luarocks install luaexpat EXPAT_DIR=/usr/local/Cellar/expat/${YOUR_VERSION_HERE}
77 luarocks install luasec OPENSSL_DIR=/usr/local/Cellar/openssl@3/${YOUR_VERSION_HERE}
78 \end{lstlisting}
79
80 \section{Usage}
81 The LaTeX package can be used by adding the following line to the \texttt{.tex} file.
82 \begin{lstlisting}[language=tex]
83 \usepackage{luahttp}
84 \end{lstlisting}
85
86 To compile the PDF-document use:
87 \begin{lstlisting}[language=bash]
88 lualatex --shell-escape
89 \end{lstlisting}
90
91 \subsection{fetchJson}
92
93 \begin{lstlisting}[language=tex]
94 \fetchJson{URL}[optional: "key1,key2,.."]
95 \end{lstlisting}
96
97 This command takes an URL as the first argument and a list of comma separated keys as a second optional argument. Upon execution a GET request will be sent to the specified address. The accept header is set to \texttt{application/json}. The keys which are to be specified like \texttt{key1,key2,..} are used to filter out the desired values from the response. They have to exactly math the keys in the response otherwise the value will not be written to the PDF-Document. The same key can occur multiple times, this will output all values found to the PDF-Document.
98
99 Values with special characters are escaped. Values are searched for URLs. If an URL pointing to a image is detected the user will be prompted to either display the image or the actual URL.
100
101 \subsection{fetchJsonUsingFile}
102
103 \begin{lstlisting}[language=tex]
104 \fetchJsonUsingFile{Path to JSON file}[optional: "key1,key2,.."]
105 \end{lstlisting}
106
107 This is very similar to the \texttt{fetchJson} command but takes a path to a JSON file instead of an URL. This allows the user to specify the request method, headers and body. The file should look something like this:
108
109 \begin{lstlisting}
110 {
111 "method": "POST",
112 "url": "https://httpbin.org/post",
113 "redirect": false,
114 "headers": {
115 "Accept": "application/json",
116 "Content-Type": "application/json"
117 },
118 "body": {
119 "name": "john",
120 "id" : 1234
121 }
122 }
123 \end{lstlisting}
124
125 Like the command before this command also takes and optional argument where the \texttt{keys} can be specified. If a value contains an URL leading to an image the user will be asked to either display the image or the URL.
126
127 \subsection{fetchJsonUsingQuery}
128
129 \begin{lstlisting}[language=tex]
130 \fetchJsonUsingQuery{URL}{"key1,key2,.."} [optional: "?queryparameter1=value1"] .. [optional: "&queryparameter5=value5"]
131 \end{lstlisting}
132
133 This command can be used to send up to five query parameters using a POST request. The required arguments are the \texttt{URL} and a list of keys. The optional query parameters need to be written in key-value pairs:
134
135 \begin{lstlisting}[language=tex]
136 \fetchJsonUsingQuery{URL}{key1,key2}[?q=The first value][&second=The second value and so on"]
137 \end{lstlisting}
138
139 The values after the \texttt{=} sign are URL-encoded and sent using the \lstinline{application/json} Accept header and \texttt{application/x-www-form-urlencoded} Content-Type header. Like in the \texttt{fetchJson} command the user will be prompted if an URL leading to an image is detected.
140
141 \subsection{fetchRss}
142
143 \begin{lstlisting}[language=tex]
144 \fetchRss{URL}{limit}[optional: "feedinfokey1,feedinfokey2,.."][optional: "entrykey1,entrykey2,.."]
145 \end{lstlisting}
146
147 This command takes an \texttt{URL} and a \texttt{limit}. The limit describes how many entries of the feed are written to the PDF-Document. There are two optional arguments. The first argument is a list of keys used to filter out feed information. At this time possible values are \texttt{title, subtitle, rights, generator, author, author\_detail, link, links, updated\_parsed, updated, id, contributors}. Every entry can be filtered using the second argument. Possible values for the entry keys are \texttt{id, link, links, updated, updated\_parsed, title, summary, contributors}. These values may change if the Lua rock called \texttt{feedparser} that is used to parse the feed changes. More information about \texttt{feedparser} can be found here: \lstinline{https://github.com/LuaDist-testing/feedparser}
148
149 The \texttt{summary} from the entries may contain HTML which will just be written to the PDF-Document. As described in the \texttt{fetchJson} command you may be promoted when a link to an image is detected.
150
151
152 \subsection{fetchImage}
153
154 \begin{lstlisting}[language=tex]
155 \fetchImage{URL}[optional: width in cm][optional: height in cm]
156 \end{lstlisting}
157
158 Images can be inserted into the PDF-Document using the URL. To resize the image, one or two optional arguments can be given to specify the width or width and height in \texttt{centimeters}:
159
160 \begin{lstlisting}[language=tex]
161 \fetchImage{URL}[7cm][5cm]
162 \end{lstlisting}
163
164 \section{Examples}
165
166 \subsection{fetchJson}
167
168 To display the title and summary of the first article returned by the space-news API we have to specify the URL and the keys that hold the desired values:
169
170 \begin{lstlisting}[language=tex]
171 \fetchJson{https://api.spaceflightnewsapi.net/v3/articles?_limit=1}[title,summary]
172 \end{lstlisting}
173
174 \subsection{fetchJsonUsingFile}
175 Like the example above the same can be done using \texttt{fetchJsonUsingFile}. For that we need a \texttt{JSON} file with the following content:
176
177 \begin{lstlisting}
178 {
179 "method": "GET",
180 "url": "https://api.spaceflightnewsapi.net/v3/articles?_limit=1",
181 "redirect": false,
182 "headers": {
183 "Accept": "application/json"
184 }
185 }
186 \end{lstlisting}
187
188 If the \texttt{JSON} file is located in the same directory as the \texttt{.lua} files the command looks like this:
189
190 \begin{lstlisting}[language=tex]
191 \fetchJsonUsingFile{myjsonfile.json}[title,summary]
192 \end{lstlisting}
193
194 If the package was not manually installed the absolute path must be used.
195
196 \subsection{fetchJsonUsingQuery}
197
198 Here is an example of an API call using query parameters:
199
200 \begin{lstlisting}[language=tex]
201 \fetchJsonUsingQuery{http://127.0.0.1:5000/translate}{translatedText}[?q=I want to translate this text][&source=en][&target=de][&format=text]
202 \end{lstlisting}
203
204 First we need to specify the first part of the URL, followed by the key(s) that hold the desired return values. The values of the query parameters get URL-encoded and put back together in a single URL. We may need to add an \texttt{\&} before the query parameter or an \texttt{?} depending on the location.
205
206 \subsection{fetchRss}
207
208 In this example the first the subtitle from the feed information is printed as a subsection. The second command prints the \texttt{title, link} and \texttt{updated} information of the first three entries received.
209
210 \begin{lstlisting}[language=tex]
211 \subsection{
212 \fetchRss{https://www.eff.org/rss/updates.xml}{1}[subtitle][none]
213 }
214
215 \fetchRss{https://www.eff.org/rss/updates.xml}{3}[none][title,link,updated]
216 \end{lstlisting}
217
218 Note that \texttt{none} is not a special keyword, if there was a key called \texttt{none} then its value would be printed to the PDF-Document.
219
220 \subsection{fetchImage}
221 Here is an example how to embed an image and scaling it to have a width of 5cm:
222
223 \begin{lstlisting}[language=tex]
224 \fetchImage{https://i0.wp.com/spacenews.com/wp-content/uploads/2023/03/vorb-march2023.jpg}[5cm]
225 \end{lstlisting}
226
227 \end{document}