# The Breakpoint library provides the convenience of # being able to inspect and modify state, diagnose # bugs all via IRB by simply setting breakpoints in # your applications by the call of a method. # # This library was written and is supported by me, # Florian Gross. I can be reached at flgr@ccan.de # and enjoy getting feedback about my libraries. # # The whole library (including breakpoint_client.rb # and binding_of_caller.rb) is licensed under the # same license that Ruby uses. (Which is currently # either the GNU General Public License or a custom # one that allows for commercial usage.) If you for # some good reason need to use this under another # license please contact me. require 'irb' require 'binding_of_caller' require 'drb' require 'drb/acl' module Breakpoint extend self # This will pop up an interactive ruby session at a # pre-defined break point in a Ruby application. In # this session you can examine the environment of # the break point. # # You can get a list of variables in the context using # local_variables via +local_variables+. You can then # examine their values by typing their names. # # You can have a look at the call stack via +caller+. # # The source code around the location where the breakpoint # was executed can be examined via +source_lines+. Its # argument specifies how much lines of context to display. # The default amount of context is 5 lines. Note that # the call to +source_lines+ can raise an exception when # it isn't able to read in the source code. # # breakpoints can also return a value. They will execute # a supplied block for getting a default return value. # A custom value can be returned from the session by doing # +throw(:debug_return, value)+. # # You can also give names to break points which will be # used in the message that is displayed upon execution # of them. # # Here's a sample of how breakpoints should be placed: # # class Person # def initialize(name, age) # @name, @age = name, age # breakpoint("Person#initialize") # end # # attr_reader :age # def name # breakpoint("Person#name") { @name } # end # end # # person = Person.new("Random Person", 23) # puts "Name: #{person.name}" # # And here is a sample debug session: # # Executing break point "Person#initialize" at file.rb:4 in `initialize' # irb(#):001:0> local_variables # => ["name", "age", "_", "__"] # irb(#):002:0> [name, age] # => ["Random Person", 23] # irb(#):003:0> [@name, @age] # => ["Random Person", 23] # irb(#):004:0> self # => # # irb(#):005:0> @age += 1; self # => # # irb(#):006:0> exit # Executing break point "Person#name" at file.rb:9 in `name' # irb(#):001:0> throw(:debug_return, "Overriden name") # Name: Overriden name # # Breakpoint sessions will automatically have a few # convenience methods available. See Breakpoint::CommandBundle # for a list of them. # # Breakpoints can also be used remotely over sockets. # This is implemented by running part of the IRB session # in the application and part of it in a special client. # You have to call Breakpoint.activate_drb to enable # support for remote breakpoints and then run # breakpoint_client.rb which is distributed with this # library. See the documentation of Breakpoint.activate_drb # for details. def breakpoint(id = nil, context = nil, &block) callstack = caller callstack.slice!(0, 3) if callstack.first["breakpoint"] file, line, method = *callstack.first.match(/^(.+?):(\d+)(?::in `(.*?)')?/).captures message = "Executing break point " + (id ? "#{id.inspect} " : "") + "at #{file}:#{line}" + (method ? " in `#{method}'" : "") if context then return handle_breakpoint(context, message, file, line, &block) end Binding.of_caller do |binding_context| handle_breakpoint(binding_context, message, file, line, &block) end end module CommandBundle # Proxy to a Breakpoint client. Lets you directly execute code # in the context of the client. class Client def initialize(eval_handler) # :nodoc: @eval_handler = eval_handler end instance_methods.each do |method| next if method[/^__.+__$/] undef_method method end # Executes the specified code at the client. def eval(code) @eval_handler.call(code) end # Will execute the specified statement at the client. def method_missing(method, *args) if args.empty? result = eval("#{method}") else result = eval("#{method}(*Marshal.load(#{Marshal.dump(args).inspect}))") end unless [true, false, nil].include?(result) result.extend(DRbUndumped) rescue nil end return result end end # Returns the source code surrounding the location where the # breakpoint was issued. def source_lines(context = 5, return_line_numbers = false) lines = File.readlines(@__bp_file).map { |line| line.chomp } break_line = @__bp_line start_line = [break_line - context, 1].max end_line = break_line + context result = lines[(start_line - 1) .. (end_line - 1)] if return_line_numbers then return [start_line, break_line, result] else return result end end # Lets an object that will forward method calls to the breakpoint # client. This is useful for outputting longer things at the client # and so on. You can for example do these things: # # client.puts "Hello" # outputs "Hello" at client console # # outputs "Hello" into the file temp.txt at the client # client.File.open("temp.txt", "w") { |f| f.puts "Hello" } def client() if Breakpoint.use_drb? then Client.new(Breakpoint.drb_service.eval_handler) else Client.new(lambda { |code| eval(code, TOPLEVEL_BINDING) }) end end end def handle_breakpoint(context, message, file = "", line = "", &block) # :nodoc: catch(:debug_return) do |value| eval(%{ @__bp_file = #{file.inspect} @__bp_line = #{line} extend Breakpoint::CommandBundle extend DRbUndumped }, context) rescue nil if not use_drb? then puts message IRB.start(nil, IRB::WorkSpace.new(context)) else @drb_service.add_breakpoint(context, message) end block.call if block end end # These exceptions will be raised on failed asserts # if Breakpoint.asserts_cause_exceptions is set to # true. class FailedAssertError < RuntimeError end # This asserts that the block evaluates to true. # If it doesn't evaluate to true a breakpoint will # automatically be created at that execution point. # # You can disable assert checking in production # code by setting Breakpoint.optimize_asserts to # true. (It will still be enabled when Ruby is run # via the -d argument.) # # Example: # person_name = "Foobar" # assert { not person_name.nil? } # # Note: If you want to use this method from an # unit test, you will have to call it by its full # name, Breakpoint.assert. def assert(context = nil, &condition) return if Breakpoint.optimize_asserts and not $DEBUG return if yield callstack = caller callstack.slice!(0, 3) if callstack.first["assert"] file, line, method = *callstack.first.match(/^(.+?):(\d+)(?::in `(.*?)')?/).captures message = "Assert failed at #{file}:#{line}#{" in `#{method}'" if method}." if Breakpoint.asserts_cause_exceptions and not $DEBUG then raise(Breakpoint::FailedAssertError, message) end message += " Executing implicit breakpoint." if context then return handle_breakpoint(context, message, file, line) end Binding.of_caller do |context| handle_breakpoint(context, message, file, line) end end # Whether asserts should be ignored if not in debug mode. # Debug mode can be enabled by running ruby with the -d # switch or by setting $DEBUG to true. attr_accessor :optimize_asserts self.optimize_asserts = false # Whether an Exception should be raised on failed asserts # in non-$DEBUG code or not. By default this is disabled. attr_accessor :asserts_cause_exceptions self.asserts_cause_exceptions = false @use_drb = false attr_reader :drb_service # :nodoc: class DRbService # :nodoc: include DRbUndumped def initialize @handler = @eval_handler = @collision_handler = nil IRB.instance_eval { @CONF[:RC] = true } IRB.run_config end def collision sleep(0.5) until @collision_handler @collision_handler.call end def ping; end def add_breakpoint(context, message) workspace = IRB::WorkSpace.new(context) workspace.extend(DRbUndumped) sleep(0.5) until @handler @handler.call(workspace, message) end def register_handler(&block) @handler = block end def unregister_handler @handler = nil end attr_reader :eval_handler def register_eval_handler(&block) @eval_handler = block end def unregister_eval_handler @eval_handler = lambda { } end def register_collision_handler(&block) @collision_handler = block end def unregister_collision_handler @collision_handler = lambda { } end end # Will run Breakpoint in DRb mode. This will spawn a server # that can be attached to via the breakpoint-client command # whenever a breakpoint is executed. This is useful when you # are debugging CGI applications or other applications where # you can't access debug sessions via the standard input and # output of your application. # # You can specify an URI where the DRb server will run at. # This way you can specify the port the server runs on. The # default URI is druby://localhost:42531. # # Please note that breakpoints will be skipped silently in # case the DRb server can not spawned. (This can happen if # the port is already used by another instance of your # application on CGI or another application.) # # Also note that by default this will only allow access # from localhost. You can however specify a list of # allowed hosts or nil (to allow access from everywhere). # But that will still not protect you from somebody # reading the data as it goes through the net. # # A good approach for getting security and remote access # is setting up an SSH tunnel between the DRb service # and the client. This is usually done like this: # # $ ssh -L20000:127.0.0.1:20000 -R10000:127.0.0.1:10000 example.com # (This will connect port 20000 at the client side to port # 20000 at the server side, and port 10000 at the server # side to port 10000 at the client side.) # # After that do this on the server side: (the code being debugged) # Breakpoint.activate_drb("druby://127.0.0.1:20000", "localhost") # # And at the client side: # ruby breakpoint_client.rb -c druby://127.0.0.1:10000 -s druby://127.0.0.1:20000 # # Running through such a SSH proxy will also let you use # breakpoint.rb in case you are behind a firewall. # # Detailed information about running DRb through firewalls is # available at http://www.rubygarden.org/ruby?DrbTutorial def activate_drb(uri = 'druby://localhost:42531', allowed_hosts = ['localhost', '127.0.0.1', '::1']) return false if @use_drb if allowed_hosts then acl = ["deny", "all"] Array(allowed_hosts).each do |host| acl += ["allow", host] end DRb.install_acl(ACL.new(acl)) end @use_drb = true @drb_service = DRbService.new did_collision = false begin DRb.start_service(uri, @drb_service) rescue Errno::EADDRINUSE # The port is already occupied by another # Breakpoint service. We will try to tell # the old service that we want its port. # It will then forward that request to the # user and retry. unless did_collision then DRbObject.new(nil, uri).collision did_collision = true end sleep(10) retry end return true end # Returns true when Breakpoints are used over DRb. # Breakpoint.activate_drb causes this to be true. def use_drb? @use_drb == true end end module IRB # :nodoc: class << self; remove_method :start; end def self.start(ap_path = nil, main_context = nil, workspace = nil) $0 = File::basename(ap_path, ".rb") if ap_path # suppress some warnings about redefined constants old_verbose, $VERBOSE = $VERBOSE, nil IRB.setup(ap_path) $VERBOSE = old_verbose if @CONF[:SCRIPT] then irb = Irb.new(main_context, @CONF[:SCRIPT]) else irb = Irb.new(main_context) end if workspace then irb.context.workspace = workspace end @CONF[:IRB_RC].call(irb.context) if @CONF[:IRB_RC] @CONF[:MAIN_CONTEXT] = irb.context old_sigint = trap("SIGINT") do irb.signal_handle end catch(:IRB_EXIT) do irb.eval_input end ensure trap("SIGINT", old_sigint) end class << self alias :old_CurrentContext :CurrentContext remove_method :CurrentContext end def IRB.CurrentContext if old_CurrentContext.nil? and Breakpoint.use_drb? then result = Object.new def result.last_value; end return result else old_CurrentContext end end class Context alias :old_evaluate :evaluate def evaluate(line, line_no) if line.chomp == "exit" then exit else old_evaluate(line, line_no) end end end class WorkSpace alias :old_evaluate :evaluate def evaluate(*args) if Breakpoint.use_drb? then result = old_evaluate(*args) if args[0] != :no_proxy and not [true, false, nil].include?(result) then result.extend(DRbUndumped) rescue nil end return result else old_evaluate(*args) end end end module InputCompletor def self.eval(code, context, *more) # Big hack, this assumes that InputCompletor # will only call eval() when it wants code # to be executed in the IRB context. IRB.conf[:MAIN_CONTEXT].workspace.evaluate(:no_proxy, code, *more) end end end module DRb # :nodoc: class DRbObject undef :inspect undef :clone end end # See Breakpoint.breakpoint def breakpoint(id = nil, &block) Binding.of_caller do |context| Breakpoint.breakpoint(id, context, &block) end end # See Breakpoint.assert def assert(&block) Binding.of_caller do |context| Breakpoint.assert(context, &block) end end