steadfast 0.0.1 → 0.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8abea2bc78eddf9d3a4785cbb385799f1ea1ec21e11b794cfc32f8b13b5a8639
-  data.tar.gz: 2ddf099e67ee8725df09a644bca9a25a26031c17363b10bdecea7b8e73511487
+  metadata.gz: 5d446eb7d3f0db23310b1ea5dfc4343ff7b82bfaae804de963ea42616977b2ac
+  data.tar.gz: c02e0997705985da9800da6db4a88ea9e5a652e4e6562a2a7aba276eadf8d536
 SHA512:
-  metadata.gz: 93299385d7b4098bdb409495d57c142de725e6328cf185f5e0a27d087b8e2e35656c31dd433d3324396f6959b8ec4c0114bbf69911788f2aefcedcb6b12d77fb
-  data.tar.gz: 04c5a30cc22f2ff6268a6fb0345c39a74632ccd559b215280dac020a5717f34802d9e8e669588a23ee21bdca040dca9d308a6153b25bcbf9896fcb50d63b397d
+  metadata.gz: 080361ccb2c5f651657f429f82c01444c60cc208b1a4fe2bb2c390dd75d879491347a12aec7f43dcc28dc8e8eb0ee2d80d18e1aa6d6765a810d2ef3f5ce70d41
+  data.tar.gz: a67148f3b42ce798e8278f043be6021e6cfa6fc3d9c89febb69bc1b0b68041ae86ef449af30351a55ec795c38fa6a46e245349118f9dab16564edd23e2140521

data/CHANGELOG.md

@@ -1,3 +1,9 @@
+# 0.0.2 2026-11-09
+
+- Emit newline upon detecting a source change while sourcifying an AST
+- Implement source mapping
+- Implement `Steadfast.translate_backtrace`
+
 # 0.0.1 2026-11-06
 
-- Implement Steadfast.to_source
+- Implement `Steadfast.to_source`

data/README.md

@@ -1,2 +1,24 @@
-# steadfast
-A modern meta-programming gem for Ruby
+<h1 align="center">
+  <br>
+  Steadfast
+</h1>
+
+<h4 align="center">A Metaprogramming Gem for Ruby</h4>
+
+<p align="center">
+  <a href="http://rubygems.org/gems/steadfast">
+    <img src="https://badge.fury.io/rb/steadfast.svg" alt="Ruby gem">
+  </a>
+  <a href="https://github.com/digital-fabric/steadfast/actions">
+    <img src="https://github.com/digital-fabric/steadfast/actions/workflows/test.yml/badge.svg" alt="Tests">
+  </a>
+  <a href="https://github.com/digital-fabric/steadfast/blob/master/LICENSE">
+    <img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="MIT License">
+  </a>
+</p>
+
+<p align="center">
+  <img src="./steadfast.png">
+</p>
+
+More information coming soon...

data/lib/steadfast/sourcifier.rb

@@ -1,5 +1,17 @@
+# frozen_string_literal: true
+
 module Steadfast
+
+  # A Sourcifier is used for converting an AST to source code. Sourcifier is
+  # implemented as an AST visitor that walks the AST, copying the relevant
+  # strings from each node into a buffer, with the addition of whitespace,
+  # commas, semicolons and newlines where applicable.
   class Sourcifier < Ruby::Prism::BasicVisitor
+    # The following visit plans are used for generating code for node types that
+    # don't require special logic. For each node, a list of fields/elements to
+    # emit is given. For each node, a visit_xxx_node method is generated from
+    # its visit plan. Nodes requiring special logic have normal visit_xxx_node
+    # method below.
     VISIT_PLANS = {
       alias_global_variable:      [:keyword_loc, :whitespace, :new_name, :whitespace, :old_name],
       alias_method:               [:keyword_loc, :whitespace, :new_name, :whitespace, :old_name],
@@ -42,8 +54,8 @@ module Steadfast
       global_variable_target:     :emit_verbatim,
       global_variable_write:      [:name_loc, :operator_loc, :value],
       imaginary:                  :emit_verbatim,
-      implicit:                   :emit_nothing,
-      implicit_rest:              :emit_nothing,
+      implicit:                   :nop,
+      implicit_rest:              :nop,
       in:                         [:in_loc, :whitespace, :pattern, :whitespace, :then_loc],
       index_target:               [:receiver, :opening_loc, :arguments, :closing_loc],
       instance_variable_operator_write: [:name_loc, :whitespace, :binary_operator_loc, :whitespace, :value],
@@ -52,7 +64,7 @@ module Steadfast
       instance_variable_target:   :emit_verbatim,
       instance_variable_write:    [:name_loc, :operator_loc, :value],
       integer:                    :emit_verbatim,
-      it_parameters:              :emit_nothing,
+      it_parameters:              :nop,
       it_local_variable_read:     :emit_verbatim,
       keyword_rest_parameter:     [:operator_loc, :name_loc],
       keyword_parameter:          :emit_verbatim,
@@ -70,7 +82,7 @@ module Steadfast
       next:                       [:keyword_loc, :whitespace, :arguments],
       nil:                        :emit_verbatim,
       no_keywords_parameter:      :emit_verbatim,
-      numbered_parameters:        :emit_nothing,
+      numbered_parameters:        :nop,
       optional_parameter:         [:name_loc, :whitespace, :operator_loc, :whitespace, :value],
       optional_keyword_parameter: [:name_loc, :whitespace, :value],
       or:                         [:left, :whitespace, :operator_loc, :whitespace, :right],
@@ -101,19 +113,30 @@ module Steadfast
 
     attr_reader :buffer
 
-    def initialize(**)
-      @buffer = +''
+    # Initializes the Sourcifier instance.
+    #
+    # @param start_line []
+    # @return [void]
+    def initialize(source_location: nil, sourcemap: false)
+      @filename, @line = source_location
+      @line ||= 1
+      @sourcemap = sourcemap
+
+      raise Steadfast::Error, "No filename given, can't generate source map" if @sourcemap && !@filename
     end
 
-    def to_source(node)
-      @buffer.clear
-      visit(node)
+    # Converts the given AST to source code.
+    #
+    # @param ast [Ruby::Prism::Node] AST
+    # @return [String] source code
+    def to_source(ast)
+      @buffer = +''
+      visit(ast)
       @buffer
     end
 
-    VISIT_PLANS.each do |key, plan|
-      sym = :"visit_#{key}_node"
-      define_method(sym) { |n| visit_plan(plan, n) }
+    VISIT_PLANS.each do |kind, plan|
+      define_method(:"visit_#{kind}_node") { |n| visit_node_with_plan(n, plan) }
     end
 
     def visit_array_node(node)
@@ -577,10 +600,15 @@ module Steadfast
 
     private
 
-    def visit_plan(plan, node)
+    # Visits a node with the given visit plan.
+    #
+    # @param node [Ruby::Prism::Node]
+    # @param plan [Array<Symbol>, Symbol] visit plan
+    # @return [void]
+    def visit_node_with_plan(node, plan)
       return send(plan, node) if plan.is_a?(Symbol)
 
-      plan.each_with_index do |sym, idx|
+      plan.each do |sym|
         case sym
         when :newline
           emit_newline
@@ -593,17 +621,28 @@ module Steadfast
       end
     end
 
+    # Visit an array of nodes, with commas emitted between them. The given comma
+    # flag determines whether to emit a comma before visiting the next node in
+    # the list, and is set to true after visiting a node.
+    #
+    # @param list [Array<Ruby::Prism::Node>, nil] node list or nil
+    # @param comma [bool] comma flag
+    # @return [bool] comma flag
     def visit_comma_separated_nodes(list, comma = false)
-      if list
-        list.each do |child|
-          emit_comma if comma
-          emit_code(child)
-          comma = true
-        end
+      return false if !list
+
+      list.each do |child|
+        emit_comma if comma
+        emit_code(child)
+        comma = true
       end
       comma
     end
 
+    # Visit an array of nodes separated by whitespace.
+    #
+    # @param list [Array<Ruby::Prism::Node>, nil] node list or nil
+    # @return [void]
     def visit_space_separated_nodes(list)
       return if !list
 
@@ -615,38 +654,88 @@ module Steadfast
       end
     end
 
+    # Appends a node's location verbatim into the source code buffer.
+    #
+    # @param node [Ruby::Prism::Node]
+    # @return [void]
     def emit_verbatim(node)
       emit_code(node.location)
     end
 
+    # Appends a code location (or a node) into the source code buffer.
+    #
+    # @param loc [Ruby::Prism::Location, Ruby::Prism::Node, nil]
+    # @return [void]
     def emit_code(loc)
       return if !loc
       return visit(loc) if loc.is_a?(Ruby::Prism::Node)
 
+      record_loc_source_mapping(loc) if @sourcemap
       emit(loc.slice.chomp)
-    end
-
+      @last_loc = loc
+    end
+
+    # Adds an entry to the sourcemap hash when detecting a change of line or
+    # filename before emitting an AST location. If a change of filename is
+    # detected, a newline is emitted in order to more accurately be able to
+    # translate backtraces if needed.
+    #
+    # @param loc [Ruby::Prism::Location] code location
+    # @return [void]
+    def record_loc_source_mapping(loc)
+      source = loc.send(:source)
+      last_source = @last_loc&.send(:source)
+      different_source = source != last_source
+      changed = different_source || (@last_loc && (loc.start_line != @last_loc.start_line))
+      return if !changed
+
+      emit_newline if different_source && last_source
+      Steadfast.sourcemap["#{@filename}:#{@line}"] ||= "#{loc.send(:source).__filename__}:#{loc.start_line}"
+    end
+
+    # Appends the given string into the source code buffer.
+    #
+    # @param str [String]
+    # @return [void]
     def emit(str)
       @buffer << str
+      @line += str.count("\n")
     end
 
+    # Appends a newline into the source code buffer.
+    #
+    # @return [void]
     def emit_newline
-      @buffer << "\n" if @buffer[-1] != "\n"
+      return if @buffer[-1] == "\n"
+      
+      @buffer << "\n"
+      @line += 1
     end
 
+    # Appends a space character into the source code buffer.
+    #
+    # @return [void]
     def emit_whitespace
       @buffer << " "
     end
 
+    # Appends a comma into the source code buffer.
+    #
+    # @return [void]
     def emit_comma
       @buffer << ","
     end
 
+    # Appends a semicolon into the source code buffer.
+    #
+    # @return [void]
     def emit_semicolon
       @buffer << ';'
     end
 
-    def emit_nothing(node)
-    end
+    # A nop method for doing nothing.
+    #
+    # @return [void]
+    def nop(node); end
   end
 end

data/lib/steadfast/version.rb

@@ -1,4 +1,4 @@
 module Steadfast
   # Steadfast version
-  VERSION = '0.0.1'
+  VERSION = '0.0.2'
 end

data/lib/steadfast.rb

@@ -2,17 +2,57 @@
 
 require 'steadfast/sourcifier'
 
+# Tell Ruby to keep script lines in memory, so calling Proc#syntax_tree or
+# Method#syntax_tree will work.
 RubyVM.keep_script_lines = true
 
+# Steadfast is a metaprogramming gem for Ruby. Steadfast provides a
+# general-purpose mecehanism for generating and rewriting Ruby code at runtime.
 module Steadfast
+  # Extensions to Ruby::Prism::Source
+  module PrismSourceExtensions
+
+    # The __filename__ attribute lets us track the source location for a given
+    # AST.
+    attr_accessor :__filename__
+  end
+  ::Ruby::Prism::Source.include(PrismSourceExtensions)
+
+  # A base error class for Steadfast errors
   class Error < StandardError
   end
 
   class << self
+    # Returns the global Steadfast source map hash. Currently *not* thread-safe.
+    # 
+    # @return [Hash] source map
+    def sourcemap
+      @sourcemap ||= {}
+    end
+
+    # Translates entries in the given backtrace according to the global source
+    # map.
+    #
+    # @param bt [Array<String>] backtrace
+    # @return [Array<String>] translated source map
+    def translate_backtrace(bt)
+      bt.map {
+        if (m = it.match(/^(.+)(\:in.+)$/)) && (loc = sourcemap[m[1]])
+          "#{sourcemap[m[1]]}#{m[2]}"
+        else
+          it
+        end
+      }
+    end
+
+    # Returns an AST for the given object.
+    #
+    # @param obj [Proc, Method, UnboundedMethod, Ruby::Prism::Node]
+    # @return [Ruby::Prism::Node]
     def to_ast(obj)
       case obj
       when Proc, Method, UnboundMethod
-        obj.syntax_tree
+        obj.syntax_tree.tap { set_source_filename(it, obj) }
       when Ruby::Prism::Node
         obj
       else
@@ -20,13 +60,29 @@ module Steadfast
       end
     end
 
-    def to_source(obj, **)
-      obj = to_ast(obj)
-      Sourcifier.new(**).to_source(obj)
+    # Returns the source code to the given object by sourcifying its AST.
+    #
+    # @param obj [Proc, Method, UnboundedMethod, Ruby::Prism::Node]
+    # @return [String]
+    def to_source(obj, **opts)
+      ast = to_ast(obj)
+      Sourcifier.new(**opts).to_source(ast)
     end
 
     private
 
+    # Sets 
+    def set_source_filename(ast, obj)
+      source = ast.send(:source)
+      source.__filename__ ||= obj.source_location.first
+    end
+
+    # Finds the AST for the given proc. This method is currently not in use, but
+    # we may eventually use this code in order to provide backward compatibility
+    # for Ruby < 4.1.
+    #
+    # @param proc [Proc]
+    # @return [Ruby::Prism::Node]
     def proc_ast(proc)
       fn, lineno = proc.source_location
       pr = Prism.parse(get_source(fn), filepath: fn)
@@ -53,6 +109,12 @@ module Steadfast
       raise Sirop::Error, "Could not get source for proc"
     end
 
+    # Finds the AST for the given method. This method is currently not in use,
+    # but we may eventually use this code in order to provide backward
+    # compatibility for Ruby < 4.1.
+    #
+    # @param method [Method, UnboundMethod]
+    # @return [Ruby::Prism::Node]
     def method_ast(method)
       fn, lineno = method.source_location
       pr = Prism.parse(get_source(fn), filepath: fn)
@@ -66,12 +128,21 @@ module Steadfast
       end
     end
 
+    # Returns the content of the given filename. Returns the IRB line buffer if
+    # '(irb)' is given. This method is not currently used.
+    #
+    # @param fn [String]
+    # @return [String] source code
     def get_source(fn)
       return get_irb_source if fn == '(irb)'
 
       IO.read(fn)
     end
 
+    # Returns the IRB line buffer (the source code for the current IRB session.)
+    # This method is currently not used.
+    #
+    # @return [String] IRB line buffer
     def get_irb_source
       io = IRB.CurrentContext.io
       last_line = io.instance_variable_get(:@line_no)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: steadfast
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.0.2
 platform: ruby
 authors:
   - Sharon Rosner