twig_ruby 0.0.2 → 0.0.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 31919ddaf84c7eb3ddbf272092cf86714ae8cc82daeaf3d9c1ea07a968a34957
-  data.tar.gz: 9e405d3820213e10efe310023576fa4d7fc10c8b132956cb86a1ce454e79568b
+  metadata.gz: 8d31d9c283bb71461856d6ddc7ee8b86b9364196d0b507a6ff9e6eceefcfb4e3
+  data.tar.gz: d364efbe75c87f5b1f1542162e441b8f92071d7414a767f43998eb3c191927ca
 SHA512:
-  metadata.gz: fe9835a8158b2f0c4e7e2147dc2055070b271539389715adfa9965eb131e052de3ce146b9677574e9005912e965c5f87f41da6a462ddc3e878e35854198df9cc
-  data.tar.gz: 291c349b4c7af42c23814a06bd4b12ddcb8182368bea8662ca0eb1bebafefb9ca2c61c100a255078b43d19e9a197f581a96ed3610f76cb68178be2a1eaffd65b
+  metadata.gz: 127f35f5679f70bf0ea083240bb122c946fd9ce4f0fa3e0837b1d1b9127986d96619c568862bd9f08eeff3be6f02c8df23313264ab21201333dfa9626523fe15
+  data.tar.gz: 30f7791e2f70e9934ff2fff4d58cc7e44e18762d9bade2b3a910b5f4bff987e86e612feb501e8a3644e009e1721d7f511c47881cd75da5be4af2def7c88382d9

data/README.md

@@ -0,0 +1,218 @@
+# twig-ruby
+
+Implementation of [Twig](https://twig.symfony.com/) in Ruby.
+
+## Table of Contents
+
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Template Features](#template-features)
+  - [Filters](#filters)
+  - [Functions](#functions)
+  - [Tests](#tests)
+  - [Tags](#tags)
+- [Rails Integration](#rails-integration)
+- [Advanced Features](#advanced-features)
+- [Configuration](#configuration)
+- Advanced Docs
+  - [Loaders](doc/loaders.md)
+  - [Extensions](doc/extensions.md)
+
+## Installation
+
+```bash
+bundle add twig-ruby
+```
+
+## Quick Start
+
+Here's a simple example to get you started:
+
+```ruby
+require 'twig_ruby'
+
+# Create a loader with your templates
+loader = Twig::Loader::Hash.new({
+  'hello.twig' => 'Hello {{ name }}!'
+})
+
+# Create environment and render
+environment = Twig::Environment.new(loader)
+template = environment.load('hello.twig')
+puts template.render({ name: "World" })
+# Output: Hello World!
+```
+
+Or from your file system:
+
+```ruby
+loader = Twig::Loader::Filesystem.new(__dir__, ['app/views'])
+```
+
+## Template Features
+
+Twig has the notion of Filters, Functions, and Tests
+
+### Filters
+
+Filters are used to modify variables.
+
+```twig
+{{ "hello"|capitalize }} {# Hello #}
+{{ ["Hello", "World"]|join(" ") }} {# Hello World #}
+```
+
+### Functions
+
+Functions are used to generate content.
+
+```twig
+{{ max([1, 2, 3]) }} {# 3 #}
+{{ include("other.twig") }} {# contents of other.twig #}
+```
+
+### Tests
+
+Tests are used to evaluate variables.
+
+```twig
+{{ 2 is even ? 'yup' : 'nope' }} {# yup #}
+{{ ([1, 2, 3] has some n => n % 2 == 0) ? 'yup' : 'nope' }} {# yup #}
+```
+
+### Tags
+
+Tags are used to control the logic of the template.
+
+```twig
+{% if n > 1 %}
+  Some
+{% else %}
+  None
+{% endif %}
+```
+
+```twig
+<ul>
+  {% for i in [1, 2, 3] %}
+    <li>Item {{ i }}</li>
+  {% endfor %}
+</ul>
+```
+
+## Rails Integration
+
+This gem includes a Railtie that will automatically add your views folder and
+register a `:twig` template handler. Just simply create your views such as
+`app/views/welcome/index.html.twig` and it will start rendering them.
+
+```twig
+{# welcome/index.html.twig #}
+
+{% extends 'base.html.twig' %}
+
+{% block body %}
+  Welcome to my site!
+{% endblock %}
+```
+
+Since Twig supports layouts through template inheritance (which is more flexible than Rails layouts),
+you'll typically want to use Twig's inheritance system instead of Rails layouts. This allows you to:
+
+1. Create a base template with common structure
+2. Override specific blocks in child templates
+3. Nest layouts for more complex page structures
+
+To use Twig's inheritance instead of Rails layouts, disable Rails layouts in your controller:
+
+```ruby
+class ApplicationController < ActionController::Base
+  layout false
+end
+```
+
+## Configuration
+
+These are all the defaults. You only need this configuration if you plan to change anything. 
+
+```ruby
+Rails.application.configure do
+  config.twig.root = ::Rails.root # Used for default Filesystem Loader
+  config.twig.paths = %w[/ app/views/] # Used for default Filesystem Loader
+  config.twig.debug = ::Rails.env.development?
+  config.twig.allow_helper_methods = true
+  config.twig.cache = ::Rails.root.join('tmp/cache/twig').to_s
+  config.twig.charset = 'UTF-8'
+  config.twig.strict_variables = true
+  config.twig.autoescape = :name
+  config.twig.auto_reload = nil
+  config.twig.loader = lambda do
+    ::Twig::Loader::Filesystem.new(
+      current.root,
+      current.paths
+    )
+  end
+end
+```
+
+The loader is memoized as late as possible, so if you need to actually access the loader instance, you can
+use `Twig.loader` to create the instance. If you do this, you can no longer set a new loader with the config
+or paths. You would need to use any available methods on the loader to alter it:
+
+```ruby
+config.after_initialize do
+  Twig.loader.prepend_path('app/views/theme', 'theme')
+end
+```
+
+If you plan to create your own loader that loads templates from another source like the database, you can provide
+a different lamba in the config for initializing it. 
+
+## Advanced Features
+
+Twig Ruby supports symbols as Ruby does and can be used in places strings can as 
+hash keys, arguments, etc.
+
+```twig
+{{ name[:first] }}
+{{ user_func(:first, :second) }}
+{% set hash = { key: :value } %}
+```
+
+Since Ruby has the concept of blocks, a new tag is introduced call `yield` it
+can be used with helpers like `form_with`
+
+```twig
+{% yield form_with(url: 'login') do |f| %}
+  {{ f.email_field(:email) }}
+{% endyield %}
+```
+### Cache Tag
+
+The way the `cache` tag works in Rails is that it captures output from the buffer that 
+sends the contents of the response. Twig cannot do this prematurely since a cache might be used within
+a block or other callable meant to return the string. There is a cache tag to handle this instead 
+that is passed the same arguments it normally would, but has extra code to capture the cache. 
+Using `{% yield cache() do %}` WILL NOT WORK CORRECTLY.
+
+```twig
+{% cache(product) %}
+  ...
+{% endcache %}
+```
+
+Macros can also use Ruby notation for default values:
+
+Typical Twig:
+```twig
+{% macro input(name, value, type = "text", size = 20) %}
+  <input type="{{ type }}" name="{{ name }}" value="{{ value|e }}" size="{{ size }}"/>
+{% endmacro %}
+```
+
+Twig Ruby (Both versions work)
+```twig
+{% macro input(name, value, type: "text", size: 20) %}
+  <input type="{{ type }}" name="{{ name }}" value="{{ value|e }}" size="{{ size }}"/>
+{% endmacro %}
+```

data/lib/tasks/twig_parity.rake

@@ -150,7 +150,7 @@ class TwigFixture
       replace(template, replacements[:fixture]) + (' ' * index)
     end
 
-    loader = ::Twig::Loader::Array.new(gsub_templates)
+    loader = ::Twig::Loader::Hash.new(gsub_templates)
     environment = ::Twig::Environment.new(loader, {
       cache: false,
       strict_variables: true,

data/lib/twig/environment.rb

@@ -137,7 +137,7 @@ module Twig
              end
 
       chain_loader = Loader::Chain.new([
-        Loader::Array.new({ name => template }),
+        Loader::Hash.new({ name => template }),
         current = loader,
       ])
 

data/lib/twig/extension/core.rb

@@ -997,7 +997,7 @@ module Twig
           (object.respond_to?(:empty?) && object.empty?) ||
           (object.respond_to?(:length) && (object.length&.== 0)) || # rubocop:disable Style/ZeroLengthPredicate
           (object.respond_to?(:size) && (object.size&.== 0)) || # rubocop:disable Style/ZeroLengthPredicate
-          (object.respond_to?(:to_s) && (object.to_s&.== ''))
+          (object.respond_to?(:to_s) && (object.to_s == ''))
       end
 
       # @param [Environment] environment

data/lib/twig/loader/{array.rb → hash.rb}

@@ -2,7 +2,7 @@
 
 module Twig
   module Loader
-    class Array < Loader::Base
+    class Hash < Loader::Base
       # @param [Hash<String>] templates
       def initialize(templates)
         super()

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: twig_ruby
 version: !ruby/object:Gem::Version
-  version: 0.0.2
+  version: 0.0.4
 platform: ruby
 authors:
 - Craig Blanchette
 - Fabian Potencier
 bindir: bin
 cert_chain: []
-date: 2025-07-23 00:00:00.000000000 Z
+date: 2025-07-30 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -44,6 +44,7 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- README.md
 - lib/tasks/twig_parity.rake
 - lib/twig/auto_hash.rb
 - lib/twig/cache/base.rb
@@ -83,10 +84,10 @@ files:
 - lib/twig/extension_set.rb
 - lib/twig/file_extension_escaping_strategy.rb
 - lib/twig/lexer.rb
-- lib/twig/loader/array.rb
 - lib/twig/loader/base.rb
 - lib/twig/loader/chain.rb
 - lib/twig/loader/filesystem.rb
+- lib/twig/loader/hash.rb
 - lib/twig/node/auto_escape.rb
 - lib/twig/node/base.rb
 - lib/twig/node/block.rb
@@ -219,9 +220,11 @@ files:
 - lib/twig_ruby.rb
 homepage: https://rubygems.org/gems/twig-ruby
 licenses:
-- MIT
+- BSD-3-Clause
 metadata:
+  allowed_push_host: https://rubygems.org
   rubygems_mfa_required: 'true'
+  source_code_uri: https://github.com/isometriks/twig-ruby
 rdoc_options: []
 require_paths:
 - lib