Literate Programming

Agda supports a limited form of literate programming, i.e. code interspersed with prose, if the corresponding filename extension is used.

Literate TeX

Files ending in .lagda or .lagda.tex are interpreted as literate TeX files. All code has to appear in code blocks:

  1. Ignored by Agda.
  3. \begin{code}[ignored by Agda]
  4. module Whatever where
  5. -- Agda code goes here
  6. \end{code}

Text outside of code blocks is ignored, as well as text right after \begin{code}, on the same line.

Agda finds code blocks by looking for the first instance of \begin{code} that is not preceded on the same line by % or \ (not counting \ followed by any code point), then (starting on the next line) the first instance of \end{code} that is preceded by nothing but spaces or tab characters (\t), and so on (always starting on the next line). Note that Agda does not try to figure out if, say, the LaTeX code changes the category code of %.

If you provide a suitable definition for the code environment, then literate Agda files can double as LaTeX document sources. Example definition:

  1. \usepackage{fancyvrb}
  3. \DefineVerbatimEnvironment
  4.   {code}{Verbatim}
  5.   {} % Add fancy options here if you like.

The LaTeX backend or the preprocessor lhs2TeX can also be used to produce LaTeX code from literate Agda files. See Known pitfalls and issues for how to make LaTeX accept Agda files using the UTF-8 character encoding.

Literate reStructuredText

Files ending in .lagda.rst are interpreted as literate reStructuredText files. Agda will parse code following a line ending in ::, as long as that line does not start with ..:

  1. This line is ordinary text, which is ignored by Agda.
  3. ::
  5.   module Whatever where
  6.   -- Agda code goes here
  8. Another non-code line.
  9. ::
  10. .. This line is also ignored

reStructuredText source files can be turned into other formats such as HTML or LaTeX using Sphinx.

  • Code blocks inside an rST comment block will be type-checked by Agda, but not rendered.

  • Code blocks delimited by .. code-block:: agda or .. code-block:: lagda will be rendered, but not type-checked by Agda.

  • All lines inside a codeblock must be further indented than the first line of the code block.

  • Indentation must be consistent between code blocks. In other words, the file as a whole must be a valid Agda file if all the literate text is replaced by white space.

Literate Markdown

Files ending in .lagda.md are interpreted as literate Markdown files. Code blocks start with ``` or ```agda on its own line, and end with ``` , also on its own line:

  1. This line is ordinary text, which is ignored by Agda.
  3. ```
  4. module Whatever where
  5. -- Agda code goes here
  6. ```
  8. Here is another code block:
  10. ```agda
  11. data ℕ : Set where
  12.  zero : ℕ
  13.  suc  : ℕ → ℕ
  14. ```

Markdown source files can be turned into many other formats such as HTML or LaTeX using PanDoc.

  • Code blocks which should be type-checked by Agda but should not be visible when the Markdown is rendered may be enclosed in HTML comment delimiters (<!-- and -->).

  • Code blocks which should be ignored by Agda, but rendered in the final document may be indented by four spaces.

  • Note that inline code fragments are not supported due to the difficulty of interpreting their indentation level with respect to the rest of the file.

Literate Org

Files ending in .lagda.org are interpreted as literate Org files. Code blocks are surrounded by two lines including only `#+begin_src agda2` and `#+end_src` (case insensitive).

  1. This line is ordinary text, which is ignored by Agda.
  3. #+begin_src agda2
  4. module Whatever where
  5. -- Agda code goes here
  6. #+end_src
  8. Another non-code line.
  • Code blocks which should be ignored by Agda, but rendered in the final document may be placed in source blocks without the agda2 label.