summaryrefslogtreecommitdiff
path: root/macros/luatex/generic/luakeys/README.md
diff options
context:
space:
mode:
Diffstat (limited to 'macros/luatex/generic/luakeys/README.md')
-rw-r--r--macros/luatex/generic/luakeys/README.md114
1 files changed, 114 insertions, 0 deletions
diff --git a/macros/luatex/generic/luakeys/README.md b/macros/luatex/generic/luakeys/README.md
index 10793d353e..ca73100b64 100644
--- a/macros/luatex/generic/luakeys/README.md
+++ b/macros/luatex/generic/luakeys/README.md
@@ -30,6 +30,120 @@ This work has the LPPL maintenance status `maintained`.
The Current Maintainer of this work is Josef Friedrich.
+## Documentation
+
+### Key-value pair definitions
+
+```lua
+local defs = {
+ key = {
+ -- Allow different key names.
+ -- or a single string: alias = 'k'
+ alias = { 'k', 'ke' },
+
+ -- The key is always included in the result. If no default value is
+ -- definied, true is taken as the value.
+ always_present = false,
+
+ -- Only values listed in the array table are allowed.
+ choices = { 'one', 'two', 'three' },
+
+ -- Possible data types: boolean, dimension, integer, number, string
+ data_type = 'string',
+
+ default = true,
+
+ -- The key belongs to a mutually exclusive group of keys.
+ exclusive_group = 'name',
+
+ -- > \MacroName
+ macro = 'MacroName', -- > \MacroName
+
+ -- See http://www.lua.org/manual/5.3/manual.html#6.4.1
+ match = '^%d%d%d%d%-%d%d%-%d%d$',
+
+ -- The name of the key, can be omitted
+ name = 'key',
+ opposite_keys = { [true] = 'show', [false] = 'hide' },
+ process = function(value, input, result, unknown)
+ return value
+ end,
+ required = true,
+ sub_keys = { key_level_2 = { } },
+ }
+}
+```
+
+### Parser options (opts)
+
+```lua
+local opts = {
+ -- Automatically convert dimensions into scaled points (1cm -> 1864679).
+ convert_dimensions = false,
+
+ -- Print the result table to the console.
+ debug = false,
+
+ -- The default value for naked keys (keys without a value).
+ default = true,
+
+ -- A table with some default values. The result table is merged with
+ -- this table.
+ defaults = { key = 'value' },
+
+ -- Key-value pair definitions.
+ defs = { key = { default = 'value' } },
+
+ -- lower, snake, upper
+ format_keys = { 'snake' },
+
+ -- Listed in the order of execution
+ hooks = {
+ kv_string = function(kv_string)
+ return kv_string
+ end,
+
+ -- Visit all key-value pairs recursively.
+ keys_before_opts = function(key, value, depth, current, result)
+ return key, value
+ end,
+
+ -- Visit the result table.
+ result_before_opts = function(result)
+ end,
+
+ -- Visit all key-value pairs recursively.
+ keys_before_def = function(key, value, depth, current, result)
+ return key, value
+ end,
+
+ -- Visit the result table.
+ result_before_def = function(result)
+ end,
+
+ -- Visit all key-value pairs recursively.
+ keys = function(key, value, depth, current, result)
+ return key, value
+ end,
+
+ -- Visit the result table.
+ result = function(result)
+ end,
+ },
+
+ -- If true, naked keys are converted to values:
+ -- { one = true, two = true, three = true } -> { 'one', 'two', 'three' }
+ naked_as_value = false,
+
+ -- Throw no error if there are unknown keys.
+ no_error = false,
+
+ -- { key = { 'value' } } -> { key = 'value' }
+ unpack = false,
+}
+local result = luakeys.parse('one,two,three', opts)
+```
+
## Tasks
### Installing