API Structure

[baweaver]

Thinking over ways to express this a bit more clearly.

---

Current API:

def testing(a, b, c)
  raise 'heck' if a.is_a?(Numeric) && a > 20

  d = 5 if c.is_a?(Numeric) && c > 3

  a + b + c
end

testing_spy = TraceSpy::Method.new(:testing) do |spy|
  # On the arguments, given as keywords, will yield arguments to the block
  spy.on_arguments do |m|
    m.when(a: String, b: String, c: String) do |v|
      puts "Oh hey! You called me with strings: #{v}"
    end

    m.when(a: 1, b: 2, c: 3) do |v|
      puts "My args were 1, 2, 3: #{v}"
    end
  end

  # On an exception, will yield exception to the block
  spy.on_exception do |m|
    m.when(RuntimeError) do |e|
      puts "I encountered an error: #{e}"
    end
  end

  # On a return value, will yield the return to the block
  spy.on_return do |m|
    m.when(String) do |v|
      puts "Strings in, Strings out no?: #{v}. I got this in though: #{spy.current_arguments}"
    end

    m.when(:even?) do |v|
      puts "I got an even return: #{v}"
    end
  end

  # On a local variable being present:
  spy.on_locals do |m|
    m.when(d: 5) do |v|
      puts "I saw d was a local in here!: #{v}. I could also ask this: #{spy.current_local_variables}"
    end
  end
end

---

Proposed ideas:

TraceSpy
  # Required conditions
  .on(method: 'testing', class: Any)
  # Optional conditional branches
  .with_return(Integer) { |ret_val| ... }
  .with_arguments(a: String, b: String) { |args| ... }
  # Combining optional-type branches
  .with(
    arguments: {
      a: Integer,
      b: nil,
      c: Float
    },
    return: Integer
  )

The problem is that some branch types are incompatible with eachother. exception handlers, for instance, cannot get arguments:

https://bugs.ruby-lang.org/issues/15568

That said, exceptions or warnings could be raised in this case.

The main idea of this change is to condense the API down into something more minimal you could hammer our in a REPL.