From fa643ba6d78fd97f0a779840dca32bfea3b296f8 Mon Sep 17 00:00:00 2001 From: Albert Krewinkel Date: Mon, 6 Dec 2021 16:55:19 +0100 Subject: Lua: update to latest pandoc-lua-marshal (0.1.1) - `walk` methods are added to `Block` and `Inline` values; the methods are similar to `pandoc.utils.walk_block` and `pandoc.utils.walk_inline`, but apply to filter also to the element itself, and therefore return a list of element instead of a single element. - Functions of name `Doc` are no longer accepted as alternatives for `Pandoc` filter functions. This functionality was undocumented. --- doc/lua-filters.md | 181 +++++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 176 insertions(+), 5 deletions(-) (limited to 'doc') diff --git a/doc/lua-filters.md b/doc/lua-filters.md index ac682a90d..fb13f4915 100644 --- a/doc/lua-filters.md +++ b/doc/lua-filters.md @@ -523,8 +523,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 @@ -532,10 +533,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 @@ -611,7 +613,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 @@ -793,6 +795,35 @@ determined via [`pandoc.utils.equals`]. `meta` : document meta information ([Meta] object) + +### walk {#type-pandoc:walk} + +`walk(self, lua_filter)` + +Applies a Lua filter to the Pandoc element. Just as for +full-document filters, the order in which elements are handled +are Inline → Inlines → Block → Blocks → Meta → Pandoc. + +Parameters: + +`self` +: the element ([Pandoc](#type-pandoc)) + +`lua_filter` +: map of filter functions (table) + +Result: + +- filtered document ([Pandoc][]) + +Usage: + + -- returns `pandoc.Pandoc{pandoc.Para{pandoc.Str 'Bye'}}` + return pandoc.Pandoc{pandoc.Para('Hi')}:walk { + Str = function (_) return 'Bye' end, + } + + ## Meta {#type-meta} Meta information on a document; string-indexed collection of @@ -834,6 +865,40 @@ or `pandoc.Blocks`. Object equality is determined via [`pandoc.utils.equals`]. +### Common Methods + +#### walk {#type-block:walk} + +`walk(self, lua_filter)` + +Applies a Lua filter to the block element. Just as for +full-document filters, the order in which elements are handled +are Inline → Inlines → Block → Blocks. + +Note that the filter is applied to the subtree, but not to the +element itself. The rationale is that the element might be +deleted by the filter, leading to possibly unexpected results. + +Parameters: + +`self` +: the element ([Block](#type-block)) + +`lua_filter` +: map of filter functions (table) + +Result: + +- filtered block ([Block][]) + +Usage: + + -- returns `pandoc.Para{pandoc.Str 'Bye'}` + return pandoc.Para('Hi'):walk { + Str = function (_) return 'Bye' end, + } + + ### BlockQuote {#type-blockquote} A block quote element. @@ -1141,11 +1206,80 @@ into Blocks wherever a value of this type is expected: 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 handled +are are Inline → Inlines → Block → Blocks. The filter is applied +to all list items *and* to the list itself. + +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 by checking the Haskell representation for equality. +### 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 handled +are are Inline → Inlines → Block → Blocks. + +Note that the filter is applied to the subtree, but *not* to the +element itself. The rationale is that the element might be +deleted by the filter, leading 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} Citation. @@ -1526,6 +1660,43 @@ into Blocks wherever a value of this type is expected: 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 -- cgit v1.2.3