rux 1.1.2 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 74fe5ea5efe72399854ca97874db7ae0f9aa59abcc9201fc31725991881148b5
-  data.tar.gz: 5a07947618af42f689f84784ed6a4ce095ef4693cd6e6187008cd4a5cf774b4c
+  metadata.gz: e2874b5336b991b08b274df04219d2c7b97247580f0587dfc3b6860e913d8af8
+  data.tar.gz: ba582dd96d6c58da357295e60267f4db9a6cdf47ddc99aa2740d590a1cec530d
 SHA512:
-  metadata.gz: fe10394671a5d56275289a84013f85ae13bf84c6690febf2906ed63d54005c13aee9417db3285855a75e3fc85484b51b84daa596223cd16844ecd4fbe008d728
-  data.tar.gz: 368880ab3405473e61114d846ec3aa54ced6490a070abd358857fcba21b373b8dcfad5eeb8a4b1100b6429a97c24e642b2c4e60bb33384baa3b9da2194d251ab
+  metadata.gz: c6c663d6d237fb6fc044dc2ebfa9c706d54eb5cdd3bc7a50011d82578ac7aab36a8f6c1ca466754f44bfed73ce708fc57bbd0ea3951681febd79f2730e7fd1d7
+  data.tar.gz: fb52a3a10cb3db47817acc7d760210758bc733b3b74b4ebfc9d241039d8d38ce00d4622957fd26effa7593acefe4d9387ebce9bcc6bab7dd20d83e9523b62322

data/CHANGELOG.md

@@ -1,3 +1,27 @@
+# 1.3.0
+* Automatically add generated files to an ignore file, eg. .gitignore.
+  - Pass the --ignore-path=PATH flag to ruxc to indicate the file to update.
+* Add the ruxlex executable that prints parser tokens for debugging purposes.
+* Preserve Ruby comments in generated files.
+* Fix the `as:` argument, which was being improperly generated in earlier versions.
+* General parser improvements.
+  - Allows fragments to be nested within other tags.
+  - Allows tags after ruby code in branch structures like `if..else`.
+* Allows HTML attributes to start with `@`.
+
+# 1.2.0
+* Improve output safety.
+  - HTML tags are now automatically escaped when they come from Ruby code.
+* Add fragment support.
+  - Analogous to JSX fragments, eg. `<>foo</>`.
+* Add keyword argument support in HTML attributes.
+  - Eg. `<div {**kwargs} bar="baz">boo</div>`.
+* Add ViewComponent slot support.
+  - Works via pseudo components that begin with `With`, eg. `<MySlotComponent><WithItem>Item</WithItem></MySlotComponent>`.
+* Allow printing `ruxc` results to STDOUT.
+* Support for unquoted attributes.
+* Drop explicit support for Ruby versions < 3.
+
 # 1.1.2
 * Don't slugify HTML attributes in the tag builder either.
 

data/Gemfile

@@ -3,7 +3,14 @@ source 'https://rubygems.org'
 gemspec
 
 group :development, :test do
-  gem 'pry-byebug'
+  gem 'debug'
   gem 'rake'
   gem 'rspec'
 end
+
+group :development do
+  gem 'appraisal'
+  gem 'appraisal-run'
+end
+
+gem 'csv'

data/README.md

@@ -148,6 +148,94 @@ end
 
 Notice we were able to embed Ruby within rux within Ruby within rux. Within Ruby. The rux parser supports unlimited levels of nesting, although you'll probably not want to go _too_ crazy.
 
+## Slots
+
+Rux fully supports the view_component gem's [slots feature](https://viewcomponent.org/guide/slots.html), which allows a component to expose specific points in the rendered output where the caller can provide their own content. Let's look at a table component that exposes rows and columns via slots:
+
+```ruby
+class TableComponent < ViewComponent::Base
+  renders_many :rows, RowComponent
+
+  def call
+    <table>
+      {rows.each do |row|
+        <>{row}</>
+      end}
+    </table>
+  end
+end
+
+class RowComponent < ViewComponent::Base
+  renders_many :columns, ColumnComponent
+
+  def call
+    <tr>
+      {columns.each do |column|
+        <>{column}</>
+      end}
+    </tr>
+  end
+end
+
+class ColumnComponent < ViewComponent::Base
+  def call
+    <td>{content}</td>
+  end
+end
+```
+
+Notice the use of rux fragments (analogous to JSX fragments) via the `<></>` syntax. This allows emitting a slot by dropping back to ruby via rux.
+
+The `TableComponent` might be rendered in an ERB template like so:
+
+```erb
+<%= render(TableComponent.new) do |table| %>
+  <% table.with_row do |row| %>
+    <% row.with_column { "Row 1, Col 1" } %>
+    <% row.with_column { "Row 1, Col 2" } %>
+  <% end %>
+  <% table.with_row do |row| %>
+    <% row.with_column { "Row 2, Col 1" } %>
+    <% row.with_column { "Row 2, Col 2" } %>
+  <% end %>
+<% end %>
+```
+
+Notice the slots are "filled in" using the `#with_row` and `#with_column` methods. In rux, these methods become components:
+
+```ruby
+<TableComponent>
+  <WithRow>
+    <WithColumn>Row 1, Col 1</WithColumn>
+    <WithColumn>Row 1, Col 2</WithColumn>
+  </WithRow>
+  <WithRow>
+    <WithColumn>Row 2, Col 1</WithColumn>
+    <WithColumn>Row 2, Col 2</WithColumn>
+  </WithRow>
+</TableComponent>
+```
+
+## The `as:` argument
+
+In ViewComponent, component instances are yielded to the block on `#render`, eg:
+
+```erb
+<%= render(MyComponent.new) do |component| %>
+  <%# 'component' is the instance of MyComponent passed to #render above %>
+<% end %>
+```
+
+Most of the time in rux, a reference to the component instance isn't necessary (see the section on slots above). Occasionally however it can be useful to, for example, call methods on the component instance to query its state, etc. Use the `as:` argument to assign the component instance to a local variable that's available inside the tag body:
+
+```ruby
+<TableComponent something={value} as={table}>
+  {if table.something
+    # your code here
+  end}
+</TableComponent>
+```
+
 ## Keyword Arguments Only
 
 Any view component that will be rendered by rux must _only_ accept keyword arguments in its constructor. For example:

data/bin/ruxc

@@ -5,6 +5,7 @@ $:.push(File.expand_path('./lib'))
 require 'pathname'
 require 'optparse'
 require 'rux'
+require 'onload'
 
 class RuxCLI
   def self.parse(argv)
@@ -14,8 +15,9 @@ class RuxCLI
     end
 
     options = {
-      recursive: false,
-      pretty: true
+      pretty: true,
+      stdout: false,
+      ignore_path: nil,
     }
 
     if argv.first != '-h' && argv.first != '--help'
@@ -33,6 +35,22 @@ class RuxCLI
         end
       end
 
+      oneline(<<~DESC).tap do |desc|
+        Print results to STDOUT instead of writing files to disk.
+      DESC
+        opts.on('-o', '--stdout', desc) do |stdout|
+          options[:stdout] = stdout
+        end
+      end
+
+      oneline(<<~DESC).tap do |desc|
+        Update the given git ignore file with transpiled file paths.
+      DESC
+        opts.on('-i', '--ignore-path=PATH', desc) do |ignore_path|
+          options[:ignore_path] = ignore_path
+        end
+      end
+
       opts.on('-h', '--help', 'Prints this help info') do
         puts opts
         exit
@@ -79,8 +97,21 @@ class RuxCLI
     @options[:pretty]
   end
 
+  def write_to_stdout?
+    @options[:stdout]
+  end
+
+  def ignore_file
+    return nil unless ignore_path
+    @ignore_file ||= Onload::IgnoreFile.load(ignore_path)
+  end
+
   private
 
+  def ignore_path
+    @options[:ignore_path]
+  end
+
   def directory?
     File.directory?(in_path)
   end
@@ -89,8 +120,19 @@ end
 cli = RuxCLI.parse(ARGV)
 cli.validate
 
-cli.each_file do |in_file, out_file, rbi_file|
+at_exit do
+  cli.ignore_file&.persist!
+end
+
+cli.each_file do |in_file, out_file|
   rux_file = Rux::File.new(in_file)
-  rux_file.write(out_file, pretty: cli.pretty?)
-  puts "Wrote #{out_file}"
+
+  if cli.write_to_stdout?
+    puts rux_file.to_ruby(pretty: cli.pretty?)
+  else
+    rux_file.write(out_file, pretty: cli.pretty?)
+    puts "Wrote #{out_file}"
+
+    cli.ignore_file&.add(out_file)
+  end
 end

data/bin/ruxlex

@@ -0,0 +1,13 @@
+#! /usr/bin/env ruby
+
+$:.push(File.expand_path('./lib'))
+
+require 'rux'
+
+code = STDIN.read
+result = Rux::Lexer.lex(code)
+
+result.each do |(type, (str, loc))|
+  loc_str = loc.to_range.to_s.rjust(12, " ")
+  puts "#{loc_str} #{type} #{str.inspect}"
+end

data/lib/rux/ast/attr_node.rb

@@ -0,0 +1,22 @@
+module Rux
+  module AST
+    class AttrNode
+      attr_reader :name, :value, :name_pos
+      attr_accessor :tag_node
+
+      def initialize(name, value, name_pos)
+        @name = name
+        @value = value
+        @name_pos = name_pos
+      end
+
+      def accept(visitor)
+        visitor.visit_attr(self)
+      end
+
+      def ruby_code?
+        false
+      end
+    end
+  end
+end

data/lib/rux/ast/attrs_node.rb

@@ -0,0 +1,30 @@
+module Rux
+  module AST
+    class AttrsNode
+      include Enumerable
+
+      attr_reader :attrs, :pos
+
+      def initialize(attrs, pos)
+        @attrs = attrs
+        @pos = pos
+      end
+
+      def accept(visitor)
+        visitor.visit_attrs(self)
+      end
+
+      def each(&block)
+        attrs.each(&block)
+      end
+
+      def empty?
+        attrs.empty?
+      end
+
+      def get(name)
+        find { |attr| attr.name == name }
+      end
+    end
+  end
+end

data/lib/rux/ast/fragment_node.rb

@@ -0,0 +1,15 @@
+module Rux
+  module AST
+    class FragmentNode
+      attr_reader :children
+
+      def initialize
+        @children = []
+      end
+
+      def accept(visitor)
+        visitor.visit_fragment(self)
+      end
+    end
+  end
+end

data/lib/rux/ast/root_node.rb

@@ -0,0 +1,19 @@
+module Rux
+  module AST
+    class RootNode
+      attr_reader :list
+
+      def initialize(list)
+        @list = list
+      end
+
+      def accept(visitor)
+        visitor.visit_root(self)
+      end
+
+      def children
+        @children ||= [list]
+      end
+    end
+  end
+end

data/lib/rux/ast/ruby_attr_node.rb

@@ -0,0 +1,28 @@
+module Rux
+  module AST
+    class RubyAttrNode
+      attr_reader :ruby_node
+      attr_accessor :tag_node
+
+      def initialize(ruby_node)
+        @ruby_node = ruby_node
+      end
+
+      def code
+        ruby_node.code
+      end
+
+      def accept(visitor)
+        visitor.visit_attr(self)
+      end
+
+      def ruby_code?
+        true
+      end
+
+      def name
+        nil
+      end
+    end
+  end
+end

data/lib/rux/ast/string_node.rb

@@ -1,10 +1,12 @@
 module Rux
   module AST
     class StringNode
-      attr_reader :str
+      attr_reader :str, :quote_type, :pos
 
-      def initialize(str)
+      def initialize(str, quote_type, pos)
         @str = str
+        @quote_type = quote_type
+        @pos = pos
       end
 
       def accept(visitor)

data/lib/rux/ast/tag_node.rb

@@ -3,9 +3,10 @@ module Rux
     class TagNode
       attr_reader :name, :attrs, :children
 
-      def initialize(name, attrs)
+      def initialize(name, attrs, pos)
         @name = name
         @attrs = attrs
+        @pos = pos
         @children = []
       end
 
@@ -16,6 +17,14 @@ module Rux
       def component?
         name.start_with?(/[A-Z]/)
       end
+
+      def slot_component?
+        name.start_with?("With")
+      end
+
+      def slot_method
+        @slot_method ||= name.gsub(/(?<!^)([A-Z])/) { |x| "_#{x}" }.downcase
+      end
     end
   end
 end

data/lib/rux/ast/text_node.rb

@@ -5,8 +5,9 @@ module Rux
     class TextNode
       attr_reader :text
 
-      def initialize(text)
+      def initialize(text, pos)
         @text = text
+        @pos = pos
       end
 
       def accept(visitor)

data/lib/rux/ast.rb

@@ -1,9 +1,14 @@
 module Rux
   module AST
-    autoload :ListNode,   'rux/ast/list_node'
-    autoload :RubyNode,   'rux/ast/ruby_node'
-    autoload :StringNode, 'rux/ast/string_node'
-    autoload :TagNode,    'rux/ast/tag_node'
-    autoload :TextNode,   'rux/ast/text_node'
+    autoload :AttrNode,     'rux/ast/attr_node'
+    autoload :AttrsNode,    'rux/ast/attrs_node'
+    autoload :FragmentNode, 'rux/ast/fragment_node'
+    autoload :ListNode,     'rux/ast/list_node'
+    autoload :RootNode,     'rux/ast/root_node'
+    autoload :RubyAttrNode, 'rux/ast/ruby_attr_node'
+    autoload :RubyNode,     'rux/ast/ruby_node'
+    autoload :StringNode,   'rux/ast/string_node'
+    autoload :TagNode,      'rux/ast/tag_node'
+    autoload :TextNode,     'rux/ast/text_node'
   end
 end

data/lib/rux/buffer.rb

@@ -1,15 +1,33 @@
 module Rux
+  class SafeString < String
+    def html_safe?
+      true
+    end
+  end
+
   class Buffer
     def initialize(init_str = '')
       @string = init_str.dup
     end
 
-    def <<(*obj)
-      @string << obj.join
+    def append(obj)
+      Array(obj).each do |o|
+        @string << if o.respond_to?(:html_safe?) && o.html_safe?
+          o.to_s
+        else
+          CGI.escapeHTML(o.to_s)
+        end
+      end
+    end
+
+    def safe_append(obj)
+      Array(obj).each { |o| @string << o.to_s }
     end
 
     def to_s
-      @string
+      SafeString.new(@string)
     end
+
+    alias html_safe to_s
   end
 end

data/lib/rux/default_tag_builder.rb

@@ -1,19 +1,28 @@
 module Rux
   class DefaultTagBuilder
-    def call(tag_name, attributes = {})
-      attr_str = attributes.empty? ? '' : " #{serialize_attrs(attributes)}"
-      "<#{tag_name}#{attr_str}>" <<
-        (block_given? ? Array(yield) : []).join <<
-        "</#{tag_name}>"
+    def call(tag_name, attributes = {}, &block)
+      SafeString.new(build(tag_name, attributes, &block))
     end
 
     private
 
+    def build(tag_name, attributes = {})
+      attr_str = attributes.empty? ? '' : " #{serialize_attrs(attributes)}"
+
+      "<#{tag_name}#{attr_str}>".tap do |result|
+        if block_given?
+          Array(yield).each { |body| result << body }
+        end
+
+        result << "</#{tag_name}>"
+      end
+    end
+
     def serialize_attrs(attributes)
       ''.tap do |result|
         attributes.each_pair.with_index do |(k, v), idx|
           result << ' ' unless idx == 0
-          result << "#{k}=\"#{CGI.escape_html(v.to_s)}\""
+          result << "#{k}=\"#{v.to_s.gsub('"', "&quot;")}\""
         end
       end
     end

data/lib/rux/default_visitor.rb

@@ -2,8 +2,18 @@ require 'cgi'
 
 module Rux
   class DefaultVisitor < Visitor
+    def initialize
+      @render_stack = []
+    end
+
+    def visit_root(node)
+      visit_list(node.list)
+    end
+
     def visit_list(node)
-      node.children.map { |child| visit(child) }.join
+      ''.tap do |result|
+        node.children.each { |child| result << visit(child) }
+      end
     end
 
     def visit_ruby(node)
@@ -11,57 +21,124 @@ module Rux
     end
 
     def visit_string(node)
-      node.str
+      case node.quote_type
+        when :single
+          "'#{node.str}'"
+        else
+          "\"#{node.str}\""
+      end
     end
 
     def visit_tag(node)
       ''.tap do |result|
-        block_arg = if (as = node.attrs['as'])
-          visit(as)
+        block_arg = if (as = node.attrs.get('as'))
+          visit(as.value)
         end
 
-        at = node.attrs.each_with_object([]) do |(k, v), ret|
-          next if k == 'as'
-          ret << Utils.attr_to_hash_elem(k, visit(v), slugify: node.component?)
-        end
+        block_arg ||= "rux_block_arg#{@render_stack.size}"
 
-        if node.component?
+        if node.slot_component?
+          result << "(#{parent_render[:block_arg]}.#{node.slot_method}"
+
+          unless node.attrs.empty?
+            result << "(#{visit(node.attrs)})"
+          end
+        elsif node.component?
           result << "render(#{node.name}.new"
 
           unless node.attrs.empty?
-            result << "(#{at.join(', ')})"
+            result << "(#{visit(node.attrs)})"
           end
+
+          result << ')'
         else
           result << "Rux.tag('#{node.name}'"
 
           unless node.attrs.empty?
-            result << ", { #{at.join(', ')} }"
+            result << ", { #{visit(node.attrs)} }"
           end
+
+          result << ')'
         end
 
-        result << ')'
+        @render_stack.push({
+          component_name: node.name,
+          block_arg: block_arg
+        })
 
-        if node.children.size > 1
+        if node.children.size > 0
           result << " { "
-          result << "|#{block_arg}| " if block_arg
+          result << "|#{block_arg}| " if block_arg && node.component?
           result << "Rux.create_buffer.tap { |_rux_buf_| "
 
-          node.children.each do |child|
-            result << "_rux_buf_ << #{visit(child).strip};"
-          end
-
+          result << visit_tag_children(node).join
           result << " }.to_s }"
-        elsif node.children.size == 1
-          result << ' { '
-          result << "|#{block_arg}| " if block_arg
-          result << visit(node.children.first).strip
-          result << ' }'
         end
+
+        # don't pass instances of ViewComponent::Slot to _rux_buf_#<< by wrapping
+        # the slot setter return value in (retval; nil)
+        if node.slot_component?
+          result << "; nil)"
+        end
+
+        @render_stack.pop
+      end
+    end
+
+    def visit_tag_children(node)
+      node.children.map do |child|
+        append_statement_for(child)
+      end
+    end
+
+    def append_statement_for(node)
+      if node.is_a?(AST::TextNode)
+        "_rux_buf_.safe_append(#{visit(node).strip.chomp(';')});"
+      else
+        "_rux_buf_.append(#{visit(node).strip.chomp(';')});"
+      end
+    end
+
+    def visit_attrs(node)
+      visited_attrs = node.attrs.each_with_object([]) do |attr, memo|
+        memo << visit(attr) unless attr.name == "as"
+      end
+
+      visited_attrs.join(", ")
+    end
+
+    def visit_attr(node)
+      if node.ruby_code?
+        node.code
+      else
+        Utils.attr_to_hash_elem(
+          node.name,
+          visit(node.value),
+          slugify: node.tag_node.component?
+        )
+      end
+    end
+
+    def visit_fragment(node)
+      ''.tap do |result|
+        result << "Rux.create_buffer.tap { |_rux_buf_| "
+
+        node.children.each do |child|
+          result << append_statement_for(child)
+        end
+
+        result << " }.to_s;"
       end
     end
 
     def visit_text(node)
       "\"#{CGI.escape_html(node.text)}\""
     end
+
+    private
+
+    def parent_render
+      @render_stack.last
+    end
   end
 end