gtmpl-rust – Golang Templates for Rust

![Travis Build Status] ![Appveyor Build Status] ![Latest Version]

[gtmpl-rust] provides the [Golang text/template] engine for Rust. This enables seamless integration of Rust application into the world of devops tools around [kubernetes], [docker] and whatnot.

Getting Started

Add the following dependency to your Cargo manifest… toml [dependencies] gtmpl = "0.5.6"

and look at the docs: * gtmpl at crates.io * gtmpl documentation * golang documentation

It's not perfect, yet. Help and feedback is more than welcome.

Some Examples

Basic template: ```rust extern crate gtmpl; use gtmpl;

fn main() { let output = gtmpl::template("Finally! Some {{ . }} for Rust", "gtmpl"); assert_eq!(&output.unwrap(), "Finally! Some gtmpl for Rust"); } ```

Adding custom functions: ```rust

[macro_use]

extern crate gtmpl; extern crate gtmplvalue; use gtmplvalue::Function; use gtmpl::{template, Value};

fn main() { gtmplfn!( fn add(a: u64, b: u64) -> Result { Ok(a + b) }); let equal = template(r#"{{ call . 1 2 }}"#, Value::Function(Function { f: add })); asserteq!(&equal.unwrap(), "3"); } ```

Passing a struct as context: ```rust

[macro_use]

extern crate gtmpl;

[macro_use]

extern crate gtmplderive; extern crate gtmplvalue;

[derive(Gtmpl)]

struct Foo { bar: u8 }

fn main() { let foo = Foo { bar: 42 }; let output = gtmpl::template("The answer is: {{ .bar }}", foo); assert_eq!(&output.unwrap(), "The answer is: 42"); } ```

Invoking a method on a context: ```rust

[macro_use]

extern crate gtmpl;

[macro_use]

extern crate gtmplderive; extern crate gtmplvalue;

use gtmpl::{Func, Value};

fn plusone(args: &[Value]) -> Result { if let Value::Object(ref o) = &args[0] { if let Some(Value::Number(ref n)) = o.get("num") { if let Some(i) = n.asi64() { return Ok((i +1).into()) } } } Err(format!("integer required, got: {:?}", args)) }

[derive(Gtmpl)]

struct AddMe { num: u8, plus_one: Func }

fn main() { let addme = AddMe { num: 42, plusone }; let output = gtmpl::template("The answer is: {{ .plusone }}", addme); assert_eq!(&output.unwrap(), "The answer is: 43"); } ```

Current Limitations

This is work in progress. Currently the following features are not supported:

Enhancements

Even though it was never intended to extend the syntax of Golang text/template there might be some convenient additions:

Dynamic Template

Enable gtmpl_dynamic_template in your Cargo.toml: ```toml [dependencies.gtmpl] version = "0.5.6" features = ["gtmpldynamictemplate"]

```

Now you can have dynamic template names for the template action.

Example

```rust extern crate gtmpl; use gtmpl::{Context, Template};

fn main() { let mut template = Template::default(); template .parse( r#" {{- define "tmpl1"}} some {{ end -}} {{- define "tmpl2"}} some other {{ end -}} there is {{- template (.) -}} template "#, ) .unwrap();

let context = Context::from("tmpl2").unwrap();

let output = template.render(&context);
assert_eq!(output.unwrap(), "there is some other template".to_string());

} ```

The following syntax is used: ``` {{template (pipeline)}} The template with the name evaluated from the pipeline (parenthesized) is executed with nil data.

{{template (pipeline) pipeline}} The template with the name evaluated from the first pipeline (parenthesized) is executed with dot set to the value of the second pipeline. ```

Context

We use [gtmplvalue]'s Value as internal data type. [gtmplderive] provides a handy derive macro to generate the From implementation for Value.

See:

Why do we need this?

Why? Dear god, why? I can already imagine the question coming up why anyone would ever do this. I wasn't a big fan of Golang templates when i first had to write some custom formatting strings for docker. Learning a new template language usually isn't something one is looking forward to. Most people avoid it completely. However, it's really useful for automation if you're looking for something more lightweight than a full blown DSL.

The main motivation for this is to make it easier to write devops tools in Rust that feel native. [docker] and [helm] ([kubernetes]) use golang templates and it feels more native if tooling around them uses the same.