justified 0.0.3 → 0.0.4

data/README.md

@@ -0,0 +1,40 @@
+# Justified
+
+[![Build Status](https://travis-ci.org/pitr-ch/justified.png?branch=master)](https://travis-ci.org/pitr-ch/justified)
+
+A mini-gem to add missing **causes** to exception `backtrace`-s like Java has. This gem will add following
+at the bottom of a `backtrace`:
+
+        from caused by: (AnError) an ugly bug
+        from justified.rb:83:in `bad_code'
+        from     ... skipped 4 lines
+        
+Exception cause can be also accessed with `#cause` method which returns `nil` or an `Exception`.
+
+## Example
+
+```ruby
+require 'justified/standard_error'
+
+begin 
+  raise 'a cause'
+rescue
+  raise 'an exception'
+end
+```
+
+will print 
+
+```
+file.rb:6:in `rescue in <main>': an exception (RuntimeError)
+  	from file.rb:3:in `<main>'
+  	from caused by: (RuntimeError) a cause
+  	from file.rb:4:in `<main>'
+  	from     ... skipped 0 lines
+```
+
+## Links
+
+-   Documentation: <http://blog.pitr.ch/justified>
+-   Source: <https://github.com/pitr-ch/justified>
+-   Blog: <http://blog.pitr.ch/blog/categories/justified/>

data/README_FULL.md

@@ -0,0 +1,125 @@
+# Justified
+
+A mini-gem to add missing **causes** to exception `backtrace`-s like Java has.
+
+        from caused by: (AnError) an ugly bug
+        from justified.rb:83:in `bad_code'
+        from     ... skipped 4 lines
+
+-   Documentation: <http://blog.pitr.ch/justified>
+-   Source: <https://github.com/pitr-ch/justified>
+-   Blog: <http://blog.pitr.ch/blog/categories/justified/>
+
+
+## Example
+
+Let's have following snippet:
+
+```ruby
+def bad_code
+  raise AnError, 'an ugly bug'
+end
+
+def handle_error(error)
+  raise AnError, 'something went wrong'
+end
+
+def do_something
+  bad_code
+rescue => error
+  handle_error error
+end
+
+do_something
+```
+
+When called it will produce:
+
+    justified.rb:93:in `handle_error': something went wrong (AnError)
+        from justified.rb:89:in `rescue in do_something'
+        from justified.rb:87:in `do_something'
+        from justified.rb:96:in `<top (required)>'
+        from -e:1:in `load'
+        from -e:1:in `<main>'
+
+The real problem `an ugly bug` is **hidden**. What will happen when `justified` is used?
+
+```ruby
+require 'justified/stadard_error'
+class AnError < StadardError; end
+
+# ... rest of the snipper
+```
+
+It will produce:
+
+    justified.rb:93:in `handle_error': something went wrong (AnError)
+        from justified.rb:89:in `rescue in do_something'
+        from justified.rb:87:in `do_something'
+        from justified.rb:96:in `<top (required)>'
+        from -e:1:in `load'
+        from -e:1:in `<main>'
+        from caused by: (AnError) an ugly bug
+        from justified.rb:83:in `bad_code'
+        from     ... skipped 4 lines
+
+Of course causes can be concatenated. 
+
+## Usage
+
+*   `require 'justified'` to include `Justified::Error` to any exception you need manually
+*   `require 'justified/standard_error'` to have causes in all exceptions which are kind of `StandardError`
+
+### Behavior
+
+When an exception is risen inside rescue block a cause is automatically recorded.
+
+```ruby
+e = begin
+      raise 'bug'
+    rescue => error
+      raise 'this does not work'
+    end rescue $!
+e.cause.message == 'bug' # => true
+```
+
+Cause can be set explicitly.
+
+```ruby
+e = begin
+      raise 'bug'
+    rescue => error
+      raise StandardError.new('this does not work', error)
+    end rescue $!
+e.cause.message == 'bug' # => true
+```
+
+Or if signature of `.new` is changed cause can be set with a setter `#cause=`
+
+```ruby
+class InspectingError < StandardError
+  def initialize(object)
+    super object.inspect
+  end
+end
+
+e = begin
+      raise 'bug'
+    rescue => error
+      raise InspectingError.new(a: 'b').tap { |e| e.cause = error }
+    end rescue $!
+e.cause.message == 'bug' # => true
+```
+ 
+and
+
+```ruby
+e = begin
+      raise 'bug'
+    rescue => error
+      raise InspectingError.new(a: 'b')
+    end rescue $!
+e.cause.message == 'bug' # => true
+```
+
+will work as well.

data/VERSION

@@ -0,0 +1 @@
+0.0.4

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: justified
 version: !ruby/object:Gem::Version
-  version: 0.0.3
+  version: 0.0.4
   prerelease: 
 platform: ruby
 authors:
@@ -115,10 +115,16 @@ executables: []
 extensions: []
 extra_rdoc_files:
 - MIT-LICENSE
+- VERSION
+- README.md
+- README_FULL.md
 files:
 - lib/justified/standard_error.rb
 - lib/justified.rb
 - MIT-LICENSE
+- VERSION
+- README.md
+- README_FULL.md
 - test/justified_test.rb
 homepage: https://github.com/pitr-ch/justified
 licenses: []