debug_me 1.1.1 → 1.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 406de0bd607687bab5c7a46e6dfde187353c24dfaf0800e2b5c0cd9223a8faf8
-  data.tar.gz: f3f85a306a6455e2e699558a41e7d78b7eded223f862ce34c8ee02e3f487a268
+  metadata.gz: f108fdf3be1ba9af408d444553e0f3f20629e63bd7a845d07a36d5b0930a1e2c
+  data.tar.gz: f7ac4bb71cf494b5a9d7673eddf4317a559c8abbd2c30e9aba0c7d5e63102f7e
 SHA512:
-  metadata.gz: 7ae3bf7696135d7d42ee5c0894a0d8d57b1ee2e93ce1236622b17f882ceaa67b9b0ac8769a2be01dd3291947363d5323c04138e2c5fdf141d0f1efcc20aa3b4c
-  data.tar.gz: 3d756257d84c6e72edaf7debfb6d7100fa8a7f43a81254cbcdbdf204cf8ff118c163a7136a92be076b017b2cd411fc1075f596e140a361036c41f0ed88e2e505
+  metadata.gz: cf266b72ecaeb9878c74a3221397f5bb2f098b521f5bdf42bffe24dd974f6e30f1cc785732240ec9379c6f25cdebcb18926896335e4129d6bb9bcd21d92c294a
+  data.tar.gz: 8826d3cd49c6661c93f36a48ff3fc42fb71282183e8cef56f8068ee560591d7f24b5145b126b239ede09d91450a5664aff18eefb36eae03ac46e27a51d8a2177

data/CHANGELOG.md

@@ -0,0 +1,80 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [1.1.2] - 2025-01-13
+
+### Changed
+- Updated test syntax for Minitest 6 compatibility
+- Improved gemspec with proper metadata and MIT license
+- Enhanced README with prominent security warning about `eval()` usage
+- Enhanced README with dedicated section explaining `$DEBUG_ME` global flag usage
+- Enhanced README with visual header image and classic debugging technique description
+- `$DEBUG_ME` now initializes from `ENV['DEBUG_ME']` environment variable automatically
+
+### Fixed
+- Fixed class variable tests by moving them to proper class context
+- Fixed type checking to use idiomatic `is_a?(Hash)` instead of string comparison
+- Fixed typos in test descriptions ("multible" → "multiple")
+- Removed commented-out dead code
+
+### Added
+- Added visual header image (debug_me.jpg) to README
+- Added `DEBUG_ME_MAX_BACKTRACE` constant for magic number
+- Added missing development dependencies (`amazing_print`, `minitest`)
+- Added `required_ruby_version` to gemspec
+- Added CHANGELOG.md file
+- Added comprehensive test suite for `$DEBUG_ME` global flag (7 tests)
+- Added documentation for `$DEBUG_ME` with Rails and non-Rails examples
+- Added `ENV['DEBUG_ME']` environment variable support for controlling debug output
+- Added environment variable tests covering all boolean value representations
+- Added production deployment examples (Docker, Heroku, systemd) to README
+
+## [1.1.1] - 2020-04-27
+
+### Added
+- Added global constant `$DEBUG_ME` as a boolean (default: true)
+- When `$DEBUG_ME` is false, the `debug_me` method does nothing
+
+## [1.1.0] - 2020-04-27
+
+### Changed
+- Changed output formatting with respect to the use of levels option
+
+### Added
+- Added `:backtrace` option for full backtrace display
+
+## [1.0.6] - 2020-04-26
+
+### Added
+- Added support for variable backtrace length via the `:levels` option
+
+## [1.0.5] - 2020-04-25
+
+### Added
+- Added support for an instance of a Logger class (e.g., Rails.logger)
+
+## [1.0.4] - 2020-04-24
+
+### Added
+- Added `:strftime` option for customizable timestamp formatting
+
+### Changed
+- Changed default timestamp format from decimal seconds since epoch to human-readable clock format (`%Y-%m-%d %H:%M:%S.%6N`)
+
+## Earlier Versions
+
+See git history for changes in versions prior to 1.0.4.
+
+[Unreleased]: https://github.com/MadBomber/debug_me/compare/v1.1.2...HEAD
+[1.1.2]: https://github.com/MadBomber/debug_me/compare/v1.1.1...v1.1.2
+[1.1.1]: https://github.com/MadBomber/debug_me/releases/tag/v1.1.1
+[1.1.0]: https://github.com/MadBomber/debug_me/releases/tag/v1.1.0
+[1.0.6]: https://github.com/MadBomber/debug_me/releases/tag/v1.0.6
+[1.0.5]: https://github.com/MadBomber/debug_me/releases/tag/v1.0.5
+[1.0.4]: https://github.com/MadBomber/debug_me/releases/tag/v1.0.4

data/README.md

@@ -1,41 +1,56 @@
 # DebugMe
 
-A tool to print the labeled value of variables.
+<table>
+<tr>
+<td width="30%">
+<img src="debug_me.jpg" alt="DebugMe Logo"/>
+</td>
+<td width="70%">
 
-This thing is pretty old; but, so am I.  Even with the gray
-in our hair we still do the job.
+## A Classic Debugging Technique That Never Gets Old
 
-There are much more complex/comprehensive
-ways of debugging in a complex application.  But,
-you know, I keep returning to this little method
-time after time.  I guess that marks me as a geezer.
+Printing labeled variable values to STDOUT is one of the oldest and most fundamental debugging techniques in computer science. From the earliest days of programming, developers have relied on simple output statements to understand what their code is doing. While modern debuggers offer sophisticated features like breakpoints and step-through execution, there's something elegantly simple and universally effective about printing variables to see their values in real-time.
 
+**DebugMe** embraces this time-tested approach, making it effortless to inspect local, instance, and class variables with clearly labeled output. Sometimes the old ways are the best ways.
 
-DebugMe::debug_me(){} works with local, instance and class variables.
+</td>
+</tr>
+</table>
+
+---
 
-## Recent Changes
+## Quick Start
+
+```ruby
+gem install debug_me
+
+require 'debug_me'
+include DebugMe
+
+my_variable = 42
+
+debug_me { :my_variable } # Use a Symbol for the variable name
+
+# or if you have several variables you want to see ...
+debug_me { %i[ var1 var2 var3 var4 ]}
+```
+
+DebugMe::debug_me(){} works with local, instance and class variables.
 
-* 1.1.1 Added global constant $DEBUG_ME as a boolean; default is true. when false the debug_me method does nothing.
-* 1.1.0 Changes the output formatting w/r/t the use of levels option; add :backtrace option for full backtrace
-* 1.0.6 Added support for variable backtrack length via the :levels option
-* 1.0.5 Added support for an instance of a Logger class.
-* 1.0.4 Added :strftime to the options; changed the default format from decimal seconds since epic to something that is more easy comprehend on a clock.
 
 ## Installation
 
 Add this line to your application's Gemfile:
 
 ```ruby
-gem 'debug_me'
+bundle add 'debug_me'
 ```
 
-And then execute:
+Or install it yourself:
 
-    $ bundle
-
-Or install it yourself as:
-
-    $ gem install debug_me
+```ruby
+gem install debug_me
+```
 
 ## Examples Usage
 
@@ -56,7 +71,7 @@ debug_me {} # prints the default header and __ALL__ variables
 
 debug_me {:just_this_variable} # prints the default header and the value of only one specific variable
 
-debug_me { [:this_one, :that_one, :that_other_one] } # prints default header and three specific variables
+debug_me { %i[ this_one that_one that_other_one ]} # prints default header and three specific variables
 
 # Use an array of symbols and strings to pass multiple variables for output
 # Each element of the array is 'eval'ed with the context binding of the caller
@@ -97,6 +112,118 @@ debug_me {[
 
 ```
 
+## Security Warning
+
+**IMPORTANT:** `debug_me` uses `eval()` to evaluate the symbols and strings you pass to it in the context of the caller. This provides powerful flexibility but comes with significant security implications:
+
+- **Never** pass untrusted input to `debug_me`
+- **Never** use `debug_me` with user-supplied data or parameters
+- Only use `debug_me` during development and testing
+- Remove or disable `debug_me` calls in production code (use `$DEBUG_ME = false`)
+
+The ability to execute arbitrary code is by design for debugging flexibility, but it means any string passed to `debug_me` will be evaluated as Ruby code. Treat this tool with the same caution you would any `eval()` statement.
+
+For production environments, consider using a proper logging framework with structured logging instead of `debug_me`.
+
+## Disabling Debug Output with $DEBUG_ME
+
+The `$DEBUG_ME` global variable provides a convenient way to enable or disable all `debug_me` output throughout your application without removing the code. This is particularly useful for QA environments.
+
+### Environment Variable Control (Recommended)
+
+The `DEBUG_ME` environment variable is automatically detected when the gem is loaded. This is the **recommended approach** for controlling debug output across environments without code changes.
+
+```bash
+# Disable debug output (QA)
+export DEBUG_ME=false
+
+# Enable debug output (development)
+export DEBUG_ME=true
+
+# Or set inline when running your app
+DEBUG_ME=false bundle exec rails server
+```
+
+**Supported values:**
+- **Truthy** (enables output): `true`, `yes`, `1`, `on`, or any other value
+- **Falsy** (disables output): `false`, `no`, `0`, `off`, or empty string
+- **Not set**: Defaults to `true` (enabled)
+
+### Runtime Control
+
+You can also control `$DEBUG_ME` programmatically at runtime:
+
+```ruby
+# Enable debug output (default)
+$DEBUG_ME = true
+
+# Disable all debug_me output
+$DEBUG_ME = false
+```
+
+When `$DEBUG_ME` is set to `false`:
+- All `debug_me` calls return `nil` immediately
+- No output is produced (even with custom file or logger options)
+- **The block is not evaluated**, so there's zero performance overhead
+
+### Production Setup Examples
+
+**Docker/Container deployment:**
+```dockerfile
+# Dockerfile
+ENV DEBUG_ME=false
+```
+
+**Systemd service:**
+```ini
+[Service]
+Environment="DEBUG_ME=false"
+```
+
+**Heroku:**
+```bash
+heroku config:set DEBUG_ME=false
+```
+
+**For Rails with fallback** (only if ENV not set):
+
+```ruby
+# config/initializers/debug_me.rb
+require 'debug_me'
+
+# Override only if not already set by environment
+$DEBUG_ME = Rails.env.development? || Rails.env.test? unless ENV.key?('DEBUG_ME')
+```
+
+### Benefits
+
+- **Leave debug code in place**: No need to remove `debug_me` calls before deployment
+- **Zero overhead**: When disabled, blocks aren't evaluated, so no performance impact
+- **Easy toggling**: Can enable debugging in production temporarily if needed
+- **Security**: Prevents accidental debug output exposure in production
+
+### Example
+
+```ruby
+# Your code with debug_me calls
+def process_data(items)
+  debug_me { :items }  # Only outputs in development/test
+
+  result = items.map do |item|
+    debug_me { :item }  # Only outputs in development/test
+    transform(item)
+  end
+
+  debug_me { :result }  # Only outputs in development/test
+  result
+end
+
+# In production with $DEBUG_ME = false:
+# - No output produced
+# - No performance overhead
+# - Code works normally
+```
+
 ## Default Options
 
 The default options is a global constant `DebugMeDefaultOptions` that is outside of the `DebugMe` name space.  I did that so that if you do `include DebugMe` to make access to the method easier you could still have the constant with a function specific name that would be outside of anything that you may have already coded in you program.
@@ -131,7 +258,6 @@ If you want the `debug_me` output to go to a real file:
 
 ```ruby
 DebugMeDefaultOptions[:file] = File.open('debug_me.log', 'w')
-
 ```
 
 ## Using a Logger class instance
@@ -139,7 +265,6 @@ DebugMeDefaultOptions[:file] = File.open('debug_me.log', 'w')
 If you are working in Rails and want all the `debug_me` output to go to the Rails.logger its as easy as:
 ```ruby
 DebugMeDefaultOptions[:logger] = Rails.logger
-
 ```
 
 Or while working in rails you only want to add a marker to the Rails.logger do this:
@@ -147,7 +272,7 @@ Or while working in rails you only want to add a marker to the Rails.logger do t
 debug_me(logger: Rails.logger, tag: 'Hello World')
 ```
 
-If you are working in Rails and want to use both the standard `debug_me` functions and occassionally put stuff into the Rails.logger but do not want to always remember the option settings then do something line this in a `config/initializers/aaaaa_debug_me.rb` file:
+If you are working in Rails and want to use both the standard `debug_me` functions and put stuff into the Rails.logger but do not want to always remember the option settings then do something line this in a `config/initializers/aaaaa_debug_me.rb` file:
 
 ```ruby
 # config/initializers/aaaaa_debug_me.rb
@@ -202,9 +327,9 @@ The rest of the default options are obvious.
 
 You can always over-ride the default options on a case by case basis like this:
 
-```
+```ruby
 debug_me {...}
-...
+# ...
 debug_me(header: false){...}
 ```
 

data/debug_me.gemspec

@@ -14,7 +14,16 @@ ways of debugging in a complex application.  But,
 you know, I keep returning to this little method
 time after time.  I guess that marks me as a geezer.'
   spec.homepage      = 'http://github.com/MadBomber/debug_me'
-  spec.license       = 'You want it, its yours'
+  spec.license       = 'MIT'
+
+  spec.required_ruby_version = '>= 2.3.0'
+
+  spec.metadata = {
+    'homepage_uri'      => 'https://github.com/MadBomber/debug_me',
+    'source_code_uri'   => 'https://github.com/MadBomber/debug_me',
+    'bug_tracker_uri'   => 'https://github.com/MadBomber/debug_me/issues',
+    'changelog_uri'     => 'https://github.com/MadBomber/debug_me/blob/master/CHANGELOG.md'
+  }
 
   spec.files         = `git ls-files -z`.split("\x0")
   spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
@@ -23,4 +32,6 @@ time after time.  I guess that marks me as a geezer.'
 
   spec.add_development_dependency 'bundler'
   spec.add_development_dependency 'rake'
+  spec.add_development_dependency 'amazing_print'
+  spec.add_development_dependency 'minitest', '~> 5.0'
 end

data/lib/debug_me/version.rb

@@ -4,5 +4,5 @@ module DebugMe
   # to get direct access to the debug_me method without
   # polluting your code with an object name that is so
   # common.
-  DEBUG_ME_VERSION = '1.1.1'
+  DEBUG_ME_VERSION = '1.1.2'
 end

data/lib/debug_me.rb

@@ -1,7 +1,14 @@
 require 'pp'
 require_relative 'debug_me/version'
 
-$DEBUG_ME = true
+# Initialize $DEBUG_ME from environment variable or default to true
+# Supports common boolean representations: true/false, yes/no, 1/0, on/off
+if ENV.key?('DEBUG_ME')
+  env_value = ENV['DEBUG_ME'].to_s.downcase
+  $DEBUG_ME = !['false', 'no', '0', 'off', ''].include?(env_value)
+else
+  $DEBUG_ME = true
+end
 
 DebugMeDefaultOptions = {
   tag:    'DEBUG',  # A tag to prepend to each output line
@@ -20,11 +27,14 @@ DebugMeDefaultOptions = {
   file:   $stdout   # The output file
 }
 
+# Maximum number of backtrace entries to show
+DEBUG_ME_MAX_BACKTRACE = 10000
+
 module DebugMe
   def debug_me(options = {}, &block)
     return unless $DEBUG_ME
 
-    if 'Hash' == options.class.to_s
+    if options.is_a?(Hash)
       options = DebugMeDefaultOptions.merge(options)
     else
       options = DebugMeDefaultOptions.merge(tag: options)
@@ -76,7 +86,7 @@ module DebugMe
       block_value.each do |v|
 
         ev  = if 'backtrace' == v
-                bt_out.size > 0 ? bt_out : bt[1..10000]
+                bt_out.size > 0 ? bt_out : bt[1..DEBUG_ME_MAX_BACKTRACE]
               else
                 eval("defined?(#{v})",block.binding).nil? ? '<undefined>' : eval(v, block.binding)
               end
@@ -96,8 +106,4 @@ module DebugMe
 
     return out_string
   end ## def debug_me( options={}, &block )
-
-  # def log_me(msg, opts={})
-  #   debug_me({tag: msg, header: false}.merge(opts))
-  # end
 end # module DebugMe

data/tests/debug_me_test.rb

@@ -77,16 +77,16 @@ describe DebugMe do
       a,b,c = 1,2,3
       out_string = debug_me(file:nil,header:false){:a}
       assert out_string.include? "a -=> #{a}"
-      out_string.split("\n").size.must_equal 1
+      _(out_string.split("\n").size).must_equal 1
     end
 
-    it "supports multible variables" do
+    it "supports multiple variables" do
       a,b,c = 1,2,3
       out_string = debug_me(file:nil,header:false){[:a, :b, :c]}
       assert out_string.include? "a -=> #{a}"
       assert out_string.include? "b -=> #{b}"
       assert out_string.include? "c -=> #{c}"
-      out_string.split("\n").size.must_equal 3
+      _(out_string.split("\n").size).must_equal 3
     end
 
     it "shows all local variables" do
@@ -104,7 +104,7 @@ describe DebugMe do
       assert out_string.include? "c -=> #{c}"
       assert out_string.include? "out_string -=> "
 
-      out_string.split("\n").size.must_equal 4
+      _(out_string.split("\n").size).must_equal 4
     end
 
   end # describe "works with local variable" do
@@ -115,16 +115,16 @@ describe DebugMe do
       @a,@b,@c = 1,2,3
       out_string = debug_me(file:nil,header:false){:@a}
       assert out_string.include? "@a -=> #{@a}"
-      out_string.split("\n").size.must_equal 1
+      _(out_string.split("\n").size).must_equal 1
     end
 
-    it "supports multible variables" do
+    it "supports multiple variables" do
       @a,@b,@c = 1,2,3
       out_string = debug_me(file:nil,header:false){[:@a, :@b, :@c]}
       assert out_string.include? "@a -=> #{@a}"
       assert out_string.include? "@b -=> #{@b}"
       assert out_string.include? "@c -=> #{@c}"
-      out_string.split("\n").size.must_equal 3
+      _(out_string.split("\n").size).must_equal 3
     end
 
     it "shows all instance variables" do
@@ -141,8 +141,8 @@ describe DebugMe do
       assert out_string.include? "@b -=> #{@b}"
       assert out_string.include? "@c -=> #{@c}"
 
-      out_string.include?("out_string -=> ").must_equal false
-      out_string.split("\n").size.must_equal instance_variables.size
+      _(out_string.include?("out_string -=> ")).must_equal false
+      _(out_string.split("\n").size).must_equal instance_variables.size
     end
 
   end # describe "works with instance variable" do
@@ -151,41 +151,33 @@ describe DebugMe do
   describe "works with class variable" do
 
     it "supports a single variable" do
-      @@a,@@b,@@c = 1,2,3
-      out_string = debug_me(file:nil,header:false){:@@a}
-      assert out_string.include? "@@a -=> #{@@a}"
-      out_string.split("\n").size.must_equal 1
+      my_world_view = WorldView.new
+      out_string = my_world_view.test_single_class_var
+      assert out_string.include? "@@d -=> 4"
+      _(out_string.split("\n").size).must_equal 1
     end
 
-    it "supports multible variables" do
-      @@a,@@b,@@c = 1,2,3
-      out_string = debug_me(file:nil,header:false){[:@@a, :@@b, :@@c]}
-      assert out_string.include? "@@a -=> #{@@a}"
-      assert out_string.include? "@@b -=> #{@@b}"
-      assert out_string.include? "@@c -=> #{@@c}"
-      out_string.split("\n").size.must_equal 3
+    it "supports multiple variables" do
+      my_world_view = WorldView.new
+      out_string = my_world_view.test_multiple_class_vars
+      assert out_string.include? "@@d -=> 4"
+      assert out_string.include? "@@e -=> 5"
+      assert out_string.include? "@@f -=> 6"
+      _(out_string.split("\n").size).must_equal 3
     end
 
     it "shows all class variables" do
-      @@a,@@b,@@c = 1,2,3
-      @d = 4
-      out_string = debug_me(
-        file:nil,
-        header:false,
-        lvar: false,
-        ivar: false,
-        cvar: true,
-        cconst: false
-        ){}
+      my_world_view = WorldView.new
+      out_string = my_world_view.test_all_class_vars
 
-      assert out_string.include? "@@a -=> #{@@a}"
-      assert out_string.include? "@@b -=> #{@@b}"
-      assert out_string.include? "@@c -=> #{@@c}"
+      assert out_string.include? "@@d -=> 4"
+      assert out_string.include? "@@e -=> 5"
+      assert out_string.include? "@@f -=> 6"
 
-      out_string.include?("out_string -=> ").must_equal false
-      out_string.include?("@d -=> ").must_equal false
+      _(out_string.include?("out_string -=> ")).must_equal false
+      _(out_string.include?("@a -=> ")).must_equal false
 
-      out_string.split("\n").size.must_equal self.class.class_variables.size
+      _(out_string.split("\n").size).must_equal WorldView.class_variables.size
     end
 
   end # describe "works with class variable" do
@@ -197,16 +189,16 @@ describe DebugMe do
       A,B,C = 1,2,3
       out_string = debug_me(file:nil,header:false){:A}
       assert out_string.include? "A -=> #{A}"
-      out_string.split("\n").size.must_equal 1
+      _(out_string.split("\n").size).must_equal 1
     end
 
-    it "supports multible CONSTANTS" do
+    it "supports multiple CONSTANTS" do
       A,B,C = 1,2,3
       out_string = debug_me(file:nil,header:false){[:A, :B, :C]}
       assert out_string.include? "A -=> #{A}"
       assert out_string.include? "B -=> #{B}"
       assert out_string.include? "C -=> #{C}"
-      out_string.split("\n").size.must_equal 3
+      _(out_string.split("\n").size).must_equal 3
     end
 
   end # describe "works with CONSTANTS" do
@@ -221,16 +213,16 @@ describe DebugMe do
     it "supports a single class CONSTANT" do
       out_string = debug_me(file:nil,header:false){'WorldView::A'}
       assert out_string.include? "WorldView::A -=> #{WorldView::A}"
-      out_string.split("\n").size.must_equal 1
+      _(out_string.split("\n").size).must_equal 1
     end
 
-    it "supports multible class CONSTANTS" do
+    it "supports multiple class CONSTANTS" do
       out_string = debug_me(file:nil,header:false){[
         'WorldView::A', 'WorldView::B', 'WorldView::C']}
       assert out_string.include? "WorldView::A -=> #{WorldView::A}"
       assert out_string.include? "WorldView::B -=> #{WorldView::B}"
       assert out_string.include? "WorldView::C -=> #{WorldView::C}"
-      out_string.split("\n").size.must_equal 3
+      _(out_string.split("\n").size).must_equal 3
     end
 
     it "shows all class CONSTANTS" do
@@ -241,10 +233,10 @@ describe DebugMe do
       assert out_string.include? "C -=> #{WorldView::C}"
       assert out_string.include? 'MY_CONSTANT -=> "Jesus"'
 
-      out_string.include?("out_string -=> ").must_equal false
-      out_string.include?("@d -=> ").must_equal false
+      _(out_string.include?("out_string -=> ")).must_equal false
+      _(out_string.include?("@d -=> ")).must_equal false
 
-      out_string.split("\n").size.must_equal WorldView.constants.size
+      _(out_string.split("\n").size).must_equal WorldView.constants.size
     end
 
   end # describe "works with class CONSTANTS" do
@@ -252,12 +244,12 @@ describe DebugMe do
   describe "works with a Logger class" do
 
     it 'default logger class is nil' do
-      DebugMeDefaultOptions[:logger].must_equal nil
+      _(DebugMeDefaultOptions[:logger]).must_be_nil
     end
 
     it 'works with standard ruby Logger class' do
       logger_output_path = Pathname.pwd + 'logger_class_output.txt'
-      logger_output_path.exist?.must_equal false
+      _(logger_output_path.exist?).must_equal false
 
       logger        = Logger.new(logger_output_path)
       logger.level  = Logger::DEBUG
@@ -276,18 +268,140 @@ describe DebugMe do
 
       lines   = logger_output_path.read.split("\n")
 
-      lines.size.must_equal 2
+      _(lines.size).must_equal 2
 
-      lines[0].start_with?('# Logfile created on').must_equal   true
-      lines[1].start_with?('D, [').must_equal                   true
-      lines[1].include?('DEBUG').must_equal                     true
-      lines[1].include?('Hello World').must_equal               true
-      lines[1].include?('debug_me_test.rb').must_equal          true
-      lines[1].include?(out_string.chomp).must_equal            true
+      _(lines[0].start_with?('# Logfile created on')).must_equal   true
+      _(lines[1].start_with?('D, [')).must_equal                   true
+      _(lines[1].include?('DEBUG')).must_equal                     true
+      _(lines[1].include?('Hello World')).must_equal               true
+      _(lines[1].include?('debug_me_test.rb')).must_equal          true
+      _(lines[1].include?(out_string.chomp)).must_equal            true
 
       logger_output_path.delete
     end
 
   end
 
+  describe "$DEBUG_ME global flag" do
+
+    before do
+      # Save the original state
+      @original_debug_me = $DEBUG_ME
+    end
+
+    after do
+      # Restore the original state after each test
+      $DEBUG_ME = @original_debug_me
+    end
+
+    it 'is true by default' do
+      _($DEBUG_ME).must_equal true
+    end
+
+    it 'returns nil when $DEBUG_ME is false' do
+      $DEBUG_ME = false
+      a = 42
+      result = debug_me(file: nil, header: false) { :a }
+      _(result).must_be_nil
+    end
+
+    it 'produces no output when $DEBUG_ME is false' do
+      $DEBUG_ME = false
+      a = 42
+      result = debug_me(file: nil) { :a }
+      _(result).must_be_nil
+    end
+
+    it 'works normally when $DEBUG_ME is true' do
+      $DEBUG_ME = true
+      a = 42
+      result = debug_me(file: nil, header: false) { :a }
+      _(result).wont_be_nil
+      assert result.include?("a -=> 42")
+    end
+
+    it 'can be toggled on and off' do
+      # Start with it on
+      $DEBUG_ME = true
+      a = 42
+      result1 = debug_me(file: nil, header: false) { :a }
+      _(result1).wont_be_nil
+      assert result1.include?("a -=> 42")
+
+      # Turn it off
+      $DEBUG_ME = false
+      result2 = debug_me(file: nil, header: false) { :a }
+      _(result2).must_be_nil
+
+      # Turn it back on
+      $DEBUG_ME = true
+      result3 = debug_me(file: nil, header: false) { :a }
+      _(result3).wont_be_nil
+      assert result3.include?("a -=> 42")
+    end
+
+    it 'does not evaluate the block when disabled' do
+      $DEBUG_ME = false
+      side_effect = false
+
+      result = debug_me(file: nil) do
+        side_effect = true  # This should not execute
+        :dummy
+      end
+
+      _(result).must_be_nil
+      _(side_effect).must_equal false
+    end
+
+    it 'works with all debug_me features when enabled' do
+      $DEBUG_ME = true
+      @instance_var = 'test'
+      local_var = 'local'
+
+      result = debug_me(file: nil, header: false) { [:@instance_var, :local_var] }
+
+      _(result).wont_be_nil
+      assert result.include?('@instance_var')
+      assert result.include?('local_var')
+    end
+
+  end # describe "$DEBUG_ME global flag" do
+
+  describe "ENV['DEBUG_ME'] environment variable" do
+
+    it 'initializes $DEBUG_ME from environment variable if set' do
+      # This test documents that $DEBUG_ME can be controlled via ENV['DEBUG_ME']
+      # The actual initialization happens when lib/debug_me.rb is loaded
+      # Users can set DEBUG_ME=false before requiring the gem to disable it
+
+      # Verify current state is set (either from ENV or default true)
+      _($DEBUG_ME).wont_be_nil
+
+      # Document that users can override at runtime
+      original = $DEBUG_ME
+      $DEBUG_ME = false
+      _($DEBUG_ME).must_equal false
+      $DEBUG_ME = original
+    end
+
+    it 'can be controlled by setting $DEBUG_ME directly at runtime' do
+      # Save original
+      original = $DEBUG_ME
+
+      # Test setting various values
+      $DEBUG_ME = false
+      _($DEBUG_ME).must_equal false
+
+      $DEBUG_ME = true
+      _($DEBUG_ME).must_equal true
+
+      $DEBUG_ME = nil
+      _($DEBUG_ME).must_be_nil
+
+      # Restore
+      $DEBUG_ME = original
+    end
+
+  end # describe "ENV['DEBUG_ME'] environment variable" do
+
 end # describe DebugMe do

data/tests/env_test.rb

@@ -0,0 +1,71 @@
+#!/usr/bin/env ruby
+# Test script to verify ENV['DEBUG_ME'] initialization behavior
+# This must be run as a separate process to test initialization
+
+require 'minitest/autorun'
+
+describe "DEBUG_ME environment variable initialization" do
+
+  it "defaults to true when ENV['DEBUG_ME'] is not set" do
+    # Remove the env var if it exists
+    env_value = ENV.delete('DEBUG_ME')
+
+    # Load the library fresh (in a subprocess to get clean initialization)
+    result = `ruby -I./lib -e 'require "debug_me"; p $DEBUG_ME' 2>&1`
+    _(result.strip).must_equal "true"
+
+    # Restore if it was set
+    ENV['DEBUG_ME'] = env_value if env_value
+  end
+
+  it "sets to false when ENV['DEBUG_ME'] is 'false'" do
+    result = `DEBUG_ME=false ruby -I./lib -e 'require "debug_me"; p $DEBUG_ME' 2>&1`
+    _(result.strip).must_equal "false"
+  end
+
+  it "sets to false when ENV['DEBUG_ME'] is 'no'" do
+    result = `DEBUG_ME=no ruby -I./lib -e 'require "debug_me"; p $DEBUG_ME' 2>&1`
+    _(result.strip).must_equal "false"
+  end
+
+  it "sets to false when ENV['DEBUG_ME'] is '0'" do
+    result = `DEBUG_ME=0 ruby -I./lib -e 'require "debug_me"; p $DEBUG_ME' 2>&1`
+    _(result.strip).must_equal "false"
+  end
+
+  it "sets to false when ENV['DEBUG_ME'] is 'off'" do
+    result = `DEBUG_ME=off ruby -I./lib -e 'require "debug_me"; p $DEBUG_ME' 2>&1`
+    _(result.strip).must_equal "false"
+  end
+
+  it "sets to false when ENV['DEBUG_ME'] is empty string" do
+    result = `DEBUG_ME= ruby -I./lib -e 'require "debug_me"; p $DEBUG_ME' 2>&1`
+    _(result.strip).must_equal "false"
+  end
+
+  it "sets to true when ENV['DEBUG_ME'] is 'true'" do
+    result = `DEBUG_ME=true ruby -I./lib -e 'require "debug_me"; p $DEBUG_ME' 2>&1`
+    _(result.strip).must_equal "true"
+  end
+
+  it "sets to true when ENV['DEBUG_ME'] is 'yes'" do
+    result = `DEBUG_ME=yes ruby -I./lib -e 'require "debug_me"; p $DEBUG_ME' 2>&1`
+    _(result.strip).must_equal "true"
+  end
+
+  it "sets to true when ENV['DEBUG_ME'] is '1'" do
+    result = `DEBUG_ME=1 ruby -I./lib -e 'require "debug_me"; p $DEBUG_ME' 2>&1`
+    _(result.strip).must_equal "true"
+  end
+
+  it "sets to true when ENV['DEBUG_ME'] is 'on'" do
+    result = `DEBUG_ME=on ruby -I./lib -e 'require "debug_me"; p $DEBUG_ME' 2>&1`
+    _(result.strip).must_equal "true"
+  end
+
+  it "sets to true when ENV['DEBUG_ME'] is any other value" do
+    result = `DEBUG_ME=whatever ruby -I./lib -e 'require "debug_me"; p $DEBUG_ME' 2>&1`
+    _(result.strip).must_equal "true"
+  end
+
+end

data/tests/world_view.rb

@@ -40,4 +40,23 @@ class WorldView
   def six
     debug_me(tag:'How did I get here?', levels: 5)
   end
+
+  def test_single_class_var
+    debug_me(file:nil, header:false){:@@d}
+  end
+
+  def test_multiple_class_vars
+    debug_me(file:nil, header:false){[:@@d, :@@e, :@@f]}
+  end
+
+  def test_all_class_vars
+    debug_me(
+      file:nil,
+      header:false,
+      lvar: false,
+      ivar: false,
+      cvar: true,
+      cconst: false
+    ){}
+  end
 end # class WorldView

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: debug_me
 version: !ruby/object:Gem::Version
-  version: 1.1.1
+  version: 1.1.2
 platform: ruby
 authors:
 - Dewayne VanHoozer
-autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-11-02 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -38,6 +37,34 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: amazing_print
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
 description: |-
   This thing is pretty old.  There are much better
   ways of debugging in a complex application.  But,
@@ -52,21 +79,27 @@ files:
 - ".envrc"
 - ".gitignore"
 - ".rultor.yml"
+- CHANGELOG.md
 - Gemfile
 - LICENSE.txt
 - README.md
 - Rakefile
 - debug_me.gemspec
+- debug_me.jpg
 - lib/debug_me.rb
 - lib/debug_me/version.rb
 - rubygems.yml.asc
 - tests/debug_me_test.rb
+- tests/env_test.rb
 - tests/world_view.rb
 homepage: http://github.com/MadBomber/debug_me
 licenses:
-- You want it, its yours
-metadata: {}
-post_install_message:
+- MIT
+metadata:
+  homepage_uri: https://github.com/MadBomber/debug_me
+  source_code_uri: https://github.com/MadBomber/debug_me
+  bug_tracker_uri: https://github.com/MadBomber/debug_me/issues
+  changelog_uri: https://github.com/MadBomber/debug_me/blob/master/CHANGELOG.md
 rdoc_options: []
 require_paths:
 - lib
@@ -74,15 +107,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '0'
+      version: 2.3.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.21
-signing_key:
+rubygems_version: 3.7.2
 specification_version: 4
 summary: A tool to print the labeled value of variables.
 test_files: []