rsx-rb 0.1.0

data/lib/rsx/children.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module RSX
+  # The `children` prop of a component element.
+  #
+  # Children compile to a block rather than a finished string, so they are
+  # rendered *inside* the component that received them. That is what lets
+  # <Theme.Provider> change what its children see, lets a caching component skip
+  # building them at all, and means a component that never renders {children}
+  # never pays for them.
+  #
+  # The block's value is memoized, and kept in its raw form as well, so React's
+  # render-prop pattern works: <Consumer>{->(value) { ... }}</Consumer>.
+  class Children
+    UNSET = Object.new
+    private_constant :UNSET
+
+    def initialize(&block)
+      @block = block
+      @value = UNSET
+    end
+
+    # The value the children expression evaluated to, before coercion.
+    def value
+      @value = @block.call if @value.equal?(UNSET)
+      @value
+    end
+
+    # The rendered markup. Used whenever children are interpolated as {children}.
+    def render
+      @render ||= RSX.child(value)
+    end
+    alias to_rsx render
+    alias to_safe_string render
+
+    def to_s
+      render.to_s
+    end
+
+    def to_str
+      render.to_s
+    end
+
+    def html_safe?
+      true
+    end
+
+    # Render props: {children.call(item)} passes a value back to the caller.
+    def call(*arguments, **options, &block)
+      raw = value
+      return raw.call(*arguments, **options, &block) if raw.respond_to?(:call)
+
+      raw
+    end
+
+    def empty?
+      render.empty?
+    end
+    alias blank? empty?
+
+    def present?
+      !empty?
+    end
+    alias any? present?
+
+    def length
+      render.length
+    end
+
+    def ==(other)
+      to_s == other.to_s
+    end
+
+    def inspect
+      "#<RSX::Children #{@render ? @render.inspect : "(not rendered)"}>"
+    end
+  end
+end

data/lib/rsx/cli.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+require "optparse"
+
+module RSX
+  # `rsx` command line tool. Useful for seeing exactly what a template compiles
+  # to, rendering a file outside of Rails, and warming the compile cache.
+  class CLI
+    BANNER = <<~TEXT
+      Usage: rsx COMMAND [options] [files]
+
+      Commands:
+        compile FILE...     Print the Ruby a .rsx file compiles to
+        render FILE         Render a .rsx file and print the HTML
+        precompile DIR...   Compile every .rsx file under DIR and cache the result
+        version             Print the RSX version
+
+      Options:
+    TEXT
+
+    def self.start(argv)
+      new.run(argv)
+    end
+
+    def run(argv)
+      options = { props: {}, cache_dir: nil }
+
+      parser = OptionParser.new do |opts|
+        opts.banner = BANNER
+        opts.on("-p", "--prop NAME=VALUE", "Pass a string prop when rendering") do |pair|
+          name, value = pair.split("=", 2)
+          options[:props][name.to_sym] = value
+        end
+        opts.on("-I", "--include PATH", "Add a directory to the RSX load path") do |path|
+          RSX.config.paths |= [File.expand_path(path)]
+        end
+        opts.on("-c", "--cache-dir DIR", "Directory for compiled output") do |dir|
+          options[:cache_dir] = dir
+        end
+        opts.on("-h", "--help", "Show this message") { puts opts; return 0 }
+      end
+
+      arguments = parser.parse(argv)
+      command = arguments.shift
+
+      RSX.config.cache_dir = options[:cache_dir]
+
+      case command
+      when "compile" then compile(arguments)
+      when "render" then render(arguments, options[:props])
+      when "precompile" then precompile(arguments, options[:cache_dir])
+      when "version", "-v", "--version" then puts RSX::VERSION
+      when nil then puts parser
+      else
+        warn "rsx: unknown command #{command.inspect}"
+        puts parser
+        return 1
+      end
+
+      0
+    rescue RSX::Error, Errno::ENOENT => e
+      warn "rsx: #{e.message}"
+      1
+    end
+
+    private
+
+    def compile(files)
+      abort_missing(files)
+      files.each do |file|
+        puts "# #{file}" if files.length > 1
+        puts RSX.compile(File.read(file), path: File.expand_path(file))
+      end
+    end
+
+    def render(files, props)
+      abort_missing(files)
+      files.each { |file| puts RSX.render_file(File.expand_path(file), **props) }
+    end
+
+    def precompile(directories, cache_dir)
+      directories = [Dir.pwd] if directories.empty?
+      RSX.config.cache_dir = cache_dir || File.join(Dir.pwd, "tmp", "cache", "rsx")
+      files = RSX.loader.files(directories)
+      RSX.precompile!(directories)
+      puts "rsx: precompiled #{files.length} file(s) into #{RSX.config.cache_dir}"
+    end
+
+    def abort_missing(files)
+      raise Error, "no files given" if files.empty?
+
+      missing = files.reject { |file| File.file?(file) }
+      raise Error, "no such file: #{missing.join(", ")}" unless missing.empty?
+    end
+  end
+end

data/lib/rsx/codegen.rb

@@ -0,0 +1,320 @@
+# frozen_string_literal: true
+
+module RSX
+  # Turns an RSX node tree into Ruby source.
+  #
+  # Markup compiles to a single interpolated string literal: static text is baked
+  # in at compile time and only the {ruby} parts remain as interpolations. Nested
+  # elements are spliced into their parent's literal, so an entire static subtree
+  # collapses to one frozen string with no intermediate objects.
+  #
+  #   <ul className="list"><li>{name}</li></ul>
+  #
+  # becomes
+  #
+  #   ::RSX::SafeString.new("<ul class=\"list\"><li>#{::RSX.child(name)}</li></ul>")
+  class Codegen
+    LITERAL_ESCAPES = {
+      "\\" => "\\\\",
+      '"' => '\"',
+      "\n" => '\n',
+      "\t" => '\t',
+      "\r" => '\r',
+      "\e" => '\e',
+      "\0" => '\0'
+    }.freeze
+
+    LITERAL_PATTERN = /[\\"\n\t\r\e\0]|#(?=[{$@])/
+
+    INNER_HTML = %w[dangerouslySetInnerHTML dangerously_set_inner_html].freeze
+
+    def initialize(path: nil, prefix: nil)
+      @path = path
+      @prefix = prefix || "rsx"
+      @statics = 0
+    end
+
+    # Returns [ruby_source, static?]
+    def compile(node, start_line:, end_line:)
+      parts = []
+      emit(node, parts)
+      parts = merge(parts)
+      static = parts.all? { |part| part[0] == :static }
+      [assemble(parts, start_line, end_line, static), static]
+    end
+
+    private
+
+    def emit(node, parts)
+      case node
+      when Nodes::Text
+        parts << [:static, Escape.static_text(node.value), node.line]
+      when Nodes::Expression
+        # The extra parentheses let a container hold anything Ruby accepts as an
+        # expression, including modifiers: {greeting if signed_in?}.
+        parts << [:dynamic, "::RSX.child((#{node.source}))", node.line]
+      when Nodes::Fragment
+        node.children.each { |child| emit(child, parts) }
+      when Nodes::Element
+        emit_element(node, parts)
+      when Nodes::Component
+        emit_component(node, parts)
+      else
+        raise Error, "unexpected node #{node.inspect}"
+      end
+    end
+
+    # ------------------------------------------------------------------
+    # Elements
+    # ------------------------------------------------------------------
+
+    def emit_element(node, parts)
+      tag = node.tag
+      parts << [:static, "<#{tag}", node.line]
+
+      inner_html = nil
+      attributes = node.attributes.reject do |attribute|
+        next false unless attribute.kind != :spread && INNER_HTML.include?(attribute.name)
+
+        inner_html = attribute
+        true
+      end
+
+      if attributes.any? { |attribute| attribute.kind == :spread }
+        emit_spread_attributes(attributes, parts)
+      else
+        attributes.each { |attribute| emit_attribute(attribute, parts) }
+      end
+
+      if inner_html
+        parts << [:static, ">", last_line(parts, node)]
+        parts << [:dynamic, "::RSX.raw_html(#{inner_html.value})", inner_html.line]
+        parts << [:static, "</#{tag}>", last_line(parts, node)]
+        return
+      end
+
+      if Attributes.void?(tag)
+        parts << [:static, ">", last_line(parts, node)]
+        return
+      end
+
+      if node.children.empty?
+        if node.self_closing && Attributes.self_closing?(tag)
+          parts << [:static, "/>", last_line(parts, node)]
+        else
+          parts << [:static, "></#{tag}>", last_line(parts, node)]
+        end
+        return
+      end
+
+      parts << [:static, ">", last_line(parts, node)]
+      node.children.each { |child| emit(child, parts) }
+      parts << [:static, "</#{tag}>", last_line(parts, node)]
+    end
+
+    # An element with a spread has all of its attributes merged at runtime, so a
+    # later value replaces an earlier one exactly as it would in React. Emitting
+    # them one by one would instead produce a duplicate HTML attribute, where
+    # the browser keeps the first.
+    def emit_spread_attributes(attributes, parts)
+      groups = []
+      attributes.each do |attribute|
+        if attribute.kind == :spread
+          groups << attribute.value
+        elsif groups.last.is_a?(Array)
+          groups.last << attribute_pair(attribute)
+        else
+          groups << [attribute_pair(attribute)]
+        end
+      end
+
+      source =
+        if groups.length == 1 && !groups.first.is_a?(Array)
+          "::RSX::Attributes.render_all(#{groups.first})"
+        else
+          arguments = groups.map { |group| group.is_a?(Array) ? "{ #{group.join(", ")} }" : "(#{group})" }
+          "::RSX::Attributes.render_all(::RSX::Attributes.merge(#{arguments.join(", ")}))"
+        end
+
+      parts << [:dynamic, source, attributes.first.line]
+    end
+
+    def attribute_pair(attribute)
+      key = symbol_literal(attribute.name)
+
+      case attribute.kind
+      when :boolean then "#{key} => true"
+      when :static then %(#{key} => "#{escape_literal(attribute.value)}")
+      when :expression then "#{key} => (#{attribute.value})"
+      end
+    end
+
+    def emit_attribute(attribute, parts)
+      name = Attributes.attribute_name(attribute.name)
+      return if name.nil? || name.empty?
+
+      case attribute.kind
+      when :boolean
+        text = Attributes.boolean?(name) ? " #{name}" : %( #{name}="true")
+        parts << [:static, text, attribute.line]
+      when :static
+        parts << [:static, static_attribute(name, attribute.value), attribute.line]
+      when :expression
+        parts << [:dynamic, dynamic_attribute(name, attribute.value), attribute.line]
+      end
+    end
+
+    def static_attribute(name, value)
+      %( #{name}="#{Escape.static_text(value)}")
+    end
+
+    def dynamic_attribute(name, source)
+      case name
+      when "class" then "::RSX::Attributes.render_class(#{source})"
+      when "style" then "::RSX::Attributes.render_style(#{source})"
+      when "data", "aria" then %(::RSX::Attributes.render_nested("#{name}", #{source}))
+      else %(::RSX::Attributes.render("#{name}", #{source}))
+      end
+    end
+
+    # ------------------------------------------------------------------
+    # Components
+    # ------------------------------------------------------------------
+
+    def emit_component(node, parts)
+      source = "::RSX.render_component(#{node.name}, #{props_source(node)}, #{children_source(node)}, self)"
+      parts << [:dynamic, source, node.line]
+    end
+
+    def props_source(node)
+      entries = node.attributes.map do |attribute|
+        case attribute.kind
+        when :spread then "**(#{attribute.value})"
+        when :boolean then "#{symbol_literal(attribute.name)} => true"
+        when :static then "#{symbol_literal(attribute.name)} => \"#{escape_literal(attribute.value)}\""
+        when :expression then "#{symbol_literal(attribute.name)} => (#{attribute.value})"
+        end
+      end
+
+      entries.empty? ? "nil" : "{ #{entries.join(", ")} }"
+    end
+
+    def symbol_literal(name)
+      name.match?(/\A[A-Za-z_][A-Za-z0-9_]*[?!]?\z/) ? ":#{name}" : %(:"#{escape_literal(name)}")
+    end
+
+    # Children are passed lazily so that components can decide whether (and in
+    # what context) to render them: caching, context providers and conditional
+    # slots all depend on not having rendered them yet. Fully static children
+    # skip the wrapper entirely since there is nothing to defer.
+    def children_source(node)
+      return "nil" if node.children.empty?
+
+      # A lone {expression} is handed over untouched rather than rendered to a
+      # string, so children can be any value: a lambda for a render prop, an
+      # array, a model. RSX.child coerces it if the component interpolates it.
+      if node.children.length == 1 && node.children.first.is_a?(Nodes::Expression)
+        return "::RSX::Children.new { #{node.children.first.source} }"
+      end
+
+      parts = []
+      node.children.each { |child| emit(child, parts) }
+      parts = merge(parts)
+      return "nil" if parts.empty?
+
+      static = parts.all? { |part| part[0] == :static }
+      body = assemble(parts, parts.first[2], parts.last[2], static)
+      static ? body : "::RSX::Children.new { #{body} }"
+    end
+
+    # ------------------------------------------------------------------
+    # Assembly
+    # ------------------------------------------------------------------
+
+    def merge(parts)
+      merged = []
+      parts.each do |part|
+        previous = merged.last
+        if part[0] == :static && previous && previous[0] == :static
+          previous[1] += part[1]
+        else
+          merged << part.dup
+        end
+      end
+      merged
+    end
+
+    def assemble(parts, start_line, end_line, static)
+      buffer = +""
+
+      # Markup with nothing dynamic in it is built once and then reused from a
+      # per-call-site slot, so re-rendering it allocates nothing at all. The
+      # literal after `||=` is never evaluated again after the first render.
+      buffer << "(::RSX::STATICS[#{static_slot}] ||= " if static
+      buffer << (static ? "::RSX.static(" : "::RSX::SafeString.new(")
+      state = { line: start_line, open: false }
+
+      parts.each do |kind, text, line|
+        pad(buffer, state, line)
+        open_literal(buffer, state)
+
+        if kind == :static
+          buffer << escape_literal(text)
+        else
+          buffer << '#{' << text << "}"
+          state[:line] += text.count("\n")
+        end
+      end
+
+      open_literal(buffer, state) if parts.empty?
+      close_literal(buffer, state)
+      pad(buffer, state, end_line)
+      buffer << ")"
+      buffer << ")" if static
+      buffer
+    end
+
+    def static_slot
+      @statics += 1
+      %(:"#{@prefix}#{@statics}")
+    end
+
+    # Keeps generated Ruby on the same lines as the .rsx source it came from.
+    # Inside a string literal, extra lines are added by closing the literal and
+    # continuing it: adjacent literals are concatenated by the parser, so no
+    # markup is affected.
+    def pad(buffer, state, target)
+      count = target - state[:line]
+      return if count <= 0
+
+      if state[:open]
+        buffer << '" ' << ("\\\n" * count) << '"'
+      else
+        buffer << ("\n" * count)
+      end
+      state[:line] = target
+    end
+
+    def open_literal(buffer, state)
+      return if state[:open]
+
+      buffer << '"'
+      state[:open] = true
+    end
+
+    def close_literal(buffer, state)
+      return unless state[:open]
+
+      buffer << '"'
+      state[:open] = false
+    end
+
+    def escape_literal(text)
+      text.gsub(LITERAL_PATTERN) { |match| LITERAL_ESCAPES[match] || "\\#{match}" }
+    end
+
+    def last_line(parts, node)
+      parts.empty? ? node.line : parts.last[2]
+    end
+  end
+end

data/lib/rsx/compile_cache.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+require "digest"
+require "fileutils"
+
+module RSX
+  # Caches the Ruby produced from .rsx files on disk, keyed by a digest of the
+  # source. A warm cache turns loading a template into reading a .rb file, so
+  # booting a large application does no transformation work at all.
+  class CompileCache
+    attr_reader :directory
+
+    def initialize(directory)
+      @directory = directory
+      @enabled = !directory.nil?
+      @memory = {}
+      @lock = Mutex.new
+    end
+
+    def enabled?
+      @enabled
+    end
+
+    def digest(source)
+      Digest::SHA256.hexdigest("#{COMPILER_VERSION}\0#{source}")[0, 32]
+    end
+
+    # Returns the compiled Ruby for source, compiling only on a cache miss.
+    def fetch(path, source)
+      key = digest(source)
+      cached = @lock.synchronize { @memory[key] }
+      return cached if cached
+
+      ruby = read(path, key) || begin
+        compiled = yield
+        write(path, key, compiled)
+        compiled
+      end
+
+      @lock.synchronize { @memory[key] = ruby }
+      ruby
+    end
+
+    def path_for(source_path, key)
+      return nil unless enabled?
+
+      basename = File.basename(source_path.to_s, ".*")
+      basename = "template" if basename.empty?
+      File.join(@directory, "#{basename}-#{key}.rb")
+    end
+
+    def read(source_path, key)
+      target = path_for(source_path, key)
+      return nil unless target && File.file?(target)
+
+      File.read(target)
+    rescue SystemCallError
+      nil
+    end
+
+    def write(source_path, key, ruby)
+      target = path_for(source_path, key)
+      return ruby unless target
+
+      FileUtils.mkdir_p(File.dirname(target))
+      temporary = "#{target}.#{Process.pid}.#{rand(1 << 24)}.tmp"
+      File.binwrite(temporary, ruby)
+      File.rename(temporary, target)
+      ruby
+    rescue SystemCallError
+      # A read-only or missing cache directory must never break rendering.
+      @enabled = false
+      ruby
+    end
+
+    def clear
+      @lock.synchronize { @memory.clear }
+      return unless enabled? && File.directory?(@directory)
+
+      Dir.glob(File.join(@directory, "*.rb")).each { |file| File.delete(file) }
+      Dir.glob(File.join(@directory, "*.tmp")).each { |file| File.delete(file) }
+    end
+  end
+end