👨‍💻 about me home CV/Resume 🖊️ Contact Github LinkedIn I’m a Haskeller 📝 Blog Freedom, privacy, tutorials… 🏆 Best of panda upp Haskell abp pp hCalc bl todo pwd TPG Nextcloud Git BitTorrent

📰 Friday 2. April 2021: upp is a panda companion. It’s is a Lua-scriptable lightweight text preprocessor.
🆕 since December 2020: Playing with the actor model in an embedded multicore context. C imperative components become C stream pure functions with no side effect ➡️ C low level programming with high level pure functional programming properties 🏆
📰 Saturday 30. January 2021: Playing with Pandoc Lua filters in Lua. panda is a lightweight alternative to abp providing a consistent set of Pandoc filters (text substitution, file inclusion, diagragrams, scripts, …).
🆕 Sunday 24. May 2020: Working at EasyMile for more than 4 years. Critical real-time software in C, simulation and monitoring in Haskell ➡️ perfect combo! It’s efficient and funny ;-)
🚌 And we are recruiting! Contact if you are interested in Haskell or embedded softwares (or both).

Panda - Pandoc add-ons (Lua filters for Pandoc)

Christophe Delord - http://cdelord.fr/panda

30th April 2021

About panda

Panda is a Pandoc Lua filter that works on internal Pandoc’s AST.

It provides several interesting features:

Panda is heavily inspired by abp reimplemented as a Pandoc Lua filter.

If you need a more generic text preprocessor, UPP may be a better choice.

Open source

Panda is an Open source software. Anybody can contribute on GitHub to:

Installation

  1. Download the sources: git clone https://github.com/CDSoft/panda.
  2. Run make test to run tests.
  3. Run make install to install panda and panda.lua to ~/.local/bin (see INSTALL_PATH in Makefile).

panda and panda.lua can also be installed anywhere. Nothing else is required (except from Pandoc obviously).

Usage

panda.lua is a Pandoc Lua filter and is not meant to be called directly. panda is just a shell script that calls pandoc -L panda.lua ....

$ pandoc -L panda.lua ...

or

$ panda ...

A complete example is given as a Makefile in the doc directory.

Cheat sheet

Syntactic item Class Attributes Description
any string {{var}} is replaced by the value of var if it is defined (variables can be environment variables or Lua variables)
div block comment commented block
div block include=file replaces the div block with the content of file (rendered according to its format)
div block shift=n adds n to header levels in an imported div block
div block, code block pattern="Lua string pattern" format="output format" applies a Lua string pattern to the content of the file. The emitted text is format. format may contain captures from pattern.
code block meta definitions for the string expansion (Lua script), defined in the code block
any block ifdef=name block emitted only if name is defined
any block ifdef=name value=val block emitted only if name is defined and its value is value
any block ifndef=name block emitted only if name is not defined
code block, inline code include=file replaces the code block content with the content of file
code block, inline code fromline=n includes a file from line number n
code block, inline code toline=n includes a file up to line number n
code block, inline code cmd="shell command" replaces the code block by the result of the shell command
code block render="command" replaces the code block by a link to the image produced by the command (%i is the input file name, its content is the content of the code block, %o is the output file name)
code block img="image path" URL of the image produced by render (optional, the default value is a generated name in the ./.panda directory).
code block out="image path" path of the image produced by render (optional, the default value is img)

Commented blocks

Div blocks with the comment class are commented:

::: comment
This block is a comment and is discarded by panda.
:::

String expansion

panda stores variables in an environment used to expand strings. Variables can be defined by a Lua script with the meta class. The include attribute can also be used to point to an external file. Variables can only contain inline elements, not blocks.

The initial environment contains:

Variable names are enclosed between double curly brackets.

E.g.:

```meta
foo = "bar (note: this is parsed as **Markdown**)"
```

foo is {{foo}}.
```{.meta include=foo.lua}
This text is ignored, definitions are in foo.lua.
```

foo is defined in `foo.lua` and is {{foo}}.

Conditional blocks

Blocks can be conditionally kept or omitted. The condition is described with attributes.

:::{ifdef="name" value="value"}
This block is emitted only if the variable "name" is defined
and its value is "value"
:::
:::{ifdef="name"}
This block is emitted only if the variable "name" is defined
(whatever its value)
:::
:::{ifndef="name"}
This block is emitted only if the variable "name" is **not** defined
:::

Div inclusion

Fragments of documents can be imported from external files. The include attribute contains the name of the file to include. The content of the file is parsed according to its format (deduced from its name) and replaces the div block content.

:::{include=file.md shift=n}
This text is optional and will be replaced by the content of file.md.
Section title levels are shifted by n (0 if not specified).
:::

The included file can be in a different format (e.g. a markdown file can include a reStructuredText file).

Block inclusion

Code examples can be imported from external files. The include attribute contains the name of the file to include. The content of the file replaces the code block content.

```{.c include=foo.c fromline=3 toline=10 pattern="Lua string pattern" format="%1"}
This text is optional and will be replaced by the content of foo.c.
```

The optional fromline and toline defines the first and last lines to be included.

The optional pattern describes the part of the text that will be rendered. The format uses the captures defined by the pattern to format the content of the block ("%1" if not defined).

Scripts

Scripts can be executed by inline or code blocks. The cmd attribute defines the command to execute. The content of the block is in a temporary file which name is added to the command. If the command contains the %s char, it is replaced by the temporary file name. If the command does not contain any %s, the file name is appended to the command. The result replaces the content of the code block.

Source Result
```{.python cmd=python}
print("Hello from Python!")
```
Hello from Python!
Python says `print("Hello from Python!")`{cmd=python}
Python says Hello from Python!

Diagrams

Code blocks containing diagrams are replaced with an image resulting from the diagram source code.

The render command is the render field. The output image can be a hash computed from the diagram source code or the value of the img field. The optional out field overloads img to change the output directory when rendering the diagram.

In the render command, %i is replaced by the name of the input document (generated from the content of the code block) and %o by the name of the output image file (generated from the img field).

The img field is optional. The default value is a name generated in the directory given by the environment variable PANDA_CACHE (.panda if PANDA_CACHE is not defined).

If img contains %h, it is replaced by a hash computed from the diagram source.

The file format (extension) must be in the render field, after the %o tag (e.g.: %o.png), not in the img field.

Source Result
``` { render="{{plantuml}}"
      img="img/panda_plantuml_test"
      out="{{build}}/img" }
@startuml
Alice -> Bob: hello
@enduml
```

Some render commands are predefined:

Diagram Predefined variable Render command
GraphViz dot dot -Tsvg -o %o.svg %i
dot.svg dot -Tsvg -o %o.svg %i
dot.png dot -Tpng -o %o.png %i
dot.pdf dot -Tpdf -o %o.pdf %i
PlantUML plantuml java -jar plantuml.jar -pipe -charset UTF-8 -tsvg < %i > %o.svg
plantuml.svg java -jar plantuml.jar -pipe -charset UTF-8 -tsvg < %i > %o.svg
plantuml.png java -jar plantuml.jar -pipe -charset UTF-8 -tpng < %i > %o.png
plantuml.pdf java -jar plantuml.jar -pipe -charset UTF-8 -tpdf < %i > %o.pdf
Asymptote asy asy -f svg -o %o.svg %i
asy.svg asy -f svg -o %o.svg %i
asy.png asy -f png -o %o.png %i
asy.pdf asy -f pdf -o %o.pdf %i
blockdiag blockdiag blockdiag -a -Tsvg -o %o.svg %i
blockdiag.svg blockdiag -a -Tsvg -o %o.svg %i
blockdiag.png blockdiag -a -Tpng -o %o.png %i
blockdiag.pdf blockdiag -a -Tpdf -o %o.pdf %i
mermaid mmdc mmdc -i %i -o %i
mmdc.svg mmdc -i %i -o %i
mmdc.png mmdc -i %i -o %i
mmdc.pdf mmdc -i %i -o %i
ditaa ditaa java -jar ditaa.jar --svg -o -e UTF-8 %i %o.svg
ditaa.svg java -jar ditaa.jar --svg -o -e UTF-8 %i %o.svg
ditaa.png java -jar ditaa.jar -o -e UTF-8 %i %o.png
gnuplot gnuplot gnuplot -e 'set terminal svg' -e 'set output "%o.svg"' -c %i
gnuplot.svg gnuplot -e 'set terminal svg' -e 'set output "%o.svg"' -c %i
gnuplot.png gnuplot -e 'set terminal png' -e 'set output "%o.png"' -c %i

Notes:

E.g.:

Source Result
```{.dot render="dot -Tsvg -o %o.svg %i"
         img="img/panda_diagram_example"
         out="./img" }
digraph {
    rankdir=LR;
    input -> pandoc -> output
    pandoc -> panda -> {pandoc, diagrams}
    { rank=same; pandoc, panda }
    { rank=same; diagrams, output }
}
```

```{ render="gnuplot -e 'set terminal svg' -e 'set output "%o.svg"' -c %i"
     img="img/panda_gnuplot_example"
     out="./img" }
set xrange [-pi:pi]
set yrange [-1.5:1.5]
plot sin(x) lw 4, cos(x) lw 4
```

Filters can be combined. E.g.: a diagram can be stored in an external file, included and rendered by panda.

Source Result
The file `hello.dot` contains:

```{.dot include="./hello.dot"
         pattern="digraph%s*%b{}" }
```

The file hello.dot contains:

digraph {
    rankdir=LR;
    Hello -> World;
}
and is rendered as:

```{ render="dot -Tsvg -o %o.svg %i"
     img="img/hello"
     out="./img"
     include="./hello.dot" }
```

and is rendered as:

Makefile dependencies

It is sometimes useful to build a dependency list on the fly. panda can generate a dependency list for make, in the same vein than the gcc -M option. The environment variable PANDA_TARGET must be defined with the target name. panda will generate a file named ${PANDA_TARGET}.d containing the dependencies of ${PANDA_TARGET}.

E.g.:

PANDA_TARGET=index.html panda index.md -o index.html

This will produce a file named index.html.d containing index.html: ....

Licenses

Panda

Panda is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

Panda is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with Panda.  If not, see <https://www.gnu.org/licenses/>.

For further information about Panda you can visit
http://cdelord.fr/panda

Feedback

Your feedback and contributions are welcome. You can contact me at cdelord.fr.