pandoc-zotxt.lua

Usage:

> function bar ()
>     print(vars_get(3).foo)
> end
> function foo ()
>     foo = 'foo'
>     bar()
> end
> foo()
foo

Tables

Set

A set representation.

Sets are represented as tables, so that a value v is a member of a set S if and only if S[v] is truthy. See Progamming in Lua (chap. 11.5) for details.

Caveats:

This table exists in documentation only.

ignore_case

Metatable to make index lookups case-insensitive.

Usage:

> tab = setmetatable({}, ignore_case)
> tab.FOO = 'bar'
> tab.foo
bar

ignore_case.__index (tab, key)

Look up an item.

Parameters:

tab tab A table.
key A key.

Returns:

The item.

ignore_case.__newindex (tab, key, val)

Store a new item.

Parameters:

tab tab A table.
key A key.
val A value.

sort_pairs

Metatable to sort key-value pairs automatically.

Usage:

> tab = setmetatable({c = 3, b = 2, a = 1}, sort_pairs)
> for k, v in pairs(tab) do
>     print(k, v)
> end
a    1
b    2
c    3

sort_pairs.__pairs (tab)

Iterate over the key-value pairs of a table in a given order.

What order pairs are iterated over is defined by the sort metamethod. Defaults to lexical order if sort is unset. See sorted for details.

Parameters:

tab tab A table.

Returns:

func

stateful

Usage:

> sort = order{'c', 'b', 'a'}
> mt = update({sort = sort}, sort_pairs)
> tab = setmetatable({a = 1, b = 2, c = 3}, mt)
> for k, v in pairs(tab) do
>     print(k, v)
> end
c    3
b    2
a    1

keys (tab)

Get the indices and number of items in a table.

Parameters:

tab tab A table.

Returns:

tab The indices.
int The number of items.

order (values)

Define a sorting function from an ordered list of values.

Parameters:

values tab Values.

Returns:

func

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=false]])

Iterate over the key-value pairs of a table in a given order.

Parameters:

tab tab A table.
func func A sorting function. If no function is given, sorts lexically. (optional)
raw bool Bypass __pairs metamethod? (default false)

Returns:

func

stateful

Usage:

> for k, v in sorted{c = 3, b = 2, a = 1} do
>     print(k, v)
> end
a    1
b    2
c    3

tabulate (iter[, tab[, key]])

Tabulate the values an iterator returns.

The iterator must accept, if not honour, the same arguments as next.

Parameters:

iter func An iterator.
tab A table to iterate over. (optional)
key The index to start iterating at. (optional)

Returns:

The values returned by the iterator.

Usage:

> str = 'key: value'
> k, v = tabulate(split(str, '%s*:%s*', 2))
> print(k, v)
key    value

update (tab, ...)

Merge tables.

Caveats:

in-place

Parameters:

tab tab A table.
... tab or userdata Mappings to merge into the table.

Returns:

tab

walk (val, func)

Walk a tree and apply a function to every node.

Nodes are only changed if the function returns a value other than nil.

Parameters:

val A value.
func func A function.

Returns:

A changed value.

Strings

split (str, pattern[, max[, include]])

Iterate over substrings of a string.

Caveats:

Neither supports multi-byte characters nor frontier patterns.

Parameters:

str string A string.
pattern string Where to split the string.
max int Split the string into at most that many substrings. (optional)
include string Include separators in substrings?
- ‘l’ includes them on the left,
- ‘r’ on the right.
By default, separators are not included. (optional)

Returns:

func

stateful

Usage:

> for s in split('CamelCase', '%u', nil, 'l') do
>     print(string.format("%s", s))
> end
""
"Camel"
"Case"

trim (str)

Remove leading and trailing whitespace.

Parameters:

str string A string.

Returns:

vars_sub (str, mapping)

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 names a variable and the whole expression is replaced with the value of that variable.

> 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 a variable name and the expression, therefore, not replaced. Moreover, any series of n dollar signs 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 the name of the variable and that of the table index with a dot (‘.’). Neither variable nor function names can contain dots.

> vars_sub(
>     '${foo.bar} is baz.', {
>         foo = { bar = 'baz' }
>     }
> )
baz is baz.

If a name is followed by a pipe symbol (‘|’), then the string between that pipe symbol and the next pipe symbol/the closing brace (‘}’) names a function; the value is then passed to that function, and the whole expression replaced with the first value that the function returns. Neither variable nor function names may contain pipe symbols.

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

Parameters:

str string A string.
mapping func or tab A mapping of variable names to values.

Returns:

Or

nil nil if an error occurred.
string An error message.

Prototypes

Object

Base prototype.

Object:clone ([tab[, mt]])

Delegate to an object.

Set a table’s metatable to a copy of the objects’s metatable and 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 roughly equivalent to

 do
     local mt = update({}, getmetatable(Object), {__index = Object}, mt)
     setmetatable(tab or {}, mt)
 end

Caveats:

in-place

Parameters:

tab tab A table. (optional)
mt tab A metatable. (optional)

Returns:

tab

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 (...)

Create and initialise a table that delegates to the object.

Object:new(...) is short for update(Object:clone(), ...).

Parameters:

... tab Properties.

Returns:

Usage:

> foo = Object:new{foo = 'foo'}
> foo.foo
foo

Object.mt

Metatable for prototypes.

Object.mt.__call (...)

Shorthand for Object:new.

Parameters:

... tab Passed to Object:new.

Returns:

Values

A simple list.

Prototype:

Tip:

You can sparse-copy a Values object by using it as a prototype:

> foo = Values:new 'foo'
> bar = foo()
> bar:add 'bar'
> #bar
2
> for i, v in ipairs(bar) do
>     print(i, v)
> end
1    foo
2    bar

Usage:

> list = Values()
> list:add 'a string'
> list.n
1

Values.mt

Metatable for values.

Values.mt.__len (obj)

Get the size of the list.

Parameters:

obj Values A list.

Returns:

number

Values.mt.__newindex (obj, key, val)

Add items to the list.

Side-effects:

Values.n

Parameters:

obj Values A list.
key An index.
val A value.

Values.mt.__pairs (obj)

Iterate over list items.

Parameters:

obj Values A list.

Returns:

function

Values.n

The number of items in the list.

Values:new (...)

Create a new list.

list = Values:new(...)

is short for:

list = Values:new()
list:add(...)

Tip:

You can convert an ‘ordinary’ list to a Values object by:

tab.n = #tab
Values:clone(tab)

Parameters:

... Items.

Returns:

Values

Values:add (...)

Add items to the list.

Side-effects:

Values.n

Parameters:

... Items.

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 mapping of indices to functions. If getters contains a function of that name, then that function is called with the table as its only argument and whatever it returns is returned as the value of the given index. If getters 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

Usage:

> -- Enable getters for an object:
> Foo = getterify(Object:clone())
> Foo.foo = 'bar'
> mt = getmetatable(Foo)
> mt.getters = {}
> function mt.getters.bar (obj) return obj.foo end
> Foo.bar
bar
> -- The getter is reached via the prototype chain,
> -- so it sees Foo.foo, not bar.foo:
> baz = Foo()
> baz.foo = 'bam!'
> 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!

Warnings

xwarn (...)

Print a message to STDERR.

Printout:

Prefixed with NAME .. ': ' and terminated with EOL. Non-string values are coerced to strings.

Message priority:

Messages are only printed if their priority is greater or equal to PANDOC_STATE.verbostiy.

Variable substitution:

If string values contain variable names, they are replaced with the values of the local variables or the upvalues of the calling function or, if there are no local variables or upvalues of the given names, the values of the global variables of the module. 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.

Parameters:

... Messages. At least one must be given.

File I/O

path_normalise (path)

Normalise a path.

Parameters:

path string A path.

Returns:

path_split (path)

Split a path into a directory and a filename.

Parameters:

path string A path.

Returns:

string The directory the file is in.
string The file’s name.

path_join (...)

Join multiple path segments.

Caveats:

Accepts empty strings as arguments.

Parameters:

... string Path segments.

Returns:

path_is_abs (path)

Check whether a path is absolute.

Caveats:

Accepts the empty string as path since Pandoc v2.12.

Parameters:

path string A path.

Returns:

bool

true

false

path_make_abs (path)

Make a path absolute.

Requires:

Pandoc v2.8

Parameters:

path string An absolute or relative path.

Returns:

path_prettify (path)

Prettify paths.

Removes the working directory from the beginning of the path. On POSIX systems, also replaces the user’s home directory with ‘~’.

Requires:

not

Parameters:

path string A path.

Returns:

project_dir ()

Guess the project directory.

The project directory is the directory of the first input file not 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 ‘.’ under Pandoc < v2.8.

Returns:

file_exists (fname)

Check whether a file exists.

Caveats:

file_exists

Parameters:

fname string A filename.

Returns:

boolean

true

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:

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:

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:

with_tmp_file

Side-effects:

Creates and deletes a temporary file.

Parameters:

fname string A filename.
... string The data.

Returns:

bool

true

Or

nil nil if an error occurred.
string An error message.
int An error number.

Raises:

Under Pandoc < v2.8, an error if no unused temporary filename could be generated. Otherwise, an error if the temporary directory could not be created; this error cannot be caught.

tmp_fname ([dir[, templ='pdz-XXXXXX']])

Generate a name for a temporary file.

Caveats:

tmp_fname

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 'pdz-XXXXXX')

Returns:

Markdown that Pandoc recognises in bibliographic data

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 or false, the temporary file is deleted.

Caveats:

another

/tmp

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.

Networking

http_get (url)

Retrieve data from a URL via an HTTP GET request.

Parameters:

url string A URL.

Returns:

string The MIME type of the HTTP content, in lower case.
string The HTTP content itself.

Raises:

An error if the host cannot be connected to. This error can only be caught in Pandoc ≥ v2.11.

Markup converters

escape_markdown (str)

Escape Markdown syntax.

Caveats:

Parameters:

str string Non-Markdown text.

Returns:

elements Pandoc permits in bibliographic data

Usage:

> escape_markdown '*text*'
\*text*

markdownify (elem)

Convert a Pandoc element to Markdown text.

Requires:

Parameters:

elem pandoc.AstElement A Pandoc AST element.

Returns:

Raises:

An error if the element cannot be converted.

yamlify (val[, ind=4])

Generate a YAML representation of a value.

Terminates lines with EOL.

Caveats:

Mangles strings in encodings other than UTF-8.
Does not escape all non-printable characters (because Unicode).

Parameters:

val A value.
ind int How many spaces to indent blocks. (default 4)

Returns:

Raises:

An error if the value cannot be represented in YAML.

zotero_to_html (pseudo)

Convert Zotero pseudo-HTML to proper HTML.

Parameters:

pseudo string Zotero pseudo-HTML code.

Returns:

pseudo-HTML that Pandoc recognises in bibliographic data

Or

nil nil if opening and closing ´´ tags are unbalanced.
string An error message.

zotero_to_markdown (pseudo)

Convert Zotero pseudo-HTML to Markdown.

Requires:

Parameters:

pseudo string Zotero pseudo-HTML code.

Returns:

Or

nil nil if an error occurred.
string An error message.

CSL items

Appendix IV of the Citation Style Language (CSL) specification lists all CSL variable names.

CSL_VARS_ORDER

Preferred order of CSL variables.

Fields:

id Item ID.
citekey Citation key (CSL v1.2).
type For example, ‘paper’, ‘book’.
author Author(s).
original-author Original author(s).
recipient Recipient of the document.
status Publication status (e.g., ‘forthcoming’).
issued When the item was published.
original-date Original date.
title The title.
title-short A short version of the title.
short-title Ditto.
translator Translator(s).
editor The editor(s).
container-title Publication the item was published in.
container-title-short A short version of that title.
collection-title E.g., a series.
collection-title-short A short version of the title.
edition Container’s edition.
volume Volume no.
issue Issue no.
page-first First page.
page Pages or page range or number of pages.
publisher Publisher.
publisher-place City/cities the item was published in.
original-title Original title.
original-publisher Original publisher.
original-publisher-place Place the item was originally published in.
url The URL.
accessed When the URL was last accessed.
doi The DOI.
pmcid PubMed Central reference number.
pmid PubMed reference number.
isbn The ISBN of the item.
issn The ISSN of the container.
call-number Call number (of a library).
language Language the item is in.
abstract The abstract.

Caveats:

“extra” field

Parameters:

item tab A CSL item.

Returns:

func

stateful

Side-effects:

May print error messages to STDERR.

Parameters:

item tab A CSL item.

Returns:

Or

nil nil if an “extra” field cannot be parsed.
string An error message.

csl_item_to_meta (item)

Convert a CSL item to a Pandoc metadata value.

This allows to use CSL items in the references metadata field.

Parameters:

item tab A CSL item.

Returns:

pandoc.MetaValue

Or

nil nil if a value cannot be converted.
string An error message.

csl_items_filter_by_ckey (items, ckey)

Filter CSL items by their citation key.

Side-effects:

May print error messages to STDERR.

Parameters:

items {tab,...} CSL items.
ckey string A citation key (e.g., 'doe:2020word', 'DoeWord2020').

Returns:

{tab,...}

csl_items_ids (items)

Pick the IDs of CSL items out of a list of CSL items.

Side-effects:

May print error messages to STDERR.

Parameters:

items {tab,...} CSL items.

Returns:

Set

csl_items_sort (a, b)

Sort CSL items by their ID.

Caveats:

Assumes that CSL item IDs are of the same type.

Parameters:

a tab A CSL item.
b tab Another CSL item.

Returns:

bool

csl_varname_normalise (var)

Normalise a CSL variable name.

Trim the variable name, lowercase it, and replace spaces with dashes.

Parameters:

var string A CSL variable name.

Returns:

Or

nil nil if the string is not a CSL variable name.
string An error message.

Usage:

> csl_varname_normalise 'Original date'
original-date

csl_vars_sort (a, b)

Sort CSL variables.

Sorts variables in the order in which they are listed in CSL_VARS_ORDER. Unlisted variables are placed after listed ones in lexical order.

Parameters:

a string A CSL variable name.
b string Another CSL variable name.

Returns:

bool

Citation keys

CITEKEY_PARSERS

A mapping of citation key types to citation key parsers.

A citation key parser is a function that takes a citation key and returns search terms or nil if no search terms can be derived from the key.

CITEKEY_PARSERS.betterbibtexkey (ckey)

Guess search terms from a BetterBibTeX citation key.

Splits up a BetterBibTeX citation key at each uppercase letter and at each start of a string of digits.

Caveats:

Non-letter characters must be encoded in ASCII.

Parameters:

ckey string A BetterBibTeX citation key (e.g., 'DoeWord2020').

Returns:

CITEKEY_PARSERS.easykey (ckey)

Guess search terms from an Easy Citekey.

Splits up an Easy Citekey into an author, a year, and a word.

Parameters:

ckey string A zotxt Easy Citekey (e.g., 'doe:2020word').

Returns:

CITEKEY_TYPIFIERS

A mapping of citation key type names to type guessing functions.

A type guessing function should take a citation key and return true if that key could be (not “is”) of that type and false otherwise.

CITEKEY_TYPIFIERS.betterbibtexkey (ckey)

Check if a citation key could be a Better BibTeX citation key.

Parameters:

ckey string A citation key.

Returns:

bool

CITEKEY_TYPIFIERS.key (ckey)

Check if a citation key is a Zotero item ID.

Parameters:

ckey string A citation key.

Returns:

bool

citekey_terms (ckey, types)

Guess search terms from a citation key.

Caveats:

CITEKEY_PARSERS

Parameters:

ckey string A citation key (e.g., 'doe:2020word', 'DoeWord2020').
types {string,...} Types to try to parse the citation key as.

Returns:

Or

nil nil if no search terms could be derived.
string An error message.

citekey_types (ckey, types)

Check whether a citation key could be of a type.

Parameters:

ckey string A citation key.
types {string,...} Citation key types.

Returns:

Bibliography files

BIBLIO_DECODERS

A case-insensitive mapping of filename suffices to decoders.

A decoder is a function that takes a string and returns a list of CSL items.

BIBLIO_DECODERS.bib (str)

Parse the contents of a BibLaTeX file.

Requires:

Only returns a list of mappings of the literal ‘id’ to CSL item IDs if run with Pandoc < v2.17.

Parameters:

str string The contents of a BibLaTeX file.

Returns:

{tab,...}

Or

nil nil if the contents could not be parsed.
string An error message.

BIBLIO_DECODERS.bibtex (str)

Parse the contents of a BibTeX file.

Requires:

Only returns a list of mappings of the literal ‘id’ to CSL item IDs if run with Pandoc < v2.17.

Parameters:

str string The contents of a BibTeX file.

Returns:

{tab,...}

Or

nil nil if the contents could not be parsed.
string An error message.

BIBLIO_DECODERS.json (str)

Parse a CSL JSON string.

Parameters:

str string A CSL JSON string.

Returns:

{tab,...}

Or

nil nil if the string could not be parsed.
string An error message.

BIBLIO_DECODERS.yaml (str)

Parse a CSL YAML string.

Caveats:

Converts formatting to Markdown, not Zotero pseudo-HTML.

Parameters:

str string A CSL YAML string.

Returns:

{tab,...}

Or

nil nil if the string could not be parsed.
string An error message.

BIBLIO_DECODERS.yml

Alternative suffix for YAML files.

BIBLIO_ENCODERS

A case-insensitive mapping of filename suffices to encoders.

BIBLIO_ENCODERS.bib (items)

Serialise a list of CSL items to a BibLaTeX string.

Requires:

Pandoc ≥ 2.17.

Parameters:

items {tab,...} CSL items.

Returns:

Or

nil nil if the items could not be serialised.
string An error message.

BIBLIO_ENCODERS.bibtex (items)

Serialise a list of CSL items to a BibTeX string.

Requires:

Pandoc ≥ 2.17.

Parameters:

items {tab,...} CSL items.

Returns:

Or

nil nil if the items could not be serialised.
string An error message.

BIBLIO_ENCODERS.json (items)

Serialise a list of CSL items to a JSON string.

Parameters:

items {tab,...} CSL items.

Returns:

Or

nil nil if the items could not be serialised.
string An error message.

BIBLIO_ENCODERS.yaml (items)

Serialise a list of CSL items to a YAML string.

Parameters:

items {tab,...} CSL items.

Returns:

Or

nil nil if the items could not be serialised.
string An error message.

BIBLIO_ENCODERS.yml

Alternative suffix for YAML files.

biblio_read (fname)

Read a bibliography file.

The filename suffix determines the file’s format. BIBLIO_DECODERS must contain a matching decoder.

Parameters:

fname string A filename.

Returns:

Values

Or

nil nil if an error occurred.
string An error message.
optional int An error number.

biblio_write (fname[, items])

Write bibliographic data to a bibliography file.

The filename suffix determines the file’s format. BIBLIO_ENCODERS must contain a matching encoder.

If no CSL items are given, tests whether data can be serialised in the given format without chaging the file.

Caveats:

file_write

Parameters:

fname string A filename.
items tab CSL items. (optional)

Returns:

Or

nil nil if an error occurred.
string An error message.
optional int An error number.

biblio_update (handle, fname, ckeys)

Add new items from Zotero to a bibliography file.

Caveats:

file_write

Side-effects:

May print error messages to STDERR.

Parameters:

handle connectors.Zotxt or connectors.ZoteroWeb A Zotero handle.
fname string The name of the bibliography file.
ckeys {string,...} The citation keys of the items to add (e.g., {'doe:2020word'}).

Returns:

bool

true

Or

nil nil if an error occurrs.
string An error message.
optional int An error number if the error is a file I/O error.

Raises:

See connectors.Zotxt and connectors.ZoteroWeb.

Document parsing

elem_clone (elem)

Make a shallow copy of a Pandoc AST element.

Parameters:

elem pandoc.AstElement A Pandoc AST element.

Returns:

pandoc.AstElement

elem_type (elem)

Get the type of a Pandoc AST element.

Parameters:

elem pandoc.AstElement A Pandoc AST element.

Returns:

string A type (e.g., ‘Str’).
string or nil A super-type (e.g., ‘Block’ or ‘Meta’).
string or nil ⋮.

Or

nil nil if the given value is not a Pandoc AST element.
string An error message.

elem_walk (elem, filter)

Walk an AST and apply a filter to matching elements.

Differs from Pandoc’s walkers by:

walking AST elements of any type (inluding documents and metadata),
walking the AST bottom-up,
not accepting the traverse keyword,
applying the filter to the given element itself,
allowing functions in the filter to return data of arbitrary types,
never modifying the original element, and
accepting ‘AstElement’ as type that matches any element.

Parameters:

elem pandoc.AstElement A Pandoc AST element.
filter {string=func,...} A filter.

Returns:

Typically but not necessarily, a new Pandoc AST element.

doc_srcs (doc)

Collect bibliographic data.

Reads the references metadata field and every bibliography file.

Parameters:

doc pandoc.Pandoc A document.

Returns:

{tab,...}

Or

nil nil if an error occurred.
string An error message.

doc_ckeys (doc[, undef])

Collect the citation keys used in a document.

Parameters:

doc pandoc.Pandoc A document.
undef bool Collect only undefind citation keys? (optional)

Returns:

{string,...} Citation keys.
int The number of citation keys found.

Or

nil nil if an error occurred.
string An error message.

Option parsing

Option

An option definition

Caveats:

This table exists in documentation only.

Fields:

name string An option name.
type string A type to coerce the option’s value to. (default 'string')
parse func A parser. (optional)
prefix string A prefix. (optional)

Prototype:

Values

Parameters:

... Option Options.

Parameters:

... Option Options.

Usage:

parser = Options()
parser:add{
    name = 'bar',
    type = 'number',
    parse = function (x)
        if x < 1 return return nil, 'not a positive number.' end
        return x
    end
}

Options:parse (meta)

Read configuration options from a metadata block.

Parameters:

meta pandoc.MetaMap A metadata block.

Returns:

tab

Or

nil nil if an error occurred.
string An error message.

Usage:

> meta = pandoc.MetaMap{
>     ['foo-bar'] = pandoc.MetaInlines(pandoc.List{
>         pandoc.Str "0123"
>     })
> parser = Options()
> parser:add{
>     name = 'bar',
>     type = 'number',
>     parse = function (x)
>         if x < 1 return return nil, 'not a positive number.' end
>         return x
>     end
> }
> opts = parser:parse(meta)
> opts.bars
123
> type(opts.bar)
number

opts_parse (meta, ...)

Read configuration options from a metadata block.

Mapping of option names to metadata fieldnames:

The name of the metadata field that is looked up by Options:parse 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 one of three types:

‘number’
‘string’
‘list’

If you declare an option to be of the scalar types ‘number’ or ‘string’, its value is required to be of the Lua type of the same name. Values are converted automatically if possible.

If you declare an option to be of the type ‘list’, its value is required to be a pandoc.List. If a scalar is encountered where a list was expected, the value is wrapped in a single-item list.

The items of a list must all be of the same type, which you declare by appending ‘<T>’ to the literal ‘list’, where T is either the name of a scalar type or another list declaration and defaults to ‘string’.

In Extended Backus-Naur Form:

Scalar = ( ‘number’ | ‘string’ )

List = ‘list’, [ ‘<’, ( scalar | list ), ‘>’ ]

No type checks or conversions are performed for nil.

Parse protocol:

A parser is a function that takes the converted value and returns a new one or nil and an error message.

Parsers are not called for nil.

Parameters:

meta pandoc.MetaMap A metadata block.
... Option Options.

Returns:

tab

Usage:

> meta = pandoc.MetaMap{
>     ['foo-bar'] = pandoc.MetaInlines(pandoc.List{
>         pandoc.Str "0123"
>     })
> opts = opts_parse(meta, {
>     name = 'bar',
>     type = 'number',
>     parse = function (x)
>         if x < 1 return return nil, 'not a positive number.' end
>         return x
>     end
> })
> opts.bars
123
> type(opts.bar)
number

Zotero connectors

connectors

A case-insensitive namespace for connector prototypes.

Connector protocol:

A connector prototype must provide two methods:

new: Called to create handles. Must have the same function signature as Object:new and return nil and an error message if the handle cannot be created.
fetch: Called to fetch bibliographc data. Must take a citation key and return either a CSL item or nil and an error message.

Connector prototypes may register configuration settings by providing an options property that points to an Options object. That object’s Options:parse method is then called with the document’s metadata block as argument and whatever it returns is passed on to new.

connectors.Zotxt

Interface to zotxt.

Prototype:

connectors.Zotxt.citekey_types

Usage:

handle = connectors.Zotxt()
item = handle:fetch 'DoeWord2020'

connectors.Zotxt.options

Zotero options.

Defines zotero-citekey-types. See the manual for details.

Prototype:

Options

connectors.Zotxt.citekey_types

Types of citation keys to expect.

List of strings. For example, {'betterbibtexkey', 'easykey'}.

Fields:

betterbibtexkey Better BibTeX citation key
easykey zotxt easy citekey
key Zotero item ID

connectors.Zotxt:fetch (ckey)

Fetch a CSL item via zotxt.

Side-effects:

Parameters:

ckey string A citation key (e.g., 'doe:2020word', 'DoeWord2020').

Returns:

Or

nil nil if an error occurred.
string An error message.

Raises:

See http_get.

connectors.ZoteroWeb

Interface to Zotero’s Web API

Prototype:

connectors.Zotxt

Uninitialised properties:

api_key string A Zotero Web API key. (optional)
user_id number A Zotero user ID. (optional)
groups {number,...} Zotero groups to search in. (optional)
public_groups {number,...} Public Zotero groups to search in. (optional)

Usage:

handle = connectors.ZoteroWeb{api_key = 'a0Bc1De2Fg3Hi4Jk5Lm6No7'}
item = handle:fetch 'DoeWord2020'

connectors.ZoteroWeb.citekey_types

Types of citation keys to expect.

See connectors.Zotxt.citekey_types for details and citekey_terms for caveats.

connectors.ZoteroWeb.options

Zotero Web API options.

Defines:

zotero-api-key
zotero-user-id
zotero-groups
zotero-public-groups

See the manual for details.

Prototype:

connectors.Zotxt.options

connectors.ZoteroWeb.mt

Metatable for Zotero Web API connectors.

connectors.ZoteroWeb.mt.getters

Getters for Zotero Web API connectors.

Parameters:

obj connectors.ZoteroWeb A Zotero Web API handle.

Returns:

Raises:

An error if

the api_key field is not set.
the Zotero Web API could not be reached (see http_get for details),
the API’s response cannot be parsed, or
no user ID could be found for the given Zotero API key.

connectors.ZoteroWeb.mt.getters.groups (obj)

Get the groups the user is a member of.

Parameters:

obj connectors.ZoteroWeb A Zotero Web API handle.

Returns:

Raises:

An error if

the api_key field is not set.
the Zotero Web API could not be reached (see http_get for details), or
the API’s response cannot be parsed.

connectors.ZoteroWeb.clone ()

Delegate to the Zotero Web API interface.

Parameters:

ep string An endpoint URL.
params {string=string,...} Request parameters.

Returns:

Or

nil nil if an error occurred.
string An error message.

Raises:

See http_get.

Parameters:

id string A Zotero item ID. (optional)

Returns:

func

stateful

connectors.ZoteroWeb:search (...)

Search items by their author, publication year, and title.

Caveats:

not

Parameters:

... string Search terms.

Returns:

tab

Or

nil nil if no items were found or an error occurred.
string An error message.
An error message.

Raises:

See connectors.ZoteroWeb.mt.getters.user_id and connectors.ZoteroWeb.mt.getters.groups.

connectors.ZoteroWeb:lookup (id)

Look up a CSL item by its Zotero ID.

Parameters:

id string A Zotero item ID.

Returns:

tab

Or

nil nil if no or more than one item has been found.
string An error message.

Raises:

See connectors.ZoteroWeb.mt.getters.user_id and connectors.ZoteroWeb.mt.getters.groups.

connectors.ZoteroWeb:fetch (ckey)

Fetch a CSL item from the Zotero Web API.

Side-effects:

Search terms for citation keys are printed to STDERR if the user has requested verbose output.

Parameters:

ckey string A citation key (e.g., 'doe:2020word', 'DoeWord2020').

Returns:

Or

nil nil if an error occurred.
string An error message.

Raises:

See connectors.ZoteroWeb.mt.getters.user_id and connectors.ZoteroWeb.mt.getters.groups.

Main

add_biblio (fname, handle, doc)

Add bibliographic data to a bibliography file.

Updates the bibliography file as needed and adds its to the bibliography metadata field. Interpretes relative filenames as relative to the directory of the first input file passed to pandoc, or, if no input files were given, as relative to the current working directory.

Caveats:

file_write

Side-effects:

May print error messages to STDERR.

Parameters:

fname string A filename for the bibliography file.
handle connectors.Zotxt or connectors.ZoteroWeb A Zotero handle.
doc pandoc.Pandoc A Pandoc document.

Returns:

pandoc.Meta

Or

nil nil if nothing was done or an error occurred.
string An error message, if applicable.

Raises:

See connectors.Zotxt and connectors.ZoteroWeb.

add_refs (handle, doc)

Add bibliographic data to the references metadata field.

Side-effects:

May print error messages to STDERR.

Parameters:

handle connectors.Zotxt or connectors.ZoteroWeb A Zotero handle.
doc pandoc.Pandoc A Pandoc document.

Returns: