Examples/Usage

there are 6 levels for tags. In order:

• :nil, never prints
• :err, for obvious error conditions, and 'canthappens' and the like
• :log, for basic logging
• :trc, for function entry
• :val, for printing values
• :dtl, for printing everything in great detail

'enable' sets up levels for the available modules. A module is an arbitrary identifier used with tags, to make it easier to select which tags will print. Tags with no module will use :generic as id.

require 'dbg_tags'

  Tag.trc 'a message' # a :generic tag on 'trc' level or higher (so val/dtl too).

# All tags print sourcefile, current method and linenumber automatically
  Tag.trc # still prints file, method and linenumber

  Tag.trc :feature, 'a message' # only called if :feature enabled.
  Tag.err 'msg' # Triggered when :generic feature is set to any level other than :nil

# use lazy evaluation with a block.
# The block expression is printed using to_s.
  Tag.dtl :complex do "val = \#{expensive.method.call}" end
  Tag.dtl(:complex) { "val = \#{expensive.method.call}" }
  Tag.dtl(:complex) {} # same as Tag.dtl :complex 

# At the start of your application enable the desired dump-level.
  Tag.enable	# Same as Tag.enable generic: :trc
                # That is enables levels <=:trc, so trc,log and err
  Tag.enable :val   # enable :generic tags at <=:val levels
  Tag.enable :feature1, :feat2, ... # enables given features on <=:trc

# Set :feature1, :feat2, and :generic to <=:trc, :feat3 to :dtl
# and ANY OTHER feature to only :err. 
  Tag.enable :feature1, :feat2, feat3: :dtl, all: :err

  Tag.enable feature: :err 
  Tag.enable feature: :dtl # so ALL tags with feature :feature

# Tags can be used to create lazy 'canthappen' constructs:
  Tag.err(:feature) { raise 'aaaarg' if expensive_check_fails? }

# Tag.enable can be passed a block for which it is active.
# Afterwards the previous config is restored.
  Tag.enable main: :trc, printing: :val, admin: :nil do
    # ....
  end # enable

PRO: very simple, robust, and versatile CON: it takes a methodcall, even if tags are disabled. Unlike using C macros.