dbg_tags 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: f67668ea968705e3998d9481a23a32d12fd5db9f42a53d97f6f7f1383f424372
+  data.tar.gz: d2ea2f479005e3d652629749b1c5d7cb2304140ca56de952c8c6b35fe3078e50
+SHA512:
+  metadata.gz: ad6860e2153812cede77a7bc1c56c16720e553e3fb1a90fc3922349f578738dd3d242e5622636327a80199038741298f407905f99f3684b8cf42e9a3c65d268e
+  data.tar.gz: 3b68a1bfffc89b93d2344f72662d0046b0d8d410047abd856f15df3f75f46d1e783cf03748478a32231c60e2d0e026b488ff2ed4655d487a27edb48f1b5ad4f7

data/lib/dbg_tags.rb

@@ -0,0 +1,145 @@
+
+# Usage:
+# require 'dbg_tags'
+# 		Tag.err 'text', short for Tag.err(:generic) 'text' 
+# 		    # :err should be used for fail states and paranoia stuff
+# 		Tag.log 'text' # prints very important messages only
+# 		Tag.trc 'text' # default level, method entries, for example
+# 		Tag.val 'text' # prints more details
+# 		Tag.dtl 'text' # prints megabytes of details
+# 		Tag.enable :log # enables log,trc,val,dtl tags for :generic
+# 		Tag.enable :dtl # only enables :dtl calls
+# 		Tag.enable :err # enable ALL :generic tags
+# 		Tag.err :feature, 'FAILURE'
+# 		Tag.log :feature, 'log me'
+# 		Tag.trc :feature, 'called method'
+# 		Tag.val(:feature) { "text#{expr}" }
+# 		Tag.dtl(:feature) { "text#{very complicated expr}" }
+#               Tag.err(:test) { raise 'aaaarg' if paranoia_failure }
+#               Tag.err(:test) { raise 'CANTHAPPEN' if paranoia_failure }
+# Tag.enable :feature1, :feature2..., featureN: :log, featureO: :val, ...
+# Tag.enable feature1: :trc, feature2: :val
+# Tag.enable feature: Tag::TRC
+# Tag.enable :val   # for :generic only
+# Tag.enable # sets :generic to :trc
+# Tag.enable(...) do ... end
+# Tag.enable feature: nil
+# Tag.enable feature: :nil
+# Tag.enable all: :err    # :all is a default for ALL systems, including :generic
+# Tag.enable test: :err # switch on paranoia checking
+module Tag
+
+  TAG_DEFAULT_LEVEL = 3
+  TAG_FEATURE_ALL = :all
+  TAG_FEATURE_GENERIC = :generic
+  NONE = 0
+  ERR = 1
+  LOG = 2
+  TRC = 3 
+  VAL = 4
+  DTL = 5
+  # nil and :nil will both map to NONE
+  TAG_MAPPING =  { none: NONE, err: ERR, log: LOG, trc: TRC, val: VAL, dtl: DTL, 
+                   nil: NONE,
+                   nil => NONE
+                 } # TAG_MAPPING
+
+# @@enabled[:feature] => 0..5
+  @@enabled = {} 
+  @@stream = STDERR
+
+  module InstanceMethods
+    @@inside = false
+
+    TAG_MAPPING.each do |meth, lev|
+      next if lev == NONE
+      define_method meth do |feature = TAG_FEATURE_GENERIC, msg = '', &msg_block|
+	msg, feature = feature, TAG_FEATURE_GENERIC if String === feature
+#STDERR.puts "DEBUGTAG #{meth}. feature=#{feature}, level=#{Tag.level(feature)}, lev=#{lev}"
+	return if @@inside || (Tag.level(feature) || 0) < lev
+	# either msg OR msg_block must be set
+	if msg_block 
+	  prev_inside = @@inside
+	  begin
+	    @@inside = true
+	    msg = msg_block.call 
+	  ensure
+	    @@inside = prev_inside
+	  end
+	end
+        if msg
+          c = caller[0]
+  #STDERR.puts "DEBUGTAG c[#{idx}] = #{c}, caller[1]=#{caller[1]}, caller[2]=#{caller[2]}"
+          label = c[/\w+\.rb:\d+:in `[^']+'/]&.sub(/in `([^']+)'/, '\1:') ||
+                  c[/\w+\.rb:\d+:/] ||
+                  c[/[^:\/]+:\d+:/] || 
+                  c
+          Tag.stream.print "#{label} #{msg}\n"
+        end
+      end # Tag.err, Tag.log, Tag.trc, Tag.val, Tag.dtl
+    end # each
+
+    # inside? -> true if we are currently executing a block in err/log/trc/val or dtl.
+    def inside?; @@inside; end
+
+  end # module Tag::InstanceMethods
+
+  public # class methods of Tag
+
+    extend InstanceMethods
+    include InstanceMethods
+
+    # enable :feature, ...[, feature: level, ...] [block]
+    # :generic is NO LONGER IMPLICETELY ENABLED as of version
+    # Use :all to set a default for all features not mentioned otherwise
+    # Integers in range 1..5 can be used as level or the constants ERR,LOG,TRC,VAL,DTL
+    # or the symbols :err, :log, :trc, :val and :dtl
+    # If no level is specified for a feature the default is :trc (== TRC == 3)
+    # use nil or :none to disable all tags, even the ERR level ones.
+    #
+    # enable performs a merge with an existing enable.
+    def self.enable *arg
+      org_enabled = @@enabled.dup
+      arg.each do |s|
+	case s
+        when Hash
+          s.each do |t, level|
+	    @@enabled[t] = Symbol === level ? TAG_MAPPING[level] : level
+	  end
+        when Integer
+          @@enabled[TAG_FEATURE_GENERIC] = s
+	else
+          if TAG_MAPPING[s]
+            @@enabled[TAG_FEATURE_GENERIC] = TAG_MAPPING[s]
+          else
+            @@enabled[s] = TAG_DEFAULT_LEVEL 
+          end
+	end # case
+      end # each
+      if arg.empty?
+        @@enabled[TAG_FEATURE_GENERIC] = TAG_DEFAULT_LEVEL
+      end
+      if block_given?
+#        STDERR.puts "TAG: block_given!"
+        begin
+#          STDERR.puts "TAG: yield!"
+          yield
+        ensure
+          @@enabled = org_enabled
+        end # ensure
+      end # block_given?
+    end # Tag.enable
+
+    # enabled -> Hash
+    def self.enabled; @@enabled; end
+    def self.stream; @@stream; end
+
+    # for testing purposes:
+    def self.stream= val; @@stream = val; end
+
+    # level(:feature) -> 0..5 or nil. Uses :all as a fallback-feature
+    def self.level feature; @@enabled[feature] || @@enabled[TAG_FEATURE_ALL]; end
+
+    # enabled?(:feature) -> bool. Could be :err up to :dtl. Ignores setting of :all!
+    def self.enabled? feature; @@enabled[feature] && @@enabled[feature] > NONE; end
+end # module Tag

data/spec/01_tag_spec.rb

@@ -0,0 +1,181 @@
+
+require 'simplecov'
+SimpleCov.start
+
+require_relative '../lib/dbg_tags'
+
+class Pathological
+  def to_s
+    Tag.trc { "HERE in #{self}!" }
+    super
+  end # to_s
+end 
+
+describe 'tag' do
+  before :each do
+    @stream = double 'stream'
+    Tag.stream = @stream
+  end # before :each
+
+  it 'prints stuff while enabled (tag_001)' do
+    expect(@stream).to receive(:print).once
+    Tag.enable :dtl do
+      Tag.trc 'this is traced'
+    end # enable
+    Tag.trc 'this is outside scope'
+  end # it
+
+  it 'prints stuff only if the level is high enough (tag_002)' do
+    expect(@stream).to_not receive :print
+    Tag.enable :val do
+      Tag.dtl 'this is not traced'
+    end # enable
+  end # it
+  
+  it 'prints stuff only if the level is high enough (tag_003)' do
+    expect(@stream).to receive(:print).once
+    Tag.enable :trc do
+      Tag.err 'this is traced'
+      Tag.val 'this is not traced'
+      Tag.dtl 'this is not traced'
+    end # enable
+  end # it
+
+  it 'prints stuff only if the level is high enough (tag_004)' do
+    expect(@stream).to receive(:print).once
+    Tag.enable :log do
+      Tag.log 'this is traced'
+      Tag.trc 'this is not traced'
+      Tag.val 'this is not traced'
+      Tag.dtl 'this is not traced'
+    end # enable
+  end # it
+
+  it 'prints stuff only if the level is high enough (tag_005)' do
+    expect(@stream).to receive(:print).once
+    Tag.enable :err do
+      Tag.err 'this is traced'
+      Tag.log 'this is not traced'
+      Tag.trc 'this is not traced'
+      Tag.val 'this is not traced'
+      Tag.dtl 'this is not traced'
+    end # enable
+  end # it
+
+  it 'allows constants for setting the level too (tag_006)' do
+    expect(@stream).to receive(:print).twice
+    Tag.enable Tag::LOG do
+      Tag.err 'this is traced'
+      Tag.log 'this is traced'
+      Tag.trc 'this is not traced'
+      Tag.val 'this is not traced'
+      Tag.dtl 'this is not traced'
+    end # enable
+  end # it
+
+  it 'prints stuff only if the feature category is set correctly (tag_010)' do
+    expect(@stream).to receive(:print).once
+    Tag.enable generic: :trc do
+      Tag.trc 'this is traced'
+      Tag.trc :feature, 'this is not traced'
+    end
+  end # it
+
+  it 'uses :generic as default feature category (tag_015)' do
+    expect(@stream).to receive(:print).once.with(/this is traced/)
+    Tag.enable :trc do
+      Tag.trc 'this is traced'
+      Tag.trc :feature, 'this is not traced'
+    end
+  end # it
+
+  it 'can enable several cats with their own levels (tag_020)' do
+    expect(@stream).to receive(:print).exactly(2).times.with(/this is traced/)
+    Tag.enable core: :trc, printing: :val, calc: :err do
+      Tag.trc :core, 'this is traced'
+      Tag.trc :printing, 'this is traced'
+      Tag.trc :emit, 'this is not traced'
+      Tag.trc :calc, 'this is not traced'
+    end
+  end # it
+
+  it 'prints the line of the source where the tag was placed (tag_030)' do
+    expect(@stream).to receive(:print).once.with(/01_tag_spec.rb:\d+:block/)
+    Tag.enable core: :trc, printing: :val, calc: :err do
+      Tag.trc :core
+    end
+    Tag.trc :core, 'outside scope'
+  end # it
+
+  it 'allows a block for lazy evaluation (tag_040)' do
+    x = 0
+    expect(@stream).to receive(:print).once.with(/this is traced/)
+    Tag.enable core: :trc do
+      Tag.trc(:core) { x += 2; 'this is traced' }
+      Tag.val(:core) { x += 1 }
+    end
+    expect(x).to be 2
+  end # it
+
+  it 'allows non-strings in blocks (tag_041)' do
+    expect(@stream).to receive(:print).once.with(/\b2828\b/)
+    Tag.enable core: :trc do
+      Tag.trc(:core) { 2828 }
+    end
+  end # it
+
+  it 'allows for a level :nil (tag_050)' do
+    expect(@stream).to_not receive :print
+    Tag.enable :nil do
+      Tag.trc 'never'
+      Tag.err 'never'
+    end
+  end # it
+
+  it 'uses :trc as default level (tag_051)' do
+    expect(@stream).to receive(:print).once.with(/this is printed/)
+    Tag.enable do
+      Tag.trc 'this is printed'
+      Tag.val 'this is not printed'
+    end
+  end # it
+
+  it 'uses :trc as default level (tag_052)' do
+    expect(@stream).to receive(:print).twice.with(/this is printed/)
+    Tag.enable :core, :printing, emit: :err do
+      Tag.trc 'this is not printed'
+      Tag.trc :core, 'this is printed'
+      Tag.trc :printing, 'this is printed'
+      Tag.trc :emit, 'this is not printed'
+    end
+  end # it
+
+  it 'can set a default level using RESERVED category :all (tag_060)' do
+    expect(@stream).to receive(:print).exactly(3).times.with(/this is printed/)
+    Tag.enable :core, :printing, all: :err do
+      Tag.trc(:core) { 'this is printed' }
+      Tag.trc(:emit) { 'this is not printed' }
+      Tag.err(:emit) { 'this is printed' }
+      Tag.err(:anything) { 'this is printed' }
+    end # enable
+  end # it
+
+  it 'can handle pathological cases (tag_100)' do
+    expect(@stream).to receive(:print).once.with(/p =/)
+    Tag.enable do
+      p = Pathological.new
+      Tag.trc { "p = #{p}" }
+    end
+  end
+
+  it 'can handle pathological cases (tag_101)' do
+    expect(@stream).to receive(:print).once.with(/HERE/)
+    Tag.enable do
+      Pathological.new.to_s
+    end
+  end
+
+  # however, it only works with LAZY calls. 
+  # def to_s; Tag.trc "HERE in #{self}"; super; end 
+  # will OBVIOUSLY cause a stack overflow.
+end # describe

metadata

@@ -0,0 +1,105 @@
+--- !ruby/object:Gem::Specification
+name: dbg_tags
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Eugene Brazwick
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2022-03-24 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.4'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.4'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.4'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.4'
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.18'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.18'
+description: "      tags in your code can be switched on using features and levels.\n
+  \     Examples:\n      Tag.trc 'a message' # a :generic tag\n        # All tags
+  print sourcefile, current method and linenumber automatically\n      Tag.trc # prints
+  file, method and linenumber\n      Tag.trc :feature, 'a message' # only called if
+  :feature enabled.\n      Tag.err 'msg' # Triggered when :generic feature is set
+  to at \n                    # least :err level.\n                    # The levels
+  are :err, :log, :trc, :val and :dtl, \n                    # in that order\n      Tag.dtl
+  :complex do \"val = #{expensive.method.call}\" end\n      Tag.dtl(:complex) { \"val
+  = #{expensive.method.call}\" }\n\t  # use lazy evaluation with a block.\n          #
+  The block expression is printed using to_s.\n      Tag.dtl(:complex) {} # same as
+  Tag.dtl :complex \n# At the start of your application enable the desired dump-level.\n
+  \     Tag.enable\t# Same as Tag.enable generic: :trc\n                        #
+  That is enables levels <=:trc\n      Tag.enable :val   # enable :generic tags at
+  <=:val levels\n      Tag.enable :feature1, :feat2, ... # enables given features
+  on <=:trc\n      Tag.enable :feature1, :feat2, feat3: :dtl, all: :err\n\t# Set :feature1,
+  :feat2, and :generic to <=:trc, :feat3 to :dtl\n\t# and ANY OTHER feature to only
+  :err. \n      Tag.enable feature: :err \n      Tag.enable feature: :dtl # so ALL
+  tags with feature :feature\n      Tag.err(:feature) { raise 'aaaarg' if expensive_check_fails?
+  }\n"
+email: eugenebrazwick@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/dbg_tags.rb
+- spec/01_tag_spec.rb
+homepage: https://github.com/Eugene-Brazwick/dbg_tags
+licenses:
+- GPL-3.0
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '2.7'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.1.2
+signing_key: 
+specification_version: 4
+summary: a versatile dynamic debug tracing system
+test_files:
+- spec/01_tag_spec.rb