pandoc-purl

pandoc-purl is Pandoc filter for literate programming and dynamic document generation in Python. It is similar in spirit to Knitr or Pweave.

pandoc-purl can be installed through pip (e.g. python3 -m pip install pandoc-purl), and used like other Pandoc filters, e.g. pandoc --filter pandoc-purl document.md -o document.tex.

Code chunks

pandoc-purl will process code blocks tagged with the python class or inline code tagged with the p or python classes.

Note This README.md file has been generated from the README.in.md using pandoc-purl.

Code blocks

Code blocks marked with the python class will behave as if executed in an interactive Python shell: they execute their content, display the content and, in a following paragraph, display any printed value as well as the value of the last expression (see below for options controlling this behavior).

```python
print("Hello pandoc-purl")
42
```

print("Hello pandoc-purl")
42

Hello pandoc-purl
42

If the last statement is not an expression, the code is still executed and displayed, but no result is printed

```python
a = 3.14
```

a = 3.14

Inline code

Inline code marked with the p or python classes should contain only a single expression, and will display the value of that expression in the text.

The answer is `6*7`{.p}

Chunk options

Options can be passed to code chunks using the key=value syntax. The following options are available:

• eval: whether to run the code chunk (true or false, defaults to true)

  Input	Rendered
  The answer is `6*7`{.p}	The answer is 42
  The answer is `6*7`{.p eval=false}	The answer is 6*7

• echo: whether to show the code (code blocks only, true or false, defaults to true)

  Input	Rendered
  ```python print("Hello pandoc-purl") ```	print("Hello pandoc-purl") Hello pandoc-purl
  ```{.python echo=false} print("Hello pandoc-purl") ```	Hello pandoc-purl

• results: how to show the result of the last expression

  • asis: show the result as a pre-formatted code block or inline (default)
  • markup: process the result through Pandoc before showing it
  • hide: hide the result

  Input	Rendered
  I'm `"**bold**"`{.p}	I’m **bold**
  I'm `"**bold**"`{.p results=markup}	I’m bold

Changing the defaults

The default chunk options can also be changed globally by modifying chunk_defaults in the pandoc_purl module:

```{.python echo=false}
import pandoc_purl
pandoc_purl.chunk_defaults["echo"] = False
```