Skip to main content

Filters

This document describes the Tera filters implemented in src/lib.rs and how to use them in templates.

Filter Syntax​

Tera filter syntax: {{ value | filter_name(arg_name=value) }}

Available Filters​

1. json_parse​

  • Description: Parse a JSON string into a Tera value (object/array/primitive).
  • Signature: json_parse(value: string) -> Value
  • Template usage: {{ json_string | json_parse }}
  • Returns: parsed JSON as native Tera/serde_json Value.
  • Errors: fails if input is not a string or JSON parsing fails.

Example​

{% set obj = json_str | json_parse %}{{ obj.key }}

2. is_array​

  • Description: Returns true when the value is a JSON array.
  • Signature: is_array(value) -> Bool
  • Template usage: {{ some_value | is_array }}
  • Returns: true/false.
  • Notes: safe to use for type checks inside templates.

Example​

{% if data | is_array %}
  <!-- handle array -->
{% endif %}

3. validate_ean13​

  • Description: Validates an EAN‑13 barcode (digits + checksum).
  • Signature: validate_ean13(value: string|number) -> Bool
  • Template usage: {{ "1234567890123" | validate_ean13 }}
  • Returns: true if value is exactly 13 digits and checksum matches; false otherwise.
  • Errors: returns false for non-digit inputs or wrong length.

Example​

{% if barcode | validate_ean13 %}
  <!-- barcode is valid -->
{% endif %}

Implementation Note​

Implements the EAN‑13 checksum algorithm and works with both string and numeric input.

4. to_fixed​

  • Description: Format a numeric value to a string with fixed number of fractional digits.
  • Signature: to_fixed(value: number|string, precision: integer = 2) -> String
  • Template usage: {{ price | to_fixed(precision=2) }}
  • Returns: string formatted with given precision (default 2).
  • Errors: fails if value cannot be interpreted as a number.

Example​

{{ 3.14159 | to_fixed(precision=2) }}
<!-- Output: "3.14" -->

Implementation Note​

Always returns a string (formatted number).

5. filter_null​

  • Description: From an array of objects, return those where the specified dotted attribute is null or missing.
  • Signature: filter_null(array, attribute="<dotted.path>") -> Array
  • Template usage: {{ items | filter_null(attribute="metadata.someKey") }}
  • Behavior: attribute must be provided; input must be an array. Returns an array of matching items.
  • Errors: fails if input is not an array or attribute not provided.

Example​

{% set missing = items | filter_null(attribute="metadata.color") %}

Implementation Note​

Accepts a dotted attribute path (uses Tera's dotted_pointer).

6. filter_empty_objects​

  • Description: From an array of objects, return those where the specified dotted attribute exists and is an empty object ().
  • Signature: filter_empty_objects(array, attribute="<dotted.path>") -> Array
  • Template usage: {{ items | filter_empty_objects(attribute="metadata.info") }}
  • Behavior: attribute must be provided; input must be an array. Matches only empty object values.
  • Errors: fails if input is not an array or attribute not provided.

Example​

{% set empty_meta = items | filter_empty_objects(attribute="metadata.extra") %}

Implementation Note​

Accepts a dotted attribute path (uses Tera's dotted_pointer).

7. debug​

  • Description: Produce a debug string representation of the value (Rust debug format).
  • Signature: debug(value) -> String
  • Template usage: {{ some_value | debug }}
  • Returns: string. Useful for inspecting values during template development.

Example​

{{ field | debug }}

Implementation Note​

Returns a Rust debug representation (useful while authoring templates).

8. format_duration​

  • Description: Convert a duration in seconds into a human-readable string (days/hours/minutes/seconds).
  • Signature: format_duration(seconds: integer, locale: string = "en") -> String
  • Template usage: {{ 3661 | format_duration(locale="en") }}
  • Returns: formatted string, e.g. "1 hours 1 minutes 1 seconds" (locale-aware labels: en/fr supported).
  • Errors: fails if seconds is not an integer or is negative.

Example​

{{ 90061 | format_duration(locale="fr") }}
<!-- Uses French translation map -->

Error Handling​

  • Most filters return Tera errors when required argument types are not met (e.g. expecting array or integer).
  • to_fixed and json_parse might return parse errors if the input cannot be interpreted correctly.

Localization​

  • format_duration uses the internal translate helper with translations for "en" and "fr".
  • Supported token translations include days, hours, minutes, seconds and other labels defined in the translate map.