Module pancake
Toolkit for writing Lua filters for Pandoc.
Synopsis:
pancake = require 'pancake'
Pancake aims to work with Pandoc ≥ v2.0.4. However, it has only been tested with v2.9–v2.18, and only on Linux and macOS.
Tip:
Pancake automatically loads Pandoc’s modules (e.g., pandoc.system
) into
the global namespace; this is useful when you are using older versions of
Pandoc, which do not do this automatically. So, you may want to load it
before setting up a per-function or per-module environment.
Info:
- Copyright: 2022 Odin Kroeger
- Release: 1.0.0b18
- License: MIT
- Author: Odin Kroeger
Metadata
VERSION | Pancake’s version. |
System
PATH_SEP | The path segment separator used by the operating system. |
EOL | The end of line sequence typically used on the given operating system. |
Type-checking
type_match (val, decl) | Check whether a value is of a type. |
type_check (...) | Decorator that adds type checks to a function. |
Errors
asserter ([fin[, msgh]]) | Create a custom assertion function. |
protect (func) | Decorator that runs a function in protected mode. |
unprotect (func) | Decorator that raises an error if a function returns a fail value. |
Tables
copy (val) | Make a deep copy of a value. |
keys (tab) | Get the indices and number of items in a table. |
order (values) | Derive a sorting function from a list of values. |
sorted (tab[, func[, raw]]) | Iterate over the key-value pairs of a table in a given order. |
tabulate (iter[, tab[, idx=1]]) | Tabulate the values that an iterator returns. |
walk (val, func) | Apply a function to each node of a tree. |
Strings
split (str, pattern[, max[, opts]]) | Iterate over substrings of a string. |
Variables
vars_get ([level=2]) | Get a copy of a function’s variables. |
vars_sub (str, vars) | Substitute variables in strings. |
env_sub (str) | Substitute environment variables in strings. |
Metatables
no_case | Metatable that makes indices case-insensitive. |
no_case.__index (tab, key) | Look up an item. |
no_case.__newindex (tab, key, val) | Store a new item. |
Prototypes
Object | Base prototype. |
Object:clone ([tab[, mt]]) | Delegate to an object. |
Object:new (...) | Initialise an Object. |
getterify (tab) | Add getters to a table. |
File I/O
file_exists (fname) | Check whether a file exists. |
file_locate (fname) | Locate a file in Pandoc’s resource path. |
file_read (fname) | Read a file. |
file_write (fname, ...) | Write data to a file. |
tmp_fname ([dir[, templ='tmp-XXXXXX']]) | Generate a name for a temporary file. |
with_tmp_file (func[, dir[, templ]]) | Run a function with a temporary file. |
Paths
path_join (...) | Join path segments. |
path_normalise (path) | Normalise a path. |
path_prettify (path) | Prettify a path. |
path_split (path) | Split a path into a directory and a filename. |
project_dir () | Guess the project directory. |
Warnings
xwarn (...) | Print a message to STDERR. |
Elements
elem_clone (elem) | Make a shallow copy of a Pandoc AST element. |
elem_type (elem) | Get the type of a Pandoc AST element. |
elem_walk (elem, filter) | Walk an AST element and apply a filter to matching elements. |
Options
Options | An option list. |
Options:new (...) | Create a new option list. |
Options:add (...) | Add an option to the list. |
Options:parse (meta) | Parse options from a metadata block (OO-interface). |
opts_parse (meta, ...) | Parse options from a metadata block (function interface). |
Metadata
System
- PATH_SEP
- The path segment separator used by the operating system.
- EOL
- The end of line sequence typically used on the given operating system.
Type-checking
- type_match (val, decl)
-
Check whether a value is of a type.
Type Declaration Grammar:
Give one or more Lua type names separated by a pipe symbol (‘|’) to check whether a value is of one of the given types (e.g., ‘string|table’ checks whether the value is a string or a table). ‘’ is short for the list of all types save for
nil
. ‘?T’ is short for ‘T*|nil’ (e.g., ‘?table’ is short for ‘table|nil’).Type = ‘boolean’ | ‘function’ | ‘nil’ | ‘number’ | ‘string’ | ‘table’ | ‘thread’ | ‘userdata’
Type list = [ ‘?’ ], type, { ‘|’, type }
Wildcard = [ ‘?’ ], ‘*’
Type declaration = type list | wildcard
Complex Types:
You can check types of table or userdata fields by declarding a table that maps indices to declarations.
> type_check({1, '2'}, {'number', 'number'}) nil index 2: expected number, got string. > type_check({foo = 'bar'}, {foo = '?table'}) nil index foo: expected table or nil, got string. > type_check('foo', {foo = '?table'}) nil expected table or userdata, got string.
Caveats:
Wrong type names (e.g., ‘int’) do not throw an error, but will always return one.
Parameters:
Returns:
-
bool
true
if the value matches the declaration.Or
-
nil
nil
otherwise. - string An error message.
-
nil
- type_check (...)
-
Decorator that adds type checks to a function.
Only adds type checks if the global
CHECK_TYPES
evaluates as true.Type declaration grammar:
The type declaration syntax is that of type_match, save for that you can use ‘…’ to declare that the remaining arguments are of the same type as the previous one.
Caveats:
- Wrong type names (e.g., ‘int’) do not throw an error.
- Sometimes the strack trace is wrong.
Tip:
-
Obscure Lua errors may indicate that
the quotes around ‘…’ are missing.
Parameters:
Returns:
-
func
A function that adds type checks to another function.
Usage:
store = type_check('*', 'table', '?number', '...')( function (val, tab, ...) local indices = table.pack(...) for i = 1, indices.n do tab[indices[i]] = val end end )
Errors
- asserter ([fin[, msgh]])
-
Create a custom assertion function.
See http://lua-users.org/wiki/FinalizedExceptions.
Parameters:
- fin func Called before an error is thrown. (optional)
- msgh func Given the error and the caller’s variables, should return a new error. (optional)
Returns:
-
func
An assertion function.
Usage:
> local assert = asserter(nil, vars_sub) > function foo () > local bar = 'The bar' > assert(false, '${bar} is to blame!') > end > foo() The bar is to blame! stack traceback: [C]: in function 'error' stdin:3: in function 'foo' (...tail calls...) [C]: in ?
- protect (func)
-
Decorator that runs a function in protected mode.
See http://lua-users.org/wiki/FinalizedExceptions.
Parameters:
- func func A function.
Returns:
-
func
A function running in protected mode.
See also:
Usage:
> foo = protect(function () return 'foo' end) > foo() foo > boo = protect(function () error 'bar!' end) > boo() nil bar!
- unprotect (func)
-
Decorator that raises an error if a function returns a fail value.
Parameters:
- func func A function.
Returns:
-
func
A function that throws an error on failures.
See also:
Usage:
> foo = unprotect(function () return 'foo' end) > foo() foo > boo = unprotect(function () return nil, 'boo.' end) > boo() boo. stack traceback: [C]: in function 'error' stdin:4: in function 'boo' (...tail calls...) [C]: in ?
Tables
- copy (val)
-
Make a deep copy of a value.
- Copies metatables.
- Handles cyclic data.
- Bypasses
__pairs
and__newindex
.
Parameters:
- val A value.
Returns:
-
A deep copy.
Usage:
> foo = {1, 2, 3} > bar = {foo, 4} > baz = copy(bar) > foo[#foo + 1] = 4 > table.unpack(baz, 1) 1 2 3
- keys (tab)
-
Get the indices and number of items in a table.
Tip:
select(2, keys(t)) == #t
checks whether a table is a list.Parameters:
- tab tab A table.
Returns:
- tab The indices.
- int The number of items.
- order (values)
-
Derive a sorting function from a list of values.
Values that are not in the list are sorted lexically.
Parameters:
- values tab Values.
Returns:
-
func
A sorting function.
Usage:
> tab = {a = 3, b = 4, c = 2, d = 1} > for k, v in sorted(tab, order{'d', 'c'}) do > print(k, v) > end d 1 c 2 a 3 b 4
- sorted (tab[, func[, raw]])
-
Iterate over the key-value pairs of a table in a given order.
Parameters:
- tab tab A table.
- func
func
A sorting function.
Defaults to the
sort
metamethod or sorting lexically. (optional) - raw
bool
Bypass
__pairs
metamethod? Done by default if__pairs
is set tosorted
. (optional)
Returns:
-
func
A stateful iterator.
Usage:
> -- Iterating over keys in lexical order. > tab = {c = 3, b = 2, a = 1} > for k, v in sorted(tab) do > print(k, v) > end a 1 b 2 c 3 -- Supplying a sorting function. > for k, v in sorted(tab, order{'c', 'b', 'a'}) do > print(k, v) > end c 3 b 2 a 1 > -- Setting the `sort` metamethod. > mt = {sort = order{'c', 'b', 'a'}} > setmetatable(tab, mt) > for k, v in sorted(tab) do > print(k, v) > end c 3 b 2 a 1 > -- Using `sorted` as `__pairs` metamethod. > mt.__pairs = sorted > for k, v in pairs(tab) do > print(k, v) > end c 3 b 2 a 1
- tabulate (iter[, tab[, idx=1]])
-
Tabulate the values that an iterator returns.
Parameters:
- iter func An iterator. Must accept, though not honour, the same arguments as next.
- tab tab A table to iterate over. (optional)
- idx An index to start at. (default 1)
Returns:
-
{...,n=number}
The values returned by the iterator.
Usage:
> tab = {a = true, b = true, c = true} > unpack(tabulate(next, tab)) a b c
- walk (val, func)
-
Apply a function to each node of a tree.
- Nodes are only changed if the function returns a non-
nil
value. - The tree is walked bottom-up.
- Handles cyclic data structures.
Parameters:
- val A value.
- func func A function.
Returns:
-
A changed value.
- Nodes are only changed if the function returns a non-
Strings
- split (str, pattern[, max[, opts]])
-
Iterate over substrings of a string.
Options:
split
accepts a string of option characters:- ‘P’: Disable pattern matching.
- ‘E’: Skip empty substrings.
- ‘l’: Add seperator to left of substring; implies ‘E’.
- ‘r’: Add seperator to right; implies ‘E’.
An empty string of options is ignored silently.
Caveats:
-
Does not support multi-byte characters.
Parameters:
- str string A string.
- pattern string Where to split the string.
- max int Split the string into at most that many substrings. (optional)
- opts string Option string. (optional)
Returns:
-
func
A stateful iterator.
Usage:
> for s in split('CamelCase', '%f[%u]') do > print(s) > end Camel Case > for s in split('CamelCase', '%f[%u]', nil, 'E') do > print(s) > end Camel Case > for s in split('foobar', '[fb]', nil, 'l') do > print(s) > end foo bar
Variables
- vars_get ([level=2])
-
Get a copy of a function’s variables.
Caveats:
-
If a global variable is shadowed by a variable that is neither one of
the function’s local variables nor one of its upvalues, then that variable
is looked up in
_ENV
and the shadowing variable is ignored.Parameters:
- level
int
A stack level > 0, where
vars_get
is at level 1, its caller is at level 2, etc. (default 2)
Returns:
-
table
A mapping of variable names to values.
Usage:
> function bar () > print(vars_get(3).foo) > end > function foo () > foo = 'foo' > bar() > end > foo() foo
- level
int
A stack level > 0, where
- vars_sub (str, vars)
-
Substitute variables in strings.
If a string of characters is placed within braces (‘{…}’) and the opening brace (‘{’) immediately follows a single dollar (‘$’) sign, then that string is interpreted as a variable name and the whole expression is replaced with the value of that variable. Variable names must only consist of letters, numbers, and underscores (‘_’) and must start with a letter or an underscore.
> vars_sub( > '${v1} is ${v2}.', > {v1 = 'foo', v2 = 'bar'} > ) foo is bar.
If a braced string is preceded by two or more dollar signs, it is not interpreted as a variable name and the expression is not replaced with the value of a variable. Moreover, any series of n dollar signs that precedes a pair of braces (e.g.,
$${...}
) is replaced with n – 1 dollar signs.> vars_sub( > '$${var} costs $1.', > {var = 'foo'} > ) ${var} costs $1.
You can lookup values in tables by joining table indices with dots (‘.’).
> vars_sub( > '${foo.bar} is baz.', { > foo = { bar = 'baz' } > } > ) baz is baz.
If a variable name is followed by a pipe symbol (‘|’), then the string between that pipe symbol and the next pipe symbol/closing brace is interpreted as a function name, this function is then given the value of that variable, and the whole expression is replaced with the first value the function returns.
> vars_sub( > '${var|barify} is bar!', { > var = 'foo', > barify = function (s) > return s:gsub('foo', 'bar') > end > } > ) bar is bar!
Variables are substituted recursively.
> vars_sub( > '${foo|barify} is bar.', { > foo = '${bar}', > bar = 'baz', > barify = function (s) return s:gsub('baz', 'bar') end > } > ) bar is bar.
The expression as a whole must evaluate either to a string or a number.
Variables can also be looked up by a function. The function is run in protected mode. If it throws an error,
vars_sub
will returnnil
and the error object thrown by the function. This mode does not support multi-dimensional lookups (${foo.bar}
), pipes (${foo|bar}
), or recursive substitution.> vars_sub( > '${foo} is bar.', > function (key) > if key == 'foo' then return 'bar' end > end > ) bar is bar.
Parameters:
- str string A string.
- vars func or tab A mapping of variable names to values.
Returns:
-
string
A transformed string.
Or
-
nil
nil
if an error occurred. - string An error message.
- env_sub (str)
-
Substitute environment variables in strings.
Uses the same syntax as vars_sub, but without pipes or recursive substitution.
Side-effects:
-
Prints a warning to STDERR if a variable is empty.
Parameters:
- str string A string.
Returns:
-
string
A transformed string.
Or
-
nil
nil
if an error occurred. - string An error message.
Metatables
- no_case
-
Metatable that makes indices case-insensitive.
Usage:
> tab = setmetatable({}, no_case) > tab.FOO = 'bar' > tab.foo bar
- no_case.__index (tab, key)
-
Look up an item.
Parameters:
- tab tab A table.
- key A key.
Returns:
-
The item.
- no_case.__newindex (tab, key, val)
-
Store a new item.
Parameters:
- tab tab A table.
- key A key.
- val A value.
Prototypes
- Object
-
Base prototype.
Tip:
Object(...)
is equivalent toObject:new(...)
. - Object:clone ([tab[, mt]])
-
Delegate to an object.
Set a table’s metatable to a copy of the objects’s metatable, then set the table’s
__index
metavalue to the object. If no table is given, create one. If a metatable is given, override the table’s new metatable with that table. In other words,Object:clone(tab, mt)
is equivalent to
do local mt = update({}, getmetatable(Object), {__index = Object}, mt) setmetatable(tab or {}, mt) end
Caveats:
-
The given table is changed in-place.
Parameters:
- tab tab A table. (optional)
- mt tab A metatable. (optional)
Returns:
-
tab
The table.
Usage:
> Foo = Object:clone({}, {__tostring = function (t) return t.bar end}) > Foo.bar = 'baz' > tostring(Foo) baz > bar = Foo() > tostring(bar) baz > bar.bar = 'bar' > tostring(bar) bar
- Object:new (...)
-
Initialise an Object.
Object:new(...)
is equivalent toupdate(Object:clone(), ...)
.Parameters:
- ... tab Properties.
Returns:
-
Object
An object.
Usage:
> foo = Object:new{foo = 'foo'} > foo.foo foo > bar = foo:new{bar = 'bar'} > bar.foo foo > bar.bar bar
- getterify (tab)
-
Add getters to a table.
Getter protocol:
If an index is not present in a the table, look for a function of the same name in the table’s
getters
metavalue, which must be a table that maps indices to functions. Ifgetters
contains a function of the give name, that function is called with the table as its only argument and whatever it returns is returned as the value of the given index. Ifgetters
does not contain a function of that name, the name is looked up using the table’s old__index
metavalue.Caveats:
- Tables are modified in-place.
- Getters are not inherited.
Parameters:
- tab tab A table.
Returns:
-
tab
The table.
Usage:
> -- Enable getters for an object: > Foo = getterify(Object:clone()) > Foo.foo = 'bar' > mt = getmetatable(Foo) > mt.getters = {bar = function (obj) return obj.foo end} > Foo.bar bar > -- Getters are *not* inherited. > baz = Foo() > baz.foo = 'bam!' > -- The getter is reached via the prototype chain, > -- so it sees Foo.foo, not bar.foo: > baz.bar bar > -- But you can make getters quasi-inheritable: > Foo.clone = function (...) return getterify(Object.clone(...)) end > baz = Foo() > baz.foo = 'bam!' > baz.bar bam! > -- Now every object down the prototype chain is getterified. > bam = baz() > bam.foo = 'BAM!' > bam.bar BAM!
File I/O
- file_exists (fname)
-
Check whether a file exists.
Caveats:
-
Another process may create a file of the given name between the time
file_exists
tries to access that file and the time it returns.Parameters:
- fname string A filename.
Returns:
-
boolean
true
if the file exists.Or
-
nil
nil
if the file does not exist. - string An error message.
- int The error number 2.
Raises:
An error if the file cannot be closed again. - file_locate (fname)
-
Locate a file in Pandoc’s resource path.
Caveats:
-
Absolute filenames are returned as they are.
Parameters:
- fname string A filename.
Returns:
-
string
A filename in Pandoc’s resource path.
Or
-
nil
nil
if the file could not be found. - string An error message.
- file_read (fname)
-
Read a file.
Parameters:
- fname string A filename.
Returns:
-
string
The contents of the file.
Or
-
nil
nil
if an error occurred. - string An error message.
- int An error number.
- file_write (fname, ...)
-
Write data to a file.
If a file of that name exists already, it is overwritten.
Caveats:
-
Data is first written to a temporary file, that file is then renamed
to the given filename. This is safe and secure starting with Pandoc
v2.8. If you are using an older version of Pandoc, the caveats of
with_tmp_file apply.
Moreover, if Pandoc exits because it catches a signal (e.g., because the user presses
Ctrl
-c
), this file will not be deleted. This is a bug in Pandoc.Side-effects:
- Creates and deletes a temporary file.
- Prints warnings to STDERR.
Parameters:
Returns:
-
bool
true
if the data was written to the given file.Or
-
nil
nil
if an error occurred. - string An error message.
- int An error number.
Raises:
An error if no unused temporary filename could be generated in Pandoc < v2.8 or if the temporary directory could not be created in Pandoc ≥ v2.8; the latter error cannot be caught. - tmp_fname ([dir[, templ='tmp-XXXXXX']])
-
Generate a name for a temporary file.
Caveats:
-
Another process may create a file of the same name between the time
tmp_fname
checks whether that name is in use and the time it returns.Parameters:
- dir string A directory to prefix the filename with. (optional)
- templ string A template for the filename. ‘X’s are replaced with random alphanumeric characters. (default 'tmp-XXXXXX')
Returns:
-
string
A filename.
Or
-
nil
nil
if the generated filename is in use. - string An error message.
- with_tmp_file (func[, dir[, templ]])
-
Run a function with a temporary file.
Generates a temporary filename. Does not create that file. If the function raises an error or returns
nil
orfalse
, the file of that name is deleted.Caveats:
-
The temporary file may have been created by another process. If that
file is located within a directory that other users have write access
to (e.g.,
/tmp
), this is a security issue!Moreover, if Pandoc exits because it catches a signal (e.g., because the user presses
Ctrl
-c
), the file will not be deleted. This is a bug in Pandoc.Side-effects:
-
May print error messages to STDERR.
Parameters:
- func func Given the name of the temporary file. Must not change the working directory!
- dir string A directory to prefix the name of the temporary file with. See tmp_fname. (optional)
- templ string A template for the name of the temporary file. See tmp_fname. (optional)
Returns:
-
The values returned by the function.
Raises:
An error if no unused temporary filename could be generated.
Paths
- path_join (...)
-
Join path segments.
Parameters:
- ... string Path segments.
Returns:
-
string
A path.
Usage:
> path_join('foo', 'bar') foo/bar
- path_normalise (path)
-
Normalise a path.
Parameters:
- path string A path.
Returns:
-
string
A normalised path.
Usage:
> path_normalise './foo/./bar//' foo/bar
- path_prettify (path)
-
Prettify a path.
Steps:
- The path is normalised.
- The current working directory is removed from its beginning.
- The user’s home directory is replaced with ‘~’, but only on POSIX systems.
Requires:
-
Pandoc ≥ v2.12 to remove the working directory from a path;
in earlier versions, this step is skipped.
Parameters:
- path string A path.
Returns:
-
string
A prettier path.
Usage:
> path_prettify(env_sub '${HOME}/foo/./bar//') ~/foo/bar
- path_split (path)
-
Split a path into a directory and a filename.
Parameters:
- path string A path.
Returns:
Usage:
> path_split 'foo/bar' foo bar
- project_dir ()
-
Guess the project directory.
The project directory is the directory of the first input file not named ‘-’ (i.e., of the first actual input file). If there is no such file, the project directory is the current working directory.
Requires:
-
The working directory is represented by ‘.’ in Pandoc < v2.8.
Returns:
-
string
A directory.
Warnings
- xwarn (...)
-
Print a message to STDERR.
Printout:
Prefixed with the filename of the script and ‘: ’, terminated with EOL. Non-strings are coerced to strings.
Message priority:
Messages are only printed if their priority is greater or equal to
PANDOC_STATE.verbosity
.Variable substitution:
If string values contain variable names, they are replaced with the values of the local variables, of the upvalues of the calling function, or, if there are no local variables or upvalues of the given names, of
_ENV
. See vars_sub for the syntax and vars_get for limitations.Options:
String values starting with an ‘@’ are interpreted as options:
- ‘@error’, ‘@warning’, ‘@info’: Set the message’s priority. (default ‘warning’)
- ‘@noopts’: Turn option processing off. (default on)
- ‘@novars’: Turn variable substitution off. (default on)
- ‘@plain’: Turn variable substitution and option processing off.
- ‘@vars’: Turn variable substitution on.
Options are case-sensitive. Unknown options are ignored silently.
Requires:
-
Pandoc ≥ v2.4 to respect
--quiet
and--verbose
; in earlier versions, those options are ignored.Parameters:
- ... Messages. At least one must be given.
Elements
- elem_clone (elem)
-
Make a shallow copy of a Pandoc AST element.
Parameters:
- elem pandoc.AstElement A Pandoc AST element.
Returns:
-
pandoc.AstElement
The clone.
- elem_type (elem)
-
Get the type of a Pandoc AST element.
Parameters:
- elem pandoc.AstElement A Pandoc AST element.
Returns:
Or
-
nil
nil
if the given value is not a Pandoc AST element. - string An error message.
- elem_walk (elem, filter)
-
Walk an AST element and apply a filter to matching elements.
Differences to Pandoc’s Walkers:
- The filter is applied to the given element itself.
- The AST is traversed bottom-up or top-down, but not typewise, and matching elements are traversed, too.
- Support for the filter keywords ‘Block’, ‘Inline’, and ‘AstElement’, which match any block, any inline, or any element respectively.
- Metadata fields and documents as a whole are traversed, too.
Direction of Traversal:
Depends on the filter’s
traverse
field:bottomup
: Traverse the AST bottom-up.topdown
: Traverse the AST top-down. (default)
The AST is traversed left-to-right either way.
Caveats:
-
This function needs more testing.
Parameters:
- elem pandoc.AstElement A Pandoc AST element.
- filter {string=func,...} A filter.
Returns:
-
Typically, but not necessarily, a new Pandoc AST element.
Options
- Options
-
An option list.
Prototype:
See also:
- Options:new (...)
-
Create a new option list.
opts = Options:new{name = 'foo'}
is equivalent to:
opts = Options() opts:add{name = 'foo'}
Parameters:
- ... tab Option definitions.
See also:
- Options:add (...)
-
Add an option to the list.
Parameters:
- ... tab Option definitions.
See also:
Usage:
opts = Options() opts:add{ name = 'bar', type = 'number', parse = function (x) if x < 1 then return nil, 'not a positive number.' end return x end }
- Options:parse (meta)
-
Parse options from a metadata block (OO-interface).
Parameters:
- meta pandoc.MetaMap A metadata block.
Returns:
-
tab
A mapping of option names to values.
Or
-
nil
nil
if an error occurred. - string An error message.
See also:
Usage:
> meta = pandoc.MetaMap{ > ['foo-bar'] = pandoc.MetaInlines(pandoc.List{ > pandoc.Str "0123" > }) > parser = Options() > parser:add{ > name = 'bar', > prefix = 'foo', > type = 'number', > parse = function (x) > if x < 1 then return nil, 'not a positive number.' end > return x > end > } > opts = parser:parse(meta) > opts.bar 123 > type(opts.bar) number
- opts_parse (meta, ...)
-
Parse options from a metadata block (function interface).
Option Definition Syntax:
An option definition is a table with the following keys:
name
: (string) An option name.type
: (string) An option type. (default ‘string’)parse
: (func) A parser. (optional)prefix
: (string) A prefix. (optional)
Mapping of Option Names to Metadata Fieldnames:
The name of the metadata field is the name of the option with underscores replaced by dashes. If the option has a prefix, then the fieldname is prefixed with that prefix and a dash after underscores have been replaced with dashes.
In Lua:
fieldname = name:gsub('_', '-') if prefix then fieldname = prefix .. '-' .. fieldname end
Type Declaration Grammar:
Configuration values can be of any of four types:
- ‘boolean’
- ‘number’
- ‘string’
- ‘array’
If an option is declared to be of one of the scalar types ‘boolean’, ‘number’, or ‘string’, then its value is required to be of the Lua type of the same name or convertible to that type; if an option is declared as ‘boolean’, the strings ‘true’, ’t', ‘yes’ and ‘y’ are converted to
true
, and ‘false’, ‘f’, ‘no’ and ‘n’ tofalse
(case is ignored).If an option is declared to be an ‘array’, its value is required to be of the Pandoc type
pandoc.List
or convertible to that type. However, if a scalar value is encountered where an array is expected, the value is wrapped in a single-item list automatically.Items in an array must all be of the same type. That type is declared by appending ‘<T>’ to ‘array’, where T is either the name of a scalar type or another array declaration (e.g., ‘array
’); T defaults to ‘string’. An option can be declared to be of any of a list of types by listing multiple type names separated by a pipe symbol (‘|’), for example, ‘string|list’. The first type that matches ‘wins’, even if winning requires a type conversion (e.g., ‘string|number’ is, effectively, equivalent to ‘string’).
Scalar = ‘boolean’ | ‘number’ | ‘string’
Array = ‘array’, [ ‘<’, ( scalar | array ), ‘>’ ]
Type = scalar | array
Type list = type, { ‘|’, type }
No type checks or conversions are performed for
nil
.Parse Protocol:
Parsers are given the converted value and should return either a new value or
nil
and an error message.Parsers are not invoked for
nil
.Caveats:
-
Options:add throws an error if it is given a wrong option type
(e.g., ‘int’ or ‘array[number]’).
opts_parse
accepts wrong option types and only throws an error if it encounters an option that is supposed to be of that type.Parameters:
- meta pandoc.MetaMap A metadata block.
- ... Option Option definitions.
Returns:
-
tab
A mapping of option names to values.
See also:
Usage:
> meta = pandoc.MetaMap{ > ['foo-bar'] = pandoc.MetaInlines(pandoc.List{ > pandoc.Str "0123" > }) > opts = opts_parse(meta, { > name = 'bar', > prefix = 'foo', > type = 'number', > parse = function (x) > if x < 1 then return nil, 'not a positive number.' end > return x > end > }) > opts.bar 123 > type(opts.bar) number