Contact me

I'm a Haskeller
Twitter  🙋  LinkedIn


News!

Wednesday 22. November 2017: Working at EasyMile for 10 month. Critical real-time software in C, simulation and monitoring in Haskell ➡️ perfect combo! It’s efficient and funny ;-)

Monday 18. July 2016: Updates on my new simulation framework project in Haskell.

Friday 25. March 2016: Dear backers, unfortunately, the FUN project was not successfully funded. I will now focus on FRP (Functional Reactive Programming) applied to real-time critical system specification and simulation.

me CDSoft CV/Resume Haskell Haskell Handy Calc abp pp Lua BonaLuna calculadoira Python TPG Vim todo pwd A.I. tools in Prolog dialog Free Free softwares Essays Oldies

Abstract Processor (for Pandoc)

Christophe Delord - https://cdsoft.fr/abp

30 November 2019

ABP - Abstract preprocessor (for Pandoc)

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

It provides several interesting features:

Open source

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

Installation

  1. Download and extract abp-0.1.2.2.tar.gz.
  2. Run stack init && stack install.
  3. Run stack install pandoc if you need to install Pandoc.

This will install abp and pandoc in ~/.local/bin.

ABP is written in Haskell and is built with Stack.

Usage

abp is a Pandoc filter and is not meant to be called directly.

$ pandoc -F abp ...

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 YAML definitions)
div block comment commented block
any block raw strings are not expanded in this block
code block meta definitions for the string expansion (YAML subset), defined in the code block
code block meta=file definitions for the string expansion (YAML subset), defined in file
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 inline=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
code block out="image path" path of the image produced by render (optional, the default value is img)
CSV tables table see Pandoc csv2table filter

Commented blocks

Div blocks with the comment class are commented:

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

String expansion

abp stores variables in an environment used to expand strings. Variables can be defined by a YAML file (currently a very limited subset of YAML) with the meta class. The meta attribute can also be used to point to an external file. Variables can only contain inline elements, not blocks.

The initial environment contains: - the environment variables - the document metadata (title, author, date) - the output document format (first argument of abp given by pandoc)

Variable names are enclosed between double curly brackets. E.g. {{title}} will be replaced with the document title.

Elements with the raw class won’t be expanded.

E.g.:

```meta
- foo: bar
```

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

foo is defined in `foo.yaml` 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
:::

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}
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.

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 % char, it is replaced by the temporary file name. If the command does not contain any %, 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).

Source Result
```{render="{{plantuml.svg}}" img="img/abp_plantuml_test.svg" out="{{doc}}/img"}
@startuml
Alice -> Bob: hello
@enduml
```

Some render commands are predefined:

Diagram Predefined variable Render command
GraphViz {{dot}} dot -Tsvg -o %o %i
{{dot.svg}} dot -Tsvg -o %o %i
{{dot.png}} dot -Tpng -o %o %i
{{dot.pdf}} dot -Tpdf -o %o %i
PlantUML {{plantuml}} java -jar {{ABP_PLANTUML}} -pipe -charset UTF-8 -tsvg < %i > %o
{{plantuml.svg}} java -jar {{ABP_PLANTUML}} -pipe -charset UTF-8 -tsvg < %i > %o
{{plantuml.png}} java -jar {{ABP_PLANTUML}} -pipe -charset UTF-8 -tpng < %i > %o
{{plantuml.pdf}} java -jar {{ABP_PLANTUML}} -pipe -charset UTF-8 -tpdf < %i > %o
Asymptote {{asy}} asy -f svg -o %o %i
{{asy.svg}} asy -f svg -o %o %i
{{asy.png}} asy -f png -o %o %i
{{asy.pdf}} asy -f pdf -o %o %i
blockdiag {{blockdiag}} blockdiag -a -Tsvg -o %o %i
{{blockdiag.svg}} blockdiag -a -Tsvg -o %o %i
{{blockdiag.png}} blockdiag -a -Tpng -o %o %i
{{blockdiag.pdf}} blockdiag -a -Tpdf -o %o %i

Notes:

E.g.:

Source Result
```{.dot render="{{dot.svg}}" img="img/abp_diagram_example.svg" out="{{doc}}/img" height=128}
digraph {
    rankdir=LR;
    input -> pandoc -> output
    pandoc -> abp -> {pandoc, diagrams}
    { rank=same; pandoc, abp }
    { rank=same; diagrams, output }
}
```

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

Source Result
The file `hello.dot` contains:

```{.dot include="{{doc}}/hello.dot" fromline=21 toline=24}
```

The file hello.dot contains:

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

```{render="{{dot.svg}}" img="img/hello.svg" out="{{doc}}/img" height=48 include="{{doc}}/hello.dot"}
```

and is rendered as:

CSV tables

CSV tables are rendered using the Pandoc csv2table filter. The filter has been included to ABP without any modification.

The table content can be defined in the code block or in an external file.

Source Result
```{.table aligns="LCR" caption="This is the **caption**" header="yes"}
Fruit, Quantity, Price
apples, 15, 3.24
oranges, 12, 2.22
```
This is the caption
Fruit Quantity Price
apples 15 3.24
oranges 12 2.22

Licenses

ABP

ABP 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.

ABP 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 ABP.  If not, see <https://www.gnu.org/licenses/>.

For further information about ABP you can visit
http://cdsoft.fr/abp

PP

Some portions of code are based on PP released under the GPL license version 3.

Pandoc csv2table filter

Pandoc csv2table filter is written by Wasif Hasan Baig and has been released under the MIT license.

Feedback

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