Debian Codegraph @

texmf-dist/doc/luatex/luakeyval/luakeyval.tex

raw
1 \useOpTeX
2 \load[doc]
3
4 \tit The `luakeyval` Module
5 \hfill Version: 0.1, 2025-12-01 \par
6 \centerline{\it Udi Fogiel, 2025}
7
8 \parindent0pt\parskip5pt\parfillskip=20ptplus1fill
9 \overfullrule=0pt
10
11 The luakeyval LuTeX module is a minimal key/value parser for LuaTeX formats
12 based on `token.scan_key_cs`. As such, the keyword parsing is similar to how \TeX/
13 parses keywords in special primitives like `\hrule`.
14
15 Unlike \TeX's scanner, `luakeyval` scans key/val pairs inside braces.
16 This avoids the need to append a `\relax` to the key/val
17 list, which would otherwise be required to stop \TeX/ from scanning
18 too far and potentially creating expansion problems.
19
20
21 \sec Usage
22 The module provides the `process` function, which accepts
23 a table of keys, and a table of error messages.
24
25 Each key in the table should have a table of parameters as a value. The possible
26 parameters are
27 \def\param #1:{{\bf #1:}\hskip1em\ignorespaces}
28 \begitems \style O
29 * \param scanner: a function that will scan the value of the key from \TeX/ to Lua.
30 The value will usually be a function from \LuaTeX's token library,
31 but you can use your own.
32 * \param args: a table of arguments that will be passed to the scanner function.
33 * \param default: default: a value returned if the key is not followed by a `=`.
34 * \param func: a function that will be executed each time the key appears.
35 \enditems
36 None of the parameters is mandatory, but a key must have at least
37 one of `default` or `scanner`.
38
39
40 The error messages table can have the following entries
41 \begitems \style O
42 * \param error1: a message that will be displayed if something went wrong
43 while processing a key/val list.
44 * \param error2: a message that will be displayed after `error1` in case a user
45 press the `H` key for more information.
46 * \param value_required: a message that will be displayed if no value given to a key
47 (when there is no `=` after the key) and the key does not have
48 a default value.
49 * \param value_forbidden: a message that will be displayed if a key was given a value
50 and the key does not have a `scanner` function.
51 \enditems
52
53 \sec Example
54 The following code defines the `\coloredrule` macro,
55 which accepts the keys `width`, `height`, `depth` and `color`,
56 and prints a colored rule according to the values given.
57
58 \begtt \hisyntax{lua}
59 local keyval = require('luakeyval')
60 local rule_keys = {
61 width = {scanner = token.scan_dimen, default = tex.sp('1cm')},
62 height = {scanner = token.scan_dimen, default = tex.sp('1ex')},
63 depth = {scanner = token.scan_dimen, default = 0},
64 color = {scanner = token.scan_string},
65 }
66
67 local messages = {
68 error1 = "colored rule: Wrong syntax in \\coloredrule",
69 value_forbidden = 'colored rule: The key "%s" does not accept a value',
70 value_required = 'colored rule: The key "%s" requires a value',
71 }
72
73 local function make_rule()
74 local opts = keyval.process(rule_keys, messages)
75 local rule = node.new('rule')
76 rule.width = opts.width or tex.sp('1cm')
77 rule.height = opts.height or tex.sp('1ex')
78 rule.depth = opts.depth or 0
79 local color_start = node.new('whatsit', 'pdf_literal')
80 color_start.mode = 0
81 color_start.data = opts.color .. " rg"
82 local color_end = node.new('whatsit', 'pdf_literal')
83 color_end.mode = 0
84 color_end.data = '0 g'
85 rule.next = color_end
86 color_start.next = rule
87 rule = color_start
88 node.write(rule)
89 end
90
91 token.set_lua('coloredrule', #lua.get_functions_table() +1, 'protected')
92 lua.get_functions_table()[#lua.get_functions_table()+1] = make_rule
93 \endtt
94
95 \beglua
96 local keyval = require('luakeyval')
97 local rule_keys = {
98 width = {scanner = token.scan_dimen, default = tex.sp('1cm')},
99 height = {scanner = token.scan_dimen, default = tex.sp('1ex')},
100 depth = {scanner = token.scan_dimen, default = 0},
101 color = {scanner = token.scan_string},
102 }
103
104 local messages = {
105 error1 = "colored rule: Wrong syntax in \\coloredrule",
106 value_forbidden = 'colored rule: The key "%s" does not accept a value',
107 value_required = 'colored rule: The key "%s" requires a value',
108 }
109
110 local function make_rule()
111 local opts = keyval.process(rule_keys, messages)
112 local width = opts.width or tex.sp('1cm')
113 local height = opts.height or tex.sp('1ex')
114 local depth = opts.depth or 0
115 local rule = node.new('rule')
116 rule.width = width
117 rule.height = height
118 rule.depth = depth
119 local color_start = node.new('whatsit', 'pdf_literal')
120 color_start.mode = 0
121 color_start.data = opts.color .. " rg"
122 local color_end = node.new('whatsit', 'pdf_literal')
123 color_end.mode = 0
124 color_end.data = '0 g'
125 rule.next = color_end
126 color_start.next = rule
127 rule = color_start
128 node.write(rule)
129 end
130
131 token.set_lua('coloredrule', #lua.get_functions_table() +1, 'protected')
132 lua.get_functions_table()[#lua.get_functions_table()+1] = make_rule
133 \endlua
134
135 Now `\coloredrule{width = 10pt height = 5pt color={1 0 0}}` prints
136 \coloredrule{width = 10pt height = 5pt color={1 0 0}}
137
138 \sec Important Limitations
139 Since the key/val parser is only a minimal layer
140 on top of `token.scan_keyword`, key/val pairs should be separated with spaces,
141 not commas, and avoid defining a key that is a prefix of another key
142 (unless you control the scanning order, see \ref[order]{Section @}).
143
144 \label[order]
145 \sec Scanning Order
146 The `process` function loops over the keys table using LuaTeX's
147 `token.scan_key_cs`. Since Lua tables do not guarantee key order when
148 iterating with `pairs()`, the scanning order is not deterministic
149 if you just provide a plain table.
150
151 This is important when one key is a prefix of another (for example,
152 `long` and `longer`). If the shorter key is checked first,
153 it may match part of the input and leave extra characters unprocessed,
154 leading to errors.
155
156 To control the scanning order explicitly, pass a third argument to
157 `process`: a list of keys in the exact order they should be scanned.
158 This also allows scanning only a subset of keys if desired.
159
160 \begtt \hisyntax{lua}
161 local keys = {
162 long = {scanner = token.scan_string},
163 longer = {scanner = token.scan_string},
164 }
165
166 -- Default scan (order not guaranteed)
167 local opts = keyval.process(keys, messages)
168 -- input: {longer="test"} may incorrectly match 'long' first
169
170 -- Controlled scan with explicit order
171 local order = {"longer", "long"}
172 local opts = keyval.process(keys, messages, order)
173 \endtt
174
175 \sec Implementation
176 The full Lua implementation is shown below for reference.
177 \verbinput \vitt{luakeyval.lua} \hisyntax{lua} (1-) luakeyval.lua
178
179 \bye
180