open_exception 0.2.1 → 0.2.2

data/README.md

@@ -12,23 +12,82 @@ in your application code when the exception occurs in a framework or lib.
 If you are on MacOSX and have the [growl gem](http://rubygems.org/gems/growl) installed,
 you will get a growl notification with the exception message when the file is opened.
 
+Editors
+-------
+
+Out if the box, the gem supports three editors (with the following open commands):
+
+    :emacs => '/usr/bin/emacsclient -n +{line} {file}',
+    :textmate => '/usr/local/bin/mate -a -d -l {line} {file}',
+    :macvim => '/usr/local/bin/mvim +{line} {file}'
+
+Note: if using emacs, you will need to be running `emacsserver`. To start the server:
+    M-x server-start
+or add the following to your init:
+    (server-start)
+
 Configuration
 -------------
 
 To configure, pass a block to the configure method:
     
     OpenException.configure do |oe|
+      # open_with can be one of the built in editors (:emacs, :macvim, :textmate)
+      # or a command to execute to open the file, where {file} and {line} will be replaced
+      # with the file path and line number, respectively. See 'Editors' above for an example.
+      # The default editor is :emacs.
+
       oe.open_with = :emacs
+
+      # you can add exclusion filters to ignore exceptions. A filter can be an exception class to 
+      # ignore, or a proc that is passed the exception, and should evaluate to true if the exception 
+      # should be ignored. Be careful with using a class - it uses is_a?, so any subclasses of the
+      # passed class will be ignored as well. The list of filters is [] by default.
+
+      oe.exclusion_filters << SomeErrorClass
+      oe.exclusion_filters << lambda { |exception| true if exception_should_be_excluded }
+
+      # you can scope the search for the file:line to open with a filter as well. A filter can be a 
+      # regular expression that is matched against the line, or a proc that is passed the line and 
+      # should evaluate to true if the line should be used. The first line that any filter passes for 
+      # will be the file:line that is opened. This is useful for opening the point in the stack just
+      # before control passes out of your app code when the exception occurs in an external 
+      # lib/framework. The list of filters is [] by default. 
+
+      oe.backtrace_line_filters << %r{/app/root/(app|lib)} 
+      oe.backtrace_line_filters << lambda { |backtrace_line| true if line_should_be_used }
+
     end
 
+
 Rails Integration
 -----------------
 
-auto filter
+The gem also alias chains in to rails' `ActionController#rescue_action_locally` method to automatically
+open exceptions in development mode. The gem also adds the following filter to the `:backtrace_line_filters` to scope the opened files to the app:
+
+    %r{#{Rails.root}/(app|lib)}
+
+To replace or remove this filter, you will need to reset the `:backtrace_line_filters` in your configure 
+block: 
+    OpenException.configure do |oe|
+      oe.backtrace_line_filters = []
+      oe.backtrace_line_filters << my_new_filter
+    end
+
+This has been tested with rails v2.3.5, but should work fine with 2.1 <= rails < 3. It may work with
+rails 3 as well, I just haven't yet looked at rails 3.
 
 Standalone/Other Frameworks
 ---------------------------
 
+To manually open an exception, or wire it up in another framework, you call:
+
+    OpenException.open(exception)
+
+You can override the default (or configured) options by passing a hash as the second arg:
+
+    OpenException.open(exception, {:open_with => :textmate, :backtrace_line_filters => [filter, another_filter])
 
 Note on Patches/Pull Requests
 -----------------------------

data/VERSION

@@ -1 +1 @@
-0.2.1
+0.2.2

data/open_exception.gemspec

@@ -5,7 +5,7 @@
 
 Gem::Specification.new do |s|
   s.name = %q{open_exception}
-  s.version = "0.2.1"
+  s.version = "0.2.2"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Tobias Crawley"]
@@ -20,6 +20,7 @@ Gem::Specification.new do |s|
     ".document",
      ".gitignore",
      "LICENSE",
+     "README.md",
      "Rakefile",
      "VERSION",
      "lib/open_exception.rb",

metadata

@@ -5,8 +5,8 @@ version: !ruby/object:Gem::Version
   segments: 
   - 0
   - 2
-  - 1
-  version: 0.2.1
+  - 2
+  version: 0.2.2
 platform: ruby
 authors: 
 - Tobias Crawley
@@ -44,6 +44,7 @@ files:
 - .document
 - .gitignore
 - LICENSE
+- README.md
 - Rakefile
 - VERSION
 - lib/open_exception.rb
@@ -54,7 +55,6 @@ files:
 - spec/open_exception_spec.rb
 - spec/spec.opts
 - spec/spec_helper.rb
-- README.md
 has_rdoc: true
 homepage: http://github.com/tobias/open_exception
 licenses: []