Lua: support topdown traversals

The traversal order of filters can now be selected by setting the key
`traverse` of the filter to either `'topdown'` or `'typewise'`; the
default remains `'typewise'`.

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.

4 files changed, 55 insertions, 4 deletions

diff --git a/cabal.project b/cabal.project
index 99c3a7815..606d8bb48 100644
--- a/cabal.project
+++ b/cabal.project
@@ -3,6 +3,11 @@ tests: True
 flags: +embed_data_files
 constraints: aeson >= 2.0.1.0
 
+source-repository-package
+  type: git
+  location: https://github.com/pandoc/pandoc-lua-marshal
+  tag: 98e3de5087bb533fadbb89720f83f7f7cc3be5bf
+
 -- source-repository-package
 --   type: git
 --   location: https://github.com/jgm/texmath.git
diff --git a/doc/lua-filters.md b/doc/lua-filters.md
index 322833c46..778934e17 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 be 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
diff --git a/pandoc.cabal b/pandoc.cabal
index 69401bc8c..13db955b9 100644
--- a/pandoc.cabal
+++ b/pandoc.cabal
@@ -484,7 +484,7 @@ library
                  mtl                   >= 2.2      && < 2.3,
                  network               >= 2.6,
                  network-uri           >= 2.6      && < 2.8,
-                 pandoc-lua-marshal    >= 0.1.2    && < 0.2,
+                 pandoc-lua-marshal    >= 0.1.3    && < 0.2,
                  pandoc-types          >= 1.22.1   && < 1.23,
                  parsec                >= 3.1      && < 3.2,
                  pretty                >= 1.1      && < 1.2,
diff --git a/stack.yaml b/stack.yaml
index 548931120..30845ad6b 100644
--- a/stack.yaml
+++ b/stack.yaml
@@ -26,7 +26,6 @@ extra-deps:
 - lua-2.0.2
 - tasty-hslua-1.0.0
 - tasty-lua-1.0.0
-- pandoc-lua-marshal-0.1.2
 - pandoc-types-1.22.1
 - commonmark-0.2.1.1
 - commonmark-extensions-0.2.2
@@ -37,6 +36,8 @@ extra-deps:
 - unicode-data-0.2.0
 - git: https://github.com/jgm/ipynb.git
   commit: 00246af10885c2ad4413ace4f69a7e6c88297a08
+- git: https://github.com/pandoc/pandoc-lua-marshal
+  commit: 98e3de5087bb533fadbb89720f83f7f7cc3be5bf
 ghc-options:
    "$locals": -fhide-source-paths -Wno-missing-home-modules
 resolver: lts-18.10