Repository: nixme/pry-debugger Branch: master Commit: fab9c7bfc535 Files: 16 Total size: 25.0 KB Directory structure: gitextract_8ueqs2hx/ ├── .gitignore ├── CHANGELOG.md ├── Gemfile ├── LICENSE ├── README.md ├── Rakefile ├── lib/ │ ├── pry-debugger/ │ │ ├── base.rb │ │ ├── breakpoints.rb │ │ ├── cli.rb │ │ ├── commands.rb │ │ ├── processor.rb │ │ ├── pry_ext.rb │ │ ├── pry_remote_ext.rb │ │ └── version.rb │ └── pry-debugger.rb └── pry-debugger.gemspec ================================================ FILE CONTENTS ================================================ ================================================ FILE: .gitignore ================================================ *.gem *.rbc .bundle .config .yardoc Gemfile.lock InstalledFiles _yardoc coverage doc/ lib/bundler/man pkg rdoc spec/reports test/tmp test/version_tmp tmp ================================================ FILE: CHANGELOG.md ================================================ ## 0.2.3 (2014-07-02) * Support [pry] 0.10 ## 0.2.2 (2013-03-07) * Relaxed [debugger][debugger] dependency. ## 0.2.1 (2012-12-26) * Support breakpoints on methods defined in the pry console. (@banister) * Fix support for specifying breakpoints by *file:line_number*. (@nviennot) * Validate breakpoint conditionals are real Ruby expressions. * Support for [debugger][debugger] ~> 1.2.0. (@jshou) * Safer `alias_method_chain`-style patching of `Pry.start` and `PryRemote::Server#teardown`. (@benizi) ## 0.2.0 (2012-06-11) * Breakpoints * **finish** command * Internal cleanup and bug fixes ## 0.1.0 (2012-06-07) * First release. **step**, **next**, and **continue** commands. [pry-remote 0.1.4][pry-remote] support. [pry]: http://pryrepl.org/ [pry-remote]: https://github.com/Mon-Ouie/pry-remote [debugger]: https://github.com/cldwalker/debugger ================================================ FILE: Gemfile ================================================ source 'http://rubygems.org' gemspec ================================================ FILE: LICENSE ================================================ MIT/Expat License Copyright (c) 2012 by Gopal Patel Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. ================================================ FILE: README.md ================================================ ### Using MRI 2.0.0+? Use [**pry-byebug**][pry-byebug]. * * * pry-debugger [![Bitdeli Badge](https://d2weczhvl823v0.cloudfront.net/nixme/pry-debugger/trend.png)](https://bitdeli.com/free "Bitdeli Badge") ============ _Fast execution control in Pry_ Adds **step**, **next**, **finish**, and **continue** commands and **breakpoints** to [Pry][pry] using [debugger][debugger]. To use, invoke pry normally. No need to start your script or app differently. ```ruby def some_method binding.pry # Execution will stop here. puts 'Hello World' # Run 'step' or 'next' in the console to move here. end ``` For a complete debugging environment, add [pry-stack_explorer][pry-stack_explorer] for call-stack frame navigation. ## Execution Commands **step:** Step execution into the next line or method. Takes an optional numeric argument to step multiple times. **next:** Step over to the next line within the same frame. Also takes an optional numeric argument to step multiple lines. **finish:** Execute until current stack frame returns. **continue:** Continue program execution and end the Pry session. ## Breakpoints You can set and adjust breakpoints directly from a Pry session using the following commands: **break:** Set a new breakpoint from a line number in the current file, a file and line number, or a method. Pass an optional expression to create a conditional breakpoint. Edit existing breakpoints via various flags. Examples: ``` break SomeClass#run Break at the start of `SomeClass#run`. break Foo#bar if baz? Break at `Foo#bar` only if `baz?`. break app/models/user.rb:15 Break at line 15 in user.rb. break 14 Break at line 14 in the current file. break --condition 4 x > 2 Change condition on breakpoint #4 to 'x > 2'. break --condition 3 Remove the condition on breakpoint #3. break --delete 5 Delete breakpoint #5. break --disable-all Disable all breakpoints. break List all breakpoints. (Same as `breakpoints`) break --show 2 Show details about breakpoint #2. ``` Type `break --help` from a Pry session to see all available options. **breakpoints**: List all defined breakpoints. Pass `-v` or `--verbose` to see the source code around each breakpoint. ## Caveats **pry-debugger** is not yet thread-safe, so only use in single-threaded environments. Only supports MRI 1.9.2 and 1.9.3. For a pure ruby approach not reliant on [debugger][debugger], check out [pry-nav][pry-nav]. Note: *pry-nav* and *pry-debugger* cannot be loaded together. ## Remote debugging Support for [pry-remote][pry-remote] (>= 0.1.4) is also included. Requires explicity requiring *pry-debugger*, not just relying on pry's plugin loader. Want to debug a Rails app running inside [foreman][foreman]? Add to your Gemfile: ```ruby gem 'pry' gem 'pry-remote' gem 'pry-stack_explorer' gem 'pry-debugger' ``` Then add `binding.remote_pry` where you want to pause: ```ruby class UsersController < ApplicationController def index binding.remote_pry ... end end ``` Load a page that triggers the code. Connect to the session: ``` $ bundle exec pry-remote ``` Using Pry with Rails? Check out [Jazz Hands][jazz_hands]. ## Tips Stepping through code often? Add the following shortcuts to `~/.pryrc`: ```ruby if defined?(PryDebugger) Pry.commands.alias_command 'c', 'continue' Pry.commands.alias_command 's', 'step' Pry.commands.alias_command 'n', 'next' Pry.commands.alias_command 'f', 'finish' end ``` ## Contributors * Gopal Patel (@nixme) * John Mair (@banister) * Nicolas Viennot (@nviennot) * Benjamin R. Haskell (@benizi) * Joshua Hou (@jshou) * ...and others who helped with [pry-nav][pry-nav] Patches and bug reports are welcome. Just send a [pull request][pullrequests] or file an [issue][issues]. [Project changelog][changelog]. [pry]: http://pry.github.com [debugger]: https://github.com/cldwalker/debugger [pry-stack_explorer]: https://github.com/pry/pry-stack_explorer [pry-nav]: https://github.com/nixme/pry-nav [pry-remote]: https://github.com/Mon-Ouie/pry-remote [foreman]: https://github.com/ddollar/foreman [jazz_hands]: https://github.com/nixme/jazz_hands [pullrequests]: https://github.com/nixme/pry-debugger/pulls [issues]: https://github.com/nixme/pry-debugger/issues [changelog]: https://github.com/nixme/pry-debugger/blob/master/CHANGELOG.md [pry-byebug]: https://github.com/deivid-rodriguez/pry-byebug ================================================ FILE: Rakefile ================================================ #!/usr/bin/env rake require "bundler/gem_tasks" ================================================ FILE: lib/pry-debugger/base.rb ================================================ module PryDebugger TRACE_IGNORE_FILES = Dir[File.join(File.dirname(__FILE__), '..', '**', '*.rb')].map { |f| File.expand_path(f) } extend self # Checks that a binding is in a local file context. Extracted from # https://github.com/pry/pry/blob/master/lib/pry/default_commands/context.rb def check_file_context(target) file = target.eval('__FILE__') file == Pry.eval_path || (file !~ /(\(.*\))|<.*>/ && file != '' && file != '-e') end # Reference to currently running pry-remote server. Used by the processor. attr_accessor :current_remote_server end ================================================ FILE: lib/pry-debugger/breakpoints.rb ================================================ module PryDebugger # Wrapper for Debugger.breakpoints that respects our Processor and has better # failure behavior. Acts as an Enumerable. # module Breakpoints extend Enumerable extend self # Add a new breakpoint. def add(file, line, expression = nil) real_file = (file != Pry.eval_path) raise ArgumentError, 'Invalid file!' if real_file && !File.exist?(file) validate_expression expression Pry.processor.debugging = true path = (real_file ? File.expand_path(file) : file) Debugger.add_breakpoint(path, line, expression) end # Change the conditional expression for a breakpoint. def change(id, expression = nil) validate_expression expression breakpoint = find_by_id(id) breakpoint.expr = expression breakpoint end # Delete an existing breakpoint with the given ID. def delete(id) unless Debugger.started? && Debugger.remove_breakpoint(id) raise ArgumentError, "No breakpoint ##{id}" end Pry.processor.debugging = false if to_a.empty? end # Delete all breakpoints. def clear Debugger.breakpoints.clear if Debugger.started? Pry.processor.debugging = false end # Enable a disabled breakpoint with the given ID. def enable(id) change_status id, true end # Disable a breakpoint with the given ID. def disable(id) change_status id, false end # Disable all breakpoints. def disable_all each do |breakpoint| breakpoint.enabled = false end end def to_a Debugger.started? ? Debugger.breakpoints : [] end def size to_a.size end def each(&block) to_a.each(&block) end def find_by_id(id) breakpoint = find { |b| b.id == id } raise ArgumentError, "No breakpoint ##{id}!" unless breakpoint breakpoint end private def change_status(id, enabled = true) breakpoint = find_by_id(id) breakpoint.enabled = enabled breakpoint end def validate_expression(expression) if expression && # `nil` implies no expression given, so pass (expression.empty? || !Pry::Code.complete_expression?(expression)) raise "Invalid breakpoint conditional: #{expression}" end end end end ================================================ FILE: lib/pry-debugger/cli.rb ================================================ # Pry's new plugin loading system ensures this file runs before pry-remote. So # attempting to load everything directly from lib/pry-debugger.rb and # referencing that here causes a circular dependency when running # bin/pry-remote. # # So delay loading our monkey-patch to when someone explicity does a: # # require 'pry-debugger' # # Load everything else here. # require 'pry-debugger/base' require 'pry-debugger/pry_ext' require 'pry-debugger/commands' ================================================ FILE: lib/pry-debugger/commands.rb ================================================ require 'pry' require 'pry-debugger/breakpoints' module PryDebugger Commands = Pry::CommandSet.new do create_command 'step' do description 'Step execution into the next line or method.' banner <<-BANNER Usage: step [TIMES] Step execution forward. By default, moves a single step. Examples: step Move a single step forward. step 5 Execute the next 5 steps. BANNER def process check_file_context breakout_navigation :step, args.first end end create_command 'next' do description 'Execute the next line within the current stack frame.' banner <<-BANNER Usage: next [LINES] Step over within the same frame. By default, moves forward a single line. Examples: next Move a single line forward. next 4 Execute the next 4 lines. BANNER def process check_file_context breakout_navigation :next, args.first end end create_command 'finish' do description 'Execute until current stack frame returns.' def process check_file_context breakout_navigation :finish end end create_command 'continue' do description 'Continue program execution and end the Pry session.' def process check_file_context run 'exit-all' end end create_command 'break' do description 'Set or edit a breakpoint.' banner <<-BANNER Usage: break [if CONDITION] break --condition N [CONDITION] break [--show | --delete | --enable | --disable] N break [--delete-all | --disable-all] Aliases: breakpoint Set a breakpoint. Accepts a line number in the current file, a file and line number, or a method, and an optional condition. Pass appropriate flags to manipulate existing breakpoints. Examples: break SomeClass#run Break at the start of `SomeClass#run`. break Foo#bar if baz? Break at `Foo#bar` only if `baz?`. break app/models/user.rb:15 Break at line 15 in user.rb. break 14 Break at line 14 in the current file. break --condition 4 x > 2 Add/change condition on breakpoint #4. break --condition 3 Remove the condition on breakpoint #3. break --delete 5 Delete breakpoint #5. break --disable-all Disable all breakpoints. break List all breakpoints. (Same as `breakpoints`) break --show 2 Show details about breakpoint #2. BANNER def options(opt) opt.on :c, :condition, 'Change the condition of a breakpoint.', :argument => true, :as => Integer opt.on :s, :show, 'Show breakpoint details and source.', :argument => true, :as => Integer opt.on :D, :delete, 'Delete a breakpoint.', :argument => true, :as => Integer opt.on :d, :disable, 'Disable a breakpoint.', :argument => true, :as => Integer opt.on :e, :enable, 'Enable a disabled breakpoint.', :argument => true, :as => Integer opt.on :'disable-all', 'Disable all breakpoints.' opt.on :'delete-all', 'Delete all breakpoints.' method_options(opt) end def process Pry.processor.pry = _pry_ { :delete => :delete, :disable => :disable, :enable => :enable, :'disable-all' => :disable_all, :'delete-all' => :clear }.each do |action, method| if opts.present?(action) Breakpoints.__send__ method, *(method == action ? [opts[action]] : []) return run 'breakpoints' end end if opts.present?(:condition) Breakpoints.change(opts[:condition], args.empty? ? nil : args.join(' ')) run 'breakpoints' elsif opts.present?(:show) print_full_breakpoint Breakpoints.find_by_id(opts[:show]) elsif args.empty? run 'breakpoints' else new_breakpoint end end def new_breakpoint place = args.shift condition = args.join(' ') if 'if' == args.shift file, line = case place when /^(\d+)$/ # Line number only line = $1 unless PryDebugger.check_file_context(target) raise ArgumentError, 'Line number declaration valid only in a file context.' end [target.eval('__FILE__'), line] when /^(.+):(\d+)$/ # File and line number [$1, $2] else # Method or class name self.args = [place] method_object.source_location end print_full_breakpoint Breakpoints.add(file, line.to_i, condition) end end alias_command 'breakpoint', 'break' create_command 'breakpoints' do description 'List defined breakpoints.' banner <<-BANNER Usage: breakpoints [OPTIONS] Aliases: breaks List registered breakpoints and their current status. BANNER def options(opt) opt.on :v, :verbose, 'Print source around each breakpoint.' end def process if Breakpoints.count > 0 if opts.verbose? # Long-form with source output Breakpoints.each { |b| print_full_breakpoint(b) } else # Simple table output max_width = [Math.log10(Breakpoints.count).ceil, 1].max header = "#{' ' * (max_width - 1)}# Enabled At " output.puts output.puts text.bold(header) output.puts text.bold('-' * header.size) Breakpoints.each do |breakpoint| output.printf "%#{max_width}d ", breakpoint.id output.print breakpoint.enabled? ? 'Yes ' : 'No ' output.print "#{breakpoint.source}:#{breakpoint.pos}" output.print " (if #{breakpoint.expr})" if breakpoint.expr output.puts end output.puts end else output.puts text.bold('No breakpoints defined.') end end end alias_command 'breaks', 'breakpoints' helpers do def breakout_navigation(action, times = nil) _pry_.binding_stack.clear # Clear the binding stack. throw :breakout_nav, { # Break out of the REPL loop and :action => action, # signal the tracer. :times => times, :pry => _pry_ } end # Ensures that a command is executed in a local file context. def check_file_context unless PryDebugger.check_file_context(target) raise Pry::CommandError, 'Cannot find local context. Did you use `binding.pry`?' end end # Print out full information about a breakpoint including surrounding code # at that point. def print_full_breakpoint(breakpoint) line = breakpoint.pos output.print text.bold("Breakpoint #{breakpoint.id}: ") output.print "#{breakpoint.source} @ line #{line} " output.print breakpoint.enabled? ? '(Enabled)' : '(Disabled)' output.puts ' :' if (expr = breakpoint.expr) output.puts "#{text.bold('Condition:')} #{expr}" end output.puts output.puts Pry::Code.from_file(breakpoint.source). around(line, 3). with_line_numbers. with_marker(line).to_s output.puts end end end end Pry.commands.import PryDebugger::Commands ================================================ FILE: lib/pry-debugger/processor.rb ================================================ require 'pry' require 'debugger' module PryDebugger class Processor attr_accessor :pry def initialize Debugger.handler = self @always_enabled = false @delayed = Hash.new(0) end # Wrap a Pry REPL to catch navigational commands and act on them. def run(initial = true, &block) return_value = nil command = catch(:breakout_nav) do # Throws from PryDebugger::Commands return_value = yield {} # Nothing thrown == no navigational command end times = (command[:times] || 1).to_i # Command argument times = 1 if times <= 0 if [:step, :next, :finish].include? command[:action] @pry = command[:pry] # Pry instance to resume after stepping Debugger.start unless Debugger.started? if initial # Movement when on the initial binding.pry line will have a frame # inside Debugger. If we step normally, it'll stop inside this # Processor. So jump out and stop at the above frame, then step/next # from our callback. Debugger.current_context.stop_frame = 1 @delayed[command[:action]] = times elsif :next == command[:action] step_over times elsif :step == command[:action] step times elsif :finish == command[:action] finish end else stop end return_value end # Adjust debugging. When set to false, the Processor will manage enabling # and disabling the debugger itself. When set to true, the debugger is # always enabled. def debugging=(enabled) if enabled @always_enabled = true Debugger.start unless Debugger.started? else @always_enabled = false # Debugger will get stopped if necessary in `stop` once the repl ends. end end # --- Callbacks from debugger C extension --- def at_line(context, file, line) return if file && TRACE_IGNORE_FILES.include?(File.expand_path(file)) # If stopped for a breakpoint or catchpoint, can't play any delayed steps # as they'll move away from the interruption point. (Unsure if scenario is # possible, but just keeping assertions in check.) @delayed = Hash.new(0) unless :step == context.stop_reason if @delayed[:next] > 1 # If any delayed nexts/steps, do 'em. step_over @delayed[:next] - 1 @delayed = Hash.new(0) elsif @delayed[:step] > 1 step @delayed[:step] - 1 @delayed = Hash.new(0) elsif @delayed[:finish] > 0 finish @delayed = Hash.new(0) else # Otherwise, resume the pry session at the stopped line. resume_pry context end end # Called when a breakpoint is triggered. Note: `at_line`` is called # immediately after with the context's `stop_reason == :breakpoint`. def at_breakpoint(context, breakpoint) @pry.output.print Pry::Helpers::Text.bold("\nBreakpoint #{breakpoint.id}. ") @pry.output.puts (breakpoint.hit_count == 1 ? 'First hit.' : "Hit #{breakpoint.hit_count} times." ) if (expr = breakpoint.expr) @pry.output.print Pry::Helpers::Text.bold("Condition: ") @pry.output.puts expr end end def at_catchpoint(context, exception) # TODO end private # Resume an existing Pry REPL at the paused point. Binding extracted from # the Debugger::Context. def resume_pry(context) new_binding = context.frame_binding(0) Debugger.stop unless @always_enabled @pry.binding_stack.clear run(false) do @pry.repl new_binding end end # Move execution forward. def step(times) Debugger.current_context.step(times) end # Move execution forward a number of lines in the same frame. def step_over(lines) Debugger.current_context.step_over(lines, 0) end # Execute until current frame returns. def finish Debugger.current_context.stop_frame = 0 end # Cleanup when debugging is stopped and execution continues. def stop Debugger.stop if !@always_enabled && Debugger.started? if PryDebugger.current_remote_server # Cleanup DRb remote if running PryDebugger.current_remote_server.teardown end end end end ================================================ FILE: lib/pry-debugger/pry_ext.rb ================================================ require 'pry' require 'pry-debugger/processor' class << Pry alias_method :start_without_pry_debugger, :start attr_reader :processor def start_with_pry_debugger(target = TOPLEVEL_BINDING, options = {}) @processor ||= PryDebugger::Processor.new if target.is_a?(Binding) && PryDebugger.check_file_context(target) # Wrap the processer around the usual Pry.start to catch navigation # commands. @processor.run(true) do start_without_pry_debugger(target, options) end else # No need for the tracer unless we have a file context to step through start_without_pry_debugger(target, options) end end alias_method :start, :start_with_pry_debugger end ================================================ FILE: lib/pry-debugger/pry_remote_ext.rb ================================================ require 'pry-remote' module PryRemote class Server # Override the call to Pry.start to save off current Server, and not # teardown the server right after Pry.start finishes. def run if PryDebugger.current_remote_server raise 'Already running a pry-remote session!' else PryDebugger.current_remote_server = self end setup Pry.start @object, { :input => client.input_proxy, :output => client.output } end # Override to reset our saved global current server session. alias_method :teardown_without_pry_debugger, :teardown def teardown_with_pry_debugger return if @torn teardown_without_pry_debugger PryDebugger.current_remote_server = nil @torn = true end alias_method :teardown, :teardown_with_pry_debugger end end # Ensure cleanup when a program finishes without another break. For example, # 'next' on the last line of a program won't hit PryDebugger::Processor#run, # which normally handles cleanup. at_exit do if PryDebugger.current_remote_server PryDebugger.current_remote_server.teardown end end ================================================ FILE: lib/pry-debugger/version.rb ================================================ module PryDebugger VERSION = '0.2.3' end ================================================ FILE: lib/pry-debugger.rb ================================================ require 'pry-debugger/cli' # Load pry-remote monkey patches if pry-remote's available begin require 'pry-debugger/pry_remote_ext' rescue LoadError end ================================================ FILE: pry-debugger.gemspec ================================================ # -*- encoding: utf-8 -*- require File.expand_path('../lib/pry-debugger/version', __FILE__) Gem::Specification.new do |gem| gem.name = 'pry-debugger' gem.version = PryDebugger::VERSION gem.author = 'Gopal Patel' gem.email = 'nixme@stillhope.com' gem.license = 'MIT' gem.homepage = 'https://github.com/nixme/pry-debugger' gem.summary = 'Fast debugging with Pry.' gem.description = "Combine 'pry' with 'debugger'. Adds 'step', 'next', and 'continue' commands to control execution." gem.executables = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) } gem.files = `git ls-files`.split("\n") gem.test_files = `git ls-files -- {test,spec,features}/*`.split("\n") gem.require_paths = ["lib"] # Dependencies gem.required_ruby_version = '>= 1.9.2' gem.add_runtime_dependency 'pry', '>= 0.9.10', '< 0.11.0' gem.add_runtime_dependency 'debugger', '~> 1.3' gem.add_development_dependency 'pry-remote', '~> 0.1.6' end