Reflection, Introspection and Tracing

# frozen_string_literal: true

Book = Struct.new(:title)

# A catalogue front-end that answers find_by_<field> calls dynamically.
class Finder
  def initialize(books) = @books = books

  def method_missing(name, *args)
    return super unless name.start_with?("find_by_")

    field = name.to_s.delete_prefix("find_by_")
    @books.find { |book| book.public_send(field) == args.first }
  end

  def respond_to_missing?(name, include_private = false) = name.start_with?("find_by_") || super
end

# The same idea without respond_to_missing?: deliberately incomplete, for the comparison.
class Plain
  # rubocop:disable-next Style/MissingRespondToMissing
  def method_missing(name, *) = name.start_with?("find_by_") ? :found : super
end

finder = Finder.new([Book.new("Ubik")])
puts "dynamic call        #{finder.find_by_title('Ubik').title}"
puts "respond_to?         #{finder.respond_to?(:find_by_title)}"
puts "method object       #{finder.method(:find_by_title).call('Ubik').title}"
puts "methods listing     #{finder.methods.include?(:find_by_title)}"

plain = Plain.new
puts "plain call          #{plain.find_by_x}"
puts "plain respond_to?   #{plain.respond_to?(:find_by_x)}"
begin
  plain.method(:find_by_x)
rescue NameError => e
  puts "plain method        #{e.class}: #{e.message}"
end
begin
  finder.other
rescue NoMethodError => e
  puts "unknown name        #{e.message}"
end

dynamic call        Ubik
respond_to?         true
method object       Ubik
methods listing     false
plain call          found
plain respond_to?   false
plain method        NameError: undefined method 'find_by_x' for class 'Plain'
unknown name        undefined method 'other' for an instance of Finder

# frozen_string_literal: true

# A method that hands out its own binding.
def due_date(loan_days: 14)
  start = "2026-10-01"
  puts "building a binding for #{start}"
  binding
end

b = due_date
puts "local_variables      #{b.local_variables}"
puts "start                #{b.local_variable_get(:start)}"
puts "receiver             #{b.receiver}"
puts "source_location      #{b.source_location.then { |file, line| "#{File.basename(file)}:#{line}" }}"
puts "eval                 #{b.eval('[start, loan_days]')}"
puts "defined?             #{b.local_variable_defined?(:loan_days)} #{b.local_variable_defined?(:nope)}"
b.local_variable_set(:loan_days, 28)
puts "after set            #{b.local_variable_get(:loan_days)}"
b.local_variable_set(:fresh, 1)
puts "new variable         #{b.local_variables} (visible only through this binding)"

# Ruby 4.0: it and numbered parameters are reached through the implicit_parameter methods.
[10].each { puts "implicit (it)        #{it} #{binding.implicit_parameters} #{binding.implicit_parameter_get(:it)}" }
# rubocop:disable-next Style/ItBlockParameter
[1].each { puts "implicit (_1)        #{_1} #{binding.implicit_parameters} #{binding.local_variables}" }

# Kernel-level views of the current scope
name = "Ada"
puts "Kernel#local_variables #{local_variables}"
puts "global_variables       #{global_variables.include?(:$stdout)}"
puts "binding of a block     #{proc { name }.binding.local_variable_get(:name)}"
puts "TOPLEVEL_BINDING       #{TOPLEVEL_BINDING.receiver}"

building a binding for 2026-10-01
local_variables      [:loan_days, :start]
start                2026-10-01
receiver             main
source_location      e05_binding.rb:7
eval                 ["2026-10-01", 14]
defined?             true false
after set            28
new variable         [:fresh, :loan_days, :start] (visible only through this binding)
implicit (it)        10 [:it] 10
implicit (_1)        1 [:_1] [:b, :name]
Kernel#local_variables [:b, :name]
global_variables       true
binding of a block     Ada
TOPLEVEL_BINDING       main

# frozen_string_literal: true

require "shelf"

def where(loc) = "#{File.basename(loc.path)}:#{loc.lineno} #{loc.label}"
def short(lines) = lines.map { it.sub(%r{^\S*/}, "") }

class Reporter
  def report = trace_it

  def trace_it
    puts "caller(0)            #{short(caller(0))}"
    puts "caller_locations(1)  #{where(caller_locations(1, 1).first)}"
    Thread.each_caller_location { |loc| puts "each_caller_location  #{where(loc)}" }
    puts "__method__/__callee__ #{__method__.inspect} #{__callee__.inspect}"
  end
  alias aliased trace_it
end

Reporter.new.report
Reporter.new.aliased
begin
  Shelf::Isbn.new("1234")
rescue ArgumentError => e
  puts "message              #{e.message}"
  puts "backtrace            #{short(e.backtrace)}"
  puts "locations            #{e.backtrace_locations.map { where(it) }}"
  puts "location class       #{e.backtrace_locations.first.class}"
  puts "label, base_label    #{e.backtrace_locations.first.label}, #{e.backtrace_locations.first.base_label}"
end
puts "backtrace limit      #{Thread::Backtrace.limit}"
puts "__FILE__ and __dir__ #{File.basename(__FILE__)} #{File.basename(__dir__)}"

caller(0)            ["e06_backtraces.rb:12:in 'Reporter#trace_it'", "e06_backtraces.rb:9:in 'Reporter#report'", "e06_backtraces.rb:20:in '<main>'"]
caller_locations(1)  e06_backtraces.rb:9 Reporter#report
each_caller_location  e06_backtraces.rb:9 Reporter#report
each_caller_location  e06_backtraces.rb:20 <main>
__method__/__callee__ :trace_it :trace_it
caller(0)            ["e06_backtraces.rb:12:in 'Reporter#trace_it'", "e06_backtraces.rb:21:in '<main>'"]
caller_locations(1)  e06_backtraces.rb:21 <main>
each_caller_location  e06_backtraces.rb:21 <main>
__method__/__callee__ :trace_it :aliased
message              invalid ISBN: 1234
backtrace            ["isbn.rb:8:in 'Shelf::Isbn#initialize'", "e06_backtraces.rb:23:in 'Shelf::Isbn.new'", "e06_backtraces.rb:23:in '<main>'"]
locations            ["isbn.rb:8 Shelf::Isbn#initialize", "e06_backtraces.rb:23 Shelf::Isbn.new", "e06_backtraces.rb:23 <main>"]
location class       Thread::Backtrace::Location
label, base_label    Shelf::Isbn#initialize, initialize
backtrace limit      -1
__FILE__ and __dir__ e06_backtraces.rb ex

x23.rb:1:in 'Object#add': wrong number of arguments (given 1, expected 2) (ArgumentError)

    caller: x23.rb:2
    | add(1)
      ^^^
    callee: x23.rb:1
    | def add(x, y) = x + y
          ^^^
	from x23.rb:2:in '<main>'

# frozen_string_literal: true

def risky = raise(ArgumentError, "boom")

def guarded
  risky
rescue ArgumentError => e
  e.message
end

log = []
events = %i[raise rescue class end b_call c_call script_compiled]
trace = TracePoint.new(*events) do |tp|
  case tp.event
  when :raise then log << "raise            #{tp.raised_exception.class} at line #{tp.lineno}"
  when :rescue then log << "rescue           #{tp.raised_exception.message.inspect} at line #{tp.lineno}"
  when :c_call then log << "c_call           #{tp.defined_class}##{tp.method_id}" if tp.method_id == :upcase
  when :script_compiled then log << "script_compiled  #{tp.eval_script.inspect}"
  else log << "#{tp.event.to_s.ljust(16)} line #{tp.lineno}"
  end
end

trace.enable
guarded
class Draft
  VERSION = 1
end
[1].each { |n| n }
"shelf".upcase
eval("1 + 1", binding, __FILE__, __LINE__)
trace.disable
puts log

raise            ArgumentError at line 3
rescue           "boom" at line 7
class            line 25
end              line 27
b_call           line 28
c_call           String#upcase
script_compiled  "1 + 1"

# frozen_string_literal: true

require "shelf"

isbn = Shelf::Isbn.new("978-0-306-40615-7")
author = Shelf::Author.new("Ursula K. Le Guin")
book = Shelf::Book.new(isbn:, title: "The Dispossessed", author:)
catalog = Shelf::Catalog.new

# 1. target: limits the hook to one method's code
seen = []
only_add = TracePoint.new(:call) { |tp| seen << "#{tp.defined_class}##{tp.method_id}" }
only_add.enable(target: Shelf::Catalog.instance_method(:add)) do
  catalog.add(book)
  catalog.each(&:itself)
end
puts "target: add only      #{seen}"

# 2. an enable block traces the current thread only (since 3.2)
events = []
thread_hook = TracePoint.new(:thread_begin, :thread_end) { |tp| events << tp.event }
thread_hook.enable { Thread.new { 1 }.join }
puts "default thread scope  #{events}"
thread_hook.enable(target_thread: nil) { Thread.new { 1 }.join }
puts "target_thread: nil    #{events}"

# 3. enable / disable return the previous state
hook = TracePoint.new(:c_call) { nil }
puts "enable, enable        #{hook.enable} #{hook.enable}"
puts "disable, disable      #{hook.disable} #{hook.disable}"

# 4. TracePoint.trace enables at once; hooks are not re-entered
own_code = ->(tp) { tp.defined_class == Object || tp.defined_class.to_s.start_with?("Shelf") }
nested = []
outer = TracePoint.trace(:call) do |tp|
  nested << "#{tp.defined_class}##{tp.method_id}" if own_code.call(tp)
  catalog.add(book) if tp.method_id == :first_call
end
def first_call = 1
first_call
outer.disable
puts "no re-entrance        #{nested}"
reentrant = []
outer = TracePoint.trace(:call) do |tp|
  reentrant << "#{tp.defined_class}##{tp.method_id}" if own_code.call(tp)
  TracePoint.allow_reentry { catalog.each(&:itself) } if tp.method_id == :first_call
end
first_call
outer.disable
puts "allow_reentry         #{reentrant}"

target: add only      ["Shelf::Catalog#add"]
default thread scope  []
target_thread: nil    [:thread_begin, :thread_end]
enable, enable        false true
disable, disable      true false
no re-entrance        ["Object#first_call"]
allow_reentry         ["Object#first_call", "Shelf::Catalog#each", "Shelf::Store::Memory#all"]

# frozen_string_literal: true

require "shelf"

# Records an indented call tree for the methods of one namespace.
class CallTracer
  def initialize(namespace) = @namespace = namespace

  def trace(&)
    lines = []
    depth = 0
    hook = TracePoint.new(:call, :return) do |point|
      next unless point.defined_class.to_s.start_with?(@namespace)

      depth -= 1 if point.event == :return
      lines << "#{'  ' * depth}#{describe(point)}"
      depth += 1 if point.event == :call
    end
    hook.enable(&)
    lines
  end

  private

  def describe(point)
    name = "#{point.defined_class.to_s.delete_prefix('Shelf::')}##{point.method_id}"
    point.event == :call ? "-> #{name}" : "<- #{name} = #{summary(point.return_value)}"
  end

  def summary(value)
    case value
    in String | Symbol | Integer | nil | true | false then value.inspect
    else value.class.to_s.delete_prefix("Shelf::")
    end
  end
end

isbn = Shelf::Isbn.new("978-0-306-40615-7")
author = Shelf::Author.new("Ursula K. Le Guin")
book = Shelf::Book.new(isbn:, title: "The Dispossessed", author:)
catalog = Shelf::Catalog.new.add(book)

tracer = CallTracer.new("Shelf::")
first = tracer.trace { Shelf::Loan.new(book).describe }
puts first
puts
second = tracer.trace { catalog.map(&:title) }
puts second

-> Loan#initialize
<- Loan#initialize = :available
-> Loan#describe
<- Loan#describe = "The Dispossessed is on the shelf"

-> Catalog#each
  -> Store::Memory#all
  <- Store::Memory#all = Array
<- Catalog#each = Array

$ ruby -W:deprecated script.rb      # one category on
$ ruby -W:no-experimental script.rb # one category off
$ ruby -w script.rb                 # verbose: $VERBOSE = true, deprecated on
$ ruby -W0 script.rb                # silent: $VERBOSE = nil
$ RUBYOPT="-W:deprecated" ruby script.rb

# frozen_string_literal: true

# Capture every warning instead of printing it (useful in tests).
module WarningCapture
  Entry = Data.define(:category, :message)

  def self.entries = @entries ||= []

  def warn(message, category: nil)
    WarningCapture.entries << Entry.new(category:, message: message.chomp)
    nil
  end
end
Warning.extend(WarningCapture)

def report(label)
  before = WarningCapture.entries.size
  yield
  fresh = WarningCapture.entries.drop(before)
  puts "#{label.ljust(26)} #{fresh.empty? ? 'nothing' : fresh.map { [it.category, it.message] }}"
end

puts "categories                 #{Warning.categories}"
puts "defaults                   #{Warning.categories.to_h { [it, Warning[it]] }}"
report("warn, no category") { warn "plain" }
report("deprecated off") { warn "old way", category: :deprecated }
Warning[:deprecated] = true
report("deprecated on") { warn "old way", category: :deprecated }
report("uplevel: 0") { warn "careful", uplevel: 0 }
report("chilled string") { eval("text = 'lit'; text << 'x'", binding, __FILE__, __LINE__) }
report("Warning.warn direct") { Warning.warn("direct\n") }
report("$VERBOSE = nil") do
  $VERBOSE = nil
  warn "silenced"
ensure
  $VERBOSE = false
end
begin
  warn "bad", category: :nope
rescue ArgumentError => e
  puts "unknown category           #{e.class}: #{e.message}"
end
Warning[:experimental] = true
report("experimental feature") { Ractor.new { 1 }.value }

categories                 [:deprecated, :experimental, :performance, :strict_unused_block]
defaults                   {deprecated: false, experimental: true, performance: false, strict_unused_block: false}
warn, no category          [[nil, "plain"]]
deprecated off             nothing
deprecated on              [[:deprecated, "old way"]]
uplevel: 0                 [[nil, "e11_warnings.rb:29: warning: careful"]]
chilled string             [[:deprecated, "e11_warnings.rb:30: warning: literal string will be frozen in the future (run with --debug-frozen-string-literal for more information)"]]
Warning.warn direct        [[nil, "direct"]]
$VERBOSE = nil             nothing
unknown category           ArgumentError: unknown category: nope
experimental feature       [[:experimental, "e11_warnings.rb:44: warning: Ractor API is experimental and may change in future versions of Ruby."]]

# frozen_string_literal: true

source = <<~RUBY
  def late_fee(days, rate: 5)
    days > 14 ? (days - 14) * rate : 0
  end
RUBY

iseq = RubyVM::InstructionSequence.compile(source, "late_fee.rb")
puts "label, path        #{iseq.label}, #{iseq.path}"
puts "first_lineno       #{iseq.first_lineno}"
puts "to_a header        #{iseq.to_a.first(3)}"
puts

# Disassemble a method that already exists in this process.
class Calculator
  def double(value) = value * 2
end

method_iseq = RubyVM::InstructionSequence.of(Calculator.instance_method(:double))
puts method_iseq.disasm
options = RubyVM::InstructionSequence.compile_option.slice(:inline_const_cache, :specialized_instruction)
puts "compile options    #{options}"
puts "eval a fresh iseq  #{RubyVM::InstructionSequence.compile('6 * 7').eval}"
puts "of a C method      #{RubyVM::InstructionSequence.of(1.method(:+)).inspect}"

label, path        <compiled>, late_fee.rb
first_lineno       1
to_a header        ["YARVInstructionSequence/SimpleDataFormat", 4, 0]

== disasm: #<ISeq:double@e14_instruction_sequence.rb:17 (17,2)-(17,31)>
local table (size: 1, argc: 1 [opts: 0, rest: -1, post: 0, block: -1, kw: -1@-1, kwrest: -1])
[ 1] value@0<Arg>
0000 getlocal_WC_0                          value@0                   (  17)[Ca]
0002 putobject                              2
0004 opt_mult                               <calldata!mid:*, argc:1, ARGS_SIMPLE>[CcCr]
0006 leave                                  [Re]
compile options    {inline_const_cache: true, specialized_instruction: true}
eval a fresh iseq  42
of a C method      nil

$ ruby --dump=insns -e 'def double(v) = v * 2'
== disasm: #<ISeq:<main>@-e:1 (1,0)-(1,21)>
0000 definemethod                           :double, double           (   1)[Li]
0003 putobject                              :double
0005 leave

== disasm: #<ISeq:double@-e:1 (1,0)-(1,21)>
local table (size: 1, argc: 1 [opts: 0, rest: -1, post: 0, block: -1, kw: -1@-1, kwrest: -1])
[ 1] v@0<Arg>
0000 getlocal_WC_0                          v@0                       (   1)[Ca]
0002 putobject                              2
0004 opt_mult                               <calldata!mid:*, argc:1, ARGS_SIMPLE>[CcCr]
0006 leave                                  [Re]

# frozen_string_literal: true

source = <<~RUBY
  def price(days)
    days * 2 + 1
  end
RUBY

def dump(node, depth = 0)
  indent = "  " * depth
  return puts("#{indent}#{node.inspect}") unless node.is_a?(RubyVM::AbstractSyntaxTree::Node)

  puts "#{indent}#{node.type} #{node.first_lineno}:#{node.first_column}-#{node.last_lineno}:#{node.last_column}"
  return if node.type == :ARGS # ten parameter slots, skipped here

  node.children.each { dump(it, depth + 1) }
end

tree = RubyVM::AbstractSyntaxTree.parse(source)
puts "root type   #{tree.type}"
dump(tree.children.last)

begin
  RubyVM::AbstractSyntaxTree.of(method(:dump))
rescue RuntimeError => e
  puts "of(method)  #{e.message}"
end

tokens = RubyVM::AbstractSyntaxTree.parse("puts 1 + 2", keep_tokens: true).tokens
puts "tokens      #{tokens.first(4).map { it[1..2] }}"

root type   SCOPE
DEFN 1:0-3:3
  :price
  SCOPE 1:0-3:3
    [:days]
    ARGS 1:10-1:14
    OPCALL 2:2-2:14
      OPCALL 2:2-2:10
        LVAR 2:2-2:6
          :days
        :*
        LIST 2:9-2:10
          INTEGER 2:9-2:10
            2
          nil
      :+
      LIST 2:13-2:14
        INTEGER 2:13-2:14
          1
        nil
of(method)  cannot get AST for ISEQ compiled by prism
tokens      [[:tIDENTIFIER, "puts"], [:tSP, " "], [:tINTEGER, "1"], [:tSP, " "]]

# frozen_string_literal: true

require "prism"
require "ripper"
require "shelf"

source = <<~RUBY
  # Price a loan.
  def price(days, rate: 2)
    days * rate + 1
  end
RUBY

result = Prism.parse(source)
puts "result class      #{result.class}, success? #{result.success?}"
puts "errors, warnings  #{result.errors.size}, #{result.warnings.size}"
puts "comments          #{result.comments.map { it.location.slice }}"

method_node = result.value.statements.body.first
puts "node              #{method_node.class} #{method_node.name.inspect}"
puts "lines             #{method_node.location.start_line}-#{method_node.location.end_line}"
puts "parameters        #{method_node.parameters.requireds.map(&:name)} #{method_node.parameters.keywords.map(&:name)}"
puts "source slice      #{method_node.location.slice.lines.first.chomp}"
puts "first tokens      #{Prism.lex('a = 1').value.map { |token, _state| token.type }}"
puts "parse_success?    #{Prism.parse_success?('1 + 2')} #{Prism.parse_success?('1 +')}"

broken = Prism.parse("def price(\n  1 +\nend")
broken.errors.each { puts "  line #{it.location.start_line}: #{it.message} (#{it.type})" }
puts "tree still built  #{broken.value.class}"

# A visitor walks the tree; override only the node types you care about.
class MethodCollector < Prism::Visitor
  attr_reader :found

  def initialize
    super
    @found = []
  end

  def visit_def_node(node)
    @found << "#{node.name}:#{node.location.start_line}"
    super
  end
end

# Reflection finds the file; Prism parses it.
isbn_file = Shelf::Isbn.instance_method(:to_s).source_location.first
collector = MethodCollector.new
Prism.parse_file(isbn_file).value.accept(collector)
puts "defs in isbn.rb   #{collector.found}"

# The same question under two language versions: `it` is a method call in 3.3 and a parameter in 3.4.
%w[3.3 3.4].each do |version|
  call = Prism.parse("[1].map { it }", version:).value.statements.body.first
  puts "it under #{version}      #{call.block.body.body.first.class}"
end

# Ripper is the older, event-based API; Prism ships a drop-in translation of it.
puts "Ripper.sexp       #{Ripper.sexp('1 + 2')}"
puts "Prism's Ripper    #{Prism::Translation::Ripper.sexp('1 + 2') == Ripper.sexp('1 + 2')}"
puts "Prism::VERSION    #{Prism::VERSION}"

result class      Prism::ParseResult, success? true
errors, warnings  0, 0
comments          ["# Price a loan."]
node              Prism::DefNode :price
lines             2-4
parameters        [:days] [:rate]
source slice      def price(days, rate: 2)
first tokens      [:IDENTIFIER, :EQUAL, :INTEGER, :EOF]
parse_success?    true false
  line 2: unexpected integer; expected a `)` to close the parameters (def_params_term_paren)
  line 2: unexpected '+', expecting end-of-input (expect_eol_after_statement)
  line 2: unexpected 'end', expected a receiver for unary `+` (unary_receiver)
  line 3: unexpected 'end', assuming it is closing the parent method definition (unexpected_token_close_context)
tree still built  Prism::ProgramNode
defs in isbn.rb   ["initialize:6", "to_s:13", "valid?:17"]
it under 3.3      Prism::CallNode
it under 3.4      Prism::ItLocalVariableReadNode
Ripper.sexp       [:program, [[:binary, [:@int, "1", [1, 0]], :+, [:@int, "2", [1, 4]]]]]
Prism's Ripper    true
Prism::VERSION    1.8.1