• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1<h1 align="center">TinyTemplate</h1>
2
3<div align="center">Minimal Lightweight Text Templating</div>
4
5<div align="center">
6    <a href="https://docs.rs/tinytemplate/">API Documentation</a>
7    |
8    <a href="https://github.com/bheisler/TinyTemplate/blob/master/CHANGELOG.md">Changelog</a>
9</div>
10
11<div align="center">
12    <a href="https://github.com/bheisler/TinyTemplate/actions">
13        <img src="https://github.com/bheisler/TinyTemplate/workflows/Continuous%20integration/badge.svg" alt="Continuous integration">
14    </a>
15    <a href="https://crates.io/crates/tinytemplate">
16        <img src="https://img.shields.io/crates/v/tinytemplate.svg" alt="Crates.io">
17    </a>
18</div>
19
20TinyTemplate is a small, minimalistic text templating system with limited dependencies.
21
22## Table of Contents
23- [Table of Contents](#table-of-contents)
24  - [Goals](#goals)
25  - [Why TinyTemplate?](#why-tinytemplate)
26  - [Quickstart](#quickstart)
27  - [Compatibility Policy](#compatibility-policy)
28  - [Contributing](#contributing)
29  - [Maintenance](#maintenance)
30  - [License](#license)
31
32### Goals
33
34 The primary design goals are:
35
36 - __Small__: TinyTemplate deliberately does not support many features of more powerful template engines.
37 - __Simple__: TinyTemplate presents a minimal but well-documented user-facing API.
38 - __Lightweight__: TinyTemplate has minimal required dependencies.
39
40Non-goals include:
41
42- __Extensibility__: TinyTemplate supports custom value formatters, but that is all.
43- __Performance__: TinyTemplate provides decent performance, but other template engines are faster.
44
45### Why TinyTemplate?
46
47I created TinyTemplate after noticing that none of the existing template libraries really suited my
48needs for Criterion.rs. Some had large dependency trees to support features that I didn't use. Some
49required adding a build script to convert templates into code at runtime, in search of extreme
50performance that I didn't need. Some had elaborate macro-based DSL's to generate HTML, where I just
51wanted plain text with some markup. Some expect the templates to be provided in a directory of text
52files, but I wanted the template to be included in the binary. I just wanted something small and
53minimal with good documentation but there was nothing like that out there so I wrote my own.
54
55TinyTemplate is well-suited to generating HTML reports and similar text files. It could be used for
56generating HTML or other text in a web-server, but for more-complex use cases another template
57engine may be a better fit.
58
59### Quickstart
60
61First, add TinyTemplate and serde-derive to your `Cargo.toml` file:
62
63```toml
64[dependencies]
65tinytemplate = "1.1"
66serde = { version = "1.0", features = ["derive"] }
67```
68
69Then add this code to "src.rs":
70
71```rust
72use serde::Serialize;
73
74use tinytemplate::TinyTemplate;
75use std::error::Error;
76
77#[derive(Serialize)]
78struct Context {
79    name: String,
80}
81
82static TEMPLATE : &'static str = "Hello {name}!";
83
84pub fn main() -> Result<(), Box<dyn Error>> {
85    let mut tt = TinyTemplate::new();
86    tt.add_template("hello", TEMPLATE)?;
87
88    let context = Context {
89        name: "World".to_string(),
90    };
91
92    let rendered = tt.render("hello", &context)?;
93    println!("{}", rendered);
94
95    Ok(())
96}
97```
98
99This should print "Hello World!" to stdout.
100
101### Compatibility Policy
102
103TinyTemplate supports the last three stable minor releases of Rust. At time of writing, this means
104Rust 1.38 or later. Older versions may work, but are not tested or guaranteed.
105
106Currently, the oldest version of Rust believed to work is 1.36. Future versions of TinyTemplate may
107break support for such old versions, and this will not be considered a breaking change. If you
108require TinyTemplate to work on old versions of Rust, you will need to stick to a
109specific patch version of TinyTemplate.
110
111### Contributing
112
113Thanks for your interest! Contributions are welcome.
114
115Issues, feature requests, questions and bug reports should be reported via the issue tracker above.
116In particular, becuase TinyTemplate aims to be well-documented, please report anything you find
117confusing or incorrect in the documentation.
118
119Code or documentation improvements in the form of pull requests are also welcome. Please file or
120comment on an issue to allow for discussion before doing a lot of work, though.
121
122For more details, see the [CONTRIBUTING.md file](https://github.com/bheisler/TinyTemplate/blob/master/CONTRIBUTING.md).
123
124### Maintenance
125
126TinyTemplate was created and is currently maintained by Brook Heisler (@bheisler).
127
128### License
129
130TinyTemplate is dual-licensed under the Apache 2.0 license and the MIT license.
131