Module: Tag

Defined in:
lib/dbg_tags.rb

Overview

Examples:

Usage:


# enabling
# -----------
require 'dbg_tags'

Tag.enable :feature1, :feature2..., featureN: :log, featureO: :val, ...
Tag.enable feature1: :trc, feature2: :val
Tag.enable feature: Tag::TRC
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 }

Defined Under Namespace

Classes: GlobalState

Constant Summary collapse

TAG_FEATURE_ALL =

:all overrides the minimum level on ALL tags in the system

:all
TAG_FEATURE_GENERIC =

:generic is the default feature, if left unspecified

:generic
NONE =

lowest level. No output

0
ERR =

level 1. Only error situation should use this

1
LOG =

level 2. Only very important information

2
TRC =

level 3. Mostly used for method entries

3
VAL =

level 4. Mostly used dumping of attribute values

4
DTL =

level 5. Mostly used for exhaustive dumping of attribute values and minor details

5
TAG_DEFAULT_LEVEL =

the default is :trc

TRC
TAG_MAPPING =

nil and :nil will both map to NONE

{ none: NONE, err: ERR, log: LOG, trc: TRC, val: VAL, dtl: DTL, 
  nil: NONE,
  nil => NONE
}

Class Attribute Summary collapse

Class Method Summary collapse

Class Attribute Details

.no_thread_local_state ⇒ Bool? Also known as: no_thread_local_state?

Returns True if we should store global state inside the Tag class itself.

Returns:

  • (Bool, nil) —

    True if we should store global state inside the Tag class itself.



201
202
203
 
# File 'lib/dbg_tags.rb', line 201

def no_thread_local_state
  @no_thread_local_state
end

Class Method Details

.disable_thread_local_state ⇒ Object Also known as: disable_fiber_local_state

shortcut for no_thread_local_state = true By default thread local state is enabled and this means that ‘enabling’ of tags in some thread does effect in others. So: when using threads leave this enabled, as it will cause race conditions otherwise. When not using threads, it is more efficient to disable it.



314
 
# File 'lib/dbg_tags.rb', line 314

def disable_thread_local_state; self.no_thread_local_state = true end

.dtl(feature = TAG_FEATURE_GENERIC, msg = '', &block) ⇒ Object

See Also:



250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
 
# File 'lib/dbg_tags.rb', line 250

TAG_MAPPING.each do |meth, lev|
  next if lev == NONE
  define_method meth do |feature = TAG_FEATURE_GENERIC, msg = '', &msg_block|
    state = global_state
	msg, feature = feature, TAG_FEATURE_GENERIC if String === feature
#STDERR.puts "DEBUGTAG #{meth}. feature=#{feature}, level=#{Tag.level(feature)}, lev=#{lev}"
    return if state.inside? || (state.level(feature) || Tag::NONE) < lev
	# either msg OR msg_block must be set
	if msg_block
      prev_inside = state.inside?
	  begin
        state.inside = true
 msg = msg_block.call 
	  ensure
        state.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
      state.stream.print "#{label} #{msg}\n"
    end
  end # Tag.err, Tag.log, Tag.trc, Tag.val, Tag.dtl
end

.enable ⇒ Object

See Also:



283
 
# File 'lib/dbg_tags.rb', line 283

def enable(...); global_state.enable(...); end

.enable_thread_local_state ⇒ Object Also known as: enable_fiber_local_state

shortcut for no_thread_local_state := false For rspec use mostly.



321
 
# File 'lib/dbg_tags.rb', line 321

def enable_thread_local_state; self.no_thread_local_state = false end

.enabled ⇒ {Symbol=>0..5} Also known as: state

Returns Keys are the features.

Returns:

  • ({Symbol=>0..5}) —

    Keys are the features



289
 
# File 'lib/dbg_tags.rb', line 289

def enabled; global_state.enabled; end

.enabled?(feature) ⇒ bool

Returns Reflects explicit enable calls only. The :all feature is IGNORED.

Parameters:

  • feature (Symbol)

Returns:

  • (bool) —

    Reflects explicit enable calls only. The :all feature is IGNORED



306
 
# File 'lib/dbg_tags.rb', line 306

def enabled? feature; (global_state.enabled[feature] || NONE) > NONE; end

.err(feature = TAG_FEATURE_GENERIC, msg = '', &block) ⇒ Object

See Also:




# File 'lib/dbg_tags.rb', line 238

.global_state ⇒ GlobalState

Returns Either thread local data (default) or truly global.

Returns:

  • (GlobalState) —

    Either thread local data (default) or truly global.



215
216
217
218
219
220
221
222
223
224
225
226
 
# File 'lib/dbg_tags.rb', line 215

def global_state
  if @no_thread_local_state
    @global_state ||= GlobalState.new
  else
    ct = Thread.current 
    unless state = ct.thread_variable_get(:dbg_tags_global_state)
      state = GlobalState.new
      ct.thread_variable_set :dbg_tags_global_state, state
    end
    state
  end
end

.inside? ⇒ Boolean

inside? -> true if we are currently executing a block in err/log/trc/val or dtl.

Returns:

  • (Boolean) 


280
 
# File 'lib/dbg_tags.rb', line 280

def inside?; global_state.inside?; end

.level(feature) ⇒ 0..5

2023-08-14 no longer returns nil

Parameters:

  • feature (Symbol)

Returns:

  • (0..5) —

    Current effective level for feature.



302
 
# File 'lib/dbg_tags.rb', line 302

def level feature; global_state.level feature; end

.log(feature = TAG_FEATURE_GENERIC, msg = '', &block) ⇒ Object

See Also:




# File 'lib/dbg_tags.rb', line 241

.restore_state ⇒ Object

See Also:



286
 
# File 'lib/dbg_tags.rb', line 286

def restore_state(...); global_state.restore_state(...); end

.stream ⇒ IO

Returns By default this is STDERR.

Returns:

  • (IO) —

    By default this is STDERR



293
 
# File 'lib/dbg_tags.rb', line 293

def stream; global_state.stream; end

.stream=(val) ⇒ Object

Override the output stream.

Parameters:

  • val (IO) 


297
 
# File 'lib/dbg_tags.rb', line 297

def stream= val; global_state.stream = val; end

.trc(feature = TAG_FEATURE_GENERIC, msg = '', &block) ⇒ Object

Note:

feature and msg can be switched

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.

Parameters:

  • feature (Symbol, nil) (defaults to: TAG_FEATURE_GENERIC) —

    Subsystem to print logging for. Fully dynamic/free

  • msg (String, nil) (defaults to: '')
  • block (Proc, nil) —

    If set the result overrides and msg passed.




# File 'lib/dbg_tags.rb', line 228

.use_thread_local_state? ⇒ Bool Also known as: use_fiber_local_state?

in each thread of the application.

Returns:

  • (Bool) —

    True (the default) if we should store global state



209
 
# File 'lib/dbg_tags.rb', line 209

def use_thread_local_state?; !no_thread_local_state? end

.val(feature = TAG_FEATURE_GENERIC, msg = '', &block) ⇒ Object

See Also:




# File 'lib/dbg_tags.rb', line 244