More

README.md

@@ -1,5 +1,3 @@
 # Tera
 
 See [migration guide](./MIGRATION.md).
-
-Alpha, docs not written yet.

docs/content/_index.md

@@ -229,11 +229,6 @@ You can use the following operators:
 - `*`: 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
 
 - `==`: checks whether the values are equal
@@ -317,6 +312,25 @@ You can use slicing on your arrays, similar to Python slicing:
 
 You can do `{{ "majeur" if age >= 18 else "mineur" }}`. Both `if` and `else` are required.
 
+#### Operator precedence
+
+From lowest to highest binding power. Operators on the same row have the same precedence.
+
+| Operators |
+|---|
+| `or` |
+| `and` |
+| `not` |
+| `in`, `not in`, `is`, `is not` |
+| `==`, `!=`, `<`, `<=`, `>`, `>=` |
+| `+`, `-` |
+| `*`, `/`, `//`, `%`, `~` |
+| `**` |
+| `\|` |
+| `-` (unary) |
+| `.`, `[]`, `()` |
+
+
 ### Filters
 
 You can modify variables using **filters**.
@@ -1257,7 +1271,7 @@ There are 3 arguments, all integers:
 
 - `end`: stop before `end`, mandatory
 - `start`: where to start from, defaults to `0`
-- `step_by`: with what number do we increment, defaults to `1`
+- `step_by`: the step between values, defaults to `1`, use a negative value to count down
 
 ##### throw
 The template rendering will error with the given message when encountered.

tera-contrib/src/filesize_format.rs

@@ -1,4 +1,4 @@
-use tera::{Kwargs, State};
+use tera::{Kwargs, State, TeraResult};
 
 /// Formats a number of bytes into a human-readable file size string.
 /// Uses binary units (KiB, MiB, GiB, etc.) by default but can use decimal.
@@ -7,13 +7,13 @@ use tera::{Kwargs, State};
 /// {{ num_bytes | filesize_format }}
 /// {{ num_bytes | filesize_format(binary=false) }}
 /// ```
-pub fn filesize_format(val: u64, kwargs: Kwargs, _: &State) -> String {
-    let binary = kwargs.get::<bool>("binary").ok().flatten().unwrap_or(true);
+pub fn filesize_format(val: u64, kwargs: Kwargs, _: &State) -> TeraResult<String> {
+    let binary = kwargs.get::<bool>("binary")?.unwrap_or(true);
 
     if binary {
-        humansize::format_size(val, humansize::BINARY)
+        Ok(humansize::format_size(val, humansize::BINARY))
     } else {
-        humansize::format_size(val, humansize::DECIMAL)
+        Ok(humansize::format_size(val, humansize::DECIMAL))
     }
 }
 
@@ -28,8 +28,14 @@ mod tests {
     fn test_filesizeformat_binary() {
         let ctx = Context::new();
         let state = State::new(&ctx);
-        assert_eq!(filesize_format(1024, Kwargs::default(), &state), "1 KiB");
-        assert_eq!(filesize_format(1048576, Kwargs::default(), &state), "1 MiB");
+        assert_eq!(
+            filesize_format(1024, Kwargs::default(), &state).unwrap(),
+            "1 KiB"
+        );
+        assert_eq!(
+            filesize_format(1048576, Kwargs::default(), &state).unwrap(),
+            "1 MiB"
+        );
     }
 
     #[test]
@@ -39,7 +45,7 @@ mod tests {
         let mut map = Map::new();
         map.insert("binary".into(), false.into());
         let kwargs = Kwargs::new(Arc::new(map));
-        assert_eq!(filesize_format(1000, kwargs, &state), "1 kB");
+        assert_eq!(filesize_format(1000, kwargs, &state).unwrap(), "1 kB");
     }
 
     #[test]

tera-contrib/src/urlencode.rs

@@ -30,6 +30,7 @@ const USERINFO_ENCODE_SET: &AsciiSet = &PATH_ENCODE_SET
 /// with `/` not escaped
 const PYTHON_ENCODE_SET: &AsciiSet = &USERINFO_ENCODE_SET
     .remove(b'/')
+    .add(b'%')
     .add(b':')
     .add(b'?')
     .add(b'#')

tera/src/components.rs

@@ -6,6 +6,7 @@ use crate::value::Value;
 
 /// The type of component arguments.
 #[derive(Clone, Copy, Debug, PartialEq, Eq)]
+#[non_exhaustive]
 pub enum ComponentArgType {
     #[allow(missing_docs)]
     String,
@@ -21,6 +22,8 @@ pub enum ComponentArgType {
     Array,
     #[allow(missing_docs)]
     Map,
+    #[allow(missing_docs)]
+    Bytes,
 }
 
 impl ComponentArgType {
@@ -34,6 +37,7 @@ impl ComponentArgType {
             ComponentArgType::Number => "number",
             ComponentArgType::Array => "array",
             ComponentArgType::Map => "map",
+            ComponentArgType::Bytes => "bytes",
         }
     }
 }
@@ -54,6 +58,7 @@ impl From<Type> for ComponentArgType {
             Type::Number => ComponentArgType::Number,
             Type::Array => ComponentArgType::Array,
             Type::Map => ComponentArgType::Map,
+            Type::Bytes => ComponentArgType::Bytes,
         }
     }
 }

tera/src/context.rs

@@ -24,7 +24,7 @@ impl Context {
     /// Meant to be used if you have a hashmap or a struct and don't want to insert values
     /// one by one in the context.
     pub fn from_serialize<T: Serialize + ?Sized>(value: &T) -> crate::TeraResult<Self> {
-        let val = Value::from_serializable(value);
+        let val = Value::try_from_serializable(value)?;
         let type_name = val.name();
 
         match val.into_map() {
@@ -125,7 +125,7 @@ macro_rules! context {
         )*
     ) => {
         {
-            let mut context = Context::new();
+            let mut context = $crate::Context::new();
             $(
                 context.insert(stringify!($key), $($value)?);
             )*

tera/src/delimiters.rs

@@ -4,7 +4,7 @@ use crate::errors::{Error, TeraResult};
 
 /// This allows customizing the delimiters used for blocks, variables, and comments in case
 /// you want to template files that contains text like `{{`, like LaTeX.
-/// Delimiters need to be 2 ASCII characters.
+/// Delimiters need to be exactly 2 bytes long (e.g. `{{`, `«`).
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct Delimiters {
     /// Start delimiter for blocks, default: `{%`
@@ -37,32 +37,32 @@ impl Default for Delimiters {
 impl Delimiters {
     /// Returns an error if any delimiter is empty or if there are conflicts
     pub(crate) fn validate(&self) -> TeraResult<()> {
-        if self.block_start.chars().count() != 2 {
+        if self.block_start.len() != 2 {
             return Err(Error::message(
-                "`block_start` delimiter must be 2 characters",
+                "`block_start` delimiter must be 2 bytes long",
             ));
         }
-        if self.block_end.chars().count() != 2 {
-            return Err(Error::message("`block_end` delimiter must be 2 characters"));
+        if self.block_end.len() != 2 {
+            return Err(Error::message("`block_end` delimiter must be 2 bytes long"));
         }
-        if self.variable_start.chars().count() != 2 {
+        if self.variable_start.len() != 2 {
             return Err(Error::message(
-                "`variable_start` delimiter must be 2 characters",
+                "`variable_start` delimiter must be 2 bytes long",
             ));
         }
-        if self.variable_end.chars().count() != 2 {
+        if self.variable_end.len() != 2 {
             return Err(Error::message(
-                "`variable_end` delimiter must be 2 characters",
+                "`variable_end` delimiter must be 2 bytes long",
             ));
         }
-        if self.comment_start.chars().count() != 2 {
+        if self.comment_start.len() != 2 {
             return Err(Error::message(
-                "`comment_start` delimiter must be 2 characters",
+                "`comment_start` delimiter must be 2 bytes long",
             ));
         }
-        if self.comment_end.chars().count() != 2 {
+        if self.comment_end.len() != 2 {
             return Err(Error::message(
-                "`comment_end` delimiter must be 2 characters",
+                "`comment_end` delimiter must be 2 bytes long",
             ));
         }
 
@@ -107,6 +107,11 @@ mod tests {
                 comment_start: "[[".into(),
                 ..Delimiters::default()
             },
+            Delimiters {
+                // 3 bytes
+                block_start: "日".into(),
+                ..Delimiters::default()
+            },
         ];
 
         for i in inputs {

tera/src/errors.rs

@@ -8,6 +8,7 @@ use crate::utils::Span;
 
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub(crate) struct Note {
+    pub(crate) label: String,
     pub(crate) filename: String,
     pub(crate) source: String,
     pub(crate) span: Span,
@@ -50,8 +51,9 @@ impl ReportError {
         self.source = source.to_string();
     }
 
-    pub(crate) fn add_note(&mut self, filename: &str, source: &str, span: &Span) {
+    pub(crate) fn add_note(&mut self, label: &str, filename: &str, source: &str, span: &Span) {
         self.notes.push(Note {
+            label: label.to_string(),
             filename: filename.to_string(),
             source: source.to_string(),
             span: span.clone(),

tera/src/filters.rs

@@ -144,7 +144,7 @@ pub(crate) fn pluralize(val: Value, kwargs: Kwargs, _: &State) -> TeraResult<Str
     let plural = kwargs.get::<&str>("plural")?.unwrap_or("s");
 
     let is_singular = match val.as_i128() {
-        Some(n) => n == 1,
+        Some(n) => n == 1 || n == -1,
         None => {
             return Err(Error::message(format!(
                 "pluralize filter requires an integer, got `{}`",
@@ -271,6 +271,10 @@ pub(crate) fn indent(val: &str, kwargs: Kwargs, _: &State) -> TeraResult<String>
         res.push_str(line);
     }
 
+    if val.ends_with('\n') {
+        res.push('\n');
+    }
+
     Ok(res)
 }
 
@@ -281,6 +285,11 @@ pub(crate) fn as_str(val: Value, _: Kwargs, _: &State) -> String {
 /// Converts a Value into an int. It defaults to a base of `10` but can be changed.
 pub(crate) fn int(val: Value, kwargs: Kwargs, _: &State) -> TeraResult<Value> {
     let base = kwargs.get::<u32>("base")?.unwrap_or(10);
+    if !(2..=36).contains(&base) {
+        return Err(Error::message(format!(
+            "int filter `base` must be between 2 and 36, got {base}"
+        )));
+    }
 
     let handle_f64 =
         |v: f64| {
@@ -635,7 +644,7 @@ pub(crate) fn group_by(val: Vec<Value>, kwargs: Kwargs, _: &State) -> TeraResult
         match v.get_from_path(attribute) {
             x if x.is_undefined() => {
                 return Err(Error::message(format!(
-                    "Value {v} does not have an attribute after following path; {attribute}"
+                    "Value {v} does not have an attribute after following path: {attribute}"
                 )));
             }
             x if x.is_none() => (),

tera/src/functions.rs

@@ -65,10 +65,10 @@ impl StoredFunction {
 const MAX_RANGE_LEN: usize = 100_000;
 
 pub(crate) fn range(kwargs: Kwargs, _: &State) -> TeraResult<Vec<isize>> {
-    let start = kwargs.get::<isize>("start")?.unwrap_or_default();
-    let end = kwargs.must_get::<isize>("end")?;
-    let step_by = kwargs.get::<usize>("step_by")?.unwrap_or(1);
-    if start > end {
+    let start = kwargs.get::<i128>("start")?.unwrap_or_default();
+    let end = kwargs.must_get::<i128>("end")?;
+    let step_by = kwargs.get::<i128>("step_by")?.unwrap_or(1);
+    if start > end && step_by > 0 {
         return Err(Error::message(
             "Function `range` was called with a `start` argument greater than the `end` one",
         ));
@@ -79,16 +79,27 @@ pub(crate) fn range(kwargs: Kwargs, _: &State) -> TeraResult<Vec<isize>> {
         ));
     }
 
-    let span = (end as i128) - (start as i128);
-    let step = step_by as i128;
-    let len = (span + step - 1) / step;
+    let len = if step_by > 0 {
+        let span = end - start;
+        (span + step_by - 1) / step_by
+    } else if start <= end {
+        0
+    } else {
+        let span = start - end;
+        let step = -step_by;
+        (span + step - 1) / step
+    };
     if len > MAX_RANGE_LEN as i128 {
         return Err(Error::message(format!(
             "Function `range` would produce {len} elements, which exceeds the limit of {MAX_RANGE_LEN}"
         )));
     }
 
-    Ok((start..end).step_by(step_by).collect())
+    let mut values = Vec::with_capacity(len as usize);
+    for i in 0..len {
+        values.push((start + i * step_by) as isize);
+    }
+    Ok(values)
 }
 
 pub(crate) fn throw(kwargs: Kwargs, _: &State) -> TeraResult<bool> {

tera/src/parsing/ast.rs

@@ -646,6 +646,7 @@ pub enum Type {
     Number,
     Array,
     Map,
+    Bytes,
 }
 
 impl FromStr for Type {
@@ -660,8 +661,9 @@ impl FromStr for Type {
             "number" => Ok(Type::Number),
             "array" => Ok(Type::Array),
             "map" => Ok(Type::Map),
+            "bytes" => Ok(Type::Bytes),
             _ => Err(Error::message(format!(
-                "Found {s} but the only types allowed are: string, bool, integer, float, number, array and map"
+                "Found {s} but the only types allowed are: string, bool, integer, float, number, array, map and bytes"
             ))),
         }
     }
@@ -677,6 +679,7 @@ impl Type {
             Type::Number => "number",
             Type::Array => "array",
             Type::Map => "map",
+            Type::Bytes => "bytes",
         }
     }
 
@@ -694,6 +697,7 @@ impl Type {
             Type::Number => value.is_number(),
             Type::Map => value.is_map(),
             Type::Array => value.is_array(),
+            Type::Bytes => value.is_bytes(),
         }
     }
 
@@ -709,7 +713,8 @@ impl Type {
             ValueKind::F64 => Some(Type::Float),
             ValueKind::Array => Some(Type::Array),
             ValueKind::Map => Some(Type::Map),
-            ValueKind::Undefined | ValueKind::None | ValueKind::Bytes => None,
+            ValueKind::Bytes => Some(Type::Bytes),
+            ValueKind::Undefined | ValueKind::None => None,
         }
     }
 }

tera/src/parsing/compiler.rs

@@ -263,8 +263,7 @@ impl Compiler {
                     .or_default()
                     .push(span.clone());
 
-                let is_inline = component_call.body.is_empty();
-                if !is_inline {
+                if !component_call.self_closing {
                     self.chunk.add(Instruction::Capture, None);
                     for node in component_call.body {
                         self.compile_node(node);
@@ -274,7 +273,7 @@ impl Compiler {
 
                 self.compile_map_entries(component_call.kwargs, None);
 
-                if is_inline {
+                if component_call.self_closing {
                     self.chunk.add(
                         Instruction::RenderInlineComponent(component_call.name),
                         Some(span),