git.iko.soy/typeable/pandoc
on master help sign in
docs/lua-filters.md: clarify filter function execution order (#6059)
467ea4eAlbert Krewinkel
doc/lua-filters.md+30−2
compare with master
unifiedsplit
@@ -2,7 +2,7 @@
2author:
2author:
3- Albert Krewinkel
3- Albert Krewinkel
4- John MacFarlane
4- John MacFarlane
5−date: 'December 6, 2017'
5+date: 'January 10, 2020'
6title: Pandoc Lua Filters
6title: Pandoc Lua Filters
7---
7---
8
8
@@ -28,7 +28,7 @@ in JSON form. One cannot simply provide a filter that can be
28used by anyone who has a certain version of the pandoc
28used by anyone who has a certain version of the pandoc
29executable.
29executable.
30
30
31−Starting with pandoc 2.0, we have made it possible to write
31+Starting with version 2.0, pandoc makes it possible to write
32filters in lua without any external dependencies at all. A lua
32filters in lua without any external dependencies at all. A lua
33interpreter (version 5.3) and a lua library for creating pandoc
33interpreter (version 5.3) and a lua library for creating pandoc
34filters is built into the pandoc executable. Pandoc data types
34filters is built into the pandoc executable. Pandoc data types
@@ -136,6 +136,34 @@ Elements without matching functions are left untouched.
136See [module documentation](#module-pandoc) for a list of pandoc
136See [module documentation](#module-pandoc) for a list of pandoc
137elements.
137elements.
138
138
139+## Execution order
140+
141+Element filter functions within a filter set are called in a
142+fixed order, skipping any which are not present:
143+
144+ 1. functions for [*Inline* elements](#type-ref-Inline),
145+ 2. functions for [*Block* elements](#type-ref-Block) ,
146+ 3. the [*Meta*](#type-ref-Meta) filter function, and last
147+ 4. the [*Pandoc*](#type-ref-Meta) filter function.
148+
149+It is still possible to force a different order by explicitly
150+returning multiple filter sets. For example, if the filter for
151+*Meta* is to be run before that for *Str*, one can write
152+
153+``` lua
154+-- ... filter definitions ...
155+
156+return {
157+ { Meta = Meta }, -- (1)
158+ { Str = Str } -- (2)
159+}
160+```
161+
162+Filter sets are applied in the order in which they are returned.
163+All functions in set (1) are thus run before those in (2),
164+causing the filter function for *Meta* to be run before the
165+filtering of *Str* elements is started.
166+
139## Global variables
167## Global variables
140
168
141Pandoc passes additional data to Lua filters by setting global
169Pandoc passes additional data to Lua filters by setting global