Debian Codegraph @

texmf-dist/doc/lualatex/luahttp/README.md

raw
1 # README for LUAHTTP
2 Version 1.0.1
3
4 ## INTRODUCTION
5 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.
6
7 This packages requires LuaTeX, Lua5.3, expat, openssl and the following Lua modules called "rocks":
8
9 * luasec
10 * dkjson
11 * ltn12
12 * feedparser
13 * luaexpat
14
15 ## MANUAL INSTALLATION
16 First the required dependencies need to be installed:
17
18 Arch:
19 ```
20 lua53 luarocks expat openssl
21 ```
22
23 Debian:
24 ```
25 liblua5.3-dev libssl-dev lua5.3 libexpat1-dev luarocks
26 ```
27
28 MacOS:
29 ```
30 [email protected] luarocks expat openssl
31 ```
32
33 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:
34
35 ```bash
36 luarocks init --lua-version=5.3
37 luarocks install dkjson --lua-version=5.3
38 luarocks install luasec --lua-version=5.3
39 luarocks install ltn12 --lua-version=5.3
40 luarocks install luaexpat --lua-version=5.3
41 luarocks install feedparser --lua-version=5.3
42 ```
43
44 For **MacOS** it may be necessary to add Lua 5.3 to your "$PATH" and install **luaexpat** and **luasec** using the commands bellow:
45 ```bash
46 echo 'export PATH="/usr/local/opt/[email protected]/bin:$PATH"' >> ~/.zshrc
47 luarocks install luaexpat EXPAT_DIR=/usr/local/Cellar/expat/${YOUR_VERSION_HERE}
48 luarocks install luasec OPENSSL_DIR=/usr/local/Cellar/openssl@3/${YOUR_VERSION_HERE}
49 ```
50
51 ## USAGE
52 Compilation requires the use of ```lualatex``` with the ```--shell-escape``` option.
53
54 ```
55 lualatex --shell-escape
56 ```
57
58 Add the package to your TeX file:
59 ```
60 \usepackage{luahttp}
61 ```
62
63 Here is a quick overview of the commands and their parameters. For further details and examples please read the package documentation.
64
65 * fetchJson, send a GET request and filter the response using optional keys:
66 ```tex
67 \fetchJson{URL}[optional: "key1,key2,.."]
68 ```
69
70 * fetchJsonUsingFile, send a request specified in a JSON-file and filter the response using optional keys:
71 ```tex
72 \fetchJsonUsingFile{Path to JSON-file}[optional: "key1,key2,.."]
73 ```
74
75 * fetchJsonUsingQuery, send a POST request with up to five query parameters and filter the response using keys:
76 ```tex
77 \fetchJsonUsingQuery{URL}{"key1,key2,.."} [optional: "?queryparameter1=value1"] .. [optional: "&queryparameter5=value5"]
78 ```
79
80 * fetchRss, send a GET request and filter the feed and entries (limited by the second argument) using optional keys:
81 ```tex
82 \fetchRss{URL}{limit}[optional: "feedinfokey1,feedinfokey2,.."][optional: "entrykey1,entrykey2,.."]
83 ```
84
85 * fetchImage, fetch an image from the internet and specify the width and height in **cm** using optional arguments:
86 ```tex
87 \fetchImage{URL}[optional: width in cm][optional: height in cm]
88 ```
89
90
91 ## AUTHOR / MAINTAINER
92
93 * Johannes Casaburi ([email protected])
94
95 ## LICENSE
96
97 LATEX Project Public License, version 1.3c or later.
98
99 ## KNOWN PROBLEMS
100 * Not all URL leading to an image are detected
101 * Results that where filtered using keys may not be displayed in the order of the given keys.
102