rblade 2.0.2 → 3.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fb23406b9206cc5eb7d20f10d700375c1b49c588c2805ae77710aff217ab39f1
-  data.tar.gz: '0330179c0e5113c74d0678c54fa08a489820f0d72ea21eb179caa372c7e54a42'
+  metadata.gz: 5760d0a2af4a86bf0ffcc9451abb3a46357029b9f5fea33afdf8305282c3d5e3
+  data.tar.gz: aaf764e044528fac1287219268ed117d332fd13204eb52971de9a88402665780
 SHA512:
-  metadata.gz: c592ebfb01c89d56e996c1e0c7815e50ab2363a2d9badb41a8573067b230796807392789418b81593eecbacfa1160b34843ba6bce102f600acd5ea08ca9a2521
-  data.tar.gz: dcb59ca067167dbbe63a4ea86b2fce0d04e25beb4fe728826abc1e19f33613a6d3a472a36896f55bbc0c97979d1c265fa4be8b20e8c0ec62569218099bb62d1a
+  metadata.gz: d38f0abf519963a665c5780a2e2328f4bc357455c2cbec99d49362eb76f4529ece7edd65b08ec4c9669700a2c0fca5feeade897fff938aa5c8ed64790f96c152
+  data.tar.gz: 4ef6e7d9bffb6b9a4360af6ffe7030d9cac15ce6b3c67da546af9739659cb68ea801f06e4ddeaa67f66ce48e4885d4b2931a090518d39b05b994592bd7db0447

data/.rubocop.yml

@@ -0,0 +1,24 @@
+AllCops:
+  DisabledByDefault: true
+  SuggestExtensions: false
+  TargetRubyVersion: 3.4
+  UseCache: true
+
+inherit_gem:
+  standard: config/base.yml
+
+# Enforce commas at the end of multiline arguments, hashes and arrays, improving git diffs
+Style/TrailingCommaInArrayLiteral:
+  EnforcedStyleForMultiline: diff_comma
+
+Style/TrailingCommaInHashLiteral:
+  EnforcedStyleForMultiline: diff_comma
+
+Style/TrailingCommaInArguments:
+  EnforcedStyleForMultiline: comma
+
+# Enforce standardisation of method definitions
+Style/MethodDefParentheses:
+  Enabled: true
+Naming/MethodName:
+  Enabled: true

data/CHANGELOG.md

@@ -1,3 +1,14 @@
+## 3.0.0 [2025-03-18]
+- Add ability to add raw directive handlers that add ruby code to the template
+- Add `RBlade.direct_component_rendering` option to allow RBlade components to be rendered directly
+- Add `component` view helper for rendering RBlade components in other templates
+- Add support for dynamic components using `<x-dynamic component="...">`
+- Improve performance of regular expressions
+- Refactor public RBlade methods
+- Remove deprecated "_required" option for props statement values (use "required" instead)
+- Update README
+- Fix issue with component tokenizer hanging
+
 ## 2.0.2 [2025-03-10]
 - Fix issue with empty component attributes
 

data/README.md

@@ -54,12 +54,14 @@ For a quick overview of RBlade's capabilities, refer to the [reference file](REF
       - [Retrieving and Filtering Attributes](#retrieving-and-filtering-attributes)
     + [Slots](#slots)
       - [Slot Attributes](#slot-attributes)
+    + [Dynamic Components](#dynamic-components)
     + [Registering Additional Component Directories](#registering-additional-component-directories)
     + [Index Components](#index-components)
   * [Forms](#forms)
     + [Old Input](#old-input)
     + [Method Field](#method-field)
   * [Stacks](#stacks)
+  * [Integrating RBlade With Other Templates](#rblade-integration)
 
 <a name="displaying-data"></a>
 ## Displaying Data
@@ -140,7 +142,7 @@ If you are displaying JavaScript variables in a large portion of your template,
     <div class="container">
         Hello, {{ name }}.
     </div>
-@endverbatim
+@endVerbatim
 ```
 
 <a name="rblade-directives"></a>
@@ -175,7 +177,7 @@ In addition to the conditional directives above, the `@blank?`, `defined?`, `@em
     // records is defined and is not nil
 @else
     // Since these directives are compiled to if statements, you can also use the @else directive
-@endempty?
+@endEmpty?
 ```
 
 <a name="environment-directives"></a>
@@ -304,12 +306,12 @@ The `@class` directive conditionally adds CSS classes. The directive accepts a H
     hasError = true;
 @endRuby
 
-<span @class({
+<span @class(
     "p-4": true,
     "font-bold": isActive,
     "text-gray-500": !isActive,
     "bg-red": hasError,
-})></span>
+)></span>
 
 <span class="p-4 text-gray-500 bg-red"></span>
 ```
@@ -321,10 +323,10 @@ Likewise, the `@style` directive can be used to conditionally add inline CSS sty
     isActive = true;
 @endRuby
 
-<span @style({
+<span @style(
     "background-color: red": true,
     "font-weight: bold" => isActive,
-})></span>
+)></span>
 
 <span style="background-color: red; font-weight: bold;"></span>
 ```
@@ -432,9 +434,7 @@ In some situations, it's useful to embed Ruby code into your views. You can use
 <a name="custom-directives"></a>
 ### Custom Directives
 
-RBlade also allows you to define your own directives using the `RBlade.register_directive_handler`
-method. When the compiler encounters the custom directive, it will call the provided block and
-output the returned value.
+RBlade also allows you to define your own output directives using the `RBlade.register_directive_handler` method. When the compiler encounters the custom directive, it will call the provided block and output the returned value.
 
 ```rblade
 RBlade::register_directive_handler('sum') do |args|
@@ -446,6 +446,17 @@ end
 @sum(1, 2, 3) -> 6
 ```
 
+The `RBlade.register_raw_directive_handler` method allows you to register a directive that outputs raw Ruby code into the template. When the compiler encounters the custom directive, it will call the provided block insert the returned value into the template. The returned ruby code must end in a semicolon, `;`.
+
+```rblade
+RBlade::register_raw_directive_handler('not') do |args|
+  "if !(#{args[0]});"
+end
+
+@not(true) 1 @endNot    -> ""
+@not(false) 1 @endNot   -> "1"
+```
+
 <a name="comments"></a>
 ### Comments
 
@@ -506,12 +517,26 @@ Namespaced components can be rendered using the namespace as a prefix to the nam
 <a name="passing-data-to-components"></a>
 ### Passing Data to Components
 
-You can pass data to RBlade components using HTML attributes. Hard-coded strings can be passed to the component using simple HTML attribute strings. Ruby expressions and variables should be passed to the component via attributes that use the `:` character as a prefix:
+You can pass data to RBlade components using HTML-style attributes. Within these attributes, you can use `{{ ... }}` to insert Ruby code.
+
+If the attribute name begins with a colon, `:`, the contents are parsed as Ruby.
 
 ```rblade
-<x-alert type="error" :message="message"/>
+@ruby(what = 'Something')
+@ruby(message = "#{what} happened!")
+
+{{-- The message attribute will be identical in all of the following components --}}
+<x-alert message="Something happened!"/>
+<x-alert message="{{ what }} happened!"/>
+<x-alert :message="message"/>
+<x-alert :message/>
+<x-alert message={{ message }}/>
+<x-alert message="{{ message }}"/>
 ```
 
+> [!NOTE]  
+> When using print blocks within an attribute, e.g. `{{ {hash: true} }}`, the contents will be converted to a string. If the print block is the entirety of the attribute, or the attribute name starts with a colon, the contents are passed through as-is.
+
 #### Component Properties
 
 You can define a component's data properties using a `@props` directive at the top of the component. You can then reference these properties using local variables within the template:
@@ -552,9 +577,13 @@ When passing attributes to components, you can also use a "short attribute" synt
 <a name="escaping-attribute-rendering"></a>
 #### Escaping Attribute Rendering
 
-Since some JavaScript frameworks such as Alpine.js also use colon-prefixed attributes, you can use a double colon (`::`) prefix to inform RBlade that the attribute is not a Ruby expression. For example, given the following component:
+Since some JavaScript frameworks such as Alpine.js also use colon-prefixed attributes, you can use a double colon (`::`) prefix to inform RBlade that the attribute is not a Ruby expression. For example, given the following template:
 
 ```rblade
+# The button component:
+<button {{ attributes }}>{{ slot }}</button>
+
+# Our template
 <x-button ::class="{ danger: isDeleting }">
     Submit
 </x-button>
@@ -591,7 +620,7 @@ All of the attributes that are not part of the component's constructor will auto
 Sometimes you can need to specify default values for attributes or merge additional values into some of the component's attributes. To accomplish this, you can use the attribute manager's `merge` method. This method is particularly useful for defining a set of default CSS classes that should always be applied to a component:
 
 ```rblade
-<div {{ attributes.merge({"class": "alert alert-#{type}"}) }}>
+<div {{ attributes.merge("class": "alert alert-#{type}") }}>
     {{ message }}
 </div>
 ```
@@ -618,7 +647,7 @@ Both the `class` and `style` attributes are combined this way when using the `at
 When merging attributes that are not `class` or `style`, the values provided to the `merge` method will be considered the "default" values of the attribute. However, unlike the `class` and `style` attributes, these defaults will be overwritten if the attribute is defined in the component tag. For example:
 
 ```rblade
-<button {{ attributes.merge({type: "button"}) }}>
+<button {{ attributes.merge(type: "button") }}>
     {{ slot }}
 </button>
 ```
@@ -645,7 +674,7 @@ The rendered HTML of the `button` component in this example would be:
 Sometimes you may wish to merge classes if a given condition is `true`. You can accomplish this via the `class` method, which accepts a Hash of classes where the array key contains the class or classes you wish to add, while the value is a boolean expression:
 
 ```rblade
-<div {{ attributes.class({'p-4': true, 'bg-red': hasError}) }}>
+<div {{ attributes.class('p-4': true, 'bg-red': hasError) }}>
     {{ message }}
 </div>
 ```
@@ -653,7 +682,7 @@ Sometimes you may wish to merge classes if a given condition is `true`. You can
 If you need to merge other attributes onto your component, you can chain the `merge` method onto the `class` method:
 
 ```rblade
-<button {{ attributes.class({'bg-red': hasError}).merge({type: 'button'}) }}>
+<button {{ attributes.class('bg-red': hasError).merge(type: 'button') }}>
     {{ slot }}
 </button>
 ```
@@ -809,6 +838,20 @@ Sometimes, you may wish to return early from a component without printing anythi
 ...
 ```
 
+<a name="dynamic-components"></a>
+### Dynamic Components
+
+Sometimes you may need to render a component but not know which component should be rendered until runtime. In this situation, you may use RBlades's built-in dynamic component to render the component based on a runtime value or variable:
+
+```rblade
+<% component_name = 'button' %>
+
+<x-dynamic :component="component_name"/>
+```
+
+> [!NOTE]  
+> Dynamic components use the `component` helper class, and thus don't take advantage of RBlade's performance improvements over using partials
+
 <a name="registering-additional-component-directories"></a>
 ### Registering Additional Component Directories
 
@@ -928,3 +971,27 @@ If you would like to prepend content onto the beginning of a stack, you should u
     This will be first...
 @endPrepend
 ```
+
+
+<a name="rblade-integration"></a>
+## Integrating RBlade With Other Templates
+
+You might want to use RBlade components within other templates, e.g. if you are using a component library that uses them. By default, RBlade components cannot be rendered directly, but this can be enabled using the `direct_component_rendering` option. 
+
+```ruby
+# config/initializers/rblade.rb
+
+# Enable partial rendering of RBlade components
+RBlade.direct_component_rendering = true
+```
+
+Once enabled, RBlade components can be rendered using `render partial: ...`. Block contents are passed to the component in the `slot` variable, `attributes` is initialized using `local_assigns`, and the `@props` directive will look for content set using `content_for`.
+
+```erb
+<%= render template: "components/button", locals: {class: "mt-4", slot: capture do %>
+  
+<% end } %>
+```
+
+> [!NOTE]  
+> RBlade's `{{ }}` print directives are automatically sent through Rails' `h` function to prevent XSS attacks.

data/REFERENCE.md

@@ -24,12 +24,14 @@ By default, RBlade will look for components in the `app/views/components` folder
 | `<x-component.name>...</x-component.name>`               | Render the component with the given slot content                                                                                           |
 | `<x-component.name>...<//>`                              | Short closing tag syntax (note: this bypasses some sanity checking during compilation)                                                     |
 | `<x-name attribute="STRING"/>`                           | Pass a string value to a component                                                                                                         |
+| `<x-name attribute="STRING{{ RUBY_EXPRESSION }}"/>`      | Pass a string value to a component with an interpolated ruby value                                                                         |
 | `<x-name :attribute="RUBY_EXPRESSION"/>`                 | Pass a ruby expression, executed in the local scope, to a component                                                                        |
 | `<x-name :attribute/>`                                   | Pass the `attribute` local variable into a component                                                                                       |
 | `<x-name @class({'bg-red-600': is_error})/>`             | Conditionally pass classes to a component                                                                                                  |
 | `<x-name @style({'bg-red-600': is_error})/>`             | Conditionally pass styles to a component                                                                                                   |
 | `<x-name attribute/>`                                    | Pass an attribute to a component with value `true`                                                                                         |
 | `<x-name {{ attributes }}/>`                             | Pass attributes to a child component                                                                                                       |
+| `<x-dynamic component="name"/>`                          | Dynamically render a component based on the runetime value of the `component` attribute                                                    |
 | `@props(header: "Header")`                               | Remove `header` from the attributes Hash and introduce it as a local variable, using the specified value as a default                      |
 | `@props(header: required)`                               | Remove `header` from the attributes Hash and introduce it as a local variable, raising an error if it is not set                           |
 | `{{ slot }}`                                             | Output the block content passed into the current component                                                                                 |
@@ -130,11 +132,11 @@ Note that the stack is printed once the current view or component finishes.
 
 ## Tips
 
-* Except for `@push`, `@prepend` and their variants, all end directives can simply be replaced with `@end` if preferred:
+* All end directives can simply be replaced with `@end` if preferred:
     -  `@nil?(...) ... @endnil?`
     -  `@nil?(...) ... @endnil`
     -  `@nil?(...) ... @end`
-* Except for `@ruby` and `@verbatim`, directives are case insensitive and can contain underscores. The following are identical:
+* Directives are case insensitive and can contain underscores. The following are identical:
     - `@pushonce`
     - `@pushOnce`
     - `@PushOnce` 

data/do

@@ -57,15 +57,15 @@ fi
 
 if [ "$1" == "cs" ] || [ "$1" == "c" ]
 then
-    echo Running: ${DOCKER_COMPOSE_COMMAND} run blade rake standard "${@:2}"
-    ${DOCKER_COMPOSE_COMMAND} run blade rake standard "${@:2}"
+    echo Running: ${DOCKER_COMPOSE_COMMAND} run blade rubocop "${@:2}"
+    ${DOCKER_COMPOSE_COMMAND} run blade rubocop "${@:2}"
     exit 0
 fi
 
 if [ "$1" == "cs:fix" ]
 then
-    echo Running: ${DOCKER_COMPOSE_COMMAND} run blade rake standard:fix "${@:2}"
-    ${DOCKER_COMPOSE_COMMAND} run blade rake standard:fix "${@:2}"
+    echo Running: ${DOCKER_COMPOSE_COMMAND} run blade rubocop --autocorrect "${@:2}"
+    ${DOCKER_COMPOSE_COMMAND} run blade rubocop --autocorrect "${@:2}"
     exit 0
 fi
 

data/docker-compose.yml

@@ -4,4 +4,7 @@ services:
     working_dir: /var/source
     volumes:
       - .:/var/source
-      - ./storage/bundle_cache:/usr/local/bundle
+      - ruby-gems:/usr/local/bundle
+
+volumes:
+  ruby-gems:

data/lib/rblade/compiler/compiles_comments.rb

@@ -6,8 +6,8 @@ module RBlade
       tokens.each do |token|
         next if token.type != :unprocessed
 
-        token.value.gsub!(/\{\{--.*?--\}\}/m, "")
-        token.value.gsub!(/<%#.*?%>/m, "")
+        token.value.gsub!(/\{\{--(?:[^-]++|-)*?--}}/, "")
+        token.value.gsub!(/<%#(?:[^%]++|-)*?%>/, "")
       end
     end
   end

data/lib/rblade/compiler/compiles_components.rb

@@ -34,12 +34,14 @@ module RBlade
 
     private
 
-    def compile_token_start token
+    def compile_token_start(token)
       component = {
-        name: token.value[:name]
+        name: token.value[:name],
       }
       @component_stack << component
 
+      return compile_dynamic_component(token) if component[:name] == "dynamic"
+
       attributes = compile_attributes token.value[:attributes]
 
       if component[:name].start_with? "slot::"
@@ -49,7 +51,26 @@ module RBlade
       end
     end
 
-    def compile_token_end token
+    def compile_dynamic_component(token)
+      component_index = token.value[:attributes].index { |item| item[:name] == "component" }
+      component = token.value[:attributes].delete_at(component_index)
+      component_value = case component[:type]
+      when "string"
+        process_string_attribute(component[:value])
+      when "ruby"
+        component[:value]
+      when "pass_through"
+        component[:name]
+      else
+        raise RBladeTemplateError.new "Component compiler: unexpected attribute type for component attribute (#{attribute[:type]})"
+      end
+
+      attributes = compile_attributes token.value[:attributes]
+
+      "@output_buffer.raw_buffer<<component(#{component_value}, '#{RBlade.escape_quotes(@component_store.current_view_name)}', #{attributes.join ","}) do;"
+    end
+
+    def compile_token_end(token)
       component = @component_stack.pop
       if component.nil?
         raise RBladeTemplateError.new "Unexpected closing tag </x-#{token.value[:name]}>"
@@ -62,7 +83,7 @@ module RBlade
       "end;"
     end
 
-    def compile_attributes attributes
+    def compile_attributes(attributes)
       attributes.map do |attribute|
         case attribute[:type]
         when "class"
@@ -86,7 +107,7 @@ module RBlade
     end
 
     def process_string_attribute(string)
-      result = string.split(/((?<!@)\{\{.*?\}\})/).map do |substring|
+      result = string.split(/((?<!@)\{\{(?:[^}]++|\})*?\}\})/).map do |substring|
         if substring.start_with?("{{") && substring.end_with?("}}")
           "(#{substring[2..-3]}).to_s"
         elsif !substring.empty?

data/lib/rblade/compiler/compiles_injections.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module RBlade
+  class CompilesInjections
+    def compile!(tokens)
+      tokens.map! do |token|
+        next(token) if token.type != :unprocessed
+
+        segments = token.value.split(/
+          (@?\{!!)(\s*+(?:[^!}%@]++|[!}%@])+?\s*+)(!!})
+          |
+          (@?\{\{)(\s*+(?:[^!}%@]++|[!}%@])+?\s*+)(}})
+          |
+          (\s?(?<!\w)@?@ruby)(\s++(?:[^!}%@]++|[!}%@])+?\s*+)((?<!\w)@end_?ruby(?!\w)\s?)
+          |
+          (<%%?=?=?)(\s*+(?:[^!}%@]++|[!}%@])+?\s*+)(%%?>)
+        /xi)
+
+        i = 0
+        while i < segments.count
+          case segments[i]
+          when "{{", "<%="
+            segments[i] = create_token(segments[i + 1].strip, true)
+          when "<%", /\A\s?@ruby\z/i
+            segments[i + 1].strip!
+            segments[i + 1] << ";" unless segments[i + 1].end_with?(";")
+            segments[i] = Token.new(type: :ruby, value: segments[i + 1])
+          when "{!!", "<%=="
+            segments[i] = create_token(segments[i + 1].strip, false)
+          when "@{!!", "@{{", /\A\s?@@ruby\z/i
+            segments[i].sub!("@", "")
+            segments[i] = Token.new(type: :raw_text, value: "#{segments[i]}#{segments[i + 1]}#{segments[i + 2]}")
+          when "<%%", "<%%=", "<%%=="
+            segments[i] = Token.new(type: :raw_text, value: "<#{segments[i].delete_prefix!("<%")}#{segments[i + 1]}%>")
+          when "", nil
+            segments.delete_at i
+            next
+          else
+            segments[i] = Token.new(type: :unprocessed, value: segments[i])
+            i += 1
+            next
+          end
+
+          segments.delete_at i + 1
+          segments.delete_at i + 1
+          i += 1
+        end
+
+        segments
+      end.flatten!
+    end
+
+    private
+
+    def create_token(expression, escape_html)
+      # Don't try to print ends
+      if expression.match?(/\A(?:}|end(?![[:alnum:]_]|[^\0-\177]))/i)
+        return Token.new(:ruby, "#{expression};")
+      end
+
+      segment_value = if escape_html
+        "@output_buffer.append=#{expression};"
+      # If this is a block, don't wrap in parentheses
+      elsif expression.match?(/
+        (?:\{|do)\s*+
+        (
+          \|\s*+
+          [a-zA-Z0-9_]++\s*+
+          (,\s*+[a-zA-Z0-9_]++)?\s*+
+          \|
+        )?
+        \z/x)
+        "@output_buffer.safe_expr_append=#{expression};"
+      else
+        "@output_buffer.raw_buffer<<(#{expression}).to_s;"
+      end
+
+      Token.new(:print, segment_value)
+    end
+  end
+end