Struct Template 

pub struct Template { /* private fields */ }

Available on crate feature svg only.

Template for rendering Transcripts, e.g. into an SVG image.

Available templates

When using a template created with Self::new(), a transcript is rendered into SVG with the text content embedded as an HTML fragment. This is because SVG is not good at laying out multiline texts and text backgrounds, while HTML excels at both. As a downside of this approach, the resulting SVG requires for its viewer to support HTML embedding; while web browsers a priori support such embedding, some other SVG viewers may not.

A template created with Self::pure_svg() renders a transcript into pure SVG, in which text is laid out manually. The resulting SVG is supported by more viewers, but it may look incorrectly in certain corner cases.

Snapshot testing functionality produces snapshots using Self::new() (i.e., with HTML embedding); pure SVG templates cannot be tested.

Customization

A custom Handlebars template can be supplied via Self::custom(). This can be used to partially or completely change rendering logic, including the output format (e.g., to render to HTML instead of SVG).

Data supplied to a template is HandlebarsData.

Besides built-in Handlebars helpers (a superset of standard helpers), custom templates have access to the following additional helpers. All the helpers are extensively used by the default template; thus, studying it may be a good place to start customizing. Another example is an HTML template from the crate examples.

Arithmetic operations: add, sub, mul, div

Perform the specified arithmetic operation on the supplied args. add and mul support any number of numeric args; sub and div exactly 2 numeric args.

{{add 2 3 5}}
{{div (len xs) 3}}

Rounding

Rounds the provided value with a configurable number of decimal digits. Also allows specifying the rounding mode: up / ceil, down / floor, or nearest / round (default).

{{round 7.8}} {{! 8 }}
{{round 7.13 digits=1}} {{! 7.1 }}
{{round 7.13 digits=1 mode="up"}} {{! 7.2 }}

Counting lines: count_lines

Counts the number of lines in the supplied string.

{{count_lines test}}

Integer ranges: range

Creates an array with integers in the range specified by the 2 provided integer args. The “from” bound is inclusive, the “to” one is exclusive.

{{#each (range 0 3)}}{{@index}}, {{/each}}
{{! Will output `0, 1, 2,` }}

Variable scope: scope, set

A block helper that creates a scope with variables specified in the options hash. In the block, each variable can be obtained using local variable syntax (e.g., @test). Variables can be set with the set helper:

• If set is called as a block helper, the variable is set to the contents of the block, which is treated as JSON.
• If set is called as a block helper with append=true, then the contents of the block is appended to the var, which must be a string.
• If the set helper is called as an inline helper, it sets values of the listed variables.

{{#scope test=""}}
  {{set test="Hello"}}
  {{@test}} {{! Outputs `Hello` }}
  {{#set "test"}}"{{@test}}, world!"{{/set}}
  {{@test}} {{! Outputs `Hello, world!` }}
{{/scope}}

Examples

use term_transcript::{svg::*, Transcript, UserInput};

let mut transcript = Transcript::new();
transcript.add_interaction(
    UserInput::command("test"),
    "Hello, \u{1b}[32mworld\u{1b}[0m!",
);

let template_options = TemplateOptions {
    palette: NamedPalette::Dracula.into(),
    ..TemplateOptions::default()
}
.validated()?;
let mut buffer = vec![];
Template::new(template_options).render(&transcript, &mut buffer)?;
let buffer = String::from_utf8(buffer)?;
assert!(buffer.contains(r#"Hello, <span class="fg2">world</span>!"#));

Implementations

impl Template

pub fn new(options: ValidTemplateOptions) -> Self

Initializes the default template based on provided options.

pub fn pure_svg(options: ValidTemplateOptions) -> Self

Initializes the pure SVG template based on provided options.

pub fn custom( template: HandlebarsTemplate, options: ValidTemplateOptions, ) -> Self

Initializes a custom template.

pub fn render<W: Write>( &self, transcript: &Transcript, destination: W, ) -> Result<(), RenderError>

Renders the transcript using the template (usually as an SVG image, although custom templates may use a different output format).

Errors

Returns a Handlebars rendering error, if any. Normally, the only errors could be related to I/O (e.g., the output cannot be written to a file).

Trait Implementations

impl Debug for Template

fn fmt(&self, formatter: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for Template

fn default() -> Self

Returns the “default value” for a type.