enhanced_errors 0.1.0 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1381112bfa16b295aa6916a6248fba5951ae7362984fd7741d8cef0c81d60769
-  data.tar.gz: e60c4a237637dae49192c670ed291d1b6d90d97ea868572b834df2ec17c0e048
+  metadata.gz: b74f8777e19b73bcfd4024c4d3191abf98acfa397adaf99252b80cbbabf583af
+  data.tar.gz: 47df87c1b8820fc1f0c0bdea2abe48ad4ed817472b22d8728328b52397e21b4c
 SHA512:
-  metadata.gz: 387e0660918b06a32515f2ef928d9caacf4394640bce877438b4d25d278664999d831aef693bb128b24efbed490e66991b32a1663927b099fa50fb1d77d1e620
-  data.tar.gz: fbfdee8971f463d7697321b4873fd0bc4a48ca39acd59f172ca81e64b8e52bde4c5a83d3c56599e772bfdc61eae034b179fbd7bec42dee1442685fd23e00919d
+  metadata.gz: c1db064f46691c84d3321b735c4bbf3258aa9d6f71a1611096cbe21d9a52bd67a352cc750a2fe16ad5f9fb46911fd4111e5166f4bb08844e28b80b64ba4af7ee
+  data.tar.gz: cb1664d2de142e882f6d408817ac9c7a8b0bb14a54dedf30fa35fde05ba215bed7b42c17eef3109ffa4e7736f35f9eb937eac1c37a6d9a7278a6a989baff070f

data/.yardoc/checksums

@@ -0,0 +1,4 @@
+lib/colors.rb a4314ef9531d4713907c3fea22955c943fdb8cf3
+lib/binding.rb fdd7d5a2dd2edde22e3b10773510738dcdce4aeb
+lib/enhanced_errors.rb 314e2109290db51b63e2e417f67b834425131726
+lib/error_enhancements.rb 5ff3b60d76a44979b9745d1c47e77f7569fd03ac

data/README.md

@@ -7,10 +7,13 @@
 **EnhancedErrors** leverages Ruby's built-in [TracePoint](https://ruby-doc.org/core-3.1.0/TracePoint.html) feature to provide detailed context for exceptions, making debugging easier without significant performance overhead.
 
 When an exception is raised, EnhancedErrors captures the surrounding context.  It works like this:
+<br>
+
+#### Enhanced Exception In Code:
 
 ```ruby
 
-require './lib/enhanced_errors'
+require 'enhanced_errors'
 require 'awesome_print' # Optional, for better output
 
 EnhancedErrors.enhance!
@@ -29,37 +32,38 @@ foo
 
 ```
 
-#### Enhanced Exception In Code:
-
-<img src="./doc/images/enhanced-error.png" style="height: 171px; width: 440px;"></img>
+##### Output:
 
+<img src="./doc/images/enhanced-error.png" style="height: 215px; width: 429px;"></img>
+<br>
+#### Enhanced Exception In Specs:
 
 ```ruby
-  describe 'attains enlightenment' do
-    let(:the_matrix) { 'code rains, dramatically' }
+describe 'sees through' do
 
-    before(:each) do
-      @spoon = 'there is no spoon'
-    end
+  let(:the_matrix) { 'code rains, dramatically' }
 
-    it 'in the matrix' do
-      #activate memoized item
-      the_matrix
-      stop = 'bullets'
-      raise 'No!'
-    end
+  before(:each) do
+    @spoon = 'there is no spoon'
+  end
+
+  it 'the matrix' do
+    #activate memoized item
+    the_matrix
+    stop = 'bullets'
+    raise 'No!'
   end
+end
 ```
 
-#### Enhanced Exception In Specs:
+#### Output:
 
-<img src="./doc/images/enhanced-spec.png" style="height: 426px; width: 712px;"></img>
+<img src="./doc/images/enhanced-spec.png" style="height: 369px; width: 712px;"></img>
 
 
 ## Features
 
-- **Pure Ruby**: No external dependencies or C extensions.
-- **Standalone**: Does not rely on any external libraries.
+- **Pure Ruby**: No external dependencies, C extensions, or C API calls.
 - **Lightweight**: Minimal performance impact, as tracing is only active during exception raising.
 - **Customizable Output**: Supports multiple output formats (`:json`, `:plaintext`, `:terminal`).
 - **Flexible Hooks**: Redact or modifying captured data via the `on_capture` hook.
@@ -71,26 +75,24 @@ foo
 
 EnhancedErrors has a few big use-cases:
 
-* Data-driven bugs. For example, if, while processing a 10 gig file, you get an error, you can't just re-run the code with a debugger.
+* **Catch Data-driven bugs**. For example, if, while processing a 10 gig file, you get an error, you can't just re-run the code with a debugger.
 You also can't just print out all the data, because it's too big. You want to know what the data was the cause of the error.
-Ideally, without long instrument-re-run-fix loops. 
-
-If your logging didn't capture the data, normally, you'd be stuck. 
+Ideally, without long instrument-re-run-fix loops. If your logging didn't capture the data, normally, you'd be stuck. 
 
-* Debug a complex application erroring deep in the stack when you can't tell where the error originates
+* **Debug** a complex application erroring deep in the stack when you can't tell where the error originates
 
-* Faster TDD - Often, you won't have to re-run to see an error--you can go straight to the fix.
+* **Faster TDD** - Often, you won't have to re-run to see an error--you can go straight to the fix.
 
-* Faster CI -> Dev fixes. When a bug happens in CI, usually there's a step where you first reproduce it locally.
+* **Faster CI -> Fix loop**. When a bug happens in CI, usually there's a step where you first reproduce it locally.
   EnhancedErrors can help you skip that step.
 
-* Faster debugging. In general, you can skip the add-instrumentation step and jump to the fix.
+* **Faster debugging**. In general, you can skip the add-instrumentation step and jump to the fix.
 
-* Heisenbugs - bugs that disappear when you try to debug them. EnhancedErrors can help you capture the data that causes the bug before it disappears.
+* **Heisenbugs** - bugs that disappear when you try to debug them. EnhancedErrors can help you capture the data that causes the bug before it disappears.
 
-* "Unknown Unknowns" - you can't pre-emptively log variables from failure cases you never imagined.
+* **Unknown Unknowns** - you can't pre-emptively log variables from failure cases you never imagined.
 
-* Cron jobs and daemons - when it fails for unknown reasons at 4am, check the log and fix--it probably has what you need.
+* **Cron jobs** and **daemons** - when it fails for unknown reasons at 4am, check the log and fix--it probably has what you need.
 
 ## Installation
 
@@ -117,11 +119,19 @@ $ gem install enhanced_errors
 To enable EnhancedErrors, call the `enhance!` method:
 
 ```ruby
+# For a rails app, put this in an initializer, or spec_helper.rb
+# ex:  config/initializers/enhanced_errors.rb
+
+require 'awesome_print' # Optional, for better output
 EnhancedErrors.enhance!
+
+# -> now your error messages will have variables and their values appended to them.
+
 ```
 
 This activates the TracePoint to start capturing exceptions and their surrounding context.
 
+
 ### Configuration Options
 
 You can pass configuration options to `enhance!`:
@@ -133,9 +143,14 @@ EnhancedErrors.enhance!(enabled: true, max_length: 2000) do
 end
 
 ```
+- `add_to_skip_list`: Variables to ignore, as symbols. ex:  :@instance_variable_to_skip, :local_to_skip`
 - `enabled`: Enables or disables the enhancement (default: `true`).
 - `max_length`: Sets the maximum length of the enhanced message (default: `2500`).
 
+Currently, the first `raise` exception binding is presented. 
+This may be changed in the future to allow more binding data to be presented.
+
+
 ### Environment-Based Defaults
 
 EnhancedErrors adjusts its default settings based on the environment:
@@ -252,14 +267,13 @@ The skip list is pre-populated with common variables to exclude and can be exten
 
 
 
-
 ### Capture Levels
 
 EnhancedErrors supports different capture levels to control the verbosity of the captured data:
 
 - **Info Level**: Respects the skip list, excluding predefined sensitive or irrelevant variables. Global variables are ignored.
 - **Debug Level**: Ignores the skip lists, capturing all variables including those typically excluded and global variables.
-  Global variables,
+  Global variables are only captured in debug mode, and they exclude the default Ruby global variables.
 
 **Default Behavior**: By default, `info` level is used, which excludes variables in the skip list to protect sensitive information. In `debug` mode, the skip lists are ignored to provide more comprehensive data, which is useful during development but should be used cautiously to avoid exposing sensitive data.
 The info mode is recommended.
@@ -274,7 +288,7 @@ EnhancedErrors differentiates between two types of capture events:
 - **`rescue`**: Captures the context when an exception is last rescued.
 
 **Default Behavior**: By default, EnhancedErrors returns the first `raise` and the last `rescue` event for each exception. 
-This provides a clear picture of where and how the exception was handled.
+The `rescue` exception is only available in Ruby 3.2+ as it was added to TracePoint events in Ruby 3.2.
 
 
 ### Example: Redacting Sensitive Information
@@ -291,39 +305,6 @@ EnhancedErrors.on_capture do |binding_info|
 end
 ```
 
-### Example: Encrypting Data in Custom Format
-
-
-```ruby
-# config/initializers/encryption.rb
-
-require 'active_support'
-
-# Retrieve the encryption key from Rails credentials or environment variables
-ENCRYPTION_KEY = Rails.application.credentials.encryption_key || ENV['ENCRYPTION_KEY']
-
-# It's recommended to use a 256-bit key (32 bytes)
-# If your key is in hex or another format, ensure it's properly decoded
-key = ActiveSupport::KeyGenerator.new(ENCRYPTION_KEY).generate_key('enhanced_errors', 32)
-ENCRYPTOR = ActiveSupport::MessageEncryptor.new(key)
-```
-
-```ruby
-
-require_relative 'path_to/enhanced_errors' # Adjust the path accordingly
-require 'active_support/message_encryptor'
-
-# Ensure the encryptor is initialized
-encryptor = ENCRYPTOR
-
-EnhancedErrors.on_format = lambda do |formatted_string|
-  encrypted_data = encryptor.encrypt_and_sign(formatted_string)
-  encrypted_base64 = Base64.strict_encode64(encrypted_data)
-  "ENCRYPTED[#{encrypted_data}]"
-end
-```
-
-
 ## How It Works
 
 EnhancedErrors uses Ruby's `TracePoint` to listen for `:raise` and `:rescue` events. 
@@ -342,10 +323,11 @@ The captured data is then appended to the exception's message, providing rich co
 
 ## Awesome Print
 
-EnhancedErrors uses the [awesome_print](https://github.com/awesome-print/awesome_print) 
-gem to format the captured data, if it is installed and available.
-If not, errors should still work, but the output may be less readable.  AwesomePrint is not
-required directly by EnhancedErrors, so you will need to add it to your Gemfile if you want to use it.
+EnhancedErrors automatically uses the [awesome_print](https://github.com/awesome-print/awesome_print) 
+gem to format the captured data, ___if___ it is installed and available.
+If not, error enhancement will work, but the output may be less pretty (er, awesome).
+AwesomePrint is not required directly by EnhancedErrors, so you will need to add it to your Gemfile 
+if you want to use it.
 
 ```ruby
 gem 'awesome_print'

data/doc/Binding.html

@@ -0,0 +1,137 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1.0">
+<title>
+  Class: Binding
+  
+    &mdash; Documentation by YARD 0.9.37
+  
+</title>
+
+  <link rel="stylesheet" href="css/style.css" type="text/css" />
+
+  <link rel="stylesheet" href="css/common.css" type="text/css" />
+
+<script type="text/javascript">
+  pathId = "Binding";
+  relpath = '';
+</script>
+
+
+  <script type="text/javascript" charset="utf-8" src="js/jquery.js"></script>
+
+  <script type="text/javascript" charset="utf-8" src="js/app.js"></script>
+
+
+  </head>
+  <body>
+    <div class="nav_wrap">
+      <iframe id="nav" src="class_list.html?1"></iframe>
+      <div id="resizer"></div>
+    </div>
+
+    <div id="main" tabindex="-1">
+      <div id="header">
+        <div id="menu">
+  
+    <a href="_index.html">Index (B)</a> &raquo;
+    
+    
+    <span class="title">Binding</span>
+  
+</div>
+
+        <div id="search">
+  
+    <a class="full_list_link" id="class_list_link"
+        href="class_list.html">
+
+        <svg width="24" height="24">
+          <rect x="0" y="4" width="24" height="4" rx="1" ry="1"></rect>
+          <rect x="0" y="12" width="24" height="4" rx="1" ry="1"></rect>
+          <rect x="0" y="20" width="24" height="4" rx="1" ry="1"></rect>
+        </svg>
+    </a>
+  
+</div>
+        <div class="clear"></div>
+      </div>
+
+      <div id="content"><h1>Class: Binding
+  
+  
+  
+</h1>
+<div class="box_info">
+  
+  <dl>
+    <dt>Inherits:</dt>
+    <dd>
+      <span class="inheritName">Object</span>
+      
+        <ul class="fullTree">
+          <li>Object</li>
+          
+            <li class="next">Binding</li>
+          
+        </ul>
+        <a href="#" class="inheritanceTree">show all</a>
+      
+    </dd>
+  </dl>
+  
+
+  
+  
+  
+  
+  <dl>
+      <dt>Includes:</dt>
+      <dd><span class='object_link'><a href="Debugging.html" title="Debugging (module)">Debugging</a></span></dd>
+  </dl>
+  
+  
+
+  
+
+  
+  <dl>
+    <dt>Defined in:</dt>
+    <dd>lib/binding.rb</dd>
+  </dl>
+  
+</div>
+
+
+
+
+
+
+
+
+
+  
+  
+  
+  
+  
+  
+  <h2>Method Summary</h2>
+  
+  <h3 class="inherited">Methods included from <span class='object_link'><a href="Debugging.html" title="Debugging (module)">Debugging</a></span></h3>
+  <p class="inherited"><span class='object_link'><a href="Debugging.html#let_vars_hash-instance_method" title="Debugging#let_vars_hash (method)">#let_vars_hash</a></span></p>
+
+
+</div>
+
+      <div id="footer">
+  Generated on Tue Oct 22 23:16:25 2024 by
+  <a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
+  0.9.37 (ruby-3.1.3).
+</div>
+
+    </div>
+  </body>
+</html>