brut 0.0.12 → 0.0.20

data/lib/brut/front_end/template.rb

@@ -1,47 +0,0 @@
-require "temple"
-
-# Holds code related to rendering ERB templates
-module Brut::FrontEnd::Templates
-  autoload(:HTMLSafeString,"brut/front_end/templates/html_safe_string")
-  autoload(:ERBParser,"brut/front_end/templates/erb_parser")
-  autoload(:EscapableFilter,"brut/front_end/templates/escapable_filter")
-  autoload(:BlockFilter,"brut/front_end/templates/block_filter")
-  autoload(:ERBEngine,"brut/front_end/templates/erb_engine")
-  autoload(:Locator,"brut/front_end/templates/locator")
-end
-
-# Handles rendering HTML templates written in ERB.  This is a light wrapper around `Tilt`.
-# This also configured a few customizations to allow a Rails-like rendering of ERB:
-#
-# * HTML escaping by default
-# * Helpers that return {Brut::FrontEnd::Templates::HTMLSafeString}s won't be escaped
-#
-# @see https://github.com/rtomayko/tilt
-class Brut::FrontEnd::Template
-
-  # @!visibility private
-  # This sets up global state somewhere, even though we aren't using `TempleTemplate`
-  # anywhere.
-  TempleTemplate = Temple::Templates::Tilt(Brut::FrontEnd::Templates::ERBEngine,
-                                           register_as: "html.erb")
-
-  attr_reader :template_file_path
-
-  # Wraps a string that is deemed safe to insert into
-  # HTML without escaping it.  This allows stuff like
-  # <%= component(SomeComponent) %> to work without
-  # having to remember to <%== all the time.
-  def initialize(template_file_path)
-    @template_file_path = template_file_path
-    @tilt_template = Tilt.new(@template_file_path)
-  end
-
-  def render_template(...)
-    @tilt_template.render(...)
-  end
-
-  # Convienience method to escape HTML in the canonical way.
-  def self.escape_html(string)
-    Brut::FrontEnd::Templates::EscapableFilter.escape_html(string)
-  end
-end

data/lib/brut/front_end/templates/block_filter.rb

@@ -1,61 +0,0 @@
-# Allows rendering blocks in ERB the way Rails' helpers like `form_with` do.
-# This is a slightly modified copy of Hanami's `Filters::Block`.
-#
-# @see https://github.com/hanami/view/blob/main/lib/hanami/view/erb/filters/block.rb
-class Brut::FrontEnd::Templates::BlockFilter < Temple::Filter
-  END_LINE_RE = /\bend\b/
-
-  # @!visibility private
-  def on_erb_block(escape, code, content)
-    tmp = unique_name
-
-    # Remove the last `end` :code sexp, since this is technically "outside" the block
-    # contents, which we want to capture separately below. This `end` is added back after
-    # capturing the content below.
-    case content.last
-    in [:code, c] if c =~ END_LINE_RE
-      content.pop
-    end
-
-    [:multi,
-     # Capture the result of the code in a variable. We can't do `[:dynamic, code]` because
-     # it's probably not a complete expression (which is a requirement for Temple).
-     # DBC: an example is that 'code' might be "form_for do" which is not an expression.
-     #      Because we later put an "end" in, the result will be
-     #
-     #      some_var = helper do
-     #      end
-     #
-     #      Which IS valid Ruby.
-     [:code, "#{tmp} = #{code}"],
-     # Capture the content of a block in a separate buffer. This means that `yield` will
-     # not output the content to the current buffer, but rather return the output.
-     [:capture, unique_name, compile(content)],
-     [:code, "end"],
-     # Output the content, without escaping it.
-     # Hanami has this ↴
-     # [:escape, escape, [:dynamic, tmp]]
-     [:escape, escape, [:dynamic, Brut::FrontEnd::Templates.name + "::HTMLSafeString.new(#{tmp})"]]
-    ]
-
-    # Details explaining the change:
-    #
-    # The sexps for template are quite convoluted and highly dynamic, so it is hard
-    # to understand exactly what effect they will have.  Basically, what this [:multi thing is
-    # doing is to capture the result of the block in a variable:
-    #
-    # some_var = form_for(args) do
-    #
-    # It then captures the inside of the block in a new variable:
-    #
-    # some_other_var = «whatever was inside that `do`»
-    #
-    # And follows it with an end.
-    #
-    # The first variable—some_var—now holds the return value of the helper, form_for in this case. To
-    # output this content to the actual view, it must be dereferenced, thus [ :dynamic, "some_var" ].
-    #
-    # We are going to treat the return value of the block helper as HTML safe.  Thus, we'll wrap it
-    # with HTMLSafeString.new(…).
-  end
-end

data/lib/brut/front_end/templates/erb_engine.rb

@@ -1,26 +0,0 @@
-# A temple "engine" that can be used to parse ERB and generate HTML
-# in just the way we need.
-class Brut::FrontEnd::Templates::ERBEngine < Temple::Engine
-  # Parse the ERB into sexps
-  use Brut::FrontEnd::Templates::ERBParser
-
-  # Handle block syntax used in a <%= 
-  use Brut::FrontEnd::Templates::BlockFilter
-
-  # Trim whitespace like ERB does
-  use Temple::ERB::Trimming
-
-  # Escape strings only if they are not HTMLSafeString
-  use Brut::FrontEnd::Templates::EscapableFilter
-  # This filter actually runs the Ruby code
-  use Temple::Filters::StaticAnalyzer
-  # Flattens nested :multi expressions which I'm not sure is needed, but
-  # have cargo-culted from hanami
-  use Temple::Filters::MultiFlattener
-  # merges sequential :static, which again, not sure is needed, but
-  # have cargo-culted from hanami
-  use Temple::Filters::StaticMerger
-
-  # This generates everything into a string
-  use Temple::Generators::ArrayBuffer
-end

data/lib/brut/front_end/templates/erb_parser.rb

@@ -1,84 +0,0 @@
-# Almost verbatim copy of Hanami's parser:
-#
-# https://github.com/hanami/view/blob/main/lib/hanami/view/erb/parser.rb
-#
-# That is licensed MIT and thus so is this file.
-#
-# Avoid changes to this file so it can be kept updated with Hanami.
-class Brut::FrontEnd::Templates::ERBParser < Temple::Parser
-  ERB_PATTERN = /(\n|<%%|%%>)|<%(==?|\#)?(.*?)?-?%>/m
-
-  IF_UNLESS_CASE_LINE_RE = /\A\s*(if|unless|case)\b/
-  BLOCK_LINE_RE = /\s*((\s+|\))do|\{)(\s*\|[^|]*\|)?\s*\Z/
-  END_LINE_RE = /\bend\b/
-
-  def call(input)
-    results = [[:multi]]
-    pos = 0
-
-    input.scan(ERB_PATTERN) do |token, indicator, code|
-      # Capture any text between the last ERB tag and the current one, and update the position
-      # to match the end of the current tag for the next iteration of text collection.
-      text = input[pos...$~.begin(0)]
-      pos  = $~.end(0)
-
-      if token
-        # First, handle certain static tokens picked up by our ERB_PATTERN regexp. These are
-        # newlines as well as the special codes for literal `<%` and `%>` values.
-        case token
-        when "\n"
-          results.last << [:static, "#{text}\n"] << [:newline]
-        when "<%%", "%%>"
-          results.last << [:static, text] unless text.empty?
-          token.slice!(1)
-          results.last << [:static, token]
-        end
-      else
-        # Next, handle actual ERB tags. Start by adding any static text between this match and
-        # the last.
-        results.last << [:static, text] unless text.empty?
-
-        case indicator
-        when "#"
-          # Comment tags: <%# this is a comment %>
-          results.last << [:code, "\n" * code.count("\n")]
-        when %r{=}
-          # Expression tags: <%= "hello (auto-escaped)" %> or <%== "hello (not escaped)" %>
-          if code =~ BLOCK_LINE_RE
-            # See Hanami::View::Erb::Filters::Block for the processing of `:erb, :block` sexps
-            block_node = [:erb, :block, indicator.size == 1, code, (block_content = [:multi])]
-            results.last << block_node
-
-            # For blocks opened in ERB expression tags, push this `[:multi]` sexp
-            # (representing the content of the block) onto the stack of resuts. This allows
-            # subsequent results to be appropriately added inside the block, until its closing
-            # tag is encountered, and this `block_content` multi is subsequently popped off
-            # the results stack.
-            results << block_content
-          else
-            results.last << [:escape, indicator.size == 1, [:dynamic, code]]
-          end
-        else
-          # Code tags: <% if some_cond %>
-          if code =~ BLOCK_LINE_RE || code =~ IF_UNLESS_CASE_LINE_RE
-            results.last << [:code, code]
-
-            # For ERB code tags that will result in a matching `end`, push the last result
-            # back onto the stack of results. This might seem redundant, but it allows
-            # subsequent sexps to continue to be pushed onto the same result while also
-            # allowing it to be safely popped again when the matching `end` is encountered.
-            results << results.last
-          elsif code =~ END_LINE_RE
-            results.last << [:code, code]
-            results.pop
-          else
-            results.last << [:code, code]
-          end
-        end
-      end
-    end
-
-    # Add any text after the final ERB tag
-    results.last << [:static, input[pos..-1]]
-  end
-end

data/lib/brut/front_end/templates/escapable_filter.rb

@@ -1,20 +0,0 @@
-# A temple filter that handles escaping HTML unless it's been wrapped in
-# an HTMLSafeString.
-class Brut::FrontEnd::Templates::EscapableFilter < Temple::Filters::Escapable
-  using Brut::FrontEnd::Templates::HTMLSafeString::Refinement
-
-  # @!visibility private
-  def initialize(opts = {})
-    opts[:escape_code] ||= "::Brut::FrontEnd::Templates::EscapableFilter.escape_html((%s))"
-    super(opts)
-  end
-
-  # @!visibility private
-  def self.escape_html(html)
-    if html.kind_of?(Brut::FrontEnd::Templates::HTMLSafeString)
-      html.string
-    else
-      Temple::Utils.escape_html(html)
-    end
-  end
-end

data/lib/brut/front_end/templates/html_safe_string.rb

@@ -1,68 +0,0 @@
-# A wrapper around a string to indicate it is HTML-safe and
-# can be rendered directly without escaping. This was done to avoid adding methods on `String` and the internal state
-# required to make something like `"foo".html_safe!` work.
-class Brut::FrontEnd::Templates::HTMLSafeString
-  # This can be used via `using` to add `html_safe!` and `html_safe?` method to `String` when they might be more convienient
-  # than using {Brut::FrontEnd::Templates::HTMLSafeString} directly.
-  module Refinement
-    refine String do
-      def html_safe! = Brut::FrontEnd::Templates::HTMLSafeString.from_string(self)
-      def html_safe? = false
-    end
-  end
-  using Refinement
-
-  # @return [String] the underlying string being wrapped
-  attr_reader :string
-
-  # Create an HTML safe string based on the parameter. It's recommended to use {.from_string} instead.
-  #
-  # @param [String] string A string that is considered safe to put directly into a web page without escaping.
-  def initialize(string)
-    @string = string
-  end
-
-  # Creates an HTML Safe string based on the parameter, properly handling if a HTML safe string is being passed.
-  #
-  # @param [String|Brut::FrontEnd::Templates::HTMLSafeString] string_or_html_safe_string the value to turn into an HTML safe string.
-  #
-  # @return [Brut::FrontEnd::Templates::HTMLSafeString] if `string_or_html_safe_string` is already HTML safe, returns it. Otherwise,
-  # wraps the string as HTML safe.
-  def self.from_string(string_or_html_safe_string)
-    if string_or_html_safe_string.kind_of?(self)
-      string_or_html_safe_string
-    else
-      self.new(string_or_html_safe_string)
-    end
-  end
-
-  # This must be convertible to a string
-  def to_s       = @string
-  def to_str     = @string
-  # Matches the protocol in {Brut::FrontEnd::Templates::HTMLSafeString::Refinement}
-  # @return [Brut::FrontEnd::Templates::HTMLSafeString] self
-  def html_safe! = self
-  # Matches the protocol in {Brut::FrontEnd::Templates::HTMLSafeString::Refinement}
-  # @return [true|false] true
-  def html_safe? = true
-
-  # Return a new instance that has called `capitalize` on the underlying string
-  def capitalize = self.class.new(@string.capitalize)
-  # Return a new instance that has called `downcase` on the underlying string
-  def downcase   = self.class.new(@string.downcase)
-  # Return a new instance that has called `upcase` on the underlying string
-  def upcase     = self.class.new(@string.upcase)
-
-  # Returns the concatenation of two strings. If the other is HTML safe, then this returns an HTML safe string.
-  # If the other is not, this returns a normal unsafe string.
-  #
-  # @param [String|Brut::FrontEnd::Templates::HTMLSafeString] other
-  # @return [String|Brut::FrontEnd::Templates::HTMLSafeString] A safe or unsafe string, depending on what was passed.
-  def +(other)
-    if other.html_safe?
-      self.class.new(@string + other.to_s)
-    else
-      @string + other.to_s
-    end
-  end
-end

data/lib/brut/front_end/templates/locator.rb

@@ -1,60 +0,0 @@
-# Locates a template, based on a name, configured paths, and an extension.  This class forms both an API
-# for template location ({#locate}) as well as an implementation that is conventional with Brut apps.
-class Brut::FrontEnd::Templates::Locator
-  # Create a locator that will search the given paths and require that template
-  # files have the given extension
-  #
-  # @param [Pathname|String|Array<Pathname|String>] paths one or more paths that will be searched for templates
-  # @param [String] extension file extension, without the dot, of the name of files that are considered templates
-  def initialize(paths:, extension:)
-    @paths     = Array(paths).map { |path| Pathname(path) }
-    @extension = extension
-  end
-
-  # Given a base name, which may or may not be nested paths, returns the path to the template
-  # for this file.  There must be exactly one template that matches.
-  #
-  # @example
-  #
-  #    locator = Locator.new(
-  #      paths: [
-  #        Brut.container.app_src_dir / "front_end" / "components",
-  #        Brut.container.app_src_dir / "front_end" / "other_components",
-  #      ],
-  #      extension: "html.erb"
-  #    )
-  #
-  #    # Suppose app/src/front_end/components/foo.html.erb exists
-  #    path = locator.locate("foo")
-  #    # => "app/src/front_end/components/foo.html.erb"
-  #
-  #    # Suppose app/src/front_end/components/bar/blah.html.erb exists
-  #    path = locator.locate("bar/blah")
-  #    # => "app/src/front_end/components/bar/blah.html.erb"
-  #
-  #    # Suppose both app/src/front_end/components/bar/blah.html.erb and
-  #    #              app/src/front_end/other_components/bar/blah.html.erb
-  #    # both exist
-  #    path = locator.locate("bar/blah")
-  #    # => raises an error since there are two matches
-  #
-  # @param [String] base_name the base name of a file that is expected to have a template.  This is searched relative to the paths
-  # provided to the constructor, so it may have nested paths
-  # @return [String] path to the template for the given `base_name`
-  # @raise StandardError if zero or more than one templates are found
-  def locate(base_name)
-    paths_to_try = @paths.map { |path|
-      path / "#{base_name}.#{@extension}"
-    }
-    paths_found = paths_to_try.select { |path|
-      path.exist?
-    }
-    if paths_found.empty?
-      raise "Could not locate template for #{base_name}. Tried: #{paths_to_try.map(&:to_s).join(', ')}"
-    end
-    if paths_found.length > 1
-      raise "Found more than one valid pat for #{base_name}.  You must rename your files to disambiguate them. These paths were all found: #{paths_found.map(&:to_s).join(', ')}"
-    end
-    return paths_found[0]
-  end
-end