Module tpl 

TeX templating

The tpl module contains a way of constructing a TeX-document programmatically. It ensures documents are well-formed syntactically, but not semantically (e.g. it is possible to express documents that contain multiple \documentclass macro calls inside the document but not a \begin{foo} without a matching \end).

As a result of this deliberate limitation, the API is fairly simple. The core module offers the entire abstraction through the TexElement trait, while the elements module contains syntactic sugar for building documents quickly.

“Hello, world” using TexElement directly.

use texrender::tpl::{Args, BeginEndBlock, Group, IntoTexElement, MacroCall, OptArgs, RawTex,
                     TexElement, Text};

let doctype = MacroCall::new("documentclass",
                             OptArgs::single("12pt"),
                             Args::single("article"));
let mut contents: Vec<Box<dyn TexElement>> = Vec::new();
contents.push(Box::new(MacroCall::new("section",
                       Default::default(),
                       Args::single("Hello, world"))));
contents.push("This is fun & easy.".into_tex_element());
let document = BeginEndBlock::new("document", Default::default(), Default::default(), contents);
let tex = Group::new(vec![Box::new(doctype) as Box<dyn TexElement>, Box::new(document)]);
let output = tex.render().expect("rendering failed");
assert_eq!(output,
           "\\documentclass[12pt]{article}\n\
            \\begin{document}\n\
            \\section{Hello, world}\n\
            This is fun \\& easy.\n\
            \\end{document}\n");

While this form uses no macros, it is rather inconvenient to write. Luckily there is an alternative:

“Hello, world” using elements and macros.

use texrender::elems;
use texrender::tpl::TexElement;
use texrender::tpl::elements::{N, doc, document, documentclass, section};

let tex = doc(elems!(
    documentclass(elems!(), "article"),
    document(elems!(
        section("Hello, world"),
        "This is fun & easy."
    ))
));

let output = tex.render().expect("rendering failed");

assert_eq!(output,
           "\\documentclass{article}\n\
            \\begin{document}\n\
            \\section{Hello, world}\n\
            This is fun \\& easy.\n\
            \\end{document}\n");

Element functions like section above typically cover most use cases, while not preventing the u ser to drop back to the raw functions above. The elems macro conveniently boxes and type-erases children, while N can be used for “no arguments” for both args and optargs.

Modules

elements

Predefined LaTeX elements.

macros

Macros used for tex templating.

Structs

AnonymousBlock

An anonymous block.

Args

A set of arguments.

BeginEndBlock

A block with a begin and end instruction.

Group

Grouping of elements.

MacroCall

A TeX-macro invocation.

OptArgs

A set of optional arguments.

RawTex

A raw, unescaped piece of tex code.

TableRow

Table row.

Text

A text string.

Traits

IntoTexElement

Conversion trait for various types.

TexElement

Renderable Tex element.

Functions

write_list

Writes a list of tex elements to a stream with a separator.