feat(template): add filters support (V2)

- add FilterNode to AST and extend VariableNode
- extend parser to support filter pipelines (| syntax)
- update renderer to apply filters with Builtins registry
- allow filters on missing variables (enables default behavior)
- add unit tests for filters (parser + renderer)
- add vix.json package definition

Author: GaspardKirira

include/vix/template/AST.hpp

@@ -52,6 +52,50 @@ namespace vix::template_
    */
   using NodeList = std::vector<NodePtr>;
 
+  /**
+   * @brief Filter node attached to a variable interpolation.
+   *
+   * Example:
+   * {{ name | upper | length }}
+   *
+   * In this example:
+   * - upper is one FilterNode
+   * - length is another FilterNode
+   *
+   * V2 keeps filters simple:
+   * - filter name only
+   * - no arguments yet
+   */
+  class FilterNode
+  {
+  public:
+    /**
+     * @brief Construct a filter node.
+     *
+     * @param name Filter name.
+     */
+    explicit FilterNode(std::string name)
+        : name_(std::move(name))
+    {
+    }
+
+    /**
+     * @brief Get the filter name.
+     *
+     * @return Filter name.
+     */
+    [[nodiscard]] const std::string &name() const noexcept
+    {
+      return name_;
+    }
+
+  private:
+    /**
+     * @brief Filter name.
+     */
+    std::string name_;
+  };
+
   /**
    * @brief Base class for all AST nodes.
    */
@@ -190,14 +234,16 @@ namespace vix::template_
   /**
    * @brief Variable interpolation node.
    *
-   * Example:
+   * Examples:
    * {{ user }}
+   * {{ user | upper }}
+   * {{ items | length }}
    */
   class VariableNode final : public Node
   {
   public:
     /**
-     * @brief Construct a variable node.
+     * @brief Construct a variable node without filters.
      *
      * @param name Variable name.
      */
@@ -206,6 +252,18 @@ namespace vix::template_
     {
     }
 
+    /**
+     * @brief Construct a variable node with filters.
+     *
+     * @param name Variable name.
+     * @param filters Filter pipeline.
+     */
+    VariableNode(std::string name, std::vector<FilterNode> filters)
+        : name_(std::move(name)),
+          filters_(std::move(filters))
+    {
+    }
+
     /**
      * @brief Get the node type.
      *
@@ -226,11 +284,36 @@ namespace vix::template_
       return name_;
     }
 
+    /**
+     * @brief Get the filter pipeline.
+     *
+     * @return Ordered list of filters to apply.
+     */
+    [[nodiscard]] const std::vector<FilterNode> &filters() const noexcept
+    {
+      return filters_;
+    }
+
+    /**
+     * @brief Check whether the variable has filters.
+     *
+     * @return True if one or more filters are attached.
+     */
+    [[nodiscard]] bool has_filters() const noexcept
+    {
+      return !filters_.empty();
+    }
+
   private:
     /**
      * @brief Variable name to resolve from the rendering context.
      */
     std::string name_;
+
+    /**
+     * @brief Ordered filter pipeline.
+     */
+    std::vector<FilterNode> filters_;
   };
 
   /**

include/vix/template/Parser.hpp

@@ -30,9 +30,11 @@ namespace vix::template_
    * Parser consumes the token stream produced by Lexer and builds
    * a structured AST representation of the template.
    *
-   * Supported V1 constructs:
+   * Supported V2 constructs:
    * - plain text
    * - variable interpolation: {{ name }}
+   * - filtered variable interpolation: {{ name | upper }}
+   * - chained filters: {{ name | upper | length }}
    * - if blocks: {% if cond %} ... {% endif %}
    * - for blocks: {% for item in items %} ... {% endfor %}
    */
@@ -146,13 +148,25 @@ namespace vix::template_
     /**
      * @brief Parse a variable interpolation node.
      *
-     * Expected form:
+     * Expected forms:
      * {{ identifier }}
+     * {{ identifier | filter }}
+     * {{ identifier | filter1 | filter2 }}
      *
      * @return Parsed variable node.
      */
     [[nodiscard]] NodePtr parse_variable();
 
+    /**
+     * @brief Parse a filter pipeline attached to a variable expression.
+     *
+     * Expected form:
+     * | filter_name | other_filter
+     *
+     * @return Ordered filter list.
+     */
+    [[nodiscard]] std::vector<FilterNode> parse_filters();
+
     /**
      * @brief Parse a block expression.
      *

include/vix/template/Renderer.hpp

@@ -17,8 +17,11 @@
 #define VIX_TEMPLATE_RENDERER_HPP
 
 #include <string>
+#include <unordered_map>
+#include <vector>
 
 #include <vix/template/AST.hpp>
+#include <vix/template/Builtins.hpp>
 #include <vix/template/Context.hpp>
 #include <vix/template/RenderResult.hpp>
 
@@ -30,12 +33,16 @@ namespace vix::template_
    * Renderer walks the parsed AST and produces the final textual output
    * using the provided runtime context.
    *
-   * Supported V1 nodes:
+   * Supported V2 nodes:
    * - RootNode
    * - TextNode
    * - VariableNode
    * - IfNode
    * - ForNode
+   *
+   * Variable nodes may include a filter pipeline such as:
+   * - {{ name | upper }}
+   * - {{ items | length }}
    */
   class Renderer
   {
@@ -96,6 +103,9 @@ namespace vix::template_
     /**
      * @brief Render a variable node.
      *
+     * Variable rendering resolves the source variable, applies filters
+     * in declaration order, then converts the final value to string.
+     *
      * @param node Variable node.
      * @param context Runtime rendering context.
      * @param output Output string buffer.
@@ -140,11 +150,37 @@ namespace vix::template_
         const std::string &name,
         const Context &context) const noexcept;
 
+    /**
+     * @brief Apply a filter pipeline to a value.
+     *
+     * Filters are applied from left to right.
+     *
+     * Example:
+     * {{ name | upper | length }}
+     *
+     * This means:
+     * 1. resolve name
+     * 2. apply upper
+     * 3. apply length
+     *
+     * @param input Initial value.
+     * @param filters Ordered filter pipeline.
+     * @return Transformed value.
+     */
+    [[nodiscard]] Value apply_filters(
+        const Value &input,
+        const std::vector<FilterNode> &filters) const;
+
   private:
     /**
      * @brief Whether HTML escaping is enabled for variable output.
      */
     bool auto_escape_html_{true};
+
+    /**
+     * @brief Built-in filter registry.
+     */
+    std::unordered_map<std::string, Filter> filters_;
   };
 
 } // namespace vix::template_

src/Parser.cpp

@@ -18,6 +18,7 @@
 
 #include <memory>
 #include <utility>
+#include <vector>
 
 namespace vix::template_
 {
@@ -59,6 +60,7 @@ namespace vix::template_
     {
       ++pos_;
     }
+
     return token;
   }
 
@@ -140,9 +142,27 @@ namespace vix::template_
     const Token &name =
         expect(TokenType::Identifier, "expected identifier inside variable expression");
 
+    std::vector<FilterNode> filters = parse_filters();
+
     expect(TokenType::VariableClose, "expected '}}'");
 
-    return std::make_unique<VariableNode>(name.value);
+    return std::make_unique<VariableNode>(name.value, std::move(filters));
+  }
+
+  std::vector<FilterNode> Parser::parse_filters()
+  {
+    std::vector<FilterNode> filters;
+
+    while (check(TokenType::Operator, "|"))
+    {
+      advance();
+
+      const Token &filter_name =
+          expect(TokenType::Identifier, "expected filter name after '|'");
+      filters.emplace_back(filter_name.value);
+    }
+
+    return filters;
   }
 
   NodePtr Parser::parse_block()

src/Renderer.cpp

@@ -20,7 +20,8 @@
 namespace vix::template_
 {
   Renderer::Renderer(bool auto_escape_html)
-      : auto_escape_html_(auto_escape_html)
+      : auto_escape_html_(auto_escape_html),
+        filters_(Builtins::filters())
   {
   }
 
@@ -98,12 +99,11 @@ namespace vix::template_
       std::string &output) const
   {
     const Value *value = resolve_variable(node.name(), context);
-    if (value == nullptr)
-    {
-      return;
-    }
 
-    std::string rendered = value->to_string();
+    const Value initial = (value != nullptr) ? *value : Value{};
+    Value transformed = apply_filters(initial, node.filters());
+
+    std::string rendered = transformed.to_string();
     if (auto_escape_html_)
     {
       rendered = Escape::html(rendered);
@@ -174,4 +174,24 @@ namespace vix::template_
     return context.get(name);
   }
 
+  Value Renderer::apply_filters(
+      const Value &input,
+      const std::vector<FilterNode> &filters) const
+  {
+    Value current = input;
+
+    for (const auto &filter : filters)
+    {
+      const auto it = filters_.find(filter.name());
+      if (it == filters_.end())
+      {
+        throw RendererError("unknown filter: " + filter.name());
+      }
+
+      current = it->second(current);
+    }
+
+    return current;
+  }
+
 } // namespace vix::template_

tests/parser_test.cpp

@@ -59,6 +59,38 @@ static void test_parse_variable()
       static_cast<const VariableNode *>(root.children()[1].get());
 
   assert(var->name() == "name");
+  assert(var->filters().empty());
+}
+
+static void test_parse_variable_with_one_filter()
+{
+  RootNode root = parse_template("{{ name | upper }}");
+
+  assert(root.children().size() == 1);
+  assert(root.children()[0]->type() == NodeType::Variable);
+
+  const auto *var =
+      static_cast<const VariableNode *>(root.children()[0].get());
+
+  assert(var->name() == "name");
+  assert(var->filters().size() == 1);
+  assert(var->filters()[0].name() == "upper");
+}
+
+static void test_parse_variable_with_multiple_filters()
+{
+  RootNode root = parse_template("{{ name | upper | length }}");
+
+  assert(root.children().size() == 1);
+  assert(root.children()[0]->type() == NodeType::Variable);
+
+  const auto *var =
+      static_cast<const VariableNode *>(root.children()[0].get());
+
+  assert(var->name() == "name");
+  assert(var->filters().size() == 2);
+  assert(var->filters()[0].name() == "upper");
+  assert(var->filters()[1].name() == "length");
 }
 
 static void test_parse_if()
@@ -100,6 +132,7 @@ static void test_parse_for()
       static_cast<const VariableNode *>(for_node->body()[0].get());
 
   assert(var->name() == "item");
+  assert(var->filters().empty());
 }
 
 static void test_parse_nested_if_in_for()
@@ -128,6 +161,8 @@ int main()
 {
   test_parse_text();
   test_parse_variable();
+  test_parse_variable_with_one_filter();
+  test_parse_variable_with_multiple_filters();
   test_parse_if();
   test_parse_for();
   test_parse_nested_if_in_for();