diff options
Diffstat (limited to 'doc/lua-filters.md')
| -rw-r--r-- | doc/lua-filters.md | 743 |
1 files changed, 634 insertions, 109 deletions
diff --git a/doc/lua-filters.md b/doc/lua-filters.md index e2a65fe1e..eba4dcfe9 100644 --- a/doc/lua-filters.md +++ b/doc/lua-filters.md @@ -109,7 +109,8 @@ element filtering function. In other words, filter entries will be called for each corresponding element in the document, getting the respective element as input. -The return of a filter function must be one of the following: +The return value of a filter function must be one of the +following: - nil: this means that the object should remain unchanged. - a pandoc object: this must be of the same type as the input @@ -173,7 +174,26 @@ This functionality has been added in pandoc 2.9.2. [Inlines filter example]: #remove-spaces-before-citations -## Execution Order +## Traversal order + +The traversal order of filters can be selected by setting the key +`traverse` to either `'topdown'` or `'typewise'`; the default is +`'typewise'`. + +Example: + +``` lua +local filter = { + traverse = 'topdown', + -- ... filter functions ... +} +return {filter} +``` + +Support for this was added in pandoc 2.16.3; previous versions +ignore the `traverse` setting. + +### Typewise traversal Element filter functions within a filter set are called in a fixed order, skipping any which are not present: @@ -203,6 +223,31 @@ All functions in set (1) are thus run before those in (2), causing the filter function for *Meta* to be run before the filtering of *Str* elements is started. +### Topdown traversal + +It is sometimes more natural to traverse the document tree +depth-first from the root towards the leaves, and all in a single +run. + +For example, a block list `[Plain [Str "a"], Para [Str +"b"]]`{.haskell} will try the following filter functions, in +order: `Blocks`, `Plain`, `Inlines`, `Str`, `Para`, `Inlines`, +`Str`. + +Topdown traversals can be cut short by returning `false` as a +second value from the filter function. No child-element of +the returned element is processed in that case. + +For example, to exclude the contents of a footnote from being +processed, one might write + +``` lua +traverse = 'topdown' +function Note (n) + return n, false +end +``` + ## Global variables Pandoc passes additional data to Lua filters by setting global @@ -245,6 +290,38 @@ variables. variable is of type [CommonState] and is read-only. +`pandoc` +: The *pandoc* module, described in the next section, is + available through the global `pandoc`. The other modules + described herein are loaded as subfields under their + respective name. + +`lpeg` +: This variable holds the `lpeg` module, a package based on + Parsing Expression Grammars (PEG). It provides excellent + parsing utilities and is documented on the official [LPeg + homepage]. Pandoc uses a built-int version of the library, + unless it has been configured by the package maintainer to + rely on a system-wide installation. + + Note that the result of `require 'lpeg'` is not necessarily + equal to this value; the `require` mechanism prefers the + system's lpeg library over the built-in version. + +`re` +: Contains the LPeg.re module, which is built on top of LPeg + and offers an implementation of a [regex engine]. Pandoc + uses a built-in version of the library, unless it has been + configured by the package maintainer to rely on a system-wide + installation. + + Note that the result of `require 're` is not necessarily + equal to this value; the `require` mechanism prefers the + system's lpeg library over the built-in version. + +[LPeg homepage]: http://www.inf.puc-rio.br/~roberto/lpeg/ +[regex engine]: http://www.inf.puc-rio.br/~roberto/lpeg/re.html + # Pandoc Module The `pandoc` Lua module is loaded into the filter's Lua @@ -491,8 +568,9 @@ will output: This is the filter we use when converting `MANUAL.txt` to man pages. It converts level-1 headers to uppercase (using -`walk_block` to transform inline elements inside headers), -removes footnotes, and replaces links with regular text. +[`walk`](#type-block:walk) to transform inline elements inside +headers), removes footnotes, and replaces links with regular +text. ``` lua -- we use preloaded text to get a UTF-8 aware 'upper' function @@ -500,10 +578,11 @@ local text = require('text') function Header(el) if el.level == 1 then - return pandoc.walk_block(el, { + return el:walk { Str = function(el) return pandoc.Str(text.upper(el.text)) - end }) + end + } end end @@ -579,7 +658,7 @@ wordcount = { function Pandoc(el) -- skip metadata, just count body: - pandoc.walk_block(pandoc.Div(el.blocks), wordcount) + el.blocks:walk(wordcount) print(words .. " words in body") os.exit(0) end @@ -695,12 +774,12 @@ end function RawBlock(el) if starts_with('\\begin{tikzpicture}', el.text) then local filetype = extension_for[FORMAT] or 'svg' - local fname = system.get_working_directory() .. '/' .. - pandoc.sha1(el.text) .. '.' .. filetype + local fbasename = pandoc.sha1(el.text) .. '.' .. filetype + local fname = system.get_working_directory() .. '/' .. fbasename if not file_exists(fname) then tikz2image(el.text, filetype, fname) end - return pandoc.Para({pandoc.Image({}, fname)}) + return pandoc.Para({pandoc.Image({}, fbasename)}) else return el end @@ -752,8 +831,8 @@ Usage: Pandoc document Values of this type can be created with the -[`pandoc.Pandoc`](#pandoc.pandoc) constructor. Object equality is -determined via [`pandoc.utils.equals`]. +[`pandoc.Pandoc`](#pandoc.pandoc) constructor. Pandoc values are +equal in Lua if and only if they are equal in Haskell. `blocks` : document content ([List] of [Blocks]) @@ -761,83 +840,113 @@ determined via [`pandoc.utils.equals`]. `meta` : document meta information ([Meta] object) -## Meta {#type-meta} -Meta information on a document; string-indexed collection of -[MetaValues]. +### walk {#type-pandoc:walk} -Values of this type can be created with the -[`pandoc.Meta`](#pandoc.meta) constructor. Object equality is -determined via [`pandoc.utils.equals`]. +`walk(self, lua_filter)` -## MetaValue {#type-metavalue} +Applies a Lua filter to the Pandoc element. Just as for +full-document filters, the order in which elements are traversed +can be controlled by setting the `traverse` field of the filter; +see the section on [traversal order][Traversal order]. -Document meta information items. +Parameters: -Object equality is determined via [`pandoc.utils.equals`]. +`self` +: the element ([Pandoc](#type-pandoc)) -### MetaBlocks {#type-metablocks} +`lua_filter` +: map of filter functions (table) -A list of blocks usable as meta value ([List] of [Blocks]). +Result: -Fields: +- filtered document ([Pandoc][]) -`tag`, `t` -: the literal `MetaBlocks` (string) +Usage: -### MetaBool {#type-metabool} + -- returns `pandoc.Pandoc{pandoc.Para{pandoc.Str 'Bye'}}` + return pandoc.Pandoc{pandoc.Para('Hi')}:walk { + Str = function (_) return 'Bye' end, + } -Alias for Lua boolean, i.e. the values `true` and `false`. -### MetaInlines {#type-metainlines} +## Meta {#type-meta} -List of inlines used in metadata ([List] of [Inlines]) +Meta information on a document; string-indexed collection of +[MetaValues]. Values of this type can be created with the -[`pandoc.MetaInlines`](#pandoc.metainlines) constructor. +[`pandoc.Meta`](#pandoc.meta) constructor. Meta values are equal +in Lua if and only if they are equal in Haskell. -Fields: - -`tag`, `t` -: the literal `MetaInlines` (string) +## MetaValue {#type-metavalue} -### MetaList {#type-metalist} +Document meta information items. This is not a separate type, but +describes a set of types that can be used in places were a +MetaValue is expected. The types correspond to the following +Haskell type constructors: + +- boolean → MetaBool +- string or number → MetaString +- Inlines → MetaInlines +- Blocks → MetaBlocks +- List/integer indexed table → MetaList +- string-indexed table → MetaMap + +The corresponding constructors +[`pandoc.MetaBool`](#pandoc.metabool), +[`pandoc.MetaString`](#pandoc.metastring), +[`pandoc.MetaInlines`](#pandoc.metainlines), +[`pandoc.MetaBlocks`](#pandoc.metablocks), +[`pandoc.MetaList`](#pandoc.metalist), and +[`pandoc.MetaMap`](#pandoc.metamap) +can be used to ensure that a value is treated in the intended +way. E.g., an empty table is normally treated as a `MetaMap`, but +can be made into an empty `MetaList` by calling +`pandoc.MetaList{}`. However, the same can be accomplished by +using the generic functions like `pandoc.List`, `pandoc.Inlines`, +or `pandoc.Blocks`. -A list of other metadata values ([List] of [MetaValues]). +## Block {#type-block} -Values of this type can be created with the -[`pandoc.MetaList`](#pandoc.metalist) constructor. +Block values are equal in Lua if and only if they are equal in +Haskell. -Fields: +### Common methods -`tag`, `t` -: the literal `MetaList` (string) +#### walk {#type-block:walk} -All methods available for [List]s can be used on this type as -well. +`walk(self, lua_filter)` -### MetaMap {#type-metamap} +Applies a Lua filter to the block element. Just as for +full-document filters, the order in which elements are traversed +can be controlled by setting the `traverse` field of the filter; +see the section on [traversal order][Traversal order]. -A string-indexed map of meta-values. (table). +Note that the filter is applied to the subtree, but not to the +`self` block element. The rationale is that otherwise the element +could be deleted by the filter, or replaced with multiple block +elements, which might lead to possibly unexpected results. -Values of this type can be created with the -[`pandoc.MetaMap`](#pandoc.metamap) constructor. +Parameters: -Fields: +`self` +: the element ([Block](#type-block)) -`tag`, `t` -: the literal `MetaMap` (string) +`lua_filter` +: map of filter functions (table) -*Note*: The fields will be shadowed if the map contains a field -with the same name as those listed. +Result: -### MetaString {#type-metastring} +- filtered block ([Block][]) -Plain Lua string value (string). +Usage: -## Block {#type-block} + -- returns `pandoc.Para{pandoc.Str 'Bye'}` + return pandoc.Para('Hi'):walk { + Str = function (_) return 'Bye' end, + } -Object equality is determined via [`pandoc.utils.equals`]. ### BlockQuote {#type-blockquote} @@ -1133,9 +1242,94 @@ left-aligned, right-aligned, and centered, respectively. The default alignment is `AlignDefault` (often equivalent to centered). +## Blocks {#type-blocks} + +List of [Block] elements, with the same methods as a generic +[List](#type-list). It is usually not necessary to create values +of this type in user scripts, as pandoc can convert other types +into Blocks wherever a value of this type is expected: + +- a list of [Block] (or Block-like) values is used directly; +- a single [Inlines] value is wrapped into a [Plain] element; +- string values are turned into an [Inlines] value by splitting + the string into words (see [Inlines](#type-inlines)), and + then wrapping the result into a Plain singleton. + +### Methods + +Lists of type `Blocks` share all methods available in generic +lists, see the [`pandoc.List` module](#module-pandoc.list). + +Additionally, the following methods are available on Blocks +values: + +#### walk {#type-blocks:walk} + +`walk(self, lua_filter)` + +Applies a Lua filter to the Blocks list. Just as for +full-document filters, the order in which elements are traversed +can be controlled by setting the `traverse` field of the filter; +see the section on [traversal order][Traversal order]. + +Parameters: + +`self` +: the list ([Blocks](#type-blocks)) + +`lua_filter` +: map of filter functions (table) + +Result: + +- filtered list ([Blocks](#type-blocks)) + +Usage: + + -- returns `pandoc.Blocks{pandoc.Para('Salve!')}` + return pandoc.Blocks{pandoc.Plain('Salve!)}:walk { + Plain = function (p) return pandoc.Para(p.content) end, + } + ## Inline {#type-inline} -Object equality is determined via [`pandoc.utils.equals`]. +Inline values are equal in Lua if and only if they are equal in +Haskell. + +### Common methods + +#### walk {#type-inline:walk} + +`walk(self, lua_filter)` + +Applies a Lua filter to the Inline element. Just as for +full-document filters, the order in which elements are traversed +can be controlled by setting the `traverse` field of the filter; +see the section on [traversal order][Traversal order]. + +Note that the filter is applied to the subtree, but not to the +`self` inline element. The rationale is that otherwise the +element could be deleted by the filter, or replaced with multiple +inline elements, which might lead to possibly unexpected results. + +Parameters: + +`self` +: the element ([Inline](#type-inline)) + +`lua_filter` +: map of filter functions (table) + +Result: + +- filtered inline element ([Inline][]) + +Usage: + + -- returns `pandoc.SmallCaps('SPQR)` + return pandoc.SmallCaps('spqr'):walk { + Str = function (s) return string.upper(s.text) end, + } ### Cite {#type-cite} @@ -1206,9 +1400,6 @@ Values of this type can be created with the Fields: -`attr` -: attributes ([Attr]) - `caption` : text used to describe the image ([List] of [Inlines]) @@ -1216,7 +1407,10 @@ Fields: : path to the image file (string) `title` -: brief image description +: brief image description (string) + +`attr` +: attributes ([Attr]) `identifier` : alias for `attr.identifier` (string) @@ -1503,6 +1697,57 @@ Fields: `tag`, `t` : the literal `Underline` (string) +## Inlines {#type-inlines} + +List of [Inline] elements, with the same methods as a generic +[List](#type-list). It is usually not necessary to create values +of this type in user scripts, as pandoc can convert other types +into Blocks wherever a value of this type is expected: + +- lists of [Inline] (or Inline-like) values are used directly; +- single [Inline] values are converted into a list containing + just that element; +- String values are split into words, converting line breaks + into [SoftBreak](#type-softbreak) elements, and other + whitespace characters into [Spaces](#type-space). + +### Methods + +Lists of type `Inlines` share all methods available in generic +lists, see the [`pandoc.List` module](#module-pandoc.list). + +Additionally, the following methods are available on *Inlines* +values: + +#### walk {#type-inlines:walk} + +`walk(self, lua_filter)` + +Applies a Lua filter to the Inlines list. Just as for +full-document filters, the order in which elements are handled +are are Inline → Inlines → Block → Blocks. The filter is applied +to all list items *and* to the list itself. + +Parameters: + +`self` +: the list ([Inlines](#type-inlines)) + +`lua_filter` +: map of filter functions (table) + +Result: + +- filtered list ([Inlines](#type-inlines)) + +Usage: + + -- returns `pandoc.Inlines{pandoc.SmallCaps('SPQR')}` + return pandoc.Inlines{pandoc.Emph('spqr')}:walk { + Str = function (s) return string.upper(s.text) end, + Emph = function (e) return pandoc.SmallCaps(e.content) end, + } + ## Element components @@ -1522,7 +1767,8 @@ This also works when using the `attr` setter: local span = pandoc.Span 'text' span.attr = {id = 'text', class = 'a b', other_attribute = '1'} -Object equality is determined via [`pandoc.utils.equals`]. +Attr values are equal in Lua if and only if they are equal in +Haskell. Fields: @@ -1540,6 +1786,9 @@ Fields: List of key/value pairs. Values can be accessed by using keys as indices to the list table. +Attributes values are equal in Lua if and only if they are equal +in Haskell. + ### Caption {#type-caption} The caption of a table, with an optional short caption. @@ -1568,12 +1817,21 @@ Fields: : cell contents (list of [Blocks]). `col_span` -: number of columns occupied by the cell; the height of the cell - (integer). +: number of columns spanned by the cell; the width of the cell + in columns (integer). `row_span` -: number of rows occupied by the cell; the height of the cell - (integer). +: number of rows spanned by the cell; the height of the cell in + rows (integer). + +`identifier` +: alias for `attr.identifier` (string) + +`classes` +: alias for `attr.classes` ([List] of strings) + +`attributes` +: alias for `attr.attributes` ([Attributes]) ### Citation {#type-citation} @@ -1582,7 +1840,8 @@ Single citation entry Values of this type can be created with the [`pandoc.Citation`](#pandoc.citation) constructor. -Object equality is determined via [`pandoc.utils.equals`]. +Citation values are equal in Lua if and only if they are equal in +Haskell. Fields: @@ -1610,7 +1869,8 @@ Fields: Column alignment and width specification for a single table column. -This is a pair with the following components: +This is a pair, i.e., a plain table, with the following +components: 1. cell alignment ([Alignment]). 2. table column width, as a fraction of the total table width @@ -1623,8 +1883,6 @@ List attributes Values of this type can be created with the [`pandoc.ListAttributes`](#pandoc.listattributes) constructor. -Object equality is determined via [`pandoc.utils.equals`]. - Fields: `start` @@ -1643,10 +1901,13 @@ Fields: A table row. -Tuple fields: +Fields: -1. row attributes -2. row cells (list of [Cells]) +`attr` +: element attributes ([Attr][]) + +`cells` +: list of table cells ([List][] of [Cell][]s) ### TableBody {#type-tablebody} @@ -1656,35 +1917,59 @@ number of row header columns. Fields: `attr` -: table body attributes ([Attr]) +: table body attributes ([Attr][]) `body` -: table body rows (list of [Rows]) +: table body rows ([List][] of [Row][]s) `head` -: intermediate head (list of [Rows]) +: intermediate head ([List][] of [Row][]s) `row_head_columns` : number of columns taken up by the row head of each row of a - [TableBody]. The row body takes up the remaining columns. + [TableBody][]. The row body takes up the remaining columns. ### TableFoot {#type-tablefoot} The foot of a table. -This is a pair with the following components: +Fields: -1. attributes -2. foot rows ([Rows]) +`attr` +: element attributes ([Attr][]) + +`rows` +: list of rows ([List][] of [Row][]s) + +`identifier` +: alias for `attr.identifier` (string) + +`classes` +: alias for `attr.classes` ([List][] of strings) + +`attributes` +: alias for `attr.attributes` ([Attributes][]) ### TableHead {#type-tablehead} The head of a table. -This is a pair with the following components: +Fields: + +`attr` +: element attributes ([Attr][]) + +`rows` +: list of rows ([List][] of [Row][]s) + +`identifier` +: alias for `attr.identifier` (string) + +`classes` +: alias for `attr.classes` ([List][] of strings) -1. attributes -2. head rows ([Rows]) +`attributes` +: alias for `attr.attributes` ([Attributes][]) ## ReaderOptions {#type-readeroptions} @@ -1836,7 +2121,7 @@ Values of this type can be created with the `must_be_at_least(actual, expected [, error_message])` Raise an error message if the actual version is older than the -expected version; does nothing if actual is equal to or newer +expected version; does nothing if `actual` is equal to or newer than the expected version. Parameters: @@ -1867,6 +2152,7 @@ Usage: [Block]: #type-block [Blocks]: #type-block [Caption]: #type-caption +[Cell]: #type-cell [Cells]: #type-cell [Citation]: #type-citation [Citations]: #type-citation @@ -1884,6 +2170,8 @@ Usage: [LogMessage]: #type-logmessage [Pandoc]: #type-pandoc [Para]: #type-para +[Plain]: #type-plain +[Row]: #type-row [Rows]: #type-row [SimpleTable]: #type-simpletable [Table]: #type-table @@ -1891,7 +2179,6 @@ Usage: [TableFoot]: #type-tablefoot [TableHead]: #type-tablehead [Version]: #type-version -[`pandoc.utils.equals`]: #pandoc.utils.equals # Module text @@ -1978,71 +2265,83 @@ format, and functions to filter and modify a subtree. [`MetaBlocks (blocks)`]{#pandoc.metablocks} -: Meta blocks +: Creates a value to be used as a MetaBlocks value in meta + data; creates a copy of the input list via `pandoc.Blocks`, + discarding all non-list keys. Parameters: `blocks`: : blocks - Returns: [MetaBlocks] object + Returns: [Blocks](#type-blocks) [`MetaInlines (inlines)`]{#pandoc.metainlines} -: Meta inlines +: Creates a value to be used as a MetaInlines value in meta + data; creates a copy of the input list via `pandoc.Inlines`, + discarding all non-list keys. Parameters: `inlines`: : inlines - Returns: [MetaInlines] object + Returns: [Inlines](#types-inlines) [`MetaList (meta_values)`]{#pandoc.metalist} -: Meta list +: Creates a value to be used as a MetaList in meta data; + creates a copy of the input list via `pandoc.List`, + discarding all non-list keys. Parameters: `meta_values`: : list of meta values - Returns: [MetaList] object + Returns: [List] [`MetaMap (key_value_map)`]{#pandoc.metamap} -: Meta map +: Creates a value to be used as a MetaMap in meta data; creates + a copy of the input table, keeping only pairs with string + keys and discards all other keys. Parameters: `key_value_map`: : a string-indexed map of meta values - Returns: [MetaMap] object + Returns: table [`MetaString (str)`]{#pandoc.metastring} -: Creates string to be used in meta data. +: Creates a value to be used as a MetaString in meta data; this + is the identity function for boolean values and exists only + for completeness. Parameters: `str`: : string value - Returns: [MetaString] object + Returns: string [`MetaBool (bool)`]{#pandoc.metabool} -: Creates boolean to be used in meta data. +: Creates a value to be used as MetaBool in meta data; this is + the identity function for boolean values and exists only for + completeness. Parameters: `bool`: : boolean value - Returns: [MetaBool] object + Returns: boolean -## Blocks +## Block [`BlockQuote (content)`]{#pandoc.blockquote} @@ -2222,6 +2521,20 @@ format, and functions to filter and modify a subtree. Returns: [Table](#type-table) object +## Blocks + +[`Blocks (block_like_elements)`]{#pandoc.blocks} + +: Creates a [Blocks](#type-blocks) list. + + Parameters: + + `block_like_elements`: + : List where each element can be treated as a [Block] + value, or a single such value. + + Returns: [Blocks] list + ## Inline [`Cite (content, citations)`]{#pandoc.cite} @@ -2511,6 +2824,27 @@ format, and functions to filter and modify a subtree. Returns: [Underline](#type-underline) object +## Inlines + +[`Inlines (inline_like_elements)`]{#pandoc.inlines} + +: Converts its argument into an [Inlines](#type-inlines) list: + + - copies a list of [Inline] elements into a fresh list; any + string `s` within the list is treated as `pandoc.Str(s)`; + - turns a single [Inline] into a singleton list; + - splits a string into `Str`-wrapped words, treating + interword spaces as `Space`s or `SoftBreak`s. + + Parameters: + + `inline_like_elements`: + : List where each element can be treated as an [Inline] + values, or just a single such value. + + Returns: [Inlines] list + + ## Element components [`Attr ([identifier[, classes[, attributes]]])`]{#pandoc.attr} @@ -2530,6 +2864,33 @@ format, and functions to filter and modify a subtree. Returns: [Attr](#type-attr) object +[`Cell (blocks[, align[, rowspan[, colspan[, attr]]]])`]{#pandoc.attr} + +: Create a new table cell. + + Parameters: + + `blocks`: + : cell contents (list of [Blocks]) + + `align`: + : text alignment; defaults to `AlignDefault` (Alignment) + + `rowspan`: + : number of rows occupied by the cell; defaults to `1` + (integer) + + `colspan`: + : number of columns spanned by the cell; defaults to `1` + (integer) + + `attr`: + : cell attributes ([Attr](#type-attr)) + + Returns: + + - [Cell](#type-cell) object + [`Citation (id, mode[, prefix[, suffix[, note_num[, hash]]]])`]{#pandoc.citation} : Creates a single citation. @@ -2573,6 +2934,42 @@ format, and functions to filter and modify a subtree. Returns: [ListAttributes](#type-listattributes) object +[`Row ([cells[, attr]])`]{#pandoc.row} + +: Creates a table row. + + Parameters: + + `cells`: + : list of table cells in this row + + `attr`: + : row attributes + +[`TableFoot ([rows[, attr]])`]{#pandoc.tablefoot} + +: Creates a table foot. + + Parameters: + + `rows`: + : list of table rows + + `attr`: + : table foot attributes + +[`TableHead ([rows[, attr]])`]{#pandoc.tablehead} + +: Creates a table head. + + Parameters: + + `rows`: + : list of table rows + + `attr`: + : table head attributes + ## Legacy types [`SimpleTable (caption, aligns, widths, headers, rows)`]{#pandoc.simpletable} @@ -2732,7 +3129,33 @@ format, and functions to filter and modify a subtree. [`sha1`]{#pandoc.sha1} : Alias for [`pandoc.utils.sha1`](#pandoc.utils.sha1) - (DEPRECATED). + (DEPRECATED, use `pandoc.utils.sha1` instead). + +## Other constructors + +[`ReaderOptions (opts)`]{#pandoc.readeroptions} + +: Creates a new [ReaderOptions] value. + + Parameters + + `opts`: + : Either a table with a subset of the properties of a + [ReaderOptions] object, or another ReaderOptions object. + Uses the defaults specified in the manual for all + properties that are not explicitly specified. Throws an + error if a table contains properties which are not present + in a ReaderOptions object. ([ReaderOptions]|table) + + Returns: new [ReaderOptions] object + + Usage: + + -- copy of the reader options that were defined on the command line. + local cli_opts = pandoc.ReaderOptions(PANDOC_READER_OPTIONS) + + -- default reader options, but columns set to 66. + local short_colums_opts = pandoc.ReaderOptions {columns = 66} ## Helper functions @@ -2805,17 +3228,23 @@ Returns: the transformed inline element ### read {#pandoc.read} -`read (markup[, format])` +`read (markup[, format[, reader_options]])` Parse the given string into a Pandoc document. Parameters: `markup`: -: the markup to be parsed +: the markup to be parsed (string) `format`: -: format specification, defaults to `"markdown"`. +: format specification, defaults to `"markdown"` (string) + +`reader_options`: +: options passed to the reader; may be a ReaderOptions object or + a table with a subset of the keys and values of a + ReaderOptions object; defaults to the default values + documented in the manual. ([ReaderOptions]|table) Returns: pandoc document @@ -2828,6 +3257,8 @@ Usage: -- The inline element in that block is an `Emph` assert(block.content[1].t == "Emph") +[ReaderOptions]: #type-readeroptions + # Module pandoc.utils This module exposes internal pandoc functions and utility @@ -2882,12 +3313,13 @@ Test equality of AST elements. Elements in Lua are considered equal if and only if the objects obtained by unmarshaling are equal. +**This function is deprecated.** Use the normal Lua `==` equality +operator instead. + Parameters: `element1`, `element2`: -: Objects to be compared. Acceptable input types are [Pandoc], - [Meta], [MetaValue], [Block], [Inline], [Attr], - [ListAttributes], and [Citation]. +: Objects to be compared (any type) Returns: @@ -2927,9 +3359,21 @@ non-null, `Header` levels will be reorganized so that there are no gaps, and so that the base level is the level specified. +Parameters: + +`number_sections` +: whether section divs should get an additional `number` + attribute containing the section number. (boolean) + +`base_level` +: shift top-level headings to this level. (integer|nil) + +`blocks` +: list of blocks to process ([Blocks](#type-blocks)) + Returns: -- List of [Blocks](#type-block). +- [Blocks](#type-blocks). Usage: @@ -2939,6 +3383,38 @@ Usage: } local newblocks = pandoc.utils.make_sections(true, 1, blocks) +### references {#pandoc.references} + +`references (doc)` + +Get references defined inline in the metadata and via an external +bibliography. Only references that are actually cited in the +document (either with a genuine citation or with `nocite`) are +returned. URL variables are converted to links. + +The structure used represent reference values corresponds to that +used in CSL JSON; the return value can be use as `references` +metadata, which is one of the values used by pandoc and citeproc +when generating bibliographies. + +Parameters: + +`doc`: +: document ([Pandoc](#type-pandoc)) + +Returns: + +- list of references. (table) + +Usage: + + -- Include all cited references in document + function Pandoc (doc) + doc.meta.references = pandoc.utils.references(doc) + doc.meta.bibliography = nil + return doc + end + ### run\_json\_filter {#pandoc.utils.run_json_filter} `run_json_filter (doc, filter[, args])` @@ -3050,6 +3526,39 @@ Usage: -- create normal table block again table = pandoc.utils.from_simple_table(simple) +### type {#pandoc.utils.type} + +`type (value)` + +Pandoc-friendly version of Lua's default `type` function, +returning the type of a value. This function works with all types +listed in section [Lua type reference][], except if noted +otherwise. + +The function works by checking the metafield `__name`. If the +argument has a string-valued metafield `__name`, then it returns +that string. Otherwise it behaves just like the normal `type` +function. + +Parameters: + +`value` +: any Lua value + +Returns: + +- type of the given value (string) + +Usage: + + -- Prints one of 'string', 'boolean', 'Inlines', 'Blocks', + -- 'table', and 'nil', corresponding to the Haskell constructors + -- MetaString, MetaBool, MetaInlines, MetaBlocks, MetaMap, + -- and an unset value, respectively. + function Meta (meta) + print('type of metavalue `author`:', pandoc.utils.type(meta.author)) + end + # Module pandoc.mediabag The `pandoc.mediabag` module allows accessing pandoc's media @@ -3230,6 +3739,22 @@ methods and convenience functions. Returns: a new list containing all elements from list1 and list2 +[`pandoc.List:__eq (a, b)`]{#pandoc.list:__concat} + +: Compares two lists for equality. The lists are taken as equal + if and only if they are of the same type (i.e., have the same + non-nil metatable), have the same length, and if all elements + are equal. + + Parameters: + + `a`, `b`: + : any Lua object + + Returns: + + - `true` if the two lists are equal, `false` otherwise. + ## Methods [`pandoc.List:clone ()`]{#pandoc.list:clone} @@ -3442,7 +3967,7 @@ filepath Returns: -- `true` iff `filepath` is an absolute path, `false` otherwise. +- `true` if `filepath` is an absolute path, `false` otherwise. (boolean) ### is_relative (filepath) {#pandoc.path.is_relative} @@ -3456,7 +3981,7 @@ filepath Returns: -- `true` iff `filepath` is a relative path, `false` otherwise. +- `true` if `filepath` is a relative path, `false` otherwise. (boolean) ### join (filepaths) {#pandoc.path.join} |