V0.11

CHANGELOG.md

@@ -1,5 +1,32 @@
 # Changelog
 
+## 0.11.0 (unreleased)
+
+### Breaking changes
+
+- Tests parentheses are now mandatory if there are arguments (`divisibleby 2` -> `divisibleby(2)`)
+- Tests can be only used on variables now, not on expressions
+- Escaping happens immediately now instead of waiting for the filters to be called, unless `safe` is first.
+If you want the old behaviour you will need to start the a chain of filters with `| safe` as the first one
+
+### Others
+
+- Tests, global functions calls and macro calls are now expressions and can be combined like so: `if x is divisibleby(2) and x > 10`
+- Add default arguments for macro arguments
+- Add whitespace management similar to Liquid and Jinja2
+- Add parentheses to expressions to remove ambiguities
+- Block & macro end tag name are no longer mandatory and it doesn't error on mismatched names between
+the start and end tag anymore
+- Filters can now be applied to expressions
+- Add modulo operator `%` for math expressions
+- Allow comment tags before the extend tag
+- Make `NaiveDateTime` work with the `date` filter
+- `pluralize` filter now returns the plural suffix for 0 thing as it's apparently what English does
+- Add a `set_global` tag that allows you to set something in the global context: meant to be used in forloops where
+the normal `set` would put the value into the loop context
+- Add `starting_with`, `ending_with` and `containing` tests
+- Add `json_encode`, `default` and `sort` filters
+- Strings can now also be contained in backticks and single quotes in templates
 
 ## 0.10.10 (2017-08-24)
 

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "tera"
-version = "0.10.10"
+version = "0.11.0"
 authors = ["Vincent Prouillet <[email protected]>"]
 license = "MIT"
 readme = "README.md"
@@ -14,14 +14,15 @@ categories = ["template-engine"]
 glob = "0.2"
 serde = "1.0"
 serde_json = "1.0"
-pest = "0.4"
-error-chain = "0.10"
+pest = "^1"
+pest_derive = "^1"
+error-chain = "0.11"
 # used in slugify filter
 slug = "0.1"
 # used in striptags filters
 regex = "0.2"
 # used for static regex
-lazy_static = "0.2"
+lazy_static = "1.0"
 # used in urlencode filter
 url = "1"
 # used in filesizeformat filter
@@ -31,4 +32,4 @@ chrono = "0.4"
 
 [dev-dependencies]
 serde_derive = "1.0"
-hyper = "0.10"
+pretty_assertions = "0.4"

appveyor.yml

@@ -18,10 +18,6 @@ install:
   - rustc -Vv
   - cargo -V
 
-cache:
-  - C:\Users\appveyor\.cargo\registry
-  - target
-
 build: false
 
 test_script:

benches/tera.rs

@@ -1,8 +1,6 @@
 #![feature(test)]
 extern crate test;
 extern crate tera;
-extern crate serde;
-extern crate serde_json;
 #[macro_use]
 extern crate serde_derive;
 

docs/content/_index.md

@@ -4,8 +4,8 @@
 ```jinja2
 <title>{% block title %}{% endblock title %}</title>
 <ul>
-{% for user in users %}
+{% for user in users -%}
   <li><a href="{{ user.url }}">{{ user.username }}</a></li>
-{% endfor %}
+{%- endfor %}
 </ul>
 ```

docs/content/docs/installation.md

@@ -7,7 +7,7 @@ order = 1
 To use Tera in your Rust projects, simply add it to your `Config.toml`:
 
 ```toml
-tera = "0.10"
+tera = "0.11"
 ```
 
 And add the following to your `lib.rs` or `main.rs`:

docs/content/docs/templates.md

@@ -10,7 +10,7 @@ when it is rendered. The syntax is based on Jinja2 and Django templates.
 There are 3 kinds of delimiter and those cannot be changed:
 
 - `{{` and `}}` for expressions
-- `{%` and `%}` for statements
+- `{%` or `{%-` and `%}` or `-%}` for statements
 - `{#` and `#}` for comments
 
 ## Variables
@@ -27,7 +27,7 @@ A magical variable is available in every template if you want to print the curre
 
 ## Expressions
 
-Tera allows expressions everywhere.
+Tera allows expressions almost everywhere.
 
 ### Math
 You can do some basic math in Tera but it shouldn't be abused other than the occasional `+ 1` or similar.
@@ -38,6 +38,12 @@ You can use the following operators:
 - `-`: performs a substraction, `{{ 2 - 1 }}` will print `1`
 - `/`: performs a division, `{{ 10 / 2 }}` will print `5`
 - `*`: performs a multiplication, `{{ 5 * 2 }}` will print `10`
+- `%`: performs a modulo, `{{ 2 % 2 }}` will print `0`
+
+The priority of operations is the following, from lowest to highest:
+
+- `+` and `-`
+- `*` and `/` and `%`
 
 ### Comparisons
 
@@ -61,7 +67,7 @@ Filters are separated from the variable by a pipe symbol (|) and may have named
 Multiple filters can be chained: the output of one filter is applied to the next.
 
 For example, `{{ name | lower | replace(from="doctor", to="Dr.") }}` will take a variable called name, make it lowercase and then replace instances of `doctor` by `Dr.`. 
-It is equivalent to `replace(lower(name), from="doctor", to="Dr.")` if we were to look at it as function
+It is equivalent to `replace(lower(name), from="doctor", to="Dr.")` if we were to look at it as functions.
 
 Calling filters on a incorrect type like trying to capitalize an array or using invalid types for arguments will result in a error.
 
@@ -71,6 +77,17 @@ Filters are functions with the `fn(Value, HashMap<String, Value>) -> Result<Valu
 tera.register_filter("upper", string::upper);
 ```
 
+While filters can be used in math operations, they will have the lowest priority and therefore might not do what you expect:
+
+
+```css
+{{ 1 + a | length }}
+// is equal to
+{{ (1 + a) | length } // this will probably error
+
+// This will do what you wanted initially
+{{ a | length + 1 }}
+```
 Tera has many [built-in filters](./docs/templates.md#built-in-filters) that you can use.
 
 ### Filter sections
@@ -93,7 +110,7 @@ are made in `if` blocks using the `is` keyword.
 For example, you would write the following to test if an expression is odd:
 
 ```jinja2
-{% if my_number + 1 is odd %}
+{% if my_number is odd %}
  Odd
 {% endif %}
 ```
@@ -160,6 +177,16 @@ assignments outside of those will be set in the global context.
 {% set my_var = global_fn() %}
 ```
 
+If you want to assign a value in the global context while in a forloop, you can use `set_global`:
+
+```jinja2
+{% set_global my_var = "hello" %}
+{% set_global my_var = 1 + 4 %}
+{% set_global my_var = some_var %}
+{% set_global my_var = macros::some_macro() %}
+{% set_global my_var = global_fn() %}
+```
+
 ## Comments
 To comment out part of the template, wrap it in `{# #}`. Anything in between those tags
 will not be rendered.
@@ -376,6 +403,32 @@ render what's inside. Useful if you have text that contains Tera delimiters.
 ```
 would be rendered as `Hello {{ name }}`.
 
+## Whitespace control
+
+Tera comes with easy to use whitespace control: use `{%-` if you want to remove all whitespace
+before a statement and `-%}` if you want to remove all whitespace after.
+
+For example, let's look at the following template:
+
+```jinja2
+{% set my_var = 2 %}
+{{ my_var }}
+```
+
+will have the following output:
+
+```html
+
+2
+```
+
+If we want to get rid of the empty line, we can write the following:
+
+```jinja2
+{% set my_var = 2 -%}
+{{ my_var }}
+```
+
 ## Built-in filters
 
 Tera has the following filters built-in:
@@ -406,17 +459,26 @@ If value is "I'm using Tera", the output will be "I\'m using Tera".
 Transform a string into ASCII, lowercase it, trim it, converts spaces to hyphens and 
 remove all characters that are not numbers, lowercase letters or hyphens.
 
-Example: `{{ value | slugify}}`
+Example: `{{ value | slugify }}`
 
 If value is "-Hello world! ", the output will be "hello-world".
 
 ### title
 Capitalizes each word inside a sentence.
 
-Example: `{{ value | title}}`
+Example: `{{ value | title }}`
 
 If value is "foo  bar", the output will be "Foo  Bar".
 
+### trim
+Remove leading and trailing whitespace if the variable is a string.
+
+### truncate
+Truncates a string to the indicated length. If the string has a smaller length than
+the `length` argument, the string is returned as is.
+
+Example: `{{ value | truncate(length=10) }}`
+
 ### striptags
 Tries to remove HTML tags from input. Does not guarantee well formed output if input is not valid HTML.
 
@@ -445,6 +507,43 @@ Returns the length of an array or a string, 0 if the value is not an array.
 ### reverse
 Returns a reversed string or array.
 
+### sort
+Sorts an array into ascending order.
+
+The values in the array must be a sortable type:
+- numbers are sorted by their numerical value.
+- strings are sorted in alphabetical order.
+- arrays are sorted by their length.
+- bools are sorted as if false=0 and true=1
+
+If you need to sort a list of structs or tuples, use the `attribute`
+argument to specify which field to sort by.
+
+Example:
+
+Given `people` is an array of Person
+
+```rust
+struct Name(String, String);
+
+struct Person {
+    name: Name,
+    age: u32
+}
+```
+
+The `attribute` argument can be used to sort by last name:
+
+```jinja2
+{{ people | sort(attribute="name.1") }}
+```
+
+or by age:
+
+```jinja2
+{{ people | sort(attribute="age") }}
+```
+
 ### urlencode
 Percent-encodes a string.
 
@@ -503,6 +602,24 @@ Currently the position of the safe filter does not matter, e.g.
 Access a value from an object when the key is not a Tera identifier.
 Example: `{{ sections | get(key="posts/content") }}`
 
+### split
+Split a string into an array of strings, separated by a pattern given.
+Example: `{{ path | split(pat="/") }}`
+
+### json_encode
+Transforms any value into a JSON representation. This filter is better used together with `safe` or when automatic escape is disabled.
+
+Example: `{{ value | safe | json_encode() }}`
+
+It accepts a parameter `pretty` (boolean) to print a formatted JSON instead of a one-liner.
+
+Example: `{{ value | safe | json_encode(pretty=true) }}`
+
+### default
+Returns the default value given if the variable evaluated is not present in the context.
+
+Example: `{{ value | default(value=1) }}`
+
 ## Built-in tests
 
 Here are the currently built-in tests:
@@ -530,14 +647,43 @@ Returns true if the given expression is divisible by the arg given.
 
 Example:
 ```jinja2
-{% if rating is divisibleby 2 %}
+{% if rating is divisibleby(2) %}
     Divisible
 {% endif %}
 ```
 
 ### iterable
 Returns true if the given variable can be iterated over in Tera (ie is an array/tuple).
 
+### starting\_with
+Returns true if the given variable is a string starts with the arg given.
+
+Example:
+```jinja2
+{% if path is starting_with("x/") %}
+    In section x
+{% endif %}
+```
+
+### ending\_with
+Returns true if the given variable is a string ends with the arg given.
+
+### containing
+Returns true if the given variable contains the arg given.
+
+The test works on:
+
+- strings: is the arg a substring?
+- arrays: is the arg given one of the member of the array?
+- maps: is the arg given a key of the map?
+
+Example:
+```jinja2
+{% if username is containing("xXx") %}
+    Bad
+{% endif %}
+```
+
 ## Built-in global functions
 Tera comes with some built-in global functions.