Debian Codegraph @

texmf-dist/doc/luatex/luakeys/README.md

raw
1 # luakeys
2
3 `luakeys` is a Lua module that can parse key-value options like the
4 TeX packages [keyval](https://www.ctan.org/pkg/keyval),
5 [kvsetkeys](https://www.ctan.org/pkg/kvsetkeys),
6 [kvoptions](https://www.ctan.org/pkg/kvoptions),
7 [xkeyval](https://www.ctan.org/pkg/xkeyval),
8 [pgfkeys](https://www.ctan.org/pkg/pgfkeys) etc. do. `luakeys`,
9 however, accompilshes this task entirely, by using the Lua language and
10 doesn’t rely on TeX. Therefore this package can only be used with the
11 TeX engine LuaTeX. Since `luakeys` uses
12 [LPeg](http://www.inf.puc-rio.br/~roberto/lpeg/), the parsing
13 mechanism should be pretty robust.
14
15 ## Current version
16
17 2025/07/19 v0.17.0
18
19 ## License
20
21 Copyright (C) 2021-2025 by Josef Friedrich <[email protected]>
22 ------------------------------------------------------------------------
23 This work may be distributed and/or modified under the conditions of
24 the LaTeX Project Public License, either version 1.3c of this license
25 or (at your option) any later version. The latest version of this
26 license is in:
27
28 http://www.latex-project.org/lppl.txt
29
30 and version 1.3c or later is part of all distributions of LaTeX
31 version 2008/05/04 or later.
32
33 ## Maintainer
34
35 Josef Friedrich <[email protected]>
36
37 ## Packaging
38
39 ### CTAN
40
41 The `luakeys` package has been included in the Comprehensive TeX Archive
42 Network (CTAN) since January 2021.
43
44 * [Package page](https://www.ctan.org/pkg/luakeys)
45 * [Sources](https://www.ctan.org/tex-archive/macros/luatex/generic/luakeys)
46
47 ### Distributions
48
49 * TeX Live:
50 * run files:
51 * [tex/luatex/luakeys/luakeys.lua](https://tug.org/svn/texlive/trunk/Master/texmf-dist/tex/luatex/luakeys/luakeys.lua)
52 * [tex/luatex/luakeys/luakeys.sty](https://tug.org/svn/texlive/trunk/Master/texmf-dist/tex/luatex/luakeys/luakeys.sty)
53 * [tex/luatex/luakeys/luakeys.tex](https://tug.org/svn/texlive/trunk/Master/texmf-dist/tex/luatex/luakeys/luakeys.tex)
54 * [tex/luatex/luakeys/luakeys-debug.tex](https://tug.org/svn/texlive/trunk/Master/texmf-dist/tex/luatex/luakeys/luakeys-debug.tex)
55 * [tex/luatex/luakeys/luakeys-debug.sty](https://tug.org/svn/texlive/trunk/Master/texmf-dist/tex/luatex/luakeys/luakeys-debug.sty)
56 * doc files:
57 * [doc/luatex/luakeys/luakeys-doc.tex](https://tug.org/svn/texlive/trunk/Master/texmf-dist/doc/luatex/luakeys/luakeys-doc.tex)
58 * [doc/luatex/luakeys/luakeys.pdf](https://tug.org/svn/texlive/trunk/Master/texmf-dist/doc/luatex/luakeys/luakeys.pdf)
59 * [doc/luatex/luakeys/README.md](https://tug.org/svn/texlive/trunk/Master/texmf-dist/doc/luatex/luakeys/README.md)
60 * [MiKTeX](https://miktex.org/packages/luakeys)
61
62 ### Repository
63
64 The [Git repository](https://github.com/Josef-Friedrich/luakeys) in
65 which the development takes place is hosted on
66 [GitHub](https://github.com).
67
68 ## Documentation
69
70 ### Key-value pair definitions
71
72 ```lua
73 local defs = {
74 key = {
75 -- Allow different key names.
76 -- or a single string: alias = 'k'
77 alias = { 'k', 'ke' },
78
79 -- The key is always included in the result. If no default value is
80 -- definied, true is taken as the value.
81 always_present = false,
82
83 -- Only values listed in the array table are allowed.
84 choices = { 'one', 'two', 'three' },
85
86 -- Possible data types:
87 -- any, boolean, dimension, integer, number, string, list
88 data_type = 'string',
89
90 -- To provide a default value for each naked key individually.
91 default = true,
92
93 -- Can serve as a comment.
94 description = 'Describe your key-value pair.',
95
96 -- The key belongs to a mutually exclusive group of keys.
97 exclusive_group = 'name',
98
99 -- > \MacroName
100 macro = 'MacroName', -- > \MacroName
101
102 -- See http://www.lua.org/manual/5.3/manual.html#6.4.1
103 match = '^%d%d%d%d%-%d%d%-%d%d$',
104
105 -- The name of the key, can be omitted
106 name = 'key',
107
108 -- Convert opposite (naked) keys
109 -- into a boolean value and store this boolean under a target key:
110 -- show -> opposite_keys = true
111 -- hide -> opposite_keys = false
112 -- Short form: opposite_keys = { 'show', 'hide' }
113 opposite_keys = { [true] = 'show', [false] = 'hide' },
114
115 -- Pick a value by its data type:
116 -- 'any', 'string', 'number', 'dimension', 'integer', 'boolean'.
117 pick = false, -- ’false’ disables the picking.
118
119 -- A function whose return value is passed to the key.
120 process = function(value, input, result, unknown)
121 return value
122 end,
123
124 -- To enforce that a key must be specified.
125 required = true,
126
127 -- To build nested key-value pair definitions.
128 sub_keys = { key_level_2 = { } },
129 }
130 }
131 ```
132
133 ### Parser options (opts)
134
135 ```lua
136 local opts = {
137 -- Result table that is filled with each call of the parse function.
138 accumulated_result = accumulated_result,
139
140 -- Configure the delimiter that assigns a value to a key.
141 assignment_operator = '=',
142
143 -- Automatically convert dimensions into scaled points (1cm -> 1864679).
144 convert_dimensions = false,
145
146 -- Print the result table to the console.
147 debug = false,
148
149 -- The default value for naked keys (keys without a value).
150 default = true,
151
152 -- A table with some default values. The result table is merged with
153 -- this table.
154 defaults = { key = 'value' },
155
156 -- Key-value pair definitions.
157 defs = { key = { default = 'value' } },
158
159 -- Specify the strings that are recognized as boolean false values.
160 false_aliases = { 'false', 'FALSE', 'False' },
161
162 -- lower, snake, upper
163 format_keys = { 'snake' },
164
165 -- Configure the delimiter that marks the beginning of a group.
166 group_begin = '{',
167
168 -- Configure the delimiter that marks the end of a group.
169 group_end = '}',
170
171 -- Listed in the order of execution
172 hooks = {
173 kv_string = function(kv_string)
174 return kv_string
175 end,
176
177 -- Visit all key-value pairs recursively.
178 keys_before_opts = function(key, value, depth, current, result)
179 return key, value
180 end,
181
182 -- Visit the result table.
183 result_before_opts = function(result)
184 end,
185
186 -- Visit all key-value pairs recursively.
187 keys_before_def = function(key, value, depth, current, result)
188 return key, value
189 end,
190
191 -- Visit the result table.
192 result_before_def = function(result)
193 end,
194
195 -- Visit all key-value pairs recursively.
196 keys = function(key, value, depth, current, result)
197 return key, value
198 end,
199
200 -- Visit the result table.
201 result = function(result)
202 end,
203 },
204
205 invert_flag = '!',
206
207 -- Configure the delimiter that separates list items from each other.
208 list_separator = ',',
209
210 -- If true, naked keys are converted to values:
211 -- { one = true, two = true, three = true } -> { 'one', 'two', 'three' }
212 naked_as_value = false,
213
214 -- Throw no error if there are unknown keys.
215 no_error = false,
216
217 -- Configure the delimiter that marks the beginning of a string.
218 quotation_begin = '"',
219
220 -- Configure the delimiter that marks the end of a string.
221 quotation_end = '"',
222
223 -- Specify the strings that are recognized as boolean true values.
224 true_aliases = { 'true', 'TRUE', 'True' },
225
226 -- { key = { 'value' } } -> { key = 'value' }
227 unpack = false,
228 }
229 local result = luakeys.parse('one,two,three', opts)
230 ```
231
232 ## Development
233
234 `luakeys` is developed using the
235 [Lua](https://marketplace.visualstudio.com/items?itemName=sumneko.lua)
236 extension in Visual Studio Code. This extension understands the modified
237 [EmmyLua annotations](https://github.com/sumneko/lua-language-server/wiki/Annotations).
238 The Lua code is automatically formatted with the help of the
239 [LuaFormatter](https://github.com/Koihik/LuaFormatter).
240
241 ## Tasks
242
243 ### Installing
244
245 ```
246 make install
247 ```
248
249 ### Testing
250
251 The framework [busted](https://github.com/Olivine-Labs/busted) is used
252 for the tests.
253
254 ```
255 luarocks install busted
256 busted --exclude-tags=skip test/lua/*.lua
257 ```
258
259 or
260
261 ```
262 make test
263 ```
264
265 ### Release a new version
266
267 This project uses [semantic versioning](https://semver.org).
268
269 Update version in:
270
271 * luakeys-doc.tex
272 * luakeys-debug.sty
273 * luakeys.sty
274 * luakeys.lua
275
276 Update copyright in:
277
278 * luakeys-debug.sty
279 * luakeys-debug.tex
280 * luakeys.lua
281 * luakeys.sty
282 * luakeys.tex
283 * README.md
284
285 Summarize the changes in the luakeys-doc.tex as changes.
286
287 Create a new git tag `git tag -sa 0.7.0`.