From 894ad66bc1d1fa0872481d1f2be689df465e7072 Mon Sep 17 00:00:00 2001 From: semihalev Date: Tue, 11 Mar 2025 23:14:10 +0300 Subject: [PATCH] Update documentation for new features MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Add detailed README sections for sandbox mode, parent function, and whitespace control - Create dedicated wiki pages for each new feature - Update release notes for v1.0.3 - Update Home wiki page to include links to new documentation 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude --- README.md | 123 ++++++++++++++++++++++++++++++++++++++++++++++- RELEASE_NOTES.md | 44 +++++++++++++++++ 2 files changed, 166 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 75c7fb9..b4b5854 100644 --- a/README.md +++ b/README.md @@ -1022,6 +1022,125 @@ Contributions are welcome! Here's how you can contribute: Please make sure your code passes all tests and follows the existing code style. +## Security: Sandbox Mode + +Twig's sandbox mode provides a safe way to evaluate template code with restricted permissions. This is particularly useful when including templates from untrusted sources. + +### Basic Sandbox Usage + +```go +// Create a new Twig engine +engine := twig.New() + +// Create a security policy that restricts what functions and filters can be used +policy := twig.NewDefaultSecurityPolicy() + +// Customize allowed functions and filters +policy.AllowedFunctions["safe_function"] = true +policy.AllowedFilters["safe_filter"] = true + +// Enable sandbox mode with the policy +engine.EnableSandbox(policy) +``` + +### Sandboxed Includes + +The most common use for sandbox mode is including templates with restricted permissions: + +```twig +{# Include a template in sandbox mode with restricted permissions #} +{% include 'user_content.twig' sandboxed %} +``` + +When a template is included with the `sandboxed` option: +1. The included template runs in a sandbox with the security policy +2. Any functions or filters not explicitly allowed will fail +3. The main template remains unaffected by the sandbox restrictions + +### Default Security Policy + +The `DefaultSecurityPolicy` provides sensible defaults: +- Allows common, safe functions like `range`, `cycle`, `date`, etc. +- Allows safe filters like `escape`, `upper`, `lower`, etc. +- Allows basic control tags like `if`, `for`, `set`, etc. + +You can customize this policy by adding or removing items from: +- `AllowedFunctions`: Map of allowed function names +- `AllowedFilters`: Map of allowed filter names +- `AllowedTags`: Map of allowed tag names + +## Parent Function + +The `parent()` function allows blocks in child templates to access and render the content of the same block from the parent template. This is useful for extending rather than completely replacing block content. + +```twig +{# base.twig #} + + + + {% block title %}Default Title{% endblock %} + + +
{% block header %}Default Header{% endblock %}
+
{% block content %}Default Content{% endblock %}
+
{% block footer %}Default Footer{% endblock %}
+ + + +{# child.twig #} +{% extends "base.twig" %} + +{% block title %}Child Page - {{ parent() }}{% endblock %} + +{% block header %} +

Child Header

+ {{ parent() }} +{% endblock %} + +{% block content %} +

This is the child content that overrides the parent.

+{% endblock %} +``` + +When rendered, the `child.twig` template will: +- Render "Child Page - Default Title" as the title (combining its content with the parent's) +- Output the child's header content followed by the parent's header content +- Completely replace the parent's content block + +The `parent()` function is especially useful for: +- Adding to inherited CSS or JavaScript blocks +- Extending headers or footers without duplicating content +- Building complex layout hierarchies + +## Whitespace Control + +Twig provides fine-grained control over whitespace in templates using the dash (`-`) modifier: + +```twig +
+ {{- value -}} {# Trims whitespace before and after output #} +
+ +{# Output:
value
(no whitespace between the tags and value) #} +``` + +Whitespace control modifiers can be applied to any tag: + +- `{{- ... }}`: Removes whitespace before the output +- `{{ ... -}}`: Removes whitespace after the output +- `{%- ... %}`: Removes whitespace before the block tag +- `{% ... -%}`: Removes whitespace after the block tag + +This allows for clean, readable template code without producing unwanted whitespace in the output: + +```twig +{% for item in items -%} + {{ item }} +{%- endfor %} + +{# No whitespace between items #} +``` + ## Roadmap ✅ Features already implemented: @@ -1030,10 +1149,12 @@ Please make sure your code passes all tests and follows the existing code style. - Template inheritance and includes - Filters and functions - HTML escaping and safety +- Sandbox mode for enhanced security +- Whitespace control with dash modifiers +- Parent function for block inheritance Future development plans include: -- Expanded sandbox mode for enhanced security - Additional optimization techniques for macro evaluation - Template profiling tools for performance analysis - Additional loader types diff --git a/RELEASE_NOTES.md b/RELEASE_NOTES.md index 5e7b41a..9f9a2d7 100644 --- a/RELEASE_NOTES.md +++ b/RELEASE_NOTES.md @@ -1,3 +1,47 @@ +# Twig v1.0.3 Release Notes + +## New Features + +### Security Enhancement +- **Sandbox Mode**: Added comprehensive sandbox security system for templates + - Implemented a `SecurityPolicy` interface to restrict allowed functions, filters, and tags + - Added `DefaultSecurityPolicy` with safe defaults for common operations + - Added `sandboxed` option to include tag for secure template inclusion + - Added engine-level sandbox control methods: `EnableSandbox()` and `DisableSandbox()` + +### Template Inheritance Enhancement +- **Parent Function**: Implemented `parent()` function for accessing parent block content + - Allows child templates to extend rather than completely replace block content + - Preserves proper inheritance chain for multi-level inheritance + - Enhanced block context tracking for proper parent reference resolution + +### Whitespace Control +- **Dash Modifiers**: Added support for whitespace control with dash modifiers (`-`) + - Added support for `{{- ... }}` and `{{ ... -}}` to trim whitespace before/after output + - Added support for `{%- ... %}` and `{% ... -%}` to trim whitespace before/after block tags + - Preserves template readability while controlling output formatting + +## Improvements +- **Code Organization**: Enhanced internal APIs for better maintainability +- **Documentation**: Updated README and wiki with new features +- **Code Quality**: Improved error handling and memory management +- **Performance**: Optimized context handling for sandboxed includes + +## Comprehensive Testing +- Added tests for all new functionality: + - Sandbox security policy tests + - Sandbox context tests + - Parent function in template inheritance + - Whitespace control with dash modifiers + +## Wiki Documentation +- Added wiki pages for new features: + - Sandbox mode and security policy + - Parent function and advanced template inheritance + - Whitespace control with examples + +--- + # Twig v1.0.2 Release Notes ## New Features