@@ -1,9 +1,9 @@
11---
2−title: Pandoc Lua Filters
32author:
43- Albert Krewinkel
54- John MacFarlane
65date: 'December 6, 2017'
6+title: Pandoc Lua Filters
77---
88
99# Introduction
@@ -37,7 +37,7 @@ JSON to stdout and reading it from stdin.
3737Here is an example of a lua filter that converts strong emphasis
3838to small caps:
3939
40−``` lua
40+``` {.lua}
4141return {
4242 {
4343 Strong = function (elem)
@@ -49,7 +49,7 @@ return {
4949
5050or equivalently,
5151
52−``` lua
52+``` {.lua}
5353function Strong(elem)
5454 return pandoc.SmallCaps(elem.c)
5555end
@@ -88,10 +88,10 @@ then it would be applied like this:
8888
8989 pandoc --lua-filter=current-date.lua -f markdown MANUAL.txt
9090
91−The `--lua-filter` option may be supplied multiple times. Pandoc
91+The `--lua-filter` option may be supplied multiple times. Pandoc
9292applies all filters (including JSON filters specified via
93−`--filter` and lua filters specified via `--lua-filter`)
94−in the order they appear on the command line.
93+`--filter` and lua filters specified via `--lua-filter`) in the
94+order they appear on the command line.
9595
9696Pandoc expects each lua file to return a list of filters. The
9797filters in that list are called sequentially, each on the result
@@ -132,8 +132,8 @@ function. Two fallback functions are supported, `Inline` and
132132
133133Elements without matching functions are left untouched.
134134
135−See [module documentation](#module-pandoc) for a list of
136−pandoc elements.
135+See [module documentation](#module-pandoc) for a list of pandoc
136+elements.
137137
138138The global `FORMAT` is set to the format of the pandoc writer
139139being used (`html5`, `latex`, etc.), so the behavior of a filter
@@ -165,18 +165,18 @@ those elements accessible through the filter function parameter.
165165
166166Some pandoc functions have been made available in lua:
167167
168−- [`walk_block`](#walk_block) and [`walk_inline`](#walk_inline)
169− allow filters to be applied inside specific block or inline
170− elements;
171−- [`read`](#read) allows filters to parse strings into pandoc
172− documents;
173−- [`pipe`](#pipe) runs an external command with input from and
174− output to strings;
175−- the [`pandoc.mediabag`](#module-pandoc.mediabag) module allows
176− access to the "mediabag," which stores binary content such as
177− images that may be included in the final document;
178−- the [`pandoc.utils`](#module-pandoc.utils) module contains
179− various utility functions.
168+- [`walk_block`](#walk_block) and
169+ [`walk_inline`](#walk_inline) allow filters to be applied
170+ inside specific block or inline elements;
171+- [`read`](#read) allows filters to parse strings into pandoc
172+ documents;
173+- [`pipe`](#pipe) runs an external command with input from and
174+ output to strings;
175+- the [`pandoc.mediabag`](#module-pandoc.mediabag) module
176+ allows access to the "mediabag," which stores binary content
177+ such as images that may be included in the final document;
178+- the [`pandoc.utils`](#module-pandoc.utils) module contains
179+ various utility functions.
180180
181181# Lua interpreter initialization
182182
@@ -185,7 +185,7 @@ placing a file `init.lua` in pandoc's data directory. The
185185default init file loads the `pandoc` and `pandoc.mediabag`
186186modules:
187187
188−``` lua
188+``` {.lua}
189189pandoc = require 'pandoc'
190190pandoc.mediabag = require 'pandoc.mediabag'
191191```
@@ -196,7 +196,7 @@ adds all unicode-aware functions defined in the [`text`
196196module](#module-text) to the default `string` module, prefixed
197197with the string `uc_`.
198198
199−```lua
199+``` {.lua}
200200for name, fn in pairs(require 'text') do
201201 string['uc_' .. name] = fn
202202end
@@ -205,7 +205,6 @@ end
205205This makes it possible to apply these functions on strings using
206206colon syntax (`mystring:uc_upper()`).
207207
208−
209208# Examples
210209
211210## Macro substitution.
@@ -213,7 +212,7 @@ colon syntax (`mystring:uc_upper()`).
213212The following filter converts the string `{{helloworld}}` into
214213emphasized text "Hello, World".
215214
216−``` lua
215+``` {.lua}
217216return {
218217 {
219218 Str = function (elem)
@@ -233,7 +232,7 @@ This filter causes metadata defined in an external file
233232(`metadata-file.yaml`) to be used as default values in a
234233document's metadata:
235234
236−``` lua
235+``` {.lua}
237236-- read metadata file into string
238237local metafile = io.open('metadata-file.yaml', 'r')
239238local content = metafile:read("*a")
@@ -260,7 +259,7 @@ return {
260259This filter sets the date in the document's metadata to the
261260current date:
262261
263−``` lua
262+``` {.lua}
264263function Meta(m)
265264 m.date = os.date("%B %e, %Y")
266265 return m
@@ -272,7 +271,7 @@ end
272271This filter prints a table of all the URLs linked to in the
273272document, together with the number of links to that URL.
274273
275−``` lua
274+``` {.lua}
276275links = {}
277276
278277function Link (el)
@@ -313,7 +312,7 @@ Passing information from a higher level (e.g., metadata) to a
313312lower level (e.g., inlines) is still possible by using two
314313filters living in the same file:
315314
316−``` lua
315+``` {.lua}
317316local vars = {}
318317
319318function get_vars (meta)
@@ -368,13 +367,12 @@ will output:
368367
369368## Modifying pandoc's `MANUAL.txt` for man pages
370369
371−This is the filter we use when converting `MANUAL.txt`
372−to man pages. It converts level-1 headers to uppercase
373−(using `walk_block` to transform inline elements
374−inside headers), removes footnotes, and replaces links
375−with regular text.
370+This is the filter we use when converting `MANUAL.txt` to man
371+pages. It converts level-1 headers to uppercase (using
372+`walk_block` to transform inline elements inside headers),
373+removes footnotes, and replaces links with regular text.
376374
377−``` lua
375+``` {.lua}
378376-- we use preloaded text to get a UTF-8 aware 'upper' function
379377local text = require('text')
380378
@@ -398,13 +396,13 @@ end
398396
399397## Creating a handout from a paper
400398
401−This filter extracts all the numbered examples, section
402−headers, block quotes, and figures from a document, in addition
403−to any divs with class `handout`. (Note that only blocks
404−at the "outer level" are included; this ignores blocks inside
405−nested constructs, like list items.)
399+This filter extracts all the numbered examples, section headers,
400+block quotes, and figures from a document, in addition to any
401+divs with class `handout`. (Note that only blocks at the "outer
402+level" are included; this ignores blocks inside nested
403+constructs, like list items.)
406404
407−``` lua
405+``` {.lua}
408406-- creates a handout from an article, using its headings,
409407-- blockquotes, numbered examples, figures, and any
410408-- Divs with class "handout"
@@ -427,14 +425,13 @@ end
427425## Counting words in a document
428426
429427This filter counts the words in the body of a document (omitting
430−metadata like titles and abstracts), including words in code.
431−It should be more accurate than `wc -w` run directly on a
432−Markdown document, since the latter will count markup
433−characters, like the `#` in front of an ATX header, or
434−tags in HTML documents, as words. To run it,
435−`pandoc --lua-filter wordcount.lua myfile.md`.
436−
437−``` lua
428+metadata like titles and abstracts), including words in code. It
429+should be more accurate than `wc -w` run directly on a Markdown
430+document, since the latter will count markup characters, like
431+the `#` in front of an ATX header, or tags in HTML documents, as
432+words. To run it, `pandoc --lua-filter wordcount.lua myfile.md`.
433+
434+``` {.lua}
438435-- counts words in a document
439436
440437words = 0
@@ -468,18 +465,18 @@ end
468465
469466## Converting ABC code to music notation
470467
471−This filter replaces code blocks with class `abc` with
472−images created by running their contents through `abcm2ps`
473−and ImageMagick's `convert`. (For more on ABC notation, see
468+This filter replaces code blocks with class `abc` with images
469+created by running their contents through `abcm2ps` and
470+ImageMagick's `convert`. (For more on ABC notation, see
474471<http://abcnotation.com>.)
475472
476−Images are added to the mediabag. For output to binary
477−formats, pandoc will use images in the mediabag. For textual
478−formats, use `--extract-media` to specify a directory where
479−the files in the mediabag will be written, or (for HTML only)
480−use `--self-contained`.
473+Images are added to the mediabag. For output to binary formats,
474+pandoc will use images in the mediabag. For textual formats, use
475+`--extract-media` to specify a directory where the files in the
476+mediabag will be written, or (for HTML only) use
477+`--self-contained`.
481478
482−``` lua
479+``` {.lua}
483480-- Pandoc filter to process code blocks with class "abc" containing
484481-- ABC notation into images.
485482--
@@ -511,18 +508,17 @@ end
511508
512509## Building images with tikz
513510
514−This filter converts raw LaTeX tikz environments into images.
515−It works with both PDF and HTML output. The tikz code is
516−compiled to an image using `pdflatex`, and the image is
517−converted (if necessary) from pdf to png format using
518−ImageMagick's `convert`, so both of these must be in the system
519−path. Converted images are cached in the working directory
520−and given filenames based on a hash of the source, so that
521−they need not be regenerated each time the document is built.
522−(A more sophisticated version of this might put these in a special
523−cache directory.)
524−
525−```lua
511+This filter converts raw LaTeX tikz environments into images. It
512+works with both PDF and HTML output. The tikz code is compiled
513+to an image using `pdflatex`, and the image is converted (if
514+necessary) from pdf to png format using ImageMagick's `convert`,
515+so both of these must be in the system path. Converted images
516+are cached in the working directory and given filenames based on
517+a hash of the source, so that they need not be regenerated each
518+time the document is built. (A more sophisticated version of
519+this might put these in a special cache directory.)
520+
521+``` {.lua}
526522local function tikz2image(src, filetype, outfile)
527523 local tmp = os.tmpname()
528524 local tmpdir = string.match(tmp, "^(.*[\\/])") or "."
@@ -572,33 +568,31 @@ end
572568
573569Example of use:
574570
575−```
576−pandoc --lua-filter tikz.lua -s -o cycle.html <<EOF
577−Here is a diagram of the cycle:
571+ pandoc --lua-filter tikz.lua -s -o cycle.html <<EOF
572+ Here is a diagram of the cycle:
578573
579−\begin{tikzpicture}
574+ \begin{tikzpicture}
580575
581−\def \n {5}
582−\def \radius {3cm}
583−\def \margin {8} % margin in angles, depends on the radius
576+ \def \n {5}
577+ \def \radius {3cm}
578+ \def \margin {8} % margin in angles, depends on the radius
584579
585−\foreach \s in {1,...,\n}
586−{
587− \node[draw, circle] at ({360/\n * (\s - 1)}:\radius) {$\s$};
588− \draw[->, >=latex] ({360/\n * (\s - 1)+\margin}:\radius)
589− arc ({360/\n * (\s - 1)+\margin}:{360/\n * (\s)-\margin}:\radius);
590−}
591−\end{tikzpicture}
592−EOF
593−```
580+ \foreach \s in {1,...,\n}
581+ {
582+ \node[draw, circle] at ({360/\n * (\s - 1)}:\radius) {$\s$};
583+ \draw[->, >=latex] ({360/\n * (\s - 1)+\margin}:\radius)
584+ arc ({360/\n * (\s - 1)+\margin}:{360/\n * (\s)-\margin}:\radius);
585+ }
586+ \end{tikzpicture}
587+ EOF
594588
595589# Module text
596590
597591UTF-8 aware text manipulation functions, implemented in Haskell.
598−These are available to any lua filter. However, the module must
592+These are available to any lua filter. However, the module must
599593be explicitly loaded:
600594
601−```lua
595+``` {.lua}
602596-- uppercase all regular text in a document:
603597text = require 'text'
604598function Str (s)
@@ -628,7 +622,6 @@ end
628622: Returns a substring of a UTF-8 string, using lua's string
629623 indexing rules.
630624
631−
632625# Module pandoc
633626
634627Lua functions for pandoc scripts.
@@ -740,7 +733,7 @@ Lua functions for pandoc scripts.
740733 `content`:
741734 : list of items
742735
743− Returns: block quote element
736+ Returns: bullet list element
744737
745738[`CodeBlock (text[, attr])`]{#CodeBlock}
746739
@@ -766,7 +759,7 @@ Lua functions for pandoc scripts.
766759 `content`:
767760 : list of items
768761
769− Returns: block quote element
762+ Returns: definition list element
770763
771764[`Div (content[, attr])`]{#Div}
772765
@@ -780,11 +773,11 @@ Lua functions for pandoc scripts.
780773 `attr`:
781774 : element attributes
782775
783− Returns: code block element
776+ Returns: div element
784777
785778[`Header (level, content[, attr])`]{#Header}
786779
787−: Creates a block quote element.
780+: Creates a header element.
788781
789782 Parameters:
790783
@@ -814,7 +807,7 @@ Lua functions for pandoc scripts.
814807 `content`:
815808 : inline content
816809
817− Returns: block quote element
810+ Returns: line block element
818811
819812[`Null ()`]{#Null}
820813
@@ -834,7 +827,7 @@ Lua functions for pandoc scripts.
834827 `listAttributes`:
835828 : list parameters
836829
837− Returns:
830+ Returns: ordered list element
838831
839832[`Para (content)`]{#Para}
840833
@@ -845,7 +838,7 @@ Lua functions for pandoc scripts.
845838 `content`:
846839 : inline content
847840
848− Returns: block quote element
841+ Returns: paragraph element
849842
850843[`Plain (content)`]{#Plain}
851844
@@ -856,7 +849,7 @@ Lua functions for pandoc scripts.
856849 `content`:
857850 : inline content
858851
859− Returns: block quote element
852+ Returns: plain element
860853
861854[`RawBlock (format, text)`]{#RawBlock}
862855
@@ -870,7 +863,7 @@ Lua functions for pandoc scripts.
870863 `text`:
871864 : string content
872865
873− Returns: block quote element
866+ Returns: raw block element
874867
875868[`Table (caption, aligns, widths, headers, rows)`]{#Table}
876869
@@ -893,7 +886,7 @@ Lua functions for pandoc scripts.
893886 `rows`:
894887 : table rows
895888
896− Returns: block quote element
889+ Returns: table element
897890
898891## Inline
899892
@@ -1181,6 +1174,16 @@ Lua functions for pandoc scripts.
11811174
11821175## Helpers
11831176
1177+[`apairs (value)`]{#apairs}
1178+
1179+: Return an iterator which returns key-value pairs of an
1180+ associative list.
1181+
1182+ Parameters:
1183+
1184+ `value`:
1185+ : },\...} alist associative list
1186+
11841187[`Attr ([identifier[, classes[, attributes]]])`]{#Attr}
11851188
11861189: Create a new set of attributes (Attr).
@@ -1334,61 +1337,6 @@ Lua functions for pandoc scripts.
13341337
13351338## Helper Functions
13361339
1337−[`walk_block (element, filter)`]{#walk_block}
1338−
1339−: Apply a filter inside a block element, walking its
1340− contents.
1341−
1342− Parameters:
1343−
1344− `element`:
1345− : the block element
1346−
1347− `filter`:
1348− : a lua filter (table of functions) to be applied
1349− within the block element
1350−
1351− Returns: the transformed block element
1352−
1353−[`walk_inline (element, filter)`]{#walk_inline}
1354−
1355−: Apply a filter inside an inline element, walking its
1356− contents.
1357−
1358− Parameters:
1359−
1360− `element`:
1361− : the inline element
1362−
1363− `filter`:
1364− : a lua filter (table of functions) to be applied
1365− within the inline element
1366−
1367− Returns: the transformed inline element
1368−
1369−[`read (markup[, format])`]{#read}
1370−
1371−: Parse the given string into a Pandoc document.
1372−
1373− Parameters:
1374−
1375− `markup`:
1376− : the markup to be parsed
1377−
1378− `format`:
1379− : format specification, defaults to \"markdown\".
1380−
1381− Returns: pandoc document
1382−
1383− Usage:
1384−
1385− local org_markup = "/emphasis/" -- Input to be read
1386− local document = pandoc.read(org_markup, "org")
1387− -- Get the first block of the document
1388− local block = document.blocks[1]
1389− -- The inline element in that block is an `Emph`
1390− assert(block.content[1].t == "Emph")
1391−
13921340[`global_filter ()`]{#global_filter}
13931341
13941342: Use functions defined in the global namespace to create a
@@ -1399,35 +1347,14 @@ Lua functions for pandoc scripts.
13991347 Usage:
14001348
14011349 -- within a file defining a pandoc filter:
1402− local text = require('text')
14031350 function Str(text)
1404− return pandoc.Str(text.upper(text))
1351+ return pandoc.Str(utf8.upper(text))
14051352 end
14061353
14071354 return {pandoc.global_filter()}
1408− -- the above is equivalent to
1355+ -- the above is equivallent to
14091356 -- return {{Str = Str}}
14101357
1411−[`pipe (command, args, input)`]{#pipe}
1412−
1413−: Runs command with arguments, passing it some input,
1414− and returns the output.
1415−
1416− Returns:
1417−
1418− - Output of command.
1419−
1420− Raises:
1421−
1422− - A table containing the keys `command`, `error_code`, and
1423− `output` is thrown if the command exits with a non-zero
1424− error code.
1425−
1426− Usage:
1427−
1428− local output = pandoc.pipe("sed", {"-e","s/a/b/"}, "abc")
1429−
1430−
14311358# Module pandoc.utils
14321359
14331360This module exposes internal pandoc functions and utility
@@ -1501,7 +1428,7 @@ functions.
15011428
15021429[`to_roman_numeral (integer)`]{#utils-to_roman_numeral}
15031430
1504−: Converts an integer < 4000 to uppercase roman numeral.
1431+: Converts an integer \< 4000 to uppercase roman numeral.
15051432
15061433 Returns:
15071434
@@ -1513,7 +1440,6 @@ functions.
15131440 local pandoc_birth_year = to_roman_numeral(2006)
15141441 -- pandoc_birth_year == 'MMVI'
15151442
1516−
15171443# Module pandoc.mediabag
15181444
15191445The `pandoc.mediabag` module allows accessing pandoc's media
@@ -1583,9 +1509,9 @@ storage. The "media bag" is used when pandoc is called with the
15831509
15841510[`fetch (source, base_url)`]{#mediabag-fetch}
15851511
1586−: Fetches the given source from a URL or local file.
1587− Returns two values: the contents of the file and the mime
1588− type (or an empty string).
1512+: Fetches the given source from a URL or local file. Returns
1513+ two values: the contents of the file and the mime type (or
1514+ an empty string).
15891515
15901516 Returns:
15911517