span_view 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: a817462b757b21ce691f3c8c6a69db01a42ac1dc1a441fbca983c16621fbc76f
+  data.tar.gz: bcf9b53f48db929ee28596a65de0512adcad12cc920ead5714191e894bc1dcc6
+SHA512:
+  metadata.gz: 144d54323855f13488f79ca44e41274eb814ff4ee8fa50506909f599b267611cbcd61951ebe281ee9d3d35b962cddfea3817a4ded0cce47c6a8a5fde834796df
+  data.tar.gz: f499383736eab6bc7967c3b9415c5c353fd956b841f63256086f19cf96b303f62b3185cba0da9928e79c71e433f765ea0b821e420eb60326fc3881b4a284bd46

data/README.md

@@ -0,0 +1,35 @@
+# SpanView
+
+TODO: Delete this and the text below, and describe your gem
+
+Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/span_view`. To experiment with that code, run `bin/console` for an interactive prompt.
+
+## Installation
+
+TODO: Replace `UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG` with your gem name right after releasing it to RubyGems.org. Please do not do it earlier due to security reasons. Alternatively, replace this section with instructions to install your gem from git if you don't plan to release to RubyGems.org.
+
+Install the gem and add to the application's Gemfile by executing:
+
+```bash
+bundle add UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG
+```
+
+If bundler is not being used to manage dependencies, install the gem by executing:
+
+```bash
+gem install UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG
+```
+
+## Usage
+
+TODO: Write usage instructions here
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/fapapa/league.

data/Rakefile

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+Bundler::GemHelper.tag_prefix = "span_view-"
+require "minitest/test_task"
+
+Minitest::TestTask.create
+
+require "standard/rake"
+
+task default: %i[test standard]

data/lib/span_view/errors.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module SpanView
+  class Error < StandardError; end
+
+  class UnknownComponentError < Error; end
+
+  class ParseError < Error; end
+end

data/lib/span_view/parser.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require "parslet"
+require_relative "errors"
+require_relative "span/grammar"
+require_relative "span/compiler"
+
+module SpanView
+  # Public interface: `.span` source string in → compiled ERB string out.
+  # Pure function, no Rails coupling. Parses with the Span::Grammar, compiles with
+  # the Span::Compiler transform.
+  module Parser
+    def self.call(source)
+      Span::Compiler.new.apply(Span::Grammar.new.parse(source))
+    rescue Parslet::ParseFailed => e
+      raise ParseError, "Invalid .span template: #{deepest_failure_line(e)}"
+    end
+
+    # The root of `parse_failure_cause.ascii_tree` reports where the top-level
+    # repetition gave up (often "line 1 char 1"); the line that progressed
+    # furthest into the input is the one that names the actual problem.
+    def self.deepest_failure_line(error)
+      error.parse_failure_cause.ascii_tree.lines
+        .map { |line| line.strip.sub(/\A[|`\s-]+/, "") }
+        .reverse # ties resolve to the deepest (most specific) tree node
+        .max_by { |line| line.match(/line (\d+) char (\d+)\.\z/) { |m| [m[1].to_i, m[2].to_i] } || [0, 0] }
+    end
+    private_class_method :deepest_failure_line
+  end
+end

data/lib/span_view/span/compiler.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+require "parslet"
+require_relative "../errors"
+
+module SpanView
+  module Span
+    # Compiles an Span::Grammar parse tree into an ERB string.
+    # `tokens:` is ALWAYS emitted (even empty → `%i[]`); tag pairs emit `do |c|`
+    # (the block param is the slot receiver Story 4.4 will use). Self-closing tags
+    # emit no block.
+    class Compiler < Parslet::Transform
+      # Marks a kv-pair kwarg so render_call can partition it away from plain
+      # token strings; `code` is the already-formatted Ruby value (quoted or verbatim).
+      KvPair = Struct.new(:key, :code)
+
+      rule(text: simple(:t)) { t.to_s }
+      rule(token: simple(:t)) { t.to_s }
+      rule(source: sequence(:nodes)) { nodes.join }
+
+      rule(grouped: {prefix: simple(:prefix), inner: subtree(:inner)}) do
+        Array(inner).map { |tok| "#{prefix}:#{tok}" }
+      end
+
+      rule(kv: {key: simple(:key), dq: subtree(:val)}) do
+        content = val.is_a?(Array) ? "" : val.to_s
+        KvPair.new(key.to_s, "\"#{content}\"")
+      end
+      rule(kv: {key: simple(:key), bare: simple(:val)}) { KvPair.new(key.to_s, val.to_s) }
+
+      rule(self_close: {name: simple(:name), args: subtree(:args)}) do
+        "<%= render(#{Compiler.render_call(name, args)}) %>"
+      end
+
+      rule(tag_pair: {name: simple(:name), args: subtree(:args), source: subtree(:children), close: simple(:close)}) do
+        unless name.to_s == close.to_s
+          raise SpanView::ParseError, "Mismatched tags: <#{name}> closed by </#{close}>"
+        end
+        "<%= render(#{Compiler.render_call(name, args)}) do |c| %>#{Array(children).join}<% end %>"
+      end
+
+      rule(slot: {sname: simple(:sname), source: subtree(:children), close: simple(:close)}) do
+        unless sname.to_s == close.to_s
+          raise SpanView::ParseError, "Mismatched slot tags: <:#{sname}> closed by </:#{close}>"
+        end
+        "<% c.with_#{sname} do %>#{Array(children).join}<% end %>"
+      end
+
+      def self.render_call(name, args)
+        const = "#{name}Component"
+        unless Object.const_defined?(const)
+          raise SpanView::UnknownComponentError, "Unknown component <#{name}>: no #{const} class is defined"
+        end
+
+        token_strings, kv_pairs = [], []
+        Array(args).each do |item|
+          case item
+          when KvPair
+            unless item.key.match?(/\A[a-z_][a-zA-Z0-9_]*\z/)
+              raise SpanView::ParseError, "Invalid attribute key '#{item.key}': not a valid Ruby keyword argument"
+            end
+            kv_pairs << "#{item.key}: #{item.code}"
+          when Array then token_strings.concat(item)
+          else token_strings << item
+          end
+        end
+        kwargs = kv_pairs.empty? ? "" : ", #{kv_pairs.join(", ")}"
+        "#{const}.new(tokens: %i[#{token_strings.join(" ")}]#{kwargs})"
+      end
+    end
+  end
+end

data/lib/span_view/span/grammar.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+require "parslet"
+
+module SpanView
+  module Span
+    # PEG grammar for the `.span` template language (structure only; codegen lives
+    # in Span::Compiler).
+    class Grammar < Parslet::Parser
+      root(:source)
+
+      rule(:source) { (erb | component | slot | passthrough).repeat.as(:source) }
+
+      # ERB tags are atomic: the whole `<% ... %>` / `<%= ... %>` run is one
+      # opaque verbatim unit, terminated by the first subsequent `%>`. The
+      # parser never looks inside — no interpretation of Ruby content (FR-25/26).
+      rule(:erb) { (erb_edge >> (str("%>").absent? >> any).repeat >> str("%>")).as(:text) }
+
+      # Verbatim text: plain HTML, lowercase tags — anything not opening/closing a component, slot, or ERB tag.
+      rule(:passthrough) { (node_edge.absent? >> any).repeat(1).as(:text) }
+      rule(:node_edge) { component_edge | slot_edge | erb_edge }
+      rule(:component_edge) { (str("<") >> match["A-Z"]) | (str("</") >> sp? >> match["A-Z"]) }
+      # Only a lowercase-initial name opens a slot, so `<:` before anything else
+      # (uppercase, space, punctuation) falls through to passthrough as verbatim
+      # text instead of hard-failing the whole parse.
+      rule(:slot_edge) { (str("<:") | str("</:")) >> match["a-z"] }
+      # Stops passthrough at `<%` so the `erb` rule claims the tag whole —
+      # without this, passthrough would consume into an ERB tag and could
+      # hard-stop at a `<`+uppercase inside it (e.g. `<%= "<Box>" %>`).
+      # `<%%` (ERB's literal-escape) is excluded: it is not an ERB opener, so
+      # neither the erb rule claims it nor does passthrough stop at it — the
+      # sequence falls through to passthrough and emits verbatim.
+      rule(:erb_edge) { str("<%") >> str("%").absent? }
+
+      rule(:component) { self_close | tag_pair }
+      rule(:self_close) { (str("<") >> cname >> args >> sp? >> str("/>")).as(:self_close) }
+      rule(:tag_pair) do
+        (str("<") >> cname >> args >> sp? >> str(">") >>
+          source >> str("</") >> sp? >> cname_close.as(:close) >> sp? >> str(">")).as(:tag_pair)
+      end
+
+      rule(:cname) { (match["A-Z"] >> match["A-Za-z"].repeat).as(:name) }
+      rule(:cname_close) { match["A-Z"] >> match["A-Za-z"].repeat }
+
+      rule(:slot) do
+        (str("<:") >> sname >> sp? >> str(">") >>
+          source >> str("</:") >> sp? >> sname_close.as(:close) >> sp? >> str(">")).as(:slot)
+      end
+      rule(:sname) { (match["a-z"] >> match["a-zA-Z0-9_"].repeat).as(:sname) }
+      rule(:sname_close) { match["a-z"] >> match["a-zA-Z0-9_"].repeat }
+
+      # Mixed bag: tokens (bare/grouped) AND kv pairs. Compiler partitions them apart.
+      rule(:args) { (sp >> attr).repeat.as(:args) }
+      rule(:attr) { grouped | kvattr | token }
+
+      rule(:grouped) do
+        (match["^:\\[\\s"].repeat(1).as(:prefix) >> str(":[") >>
+          (group_token >> (sp >> group_token).repeat).as(:inner) >> str("]")).as(:grouped)
+      end
+      # Same charset as `token`, but a bare "]" ends the token so the group's
+      # closing bracket is never swallowed. A balanced "[...]" run (arbitrary
+      # values like gap-[13px]) is consumed whole, so its inner "]" doesn't
+      # terminate the group prematurely.
+      rule(:group_token) do
+        (bracketed | (str("/") >> str(">").absent?) | match["^\\s/>\\[\\]"]).repeat(1).as(:token)
+      end
+      rule(:bracketed) { str("[") >> match["^\\]"].repeat >> str("]") }
+
+      rule(:kvattr) { (key.as(:key) >> str("=") >> (dquoted | unquoted)).as(:kv) }
+      rule(:key) { match["a-zA-Z_\\-"].repeat(1) }
+      rule(:dquoted) { str('"') >> match['^"'].repeat.as(:dq) >> str('"') }
+      rule(:unquoted) { match["^\\s/>"].repeat(1).as(:bare) }
+
+      rule(:token) { ((str("/") >> str(">").absent?) | match["^\\s/>"]).repeat(1).as(:token) }
+
+      rule(:sp) { match["\\s"].repeat(1) }
+      rule(:sp?) { sp.maybe }
+    end
+  end
+end

data/lib/span_view/template_handler.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require "action_view"
+require_relative "parser"
+
+module SpanView
+  module TemplateHandler
+    def self.call(template, source)
+      compiled_erb = Parser.call(source)
+      ActionView::Template.handler_for_extension(:erb).call(template, compiled_erb)
+    end
+  end
+end
+
+ActionView::Template.register_template_handler(:span, SpanView::TemplateHandler)

data/lib/span_view/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module SpanView
+  VERSION = "0.1.0"
+end

data/lib/span_view.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+require "action_view"
+require_relative "span_view/version"
+require_relative "span_view/errors"
+require_relative "span_view/parser"
+require_relative "span_view/template_handler"

data/sig/span_view.rbs

@@ -0,0 +1,4 @@
+module SpanView
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end

metadata

@@ -0,0 +1,80 @@
+--- !ruby/object:Gem::Specification
+name: span_view
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Fabio Papa
+bindir: exe
+cert_chain: []
+date: 2026-07-19 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: actionview
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+- !ruby/object:Gem::Dependency
+  name: parslet
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+description: Span the gap. ActionView .span template handler for the League system.
+email:
+- me@fabiopapa.dev
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- Rakefile
+- lib/span_view.rb
+- lib/span_view/errors.rb
+- lib/span_view/parser.rb
+- lib/span_view/span/compiler.rb
+- lib/span_view/span/grammar.rb
+- lib/span_view/template_handler.rb
+- lib/span_view/version.rb
+- sig/span_view.rbs
+homepage: https://github.com/fapapa/league/tree/main/gems/span_view
+licenses: []
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/fapapa/league/tree/main/gems/span_view
+  source_code_uri: https://github.com/fapapa/league/tree/main/gems/span_view
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.2
+specification_version: 4
+summary: Span the gap.
+test_files: []