Class: Mongory::Utils::Debugger

Inherits:
SingletonBuilder show all
Includes:
Singleton
Defined in:
lib/mongory/utils/debugger.rb

Overview

Debugger provides an internal tracing system for query matching. It tracks matcher evaluation in a tree structure and provides tree-like format output.

It captures each matcher evaluation with indentation and visualizes the hierarchy, helping developers understand nested matcher flows (e.g. $and, $or, etc).

Usage: Debugger.instance.with_indent { ... } # wraps around matcher logic Debugger.instance.display # prints trace tree after execution

Note: The trace is recorded in post-order (leaf nodes enter first), and reorder_traces_for_display is used to transform it into a pre-order format suitable for display.

This class is a singleton and should be accessed via Debugger.instance.

Examples:

Enable debugging

Debugger.instance.enable
Mongory::QueryBuilder.new(...).filter(...)

Defined Under Namespace

Classes: TraceEntry

Instance Method Summary collapse

Methods inherited from SingletonBuilder

#inspect, #to_s

Constructor Details

#initialize ⇒ Debugger

Returns a new instance of Debugger.



29
30
31
32
33
 
# File 'lib/mongory/utils/debugger.rb', line 29

def initialize
  super(self.class.name)
  @indent_level = -1
  @trace_entries = []
end

Instance Method Details

#clear ⇒ Object 



104
105
106
107
108
109
 
# File 'lib/mongory/utils/debugger.rb', line 104

def clear
  # Clears the internal trace buffer.
  # This is useful when re-running a query and avoiding stale trace output.
  # @return [void]
  @trace_entries.clear
end

#disable ⇒ void

Note:

Restores the original behavior of to_proc

This method returns an undefined value.

Disables debug mode by restoring to_proc to cached_proc.



45
46
47
 
# File 'lib/mongory/utils/debugger.rb', line 45

def disable
  Matchers::AbstractMatcher.alias_method :to_proc, :cached_proc
end

#display ⇒ void

This method returns an undefined value.

Prints the visualized trace tree to STDOUT.

This processes the internal trace_entries (post-order) into a structured pre-order list that represents nested matcher evaluation.



70
71
72
73
74
75
76
77
 
# File 'lib/mongory/utils/debugger.rb', line 70

def display
  reorder_traces_for_display(@trace_entries).each do |trace|
    puts trace.formatted
  end

  @trace_entries.clear
  nil
end

#enable ⇒ void

Note:

Changes the behavior of to_proc to use debug_proc instead of cached_proc

This method returns an undefined value.

Enables debug mode by aliasing to_proc to debug_proc.



38
39
40
 
# File 'lib/mongory/utils/debugger.rb', line 38

def enable
  Matchers::AbstractMatcher.alias_method :to_proc, :debug_proc
end

#reorder_traces_for_display(traces, level = 0) ⇒ Array<TraceEntry>

Recursively reorders trace lines by indentation level to produce a display-friendly structure where parents precede children.

The original trace is built in post-order (leaf first), and this method transforms it into a pre-order structure suitable for tree display.

Parameters:

  • traces (Array<TraceEntry>) —

    the raw trace lines (leaf-first)

  • level (Integer) (defaults to: 0) —

    current processing level

Returns:

  • (Array<TraceEntry>) —

    reordered trace lines for display



88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
 
# File 'lib/mongory/utils/debugger.rb', line 88

def reorder_traces_for_display(traces, level = 0)
  result = []
  group = []
  traces.each do |trace|
    if trace.level == level
      result << trace
      result.concat reorder_traces_for_display(group, level + 1)
      group = []
    else
      group << trace
    end
  end

  result
end

#with_indent ⇒ Object

Wraps a matcher evaluation block with indentation control.

It increments the internal indent level before the block, and decrements it after. The yielded block's return value is used as trace content and pushed onto the trace_entries.

Yield Returns:

  • (String) —

    the trace content to log

Returns:

  • (Object) —

    the result of the block



57
58
59
60
61
62
63
 
# File 'lib/mongory/utils/debugger.rb', line 57

def with_indent
  @indent_level += 1
  display_string = yield
  @trace_entries << TraceEntry.new(display_string, @indent_level)
ensure
  @indent_level -= 1
end