erblite 0.5.0

data/lib/erblite/sandbox.rb

@@ -0,0 +1,192 @@
+# Copyright 2026 OpenC3, Inc.
+# All Rights Reserved.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
+# See LICENSE.md for more details.
+
+# frozen_string_literal: true
+
+module ERBLite
+  # The only file system access templates have (SPEC section 9.1). Every path
+  # is resolved against the real path of base_dir, symlinks included, and
+  # must stay inside it.
+  module Sandbox
+    module_function
+
+    def require_base(state)
+      return state.real_base if state.real_base
+
+      raise Error.new("SecurityError", "file access is disabled (no base_dir was given)")
+    end
+
+    def check_path_string(path)
+      unless path.is_a?(String)
+        raise Error.new("TypeError", "no implicit conversion of #{Builtins.tname(path)} into String")
+      end
+      raise Error.new("ArgumentError", "string contains null byte") if path.include?("\0")
+    end
+
+    def inside?(real, base)
+      return true if real == base
+
+      prefix = base.end_with?("/") ? base : "#{base}/"
+      real.start_with?(prefix)
+    end
+
+    # Lexically normalized absolute path for +path+ under +base+. A leading
+    # "~" is never expanded to a home directory.
+    def expand(path, base)
+      p = path.start_with?("~") ? "./#{path}" : path
+      File.expand_path(p, base)
+    end
+
+    # Resolves +path+ to a real path inside the sandbox or raises
+    # SecurityError. Missing trailing components are allowed (the caller
+    # reports IOError for them); the deepest existing ancestor is resolved
+    # with File.realpath so symlinks cannot escape.
+    def resolve(state, path)
+      base = require_base(state)
+      check_path_string(path)
+      full = expand(path, base)
+      rest = []
+      cur = full
+      until File.exist?(cur)
+        parent = File.dirname(cur)
+        break if parent == cur
+
+        rest.unshift(File.basename(cur))
+        cur = parent
+      end
+      real = begin
+        File.realpath(cur)
+      rescue SystemCallError
+        cur
+      end
+      real = File.join(real, *rest) unless rest.empty?
+      raise Error.new("SecurityError", "path is outside the sandbox: #{path}") unless inside?(real, base)
+
+      real
+    end
+
+    def read(state, path)
+      real = resolve(state, path)
+      raise Error.new("IOError", "No such file or directory - #{path}") unless File.exist?(real)
+      raise Error.new("IOError", "Is a directory - #{path}") if File.directory?(real)
+
+      File.binread(real).force_encoding(Encoding::UTF_8)
+    rescue SystemCallError => e
+      raise Error.new("IOError", "#{e.message} - #{path}")
+    end
+
+    def check(state, path, kind)
+      require_base(state)
+      check_path_string(path)
+      real = begin
+        resolve(state, path)
+      rescue Error => e
+        return false if e.type == "SecurityError"
+
+        raise
+      end
+      case kind
+      when :exist then File.exist?(real)
+      when :file then File.file?(real)
+      else File.directory?(real)
+      end
+    end
+
+    # Dir.glob with *, ** and ? only. Results are relative to base_dir and
+    # sorted.
+    def glob(state, pattern)
+      base = require_base(state)
+      check_path_string(pattern)
+      full = expand(pattern, base)
+      raise Error.new("SecurityError", "glob pattern is outside the sandbox: #{pattern}") unless inside?(full, base)
+
+      rel = full == base ? "" : full[(base.end_with?("/") ? base.length : base.length + 1)..]
+      segs = rel.split("/").reject(&:empty?)
+      out = []
+      walk(base, base, "", segs, out) unless segs.empty?
+      out.uniq.sort
+    end
+
+    def children(dir)
+      Dir.children(dir).sort
+    rescue SystemCallError
+      []
+    end
+
+    def safe_dir?(path, base)
+      File.directory?(path) && inside?(File.realpath(path), base)
+    rescue SystemCallError
+      false
+    end
+
+    def walk(base, dir, prefix, segs, out)
+      seg = segs[0]
+      last = segs.length == 1
+      join = ->(name) { prefix.empty? ? name : "#{prefix}/#{name}" }
+      if seg == "**" && !last
+        walk(base, dir, prefix, segs[1..], out)
+        children(dir).each do |name|
+          next if name.start_with?(".")
+
+          path = File.join(dir, name)
+          next if File.symlink?(path) || !safe_dir?(path, base)
+
+          walk(base, path, join.call(name), segs, out)
+        end
+      elsif seg.include?("*") || seg.include?("?")
+        children(dir).each do |name|
+          next if name.start_with?(".") && !seg.start_with?(".")
+          next unless wildcard_match?(seg, name)
+
+          path = File.join(dir, name)
+          if last
+            out << join.call(name)
+          elsif safe_dir?(path, base)
+            walk(base, path, join.call(name), segs[1..], out)
+          end
+        end
+      else
+        path = File.join(dir, seg)
+        return unless File.exist?(path) || File.symlink?(path)
+
+        if last
+          out << join.call(seg)
+        elsif safe_dir?(path, base)
+          walk(base, path, join.call(seg), segs[1..], out)
+        end
+      end
+    end
+
+    # Matches +name+ against a glob segment where * is any run of characters
+    # and ? is one character.
+    def wildcard_match?(pat, name)
+      p = 0
+      n = 0
+      star_p = nil
+      star_n = 0
+      while n < name.length
+        if p < pat.length && (pat[p] == "?" || pat[p] == name[n])
+          p += 1
+          n += 1
+        elsif p < pat.length && pat[p] == "*"
+          star_p = p
+          star_n = n
+          p += 1
+        elsif star_p
+          p = star_p + 1
+          star_n += 1
+          n = star_n
+        else
+          return false
+        end
+      end
+      p += 1 while p < pat.length && pat[p] == "*"
+      p == pat.length
+    end
+  end
+end

data/lib/erblite/values.rb

@@ -0,0 +1,139 @@
+# Copyright 2026 OpenC3, Inc.
+# All Rights Reserved.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
+# See LICENSE.md for more details.
+
+# frozen_string_literal: true
+
+module ERBLite
+  # A built-in class or module constant (Integer, Comparable, Math, File, ...).
+  # Templates can only reach the instances created in Builtins::CONSTANTS.
+  class ClassValue
+    attr_reader :name
+
+    def initialize(name, is_module)
+      @name = name.freeze
+      @module = is_module
+    end
+
+    def module?
+      @module
+    end
+
+    def to_s
+      @name.dup
+    end
+
+    def inspect
+      @name.dup
+    end
+  end
+
+  # What an iterator method returns when it is called without a block.
+  # Iterating it calls method +meth+ on +recv+ with +args+ and a block.
+  class Enum
+    attr_reader :recv, :meth, :args
+
+    def initialize(recv, meth, args)
+      @recv = recv
+      @meth = meth
+      @args = args
+    end
+
+    def inspect
+      a = @args.empty? ? "" : "(#{@args.map { |x| Builtins.inspect(x) }.join(", ")})"
+      if @meth == "step" && arithmetic_sequence?
+        # Ruby returns an ArithmeticSequence here, which prints differently.
+        recv = Builtins.inspect(@recv)
+        return @recv.is_a?(Range) ? "((#{recv}).step#{a})" : "(#{recv}.step#{a})"
+      end
+      "#<Enumerator: #{Builtins.inspect(@recv)}:#{@meth}#{a}>"
+    end
+
+    def arithmetic_sequence?
+      num = ->(x) { x.is_a?(Integer) || x.is_a?(Float) }
+      return @args.all?(&num) if @recv.is_a?(Range)
+
+      (@recv.is_a?(Integer) || @recv.is_a?(Float)) && @args.all? { |x| num.call(x) || x.nil? }
+    end
+
+    def to_s
+      inspect
+    end
+  end
+
+  # Local variable scope. Each block call gets its own Env whose +blk+ is the
+  # UserBlock being run, so `break`/`next` know where to go.
+  class Env
+    attr_reader :vars, :parent, :blk
+
+    def initialize(parent, blk = nil)
+      @vars = {}
+      @parent = parent
+      @blk = blk
+    end
+  end
+
+  # A block written in the template ({ |x| ... } or do |x| ... end).
+  class UserBlock
+    attr_reader :next_tag
+
+    def initialize(interp, node, env, value_used = true)
+      @it = interp
+      @node = node
+      @env = env
+      @value_used = value_used
+      @next_tag = Object.new
+    end
+
+    def call(*vals)
+      @it.step!
+      e = Env.new(@env, self)
+      params = @node.params
+      vals = vals[0] if params.length > 1 && vals.length == 1 && vals[0].is_a?(Array)
+      params.each_with_index { |p, i| bind(p, vals[i], e) }
+      @it.want = @value_used
+      catch(@next_tag) { @it.ev(@node.body, e) }
+    end
+
+    private
+
+    def bind(param, value, env)
+      if param.is_a?(Array)
+        arr = value.is_a?(Array) ? value : [value]
+        param.each_with_index { |q, j| bind(q, arr[j], env) }
+      else
+        env.vars[param] = value
+      end
+    end
+  end
+
+  # &:name - calls method +name+ (through the allowlist) on the first value.
+  class SymBlock
+    def initialize(interp, name)
+      @it = interp
+      @name = name
+    end
+
+    def call(*vals)
+      @it.step!
+      raise Error.new("ArgumentError", "no receiver given") if vals.empty?
+
+      @it.call_method(vals[0], @name, vals[1..], nil)
+    end
+  end
+
+  # A block implemented by the interpreter itself (for loops, enumerators).
+  class NativeBlock
+    def initialize(&body)
+      @body = body
+    end
+
+    def call(*vals)
+      @body.call(*vals)
+    end
+  end
+end

data/lib/erblite/version.rb

@@ -0,0 +1,13 @@
+# Copyright 2026 OpenC3, Inc.
+# All Rights Reserved.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
+# See LICENSE.md for more details.
+
+# frozen_string_literal: true
+
+module ERBLite
+  VERSION = "0.5.0"
+end

data/lib/erblite.rb

@@ -0,0 +1,134 @@
+# Copyright 2026 OpenC3, Inc.
+# All Rights Reserved.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
+# See LICENSE.md for more details.
+
+# frozen_string_literal: true
+
+require_relative "erblite/version"
+require_relative "erblite/error"
+require_relative "erblite/nodes"
+require_relative "erblite/lexer"
+require_relative "erblite/parser"
+require_relative "erblite/values"
+require_relative "erblite/builtins"
+require_relative "erblite/format"
+require_relative "erblite/json"
+require_relative "erblite/sandbox"
+require_relative "erblite/interpreter"
+
+# ERBLite: a sandboxed template engine with ERB syntax and a small subset of
+# Ruby. Templates are lexed, parsed into an AST and run by a tree-walking
+# interpreter; no template text is ever evaluated as Ruby code.
+module ERBLite
+  NAME_RE = /\A[a-z_][A-Za-z0-9_]*\z/
+
+  # A compiled template. The source is tokenized once; the token stream is
+  # parsed per set of host variable names (host variables are locals of the
+  # template, which affects parsing as in Ruby).
+  class Template
+    attr_reader :filename
+
+    def initialize(source, filename: "(erblite)")
+      @filename = filename
+      @source = ERBLite.normalize_source(source, filename)
+      @tokens = Lexer.tokenize(@source, filename)
+      @asts = {}
+    rescue SystemStackError
+      raise Error.new("LimitError", "nesting is too deep (stack exhausted)", filename, nil)
+    end
+
+    # Variables may be passed as a Hash or as extra keyword arguments
+    # (render(name: "x")); base_dir and max_steps are always options.
+    def render(vars = {}, base_dir: nil, max_steps: nil, **more)
+      vars = vars.merge(more) unless more.empty?
+      locals = ERBLite.convert_vars(vars)
+      names = locals.keys
+      ast = @asts[names.sort] ||= Parser.parse(@tokens, @filename, names)
+      state = State.new(base_dir, max_steps)
+      Interpreter.new(state, @filename).run(ast, locals)
+    rescue SystemStackError
+      raise Error.new("LimitError", "nesting is too deep (stack exhausted)", @filename, nil)
+    rescue NoMemoryError
+      raise Error.new("LimitError", "out of memory", @filename, nil)
+    end
+  end
+
+  module_function
+
+  def render(source, vars = {}, base_dir: nil, filename: "(erblite)", max_steps: nil, **more)
+    Template.new(source, filename: filename).render(vars, base_dir: base_dir, max_steps: max_steps, **more)
+  end
+
+  def render_file(path, vars = {}, base_dir: nil, filename: nil, max_steps: nil, **more)
+    vars = vars.merge(more) unless more.empty?
+    source = begin
+      File.binread(path)
+    rescue SystemCallError => e
+      raise Error.new("IOError", e.message, path.to_s, nil)
+    end
+    base_dir ||= File.dirname(File.expand_path(path))
+    Template.new(source, filename: filename || path.to_s).render(vars, base_dir: base_dir, max_steps: max_steps)
+  end
+
+  def normalize_source(source, filename)
+    raise Error.new("TypeError", "template source must be a String", filename, nil) unless source.is_a?(String)
+
+    s = source.dup.force_encoding(Encoding::UTF_8)
+    raise Error.new("SyntaxError", "template is not valid UTF-8", filename, 1) unless s.valid_encoding?
+
+    s
+  end
+
+  # Host variables: Symbol or String keys naming valid identifiers. Values
+  # are copied into fresh template values (Arrays/Hashes are copied, sharing
+  # is preserved), so templates never see host objects.
+  def convert_vars(vars)
+    raise Error.new("TypeError", "variables must be a Hash") unless vars.is_a?(Hash)
+
+    memo = {}.compare_by_identity
+    out = {}
+    vars.each do |k, v|
+      unless k.is_a?(Symbol) || k.is_a?(String)
+        raise Error.new("TypeError", "variable names must be Symbols or Strings, got #{k.inspect}")
+      end
+
+      name = k.to_s
+      next unless name.match?(NAME_RE) && !CodeLexer::KEYWORD_SET[name]
+
+      out[name] = convert_value(v, memo)
+    end
+    out
+  end
+
+  def convert_value(v, memo)
+    case v
+    when nil, true, false, Float, Symbol then v
+    when Integer then Builtins.ck(v)
+    when String
+      s = v.dup
+      s.force_encoding(Encoding::UTF_8) unless s.encoding == Encoding::UTF_8
+      s
+    when Array
+      return memo[v] if memo.key?(v)
+
+      arr = memo[v] = []
+      v.each { |x| arr << convert_value(x, memo) }
+      arr
+    when Hash
+      return memo[v] if memo.key?(v)
+
+      h = memo[v] = {}
+      h.default = convert_value(v.default, memo) unless v.default_proc
+      v.each { |k, x| h[convert_value(k, memo)] = convert_value(x, memo) }
+      h
+    when Range
+      Range.new(convert_value(v.begin, memo), convert_value(v.end, memo), v.exclude_end?)
+    else
+      raise Error.new("TypeError", "unsupported variable value of class #{v.class}")
+    end
+  end
+end

metadata

@@ -0,0 +1,57 @@
+--- !ruby/object:Gem::Specification
+name: erblite
+version: !ruby/object:Gem::Version
+  version: 0.5.0
+platform: ruby
+authors:
+- OpenC3
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: ERBLite renders ERB templates with a tree-walking interpreter for a small,
+  sandboxed subset of Ruby. It never evals template code.
+executables:
+- erblite
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.md
+- README.md
+- bin/erblite
+- lib/erblite.rb
+- lib/erblite/builtins.rb
+- lib/erblite/error.rb
+- lib/erblite/format.rb
+- lib/erblite/interpreter.rb
+- lib/erblite/json.rb
+- lib/erblite/lexer.rb
+- lib/erblite/nodes.rb
+- lib/erblite/parser.rb
+- lib/erblite/sandbox.rb
+- lib/erblite/values.rb
+- lib/erblite/version.rb
+homepage: https://github.com/OpenC3/erblite
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/OpenC3/erblite
+  bug_tracker_uri: https://github.com/OpenC3/erblite/issues
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Sandboxed ERB-syntax template engine running a safe subset of Ruby
+test_files: []