diff options
author | Karl Berry <karl@freefriends.org> | 2023-06-12 20:16:13 +0000 |
---|---|---|
committer | Karl Berry <karl@freefriends.org> | 2023-06-12 20:16:13 +0000 |
commit | 37a92634199a5d311afccd7d1dcdcb5160df452c (patch) | |
tree | fcf20fd813645e7fadb53eacf166cf4e572cb9df /Master/texmf-dist/doc/lualatex/luahttp | |
parent | 08572b84d6eb93111b79c28ca9b673ba284a173c (diff) |
luahttp (12jun23)
git-svn-id: svn://tug.org/texlive/trunk@67348 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/doc/lualatex/luahttp')
-rw-r--r-- | Master/texmf-dist/doc/lualatex/luahttp/README.md | 102 | ||||
-rw-r--r-- | Master/texmf-dist/doc/lualatex/luahttp/luahttp-doc.pdf | bin | 0 -> 135232 bytes | |||
-rw-r--r-- | Master/texmf-dist/doc/lualatex/luahttp/luahttp-doc.tex | 227 |
3 files changed, 329 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/lualatex/luahttp/README.md b/Master/texmf-dist/doc/lualatex/luahttp/README.md new file mode 100644 index 00000000000..e1a144bccfc --- /dev/null +++ b/Master/texmf-dist/doc/lualatex/luahttp/README.md @@ -0,0 +1,102 @@ +# README for LUAHTTP +Version 1.0.1 + +## INTRODUCTION +This is a small package that provides five commands to make HTTP requests using Lua and LuaTeX. Functionalities include API calls, fetching RSS feeds and the possibility to include images using a link. These commands run during the compilation of the PDF-Document and may require user interaction. + +This packages requires LuaTeX, Lua5.3, expat, openssl and the following Lua modules called "rocks": + +* luasec +* dkjson +* ltn12 +* feedparser +* luaexpat + +## MANUAL INSTALLATION +First the required dependencies need to be installed: + +Arch: +``` +lua53 luarocks expat openssl +``` + +Debian: +``` +liblua5.3-dev libssl-dev lua5.3 libexpat1-dev luarocks +``` + +MacOS: +``` +lua@5.3 luarocks expat openssl +``` + +The Lua rocks can be installed locally using ```luarocks```. To install the Lua rocks locally we need to initialize the directory where the ```.tex``` file(s) is located. In the directory execute the following commands to initialize a new Lua project and install the required dependencies: + +```bash +luarocks init --lua-version=5.3 +luarocks install dkjson --lua-version=5.3 +luarocks install luasec --lua-version=5.3 +luarocks install ltn12 --lua-version=5.3 +luarocks install luaexpat --lua-version=5.3 +luarocks install feedparser --lua-version=5.3 +``` + +For **MacOS** it may be necessary to add Lua 5.3 to your "$PATH" and install **luaexpat** and **luasec** using the commands bellow: +```bash +echo 'export PATH="/usr/local/opt/lua@5.3/bin:$PATH"' >> ~/.zshrc +luarocks install luaexpat EXPAT_DIR=/usr/local/Cellar/expat/${YOUR_VERSION_HERE} +luarocks install luasec OPENSSL_DIR=/usr/local/Cellar/openssl@3/${YOUR_VERSION_HERE} +``` + +## USAGE +Compilation requires the use of ```lualatex``` with the ```--shell-escape``` option. + +``` +lualatex --shell-escape +``` + +Add the package to your TeX file: +``` +\usepackage{luahttp} +``` + +Here is a quick overview of the commands and their parameters. For further details and examples please read the package documentation. + +* fetchJson, send a GET request and filter the response using optional keys: + ```tex + \fetchJson{URL}[optional: "key1,key2,.."] + ``` + +* fetchJsonUsingFile, send a request specified in a JSON-file and filter the response using optional keys: + ```tex + \fetchJsonUsingFile{Path to JSON-file}[optional: "key1,key2,.."] + ``` + +* fetchJsonUsingQuery, send a POST request with up to five query parameters and filter the response using keys: + ```tex + \fetchJsonUsingQuery{URL}{"key1,key2,.."} [optional: "?queryparameter1=value1"] .. [optional: "&queryparameter5=value5"] + ``` + +* fetchRss, send a GET request and filter the feed and entries (limited by the second argument) using optional keys: + ```tex + \fetchRss{URL}{limit}[optional: "feedinfokey1,feedinfokey2,.."][optional: "entrykey1,entrykey2,.."] + ``` + +* fetchImage, fetch an image from the internet and specify the width and height in **cm** using optional arguments: + ```tex + \fetchImage{URL}[optional: width in cm][optional: height in cm] + ``` + + +## AUTHOR / MAINTAINER + +* Johannes Casaburi (johannes.casaburi@protonmail.com) + +## LICENSE + +LATEX Project Public License, version 1.3c or later. + +## KNOWN PROBLEMS +* Not all URL leading to an image are detected +* Results that where filtered using keys may not be displayed in the order of the given keys. + diff --git a/Master/texmf-dist/doc/lualatex/luahttp/luahttp-doc.pdf b/Master/texmf-dist/doc/lualatex/luahttp/luahttp-doc.pdf Binary files differnew file mode 100644 index 00000000000..1063d5b3336 --- /dev/null +++ b/Master/texmf-dist/doc/lualatex/luahttp/luahttp-doc.pdf diff --git a/Master/texmf-dist/doc/lualatex/luahttp/luahttp-doc.tex b/Master/texmf-dist/doc/lualatex/luahttp/luahttp-doc.tex new file mode 100644 index 00000000000..210c12a26e5 --- /dev/null +++ b/Master/texmf-dist/doc/lualatex/luahttp/luahttp-doc.tex @@ -0,0 +1,227 @@ +\documentclass[11pt]{article} +\usepackage[english]{babel} +\usepackage{listings} + +\lstset{ + frame=shadowbox, + numbers=left, + basicstyle=\ttfamily, + keywordstyle=\bfseries, + breakatwhitespace=false, + breaklines=true, + keepspaces=true, +} + +% Document +\begin{document} + +\setlength{\parindent}{0pt} +\setlength{\parskip}{5pt plus 2pt minus 1pt} + +\title{The \textsf{LuaHTTP} package} +\author{Johannes Casaburi \\ \texttt{johannes.casaburi@protonmail.com}} +\date{\today\\Version 1.0.1} + +\maketitle + +\tableofcontents + +\newpage + +\section{Introduction} +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. + +\section{Manual Installation} +First the required dependencies need to be installed: + +\texttt{MacOS using Homebrew} +\begin{lstlisting}[language=bash] +brew install lua@5.3 luarocks expat openssl +\end{lstlisting} + +\texttt{Arch} +\begin{lstlisting}[language=bash] +pacman -S lua53 luarocks expat openssl +\end{lstlisting} + +\texttt{Debian} +\begin{lstlisting}[language=bash] +apt install liblua5.3-dev libssl-dev lua5.3 libexpat1-dev luarocks +\end{lstlisting} + +Copy the \texttt{.sty} and \texttt{.lua} files in the directory where the \texttt{.tex} file is located. + +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}. + +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): + +\begin{lstlisting}[language=bash] +luarocks --lua-version=5.3 init +luarocks --lua-version=5.3 install dkjson +luarocks --lua-version=5.3 install luasec +luarocks --lua-version=5.3 install ltn12 +luarocks --lua-version=5.3 install luaexpat +luarocks --lua-version=5.3 install feedparser +\end{lstlisting} + +The Lua version may be changed if the Lua rocks support the version. + +For \texttt{MacOS} you may need to add the Lua5.3 executable to your \texttt{\$PATH}. +\begin{lstlisting}[language=bash] +echo 'export PATH="/usr/local/opt/lua@5.3/bin:$PATH"' >> ~/.zshrc +\end{lstlisting} + +And it may also be necessary to install \texttt{luaexpat} and \texttt{luasec} using the commands below: +\begin{lstlisting}[language=bash] +luarocks install luaexpat EXPAT_DIR=/usr/local/Cellar/expat/${YOUR_VERSION_HERE} +luarocks install luasec OPENSSL_DIR=/usr/local/Cellar/openssl@3/${YOUR_VERSION_HERE} +\end{lstlisting} + +\section{Usage} +The LaTeX package can be used by adding the following line to the \texttt{.tex} file. +\begin{lstlisting}[language=tex] +\usepackage{luahttp} +\end{lstlisting} + +To compile the PDF-document use: +\begin{lstlisting}[language=bash] +lualatex --shell-escape +\end{lstlisting} + +\subsection{fetchJson} + +\begin{lstlisting}[language=tex] +\fetchJson{URL}[optional: "key1,key2,.."] +\end{lstlisting} + +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. + +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. + +\subsection{fetchJsonUsingFile} + +\begin{lstlisting}[language=tex] +\fetchJsonUsingFile{Path to JSON file}[optional: "key1,key2,.."] +\end{lstlisting} + +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: + +\begin{lstlisting} +{ + "method": "POST", + "url": "https://httpbin.org/post", + "redirect": false, + "headers": { + "Accept": "application/json", + "Content-Type": "application/json" + }, + "body": { + "name": "john", + "id" : 1234 + } +} +\end{lstlisting} + +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. + +\subsection{fetchJsonUsingQuery} + +\begin{lstlisting}[language=tex] +\fetchJsonUsingQuery{URL}{"key1,key2,.."} [optional: "?queryparameter1=value1"] .. [optional: "&queryparameter5=value5"] +\end{lstlisting} + +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: + +\begin{lstlisting}[language=tex] +\fetchJsonUsingQuery{URL}{key1,key2}[?q=The first value][&second=The second value and so on"] +\end{lstlisting} + +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. + +\subsection{fetchRss} + +\begin{lstlisting}[language=tex] +\fetchRss{URL}{limit}[optional: "feedinfokey1,feedinfokey2,.."][optional: "entrykey1,entrykey2,.."] +\end{lstlisting} + +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} + +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. + + +\subsection{fetchImage} + +\begin{lstlisting}[language=tex] +\fetchImage{URL}[optional: width in cm][optional: height in cm] +\end{lstlisting} + +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}: + +\begin{lstlisting}[language=tex] +\fetchImage{URL}[7cm][5cm] +\end{lstlisting} + +\section{Examples} + +\subsection{fetchJson} + +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: + +\begin{lstlisting}[language=tex] +\fetchJson{https://api.spaceflightnewsapi.net/v3/articles?_limit=1}[title,summary] +\end{lstlisting} + +\subsection{fetchJsonUsingFile} +Like the example above the same can be done using \texttt{fetchJsonUsingFile}. For that we need a \texttt{JSON} file with the following content: + +\begin{lstlisting} +{ + "method": "GET", + "url": "https://api.spaceflightnewsapi.net/v3/articles?_limit=1", + "redirect": false, + "headers": { + "Accept": "application/json" + } +} +\end{lstlisting} + +If the \texttt{JSON} file is located in the same directory as the \texttt{.lua} files the command looks like this: + +\begin{lstlisting}[language=tex] +\fetchJsonUsingFile{myjsonfile.json}[title,summary] +\end{lstlisting} + +If the package was not manually installed the absolute path must be used. + +\subsection{fetchJsonUsingQuery} + +Here is an example of an API call using query parameters: + +\begin{lstlisting}[language=tex] +\fetchJsonUsingQuery{http://127.0.0.1:5000/translate}{translatedText}[?q=I want to translate this text][&source=en][&target=de][&format=text] +\end{lstlisting} + +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. + +\subsection{fetchRss} + +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. + +\begin{lstlisting}[language=tex] +\subsection{ + \fetchRss{https://www.eff.org/rss/updates.xml}{1}[subtitle][none] +} + +\fetchRss{https://www.eff.org/rss/updates.xml}{3}[none][title,link,updated] +\end{lstlisting} + +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. + +\subsection{fetchImage} +Here is an example how to embed an image and scaling it to have a width of 5cm: + +\begin{lstlisting}[language=tex] +\fetchImage{https://i0.wp.com/spacenews.com/wp-content/uploads/2023/03/vorb-march2023.jpg}[5cm] +\end{lstlisting} + +\end{document} |