dbg_tags 1.0.0 → 1.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f67668ea968705e3998d9481a23a32d12fd5db9f42a53d97f6f7f1383f424372
-  data.tar.gz: d2ea2f479005e3d652629749b1c5d7cb2304140ca56de952c8c6b35fe3078e50
+  metadata.gz: 0665b5e4280aea457cd828d6cfab8730c71502fc8e32daae72904bd60abe87b3
+  data.tar.gz: 7ad792027dc763687f856bdae2126d5ad8816b949dc4b16365420c78c9b3aa10
 SHA512:
-  metadata.gz: ad6860e2153812cede77a7bc1c56c16720e553e3fb1a90fc3922349f578738dd3d242e5622636327a80199038741298f407905f99f3684b8cf42e9a3c65d268e
-  data.tar.gz: 3b68a1bfffc89b93d2344f72662d0046b0d8d410047abd856f15df3f75f46d1e783cf03748478a32231c60e2d0e026b488ff2ed4655d487a27edb48f1b5ad4f7
+  metadata.gz: 4cf3f313c0f1c54978f2b9e9538e99c80e8a9a3148fb85f03c5f63b87305db344e508745fce939e5dc94e32550a058515986cef7c282950450c506a61748e82c
+  data.tar.gz: 5bb9dafd4b182778c9e6ff07208cae8f9b6b713eef2c4ab4fef89c8d20e973faf06a9e442b28d627cc1180e4e6459250bb1a8f0431b7cd259d5e5c486652db57

data/lib/dbg_tags.rb

@@ -1,62 +1,112 @@
 
-# Usage:
+# @example Usage:
+#
+#   # enabling
+#   # -----------
 # 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 :dtl # enables ALL logging for :generic 
+# Tag.enable :val # enables val+trc+log+err for :generic only
+# Tag.enable :trc # enables trc+log+err for :generic only
+# Tag.enable :log # enables log+err tags for :generic
+# Tag.enable :err # enables err tags for :generic
 # 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
+# Tag.enable feature: '>=trc'  # make sure at least level trc
+#
+#   # logging 
+#   # -----------
+# 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' # likely prints megabytes of details
+# 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 complex_paranoia_failure }
+# Tag.err(:test) { raise 'CANTHAPPEN' if complex_paranoia_failure }
+
 module Tag
 
+  # the default is :trc
   TAG_DEFAULT_LEVEL = 3
+
+  # :all overrides the minimum level on ALL tags in the system
   TAG_FEATURE_ALL = :all
+
+  # :generic is the default feature, if left unspecified
   TAG_FEATURE_GENERIC = :generic
+
+  # lowest level. No output
   NONE = 0
+
+  # level 1. Only error situation should use this
   ERR = 1
+
+  # level 2. Only very important information
   LOG = 2
+
+  # level 3. Mostly used for method entries
   TRC = 3 
+
+  # level 4. Mostly used dumping of attribute values
   VAL = 4
+
+  # level 5. Mostly used for exhaustive dumping of attribute values and minor details
   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[:feature] => 0..5
   @@enabled = {} 
   @@stream = STDERR
 
   module InstanceMethods
     @@inside = false
 
+    # @param feature [Symbol,nil] Subsystem to print logging for. Fully dynamic/free
+    # @param msg [String,nil] 
+    # @note feature and msg can be switched
+    # @param block [Proc,nil] If set the result overrides and msg passed.
+    # The call is silently ignored if called from inside another Tag block (likely
+    #   a sign of a stack overflow in process).
+    # The call is silently ignored if the current tag level is too low.
+    # For trc it should be trc or val or dtl to actually print something.
+    # @!method trc feature = TAG_FEATURE_GENERIC, msg = '', &block
+
+    # see trc 
+    # !method err feature = TAG_FEATURE_GENERIC, msg = '', &block
+   
+    # see trc 
+    # !method log feature = TAG_FEATURE_GENERIC, msg = '', &block
+   
+    # see trc 
+    # !method val feature = TAG_FEATURE_GENERIC, msg = '', &block
+ 
+    # see trc 
+    # !method dtl feature = TAG_FEATURE_GENERIC, msg = '', &block
+  
     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
+	return if @@inside || (Tag.level(feature) || Tag::NONE) < lev
 	# either msg OR msg_block must be set
 	if msg_block 
 	  prev_inside = @@inside
@@ -84,39 +134,70 @@ module Tag
 
   end # module Tag::InstanceMethods
 
-  public # class methods of Tag
+  extend InstanceMethods
+  include InstanceMethods
+
+  class << self
+    private # class methods of Tag
 
-    extend InstanceMethods
-    include InstanceMethods
+    # @param level_spec [Integer,Symbol,String]
+    # @param feature [Symbol]
+    # @return [0..5]
+    def debunk_level level_spec, feature
+      #      raise 'AARG' unless Symbol === feature
+# OK    STDERR.puts "DEBUNK: level_spec=#{level_spec.inspect}, feature=#{feature.inspect}"
+      case level_spec
+      when 0..5 then return level_spec 
+      when Symbol
+        r = TAG_MAPPING[level_spec] and return r 
+      when /\A(err|log|trc|val|dtl)\z/
+        return TAG_MAPPING[level_spec.to_sym] 
+      when /\A>=(err|log|trc|val|dtl)\z/
+        eff_lev = level feature
+        new_lev = TAG_MAPPING[level_spec[2..].to_sym]
+# OK STDERR.puts "level_spec=#{level_spec}, feature=#{feature.inspect},eff_lev=#{eff_lev},new_lev=#{new_lev}"
+        return [eff_lev, new_lev].max
+      end # case
+      raise ArgumentError, "bad level #{level_spec.inspect}"
+    end # Tag::debunk_level
 
+    public # class methods of Tag
+
+    # @param features [<Symbol>]
     # enable :feature, ...[, feature: level, ...] [block]
-    # :generic is NO LONGER IMPLICETELY ENABLED as of version
+    # :generic is NO LONGER IMPLICETELY ENABLED as of version 1.0.0
     # 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
+    # Strings can be used in the shape of 'err' or '>=err' etc.
+    # If '>=LVL' is used the level will not lower, if already set in an outer block.
     # 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]
+    def enable *features, **opts
+      org_enabled = @@enabled.dup # to restore the state at the end (unused unless block_given)
+      features.each do |feature|
+        case feature
+        when 0..5 # not a feature, apply to :generic
+          @@enabled[TAG_FEATURE_GENERIC] = feature 
+        when Symbol
+          if TAG_MAPPING[feature] # not a feature 
+            @@enabled[TAG_FEATURE_GENERIC] = TAG_MAPPING[feature]
           else
-            @@enabled[s] = TAG_DEFAULT_LEVEL 
+            @@enabled[feature] = TAG_DEFAULT_LEVEL
           end
-	end # case
+        when String
+          @@enabled[TAG_FEATURE_GENERIC] = debunk_level feature, TAG_FEATURE_GENERIC
+        else
+          raise ArgumentError "bad level #{feature.inspect}"
+        end # case
       end # each
-      if arg.empty?
+      opts.each do |feature, level|
+        # OK        STDERR.puts "OPTION!!!!!!!!!!!!!!!!!, calling debunk_level"
+        @@enabled[feature] = debunk_level level, feature
+      end
+      if features.empty? && opts.empty?
         @@enabled[TAG_FEATURE_GENERIC] = TAG_DEFAULT_LEVEL
       end
       if block_given?
@@ -130,16 +211,23 @@ module Tag
       end # block_given?
     end # Tag.enable
 
-    # enabled -> Hash
-    def self.enabled; @@enabled; end
-    def self.stream; @@stream; end
+    # @return [{Symbol=>0..5}] Keys are the features
+    def enabled; @@enabled; end
+
+    # @return [IO] By default this is STDERR
+    def stream; @@stream; end
 
-    # for testing purposes:
-    def self.stream= val; @@stream = val; end
+    # @param val [IO] 
+    # Override the output stream.
+    def 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
+    # @param feature [Symbol]
+    # @return [0..5] Current effective level for feature.
+    # 2023-08-14 no longer returns nil
+    def level feature; @@enabled[feature] || @@enabled[TAG_FEATURE_ALL] || Tag::NONE; end
 
-    # enabled?(:feature) -> bool. Could be :err up to :dtl. Ignores setting of :all!
-    def self.enabled? feature; @@enabled[feature] && @@enabled[feature] > NONE; end
+    # @param feature [Symbol]
+    # @return [bool] Reflects explicit enable calls only. The :all feature is IGNORED
+    def enabled? feature; (@@enabled[feature] || NONE) > NONE; end
+  end # singleton class Tag
 end # module Tag

data/spec/01_tag_spec.rb

@@ -178,4 +178,89 @@ describe 'tag' do
   # however, it only works with LAZY calls. 
   # def to_s; Tag.trc "HERE in #{self}"; super; end 
   # will OBVIOUSLY cause a stack overflow.
+  #
+
+  context 'Nested levels' do
+    it 'overwrites the level set in outer temporarily (tag_200)' do
+      Tag.enable nest: :val do
+          expect(Tag.level :nest).to be Tag::VAL
+        Tag.enable nest: 'trc' do
+          expect(Tag.level :nest).to be Tag::TRC
+        end
+        expect(Tag.level :nest).to be Tag::VAL
+      end
+    end # it
+
+    it 'raises the level set in outer temporarily if >= is used (tag_201)' do
+      Tag.enable nest: :err do
+          expect(Tag.level :nest).to be Tag::ERR
+        Tag.enable nest: '>=trc' do
+          expect(Tag.level :nest).to be Tag::TRC
+        end
+        expect(Tag.level :nest).to be Tag::ERR
+      end
+    end # it
+
+    it 'ONLY raises the level set in outer temporarily if >= is used (tag_202)' do
+      Tag.enable nest: :trc do
+          expect(Tag.level :nest).to be Tag::TRC
+        Tag.enable nest: '>=err' do
+          expect(Tag.level :nest).to be Tag::TRC
+        end
+        expect(Tag.level :nest).to be Tag::TRC
+      end
+    end # it
+
+    it 'raises the level set in outer temporarily if >= is used (tag_201.b)' do
+      Tag.enable :err do
+          expect(Tag.level Tag::TAG_FEATURE_GENERIC).to be Tag::ERR
+        Tag.enable '>=trc' do
+          expect(Tag.level Tag::TAG_FEATURE_GENERIC).to be Tag::TRC
+        end
+        expect(Tag.level Tag::TAG_FEATURE_GENERIC).to be Tag::ERR
+      end
+    end # it
+
+    it 'ONLY raises the level set in outer temporarily if >= is used (tag_202.b)' do
+      Tag.enable :trc do
+          expect(Tag.level Tag::TAG_FEATURE_GENERIC).to be Tag::TRC
+        Tag.enable nest: '>=err' do
+          expect(Tag.level Tag::TAG_FEATURE_GENERIC).to be Tag::TRC
+        end
+        expect(Tag.level Tag::TAG_FEATURE_GENERIC).to be Tag::TRC
+      end
+    end # it
+
+    it 'takes :all into consideration when >= is used (tag_205)' do
+      Tag.enable all: :log do
+          expect(Tag.level :nest).to be Tag::LOG
+        Tag.enable nest: '>=err' do
+          expect(Tag.level :nest).to be Tag::LOG
+        end
+        expect(Tag.level :nest).to be Tag::LOG
+        Tag.enable nest: '>=trc' do
+          expect(Tag.level :nest).to be Tag::TRC
+        end
+        expect(Tag.level :nest).to be Tag::LOG
+      end
+    end # it
+  end # context 'Nested levels'
+
+  it 'does not allow levels out of range (tag_900)' do
+    expect do
+      Tag.enable nest: 24
+    end.to raise_error ArgumentError, /bad level/i
+    expect do
+      Tag.enable nest: -2
+    end.to raise_error ArgumentError, /bad level/i
+  end # it
+
+  it 'does not allow made up levels (tag_901)' do
+    expect do
+      Tag.enable nest: :foo
+    end.to raise_error ArgumentError, /bad level/i
+    expect do
+      Tag.enable nest: '>=foo'
+    end.to raise_error ArgumentError, /bad level/i
+  end # it
 end # describe

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: dbg_tags
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.0.1
 platform: ruby
 authors:
 - Eugene Brazwick
-autorequire: 
+autorequire:
 bindir: bin
 cert_chain: []
-date: 2022-03-24 00:00:00.000000000 Z
+date: 2023-08-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec
@@ -52,25 +52,9 @@ dependencies:
     - - "~>"
       - !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"
+description: |
+  debug 'tags' in your code can be switched on/off using features and levels.
+  See README.md
 email: eugenebrazwick@gmail.com
 executables: []
 extensions: []
@@ -82,7 +66,7 @@ homepage: https://github.com/Eugene-Brazwick/dbg_tags
 licenses:
 - GPL-3.0
 metadata: {}
-post_install_message: 
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -97,8 +81,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.1.2
-signing_key: 
+rubygems_version: 3.3.5
+signing_key:
 specification_version: 4
 summary: a versatile dynamic debug tracing system
 test_files: