| 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`. |