Template Helpers / Functions

Helpers extend the template to generate or to transform content.

The helpers from handlebars_misc_helpers are included. This page is a copy of handlebars_misc_helpers/README.md at master · davidB/handlebars_misc_helpers, and it can be can be out-of-date.

Few helpers are included, but if you need more helpers, ask via an issue or a PR.

To use an helper:

// arguments are space separated
{{ helper_name arguments}}

To chain helpers, use parenthesis:

{{ to_upper_case (to_singular "Hello foo-bars") }}
// -> BAR

{{ first_non_empty (unquote (json_str_query "package.edition" (read_to_str "Cargo.toml") format="toml")) (env_var "MY_VERSION") "foo" }}
// -> 2018

see Handlebars templating language

String transformation

helper signatureusage samplesample out
replace s:String from:String to:Stringreplace "Hello old" "old" "new""Hello new"
to_lower_case s:Stringto_lower_case "Hello foo-bars""hello foo-bars"
to_upper_case s:Stringto_upper_case "Hello foo-bars""HELLO FOO-BARS"
to_camel_case s:Stringto_camel_case "Hello foo-bars""helloFooBars"
to_pascal_case s:Stringto_pascal_case "Hello foo-bars""HelloFooBars"
to_snake_case s:Stringto_snake_case "Hello foo-bars""hello_foo_bars"
to_screaming_snake_case s:Stringto_screaming_snake_case "Hello foo-bars""HELLO_FOO_BARS"
to_kebab_case s:Stringto_kebab_case "Hello foo-bars""hello-foo-bars"
to_train_case s:Stringto_train_case "Hello foo-bars""Hello-Foo-Bars"
to_sentence_case s:Stringto_sentence_case "Hello foo-bars""Hello foo" bars
to_title_case s:Stringto_title_case "Hello foo-bars""Hello Foo Bars"
to_class_case s:Stringto_class_case "Hello foo-bars""HelloFooBar"
to_table_case s:Stringto_table_case "Hello foo-bars""hello_foo_bars"
to_plural s:Stringto_plural "Hello foo-bars""bars"
to_singular s:Stringto_singular "Hello foo-bars""bar"
trim s:Stringtrim " foo ""foo"
trim_start s:Stringtrim_start " foo ""foo "
trim_end s:Stringtrim_end " foo "" foo"
unquote s:Stringunquote "\"foo\"""foo"
enquote symbol:String s:Stringenquote "" "foo""\"foo\""
first_non_empty s:String+first_non_empty "" null "foo" "bar""foo"

Http content

Helper able to render body response from an http request.

helper signatureusage sample
http_get url:Stringhttp_get "http://hello/..."
gitignore_io templates:Stringgitignore_io "rust,visualstudiocode"

Path extraction

Helper able to extract (or transform) path (defined as string).

for the same input: "/hello/bar/foo.txt"

helper_namesample output
file_name"foo.txt"
parent"/hello/bar"
extension"txt"

File

Helper to read file content.

usageoutput
{{ read_to_str "/foo/bar" }}content of file /foo/bar
{{ read_to_str "file/does/not/exist" }}empty string

Environment variable

Helper able to get environment variables.

helper_nameusage
env_varenv_var "HOME"

Specials environment variables are predefined (some of them come from std::env::consts - Rust):

variable possible values
"ARCH"
  • x86
  • x86_64
  • arm
  • aarch64
  • mips
  • mips64
  • powerpc
  • powerpc64
  • s390x
  • sparc64
"DLL_EXTENSION"
  • so
  • dylib
  • dll
"DLL_PREFIX"
  • lib
  • "" (an empty string)
"DLL_SUFFIX"
  • .so
  • .dylib
  • .dll
"EXE_EXTENSION"
  • exe
  • "" (an empty string)
"EXE_SUFFIX"
  • .exe
  • .nexe
  • .pexe
  • "" (an empty string)
"FAMILY"
  • unix
  • windows
"OS"
  • linux
  • macos
  • ios
  • freebsd
  • dragonfly
  • netbsd
  • openbsd
  • solaris
  • android
  • windows
"USERNAME" try to find the current username, in the order:
  1. environment variable "USERNAME"
  2. environment variable "username"
  3. environment variable "USER"
  4. environment variable "user"

JSON & YAML & TOML

Helpers

  • json_query query:String data:Json: Helper able to extract information from json using JMESPath syntax for query.
  • json_str_query query:String data:String: Helper able to extract information from json using JMESPath syntax for query, data follows the requested format.
  • json_to_str data:Json: convert a json data into a string following the requested format.
  • str_to_json data:String: convert(parse) a string into a json following the requested format.

The optional requested format, is the format of the string with data:

  • "json" (default if omitted)
  • "json_pretty" json with indentation,…
  • "yaml"
  • "toml"
  • "toml_pretty"
usageoutput
{{ json_query "foo" {} }}``
{{ json_to_str ( json_query "foo" {"foo":{"bar":{"baz":true}}} ) }}{"bar":{"baz":true}}
{{ json_to_str ( json_query "foo" (str_to_json "{\"foo\":{\"bar\":{\"baz\":true}}}" ) ) }}{"bar":{"baz":true}}
{{ json_str_query "foo" "{\"foo\":{\"bar\":{\"baz\":true}}}" }}{"bar":{"baz":true}}
{{ json_str_query "foo.bar.baz" "{\"foo\":{\"bar\":{\"baz\":true}}}" }}true
{{ json_str_query "foo" "foo:\n bar:\n baz: true\n" format="yaml"}}bar:\n baz: true\n
{{ json_to_str ( str_to_json "{\"foo\":{\"bar\":{\"baz\":true}}}" format="json") format="yaml"}}foo:\n bar:\n baz: true\n

Blocks

{{#from_json format="toml"}}
{"foo": {"hello":"1.2.3", "bar":{"baz":true} } }
{{/from_json}}
[foo]
hello = "1.2.3"

[foo.bar] baz = true

{{#to_json format="toml"}}
[foo]
bar = { baz = true }
hello = "1.2.3"
{{/to_json}}
{
  "foo": {
    "bar": {
      "baz": true
    },
    "hello": "1.2.3"
  }
}
{{#from_json format="toml"}}
{"foo":{"bar":{"baz":true}}}
{{/from_json}}
foo:
  bar:
    baz: true
{{#to_json format="yaml"}}
foo:
    bar:
        baz: true
{{/to_json}}
{
  "foo": {
    "bar": {
      "baz": true
    }
  }
}

Note: YAML & TOML content are used as input and output format for json data. So capabilities are limited to what json support (eg. no date-time type like in TOML).

Edition via jsonnet

For more advanced edition of json, you can use jsonnet.

A data templating language for app and tool developers

  • See the doc of jsonnet for more samples, syntax info,…
  • This block can be combined with conversion helper/block for YAML & TOML to provide edition capabilities for those format
  • the output should a valid json, except if string_output = false is set as parameter of the block.
{{#jsonnet}}
local v = {"foo":{"bar":{"baz":false}}};
v {
  "foo" +: {
      "bar" +: {
          "baz2": true
      }
  }
}
{{/jsonnet}}
{
  "foo": {
      "bar": {
          "baz": false,
          "baz2": true
      }
  }
}

Assign

Helper able to assign (to set) a variable to use later in the template.

usageoutput
{{ assign "foo" "{}" }}``
{{ assign "foo" "{}" }}{{ foo }}{}
{{ assign "foo" "hello world" }}{{ foo }}hello world
{{ assign "foo" {} }}{{ foo }}[object]
{{ assign "foo" {"bar": 33} }}{{ foo }}[object]