ruby-breakpoint 0.5.0

data/README

@@ -0,0 +1,43 @@
+= ruby-breakpoint 0.5.0 README
+
+ruby-breakpoint lets you inspect and modify state at run time. This allows you
+to diagnose bugs, patch
 applications and more all via IRB by simply doing a
+method call at the place you want to investigate.
+
+ruby-breakpoint is integrated into the popular RubyOnRails and Nitro web
+development frameworks. In the past it has also been a part of the Ruby
+dev-utils Project.
+
+ruby-breakpoint is available from http://ruby-breakpoint.rubyforge.org/ --
+that web site also is a good place for discussing new features, filing bug
+reports and so on.
+
+See the NEWS file for the changes that were done in this release.
+
+
+== Requirements
+
+* Ruby >= 1.8.2
+* DRb, IRB (usually shipped with Ruby, but not on Debian)
+
+
+== Installation
+
+De-compress archive and enter its top directory. Then type:
+
+  ($ su)
+  # ruby setup.rb
+
+These simple step installs this program under the default location of Ruby
+libraries. You can also install files into your favorite directory by supplying
+setup.rb some options. Try "ruby setup.rb --help".
+
+
+== License
+
+Dual licensed under GPL and Ruby's custom license. See COPYING.
+
+
+== Author
+
+Florian Gross, flgr@ccan.de

data/TODO

@@ -0,0 +1,31 @@
+= TODO
+
+* Factor out remote breakpoint support to a separate file so it can be loaded
+  on-demand. This would allow the local breakpoint functionality to work even
+  when DRb is not available. (E.g. on Debian)
+
+= Done
+
+* Do further research on the write SecurityError.
+  See ruby-core for more information.
+  * This seems to have been a bug in Ruby 1.8.1 and early snapshots in Ruby 1.8.2.
+    The problem can be fixed by updating to a more current Ruby. More information
+    regarding this is available at the Wiki:
+
+    http://ruby-breakpoint.rubyforge.org/wiki/wiki.pl?FrequentlyAskedQuestions
+
+* Find out whether we need to add Windows and Linux wrappers to the bin/ directory
+  * This is handled correctly by RubyGems. setup.rb only copies the .rb file to a
+    suitable directory, but that should work in the usual case.
+
+* breakpoint_client needs logic for detecting the default client uri based on the
+  server uri:
+  * drbunix:/foo/bar => drbunix:#{File.join(Dir.tmpdir, "#{random}.breakpoint")}
+    (require 'tmpdir')
+  * druby://localhost:port => druby://localhost:#{rand_port}
+
+* Mention available ressources (especially the FAQ) in breakpoint_client --help
+
+* Document drbunix:/ uris and how they are more secure than druby:// with ACLs.
+  Suggest that this be used in environments where there are lots of users sharing
+  the same system. (E.g. web hosters)

data/bin/breakpoint_client

@@ -0,0 +1,214 @@
+#!/usr/bin/env ruby
+
+require 'breakpoint'
+require 'optparse'
+require 'timeout'
+require 'tmpdir'
+
+Options = {
+  :ClientURI  => nil,
+  :ServerURI  => "druby://localhost:42531",
+  :RetryDelay => 3,
+  :Permanent  => false,
+  :Verbose    => false
+}
+
+ARGV.options do |opts|
+  script_name = File.basename($0)
+  opts.banner = [
+    "Usage: ruby #{script_name} [Options] [server uri]",
+    "",
+    "This tool lets you connect to a breakpoint service ",
+    "which was started via Breakpoint.activate_drb.",
+    "",
+    "The server uri defaults to druby://localhost:42531",
+    "",
+    "Having trouble or need help?",
+    "* Homepage:  http://ruby-breakpoint.rubyforge.org/ (has FAQ!)",
+    "* Author:    Florian Gross, flgr@ccan.de (Read homepage first!)"
+  ].join("\n")
+
+  opts.separator ""
+
+  opts.on("-c", "--client-uri=uri",
+    "Run the client on the specified uri.",
+    "This can be used to specify the port",
+    "that the client uses to allow for back",
+    "connections from the server.",
+    "Default: Find a good URI automatically.",
+    "Example: -c druby://localhost:12345"
+  ) { |Options[:ClientURI]| }
+
+  opts.on("-s", "--server-uri=uri",
+    "Connect to the server specified at the",
+    "specified uri.",
+    "Default: druby://localhost:42531"
+  ) { |Options[:ServerURI]| }
+
+  opts.on("-R", "--retry-delay=delay", Integer,
+    "Automatically try to reconnect to the",
+    "server after delay seconds when the",
+    "connection failed or timed out.",
+    "A value of 0 disables automatical",
+    "reconnecting completely.",
+    "Default: 10"
+  ) { |Options[:RetryDelay]| }
+
+  opts.on("-P", "--[no-]permanent",
+    "Run the breakpoint client in permanent mode.",
+    "This means that the client will keep continue",
+    "running even after the server has closed the",
+    "connection. Useful for example in Rails.",
+    "Default: non-permanent"
+  ) { |Options[:Permanent]| }
+
+  opts.on("-V", "--[no-]verbose",
+    "Run the breakpoint client in verbose mode.",
+    "Will produce more messages, for example between",
+    "individual breakpoints. This might help in seeing",
+    "that the breakpoint client is still alive, but adds",
+    "quite a bit of clutter.",
+    "Default: non-verbose"
+  ) { |Options[:Verbose]| }
+
+  opts.separator ""
+
+  opts.on("-h", "--help",
+    "Show this help message."
+  ) { puts opts; exit }
+  opts.on("-v", "--version",
+    "Display the version information."
+  ) do
+    id = %q$Id: breakpoint_client 50 2005-02-26 19:31:51Z flgr $
+    puts id.sub("Id: ", "")
+    puts "(Breakpoint::Version = #{Breakpoint::Version})"
+    exit
+  end
+
+  opts.parse!
+end
+
+Options[:ServerURI] = ARGV[0] if ARGV[0]
+Options[:ClientURI] ||= case Options[:ServerURI]
+  when /^drbunix:(.+)$/i then
+    "drbunix:" << File.join(Dir.tmpdir, $1.gsub(/\W/, "_")) << ".breakpoint_client"
+  when %r{^druby://(localhost|127\.0\.0\.1|::1):(\d+)$}i then
+    "druby://" << $1 << ":" << $2.succ
+end
+
+puts "ClientURI is #{Options[:ClientURI] || "unspecified"}" if Options[:Verbose]
+
+module Handlers
+  extend self
+
+  def breakpoint_handler(workspace, message)
+    puts message
+    IRB.start(nil, nil, workspace)
+
+    puts ""
+    if Options[:Verbose] then
+      puts "Resumed execution. Waiting for next breakpoint...", ""
+    end
+  end
+
+  def eval_handler(code)
+    result = eval(code, TOPLEVEL_BINDING)
+    if result then
+      DRbObject.new(result)
+    else
+      result
+    end
+  end
+
+  def collision_handler()
+    msg = [
+      "  *** Breakpoint service collision ***",
+      "  Another Breakpoint service tried to use the",
+      "  port already occupied by this one. It will",
+      "  keep waiting until this Breakpoint service",
+      "  is shut down.",
+      "  ",
+      "  If you are using the Breakpoint library for",
+      "  debugging a Rails or other CGI application",
+      "  this likely means that this Breakpoint",
+      "  session belongs to an earlier, outdated",
+      "  request and should be shut down via 'exit'."
+    ].join("\n")
+
+    if RUBY_PLATFORM["win"] then
+      # This sucks. Sorry, I'm not doing this because
+      # I like funky message boxes -- I need to do this
+      # because on Windows I have no way of displaying
+      # my notification via puts() when gets() is still
+      # being performed on STDIN. I have not found a
+      # better solution.
+      begin
+        require 'tk'
+        root = TkRoot.new { withdraw }
+        Tk.messageBox('message' => msg, 'type' => 'ok')
+        root.destroy
+      rescue Exception
+        puts "", msg, ""
+      end
+    else
+      puts "", msg, ""
+    end
+  end
+end
+
+# Used for checking whether we are currently in the reconnecting loop.
+reconnecting = false
+
+loop do
+  DRb.start_service(Options[:ClientURI])
+
+  begin
+    service = DRbObject.new(nil, Options[:ServerURI])
+
+    begin
+      ehandler = Handlers.method(:eval_handler)
+      chandler = Handlers.method(:collision_handler)
+      handler = Handlers.method(:breakpoint_handler)
+      service.eval_handler = ehandler
+      service.collision_handler = chandler
+      service.handler = handler
+
+      reconnecting = false
+      if Options[:Verbose] then
+        puts "Connection established. Waiting for breakpoint...", ""
+      end
+
+      loop do
+        begin
+          service.ping
+        rescue DRb::DRbConnError => error
+          puts "Server exited. Closing connection...", ""
+          DRb.stop_service
+          exit! unless Options[:Permanent]
+          break
+        end
+
+        sleep(0.5)
+      end
+    ensure
+      service.eval_handler = nil
+      service.collision_handler = nil
+      service.handler = nil
+    end
+  rescue Exception => error
+    if Options[:RetryDelay] > 0 then
+      if not reconnecting then
+        reconnecting = true
+        puts "No connection to breakpoint service at #{Options[:ServerURI]} " +
+           "(#{error.class})"
+        puts error.backtrace if $DEBUG
+        puts "Tries to connect will be made every #{Options[:RetryDelay]} seconds..."
+      end
+
+      sleep Options[:RetryDelay]
+      retry
+    else
+      raise
+    end
+  end
+end

data/doc/classes/Binding.html

@@ -0,0 +1,221 @@
+<?xml version="1.0" encoding="iso-8859-1"?>
+<!DOCTYPE html 
+     PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+     "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
+<head>
+  <title>Class: Binding</title>
+  <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
+  <meta http-equiv="Content-Script-Type" content="text/javascript" />
+  <link rel="stylesheet" href=".././rdoc-style.css" type="text/css" media="screen" />
+  <script type="text/javascript">
+  // <![CDATA[
+
+  function popupCode( url ) {
+    window.open(url, "Code", "resizable=yes,scrollbars=yes,toolbar=no,status=no,height=150,width=400")
+  }
+
+  function toggleCode( id ) {
+    if ( document.getElementById )
+      elem = document.getElementById( id );
+    else if ( document.all )
+      elem = eval( "document.all." + id );
+    else
+      return false;
+
+    elemStyle = elem.style;
+    
+    if ( elemStyle.display != "block" ) {
+      elemStyle.display = "block"
+    } else {
+      elemStyle.display = "none"
+    }
+
+    return true;
+  }
+  
+  // Make codeblocks hidden by default
+  document.writeln( "<style type=\"text/css\">div.method-source-code { display: none }</style>" )
+  
+  // ]]>
+  </script>
+
+</head>
+<body>
+
+
+
+    <div id="classHeader">
+        <table class="header-table">
+        <tr class="top-aligned-row">
+          <td><strong>Class</strong></td>
+          <td class="class-name-in-header">Binding</td>
+        </tr>
+        <tr class="top-aligned-row">
+            <td><strong>In:</strong></td>
+            <td>
+                <a href="../files/lib/binding_of_caller_rb.html">
+                lib/binding_of_caller.rb
+                </a>
+        <br />
+            </td>
+        </tr>
+
+        <tr class="top-aligned-row">
+            <td><strong>Parent:</strong></td>
+            <td>
+                Object
+            </td>
+        </tr>
+        </table>
+    </div>
+  <!-- banner header -->
+
+  <div id="bodyContent">
+
+
+
+  <div id="contextContent">
+
+
+
+   </div>
+
+    <div id="method-list">
+      <h3 class="section-bar">Methods</h3>
+
+      <div class="name-list">
+      <a href="#M000003">of_caller</a>&nbsp;&nbsp;
+      </div>
+    </div>
+
+  </div>
+
+
+    <!-- if includes -->
+
+    <div id="section">
+
+
+
+
+
+      
+
+
+    <!-- if method_list -->
+    <div id="methods">
+      <h3 class="section-bar">Public Class methods</h3>
+
+      <div id="method-M000003" class="method-detail">
+        <a name="M000003"></a>
+
+        <div class="method-heading">
+          <a href="#M000003" class="method-signature">
+          <span class="method-name">of_caller</span><span class="method-args">() {|result| ...}</span>
+          </a>
+        </div>
+      
+        <div class="method-description">
+          <p>
+This method returns the binding of the method that called your method. It
+will raise an Exception when you&#8217;re not inside a method.
+</p>
+<p>
+It&#8217;s used like this:
+</p>
+<pre>
+  def inc_counter(amount = 1)
+    Binding.of_caller do |binding|
+      # Create a lambda that will increase the variable 'counter'
+      # in the caller of this method when called.
+      inc = eval(&quot;lambda { |arg| counter += arg }&quot;, binding)
+      # We can refer to amount from inside this block safely.
+      inc.call(amount)
+    end
+    # No other statements can go here. Put them inside the block.
+  end
+  counter = 0
+  2.times { inc_counter }
+  counter # =&gt; 2
+</pre>
+<p>
+<a href="Binding.html#M000003">Binding.of_caller</a> must be the last
+statement in the method. This means that you will have to put everything
+you want to do after the call to <a
+href="Binding.html#M000003">Binding.of_caller</a> into the block of it.
+This should be no problem however, because Ruby has closures. If you
+don&#8217;t do this an Exception will be raised. Because of the way that <a
+href="Binding.html#M000003">Binding.of_caller</a> is implemented it has to
+be done this way.
+</p>
+          <p><a class="source-toggle" href="#"
+            onclick="toggleCode('M000003-source');return false;">[Source]</a></p>
+          <div class="method-source-code" id="M000003-source">
+<pre>
+    <span class="ruby-comment cmt"># File lib/binding_of_caller.rb, line 35</span>
+35: <span class="ruby-keyword kw">def</span> <span class="ruby-constant">Binding</span>.<span class="ruby-identifier">of_caller</span>(<span class="ruby-operator">&amp;</span><span class="ruby-identifier">block</span>)
+36:   <span class="ruby-identifier">old_critical</span> = <span class="ruby-constant">Thread</span>.<span class="ruby-identifier">critical</span>
+37:   <span class="ruby-constant">Thread</span>.<span class="ruby-identifier">critical</span> = <span class="ruby-keyword kw">true</span>
+38:   <span class="ruby-identifier">count</span> = <span class="ruby-value">0</span>
+39:   <span class="ruby-identifier">cc</span>, <span class="ruby-identifier">result</span>, <span class="ruby-identifier">error</span>, <span class="ruby-identifier">extra_data</span> = <span class="ruby-constant">Continuation</span>.<span class="ruby-identifier">create</span>(<span class="ruby-keyword kw">nil</span>, <span class="ruby-keyword kw">nil</span>)
+40:   <span class="ruby-identifier">error</span>.<span class="ruby-identifier">call</span> <span class="ruby-keyword kw">if</span> <span class="ruby-identifier">error</span>
+41: 
+42:   <span class="ruby-identifier">tracer</span> = <span class="ruby-identifier">lambda</span> <span class="ruby-keyword kw">do</span> <span class="ruby-operator">|</span><span class="ruby-operator">*</span><span class="ruby-identifier">args</span><span class="ruby-operator">|</span>
+43:     <span class="ruby-identifier">type</span>, <span class="ruby-identifier">context</span>, <span class="ruby-identifier">extra_data</span> = <span class="ruby-identifier">args</span>[<span class="ruby-value">0</span>], <span class="ruby-identifier">args</span>[<span class="ruby-value">4</span>], <span class="ruby-identifier">args</span>
+44:     <span class="ruby-keyword kw">if</span> <span class="ruby-identifier">type</span> <span class="ruby-operator">==</span> <span class="ruby-value str">&quot;return&quot;</span>
+45:       <span class="ruby-identifier">count</span> <span class="ruby-operator">+=</span> <span class="ruby-value">1</span>
+46:       <span class="ruby-comment cmt"># First this method and then calling one will return --</span>
+47:       <span class="ruby-comment cmt"># the trace event of the second event gets the context</span>
+48:       <span class="ruby-comment cmt"># of the method which called the method that called this</span>
+49:       <span class="ruby-comment cmt"># method.</span>
+50:       <span class="ruby-keyword kw">if</span> <span class="ruby-identifier">count</span> <span class="ruby-operator">==</span> <span class="ruby-value">2</span>
+51:         <span class="ruby-comment cmt"># It would be nice if we could restore the trace_func</span>
+52:         <span class="ruby-comment cmt"># that was set before we swapped in our own one, but</span>
+53:         <span class="ruby-comment cmt"># this is impossible without overloading set_trace_func</span>
+54:         <span class="ruby-comment cmt"># in current Ruby.</span>
+55:         <span class="ruby-identifier">set_trace_func</span>(<span class="ruby-keyword kw">nil</span>)
+56:         <span class="ruby-identifier">cc</span>.<span class="ruby-identifier">call</span>(<span class="ruby-identifier">eval</span>(<span class="ruby-value str">&quot;binding&quot;</span>, <span class="ruby-identifier">context</span>), <span class="ruby-keyword kw">nil</span>, <span class="ruby-identifier">extra_data</span>)
+57:       <span class="ruby-keyword kw">end</span>
+58:     <span class="ruby-keyword kw">elsif</span> <span class="ruby-identifier">type</span> <span class="ruby-operator">==</span> <span class="ruby-value str">&quot;line&quot;</span> <span class="ruby-keyword kw">then</span>
+59:       <span class="ruby-keyword kw">nil</span>
+60:     <span class="ruby-keyword kw">elsif</span> <span class="ruby-identifier">type</span> <span class="ruby-operator">==</span> <span class="ruby-value str">&quot;c-return&quot;</span> <span class="ruby-keyword kw">and</span> <span class="ruby-identifier">extra_data</span>[<span class="ruby-value">3</span>] <span class="ruby-operator">==</span> <span class="ruby-identifier">:set_trace_func</span> <span class="ruby-keyword kw">then</span>
+61:       <span class="ruby-keyword kw">nil</span>
+62:     <span class="ruby-keyword kw">else</span>
+63:       <span class="ruby-identifier">set_trace_func</span>(<span class="ruby-keyword kw">nil</span>)
+64:       <span class="ruby-identifier">error_msg</span> = <span class="ruby-value str">&quot;Binding.of_caller used in non-method context or &quot;</span> <span class="ruby-operator">+</span>
+65:         <span class="ruby-value str">&quot;trailing statements of method using it aren't in the block.&quot;</span>
+66:       <span class="ruby-identifier">cc</span>.<span class="ruby-identifier">call</span>(<span class="ruby-keyword kw">nil</span>, <span class="ruby-identifier">lambda</span> { <span class="ruby-identifier">raise</span>(<span class="ruby-constant">ArgumentError</span>, <span class="ruby-identifier">error_msg</span>) }, <span class="ruby-keyword kw">nil</span>)
+67:     <span class="ruby-keyword kw">end</span>
+68:   <span class="ruby-keyword kw">end</span>
+69: 
+70:   <span class="ruby-keyword kw">unless</span> <span class="ruby-identifier">result</span>
+71:     <span class="ruby-identifier">set_trace_func</span>(<span class="ruby-identifier">tracer</span>)
+72:     <span class="ruby-keyword kw">return</span> <span class="ruby-keyword kw">nil</span>
+73:   <span class="ruby-keyword kw">else</span>
+74:     <span class="ruby-constant">Thread</span>.<span class="ruby-identifier">critical</span> = <span class="ruby-identifier">old_critical</span>
+75:     <span class="ruby-keyword kw">case</span> <span class="ruby-identifier">block</span>.<span class="ruby-identifier">arity</span>
+76:       <span class="ruby-keyword kw">when</span> <span class="ruby-value">1</span> <span class="ruby-keyword kw">then</span> <span class="ruby-keyword kw">yield</span>(<span class="ruby-identifier">result</span>)
+77:       <span class="ruby-keyword kw">else</span> <span class="ruby-keyword kw">yield</span>(<span class="ruby-identifier">result</span>, <span class="ruby-identifier">extra_data</span>)        
+78:     <span class="ruby-keyword kw">end</span>
+79:   <span class="ruby-keyword kw">end</span>
+80: <span class="ruby-keyword kw">end</span>
+</pre>
+          </div>
+        </div>
+      </div>
+
+
+    </div>
+
+
+  </div>
+
+
+<div id="validator-badges">
+  <p><small><a href="http://validator.w3.org/check/referer">[Validate]</a></small></p>
+</div>
+
+</body>
+</html>