Module: Kotoshu::Debug

Defined in:
lib/kotoshu/debug_mode.rb,
lib/kotoshu/debug_logger.rb

Overview

Debug mode for detailed spellchecking insights.

When enabled, debug mode provides:

  • Lookup timing information

  • Suggestion scoring details

  • Decision tree visualization

  • Cache hit/miss tracking

  • Performance metrics

Examples:

Enable debug mode

Kotoshu::Debug.enable
Kotoshu.correct?("hello")
# Output: DEBUG: lookup "hello" - 0.001ms

Disable debug mode

Kotoshu::Debug.disable

Defined Under Namespace

Classes: Logger

Class Attribute Summary collapse

Class Method Summary collapse

Class Attribute Details

.logger ⇒ Debug::Logger? (readonly)

Get the debug logger.

Returns:



49
50
51
 
# File 'lib/kotoshu/debug_mode.rb', line 49

def logger
  @logger
end

Class Method Details

.disable ⇒ Object

Disable debug mode.



34
35
36
37
 
# File 'lib/kotoshu/debug_mode.rb', line 34

def disable
  @enabled = false
  @logger = nil
end

.enable(output: $stderr, level: :info) ⇒ Object

Enable debug mode.

Parameters:

  • output (IO) (defaults to: $stderr) —

    Output stream (default: $stderr)

  • level (Symbol) (defaults to: :info) —

    Debug level (:info, :verbose, :trace)



26
27
28
29
30
31
 
# File 'lib/kotoshu/debug_mode.rb', line 26

def enable(output: $stderr, level: :info)
  @enabled = true
  @output = output
  @level = level
  @logger = Debug::Logger.new(output: output, level: level)
end

.enabled? ⇒ Boolean

Check if debug mode is enabled.

Returns:

  • (Boolean) —

    True if enabled



42
43
44
 
# File 'lib/kotoshu/debug_mode.rb', line 42

def enabled?
  @enabled ||= false
end

.log_cache(cache_type, key, hit:) ⇒ Object

Log a cache hit/miss.

Parameters:

  • cache_type (String) —

    Type of cache (lookup, suggestion)

  • key (String) —

    The cache key

  • hit (Boolean) —

    True if cache hit



78
79
80
81
82
 
# File 'lib/kotoshu/debug_mode.rb', line 78

def log_cache(cache_type, key, hit:)
  return unless enabled?

  logger&.debug_cache(cache_type, key, hit: hit)
end

.log_decision_tree(word, decisions:) ⇒ Object

Log a decision tree.

Parameters:

  • word (String) —

    The input word

  • decisions (Array) —

    Array of decision nodes



88
89
90
91
92
 
# File 'lib/kotoshu/debug_mode.rb', line 88

def log_decision_tree(word, decisions:)
  return unless enabled?

  logger&.debug_decision_tree(word, decisions: decisions)
end

.log_lookup(word, result:, time:) ⇒ Object

Log a lookup operation.

Parameters:

  • word (String) —

    The word being looked up

  • result (Boolean) —

    The lookup result

  • time (Float) —

    Time taken in milliseconds



56
57
58
59
60
 
# File 'lib/kotoshu/debug_mode.rb', line 56

def log_lookup(word, result:, time:)
  return unless enabled?

  logger&.debug_lookup(word, result: result, time: time)
end

.log_suggestions(word, suggestions:, time:) ⇒ Object

Log a suggestion generation.

Parameters:

  • word (String) —

    The input word

  • suggestions (Array) —

    Generated suggestions

  • time (Float) —

    Time taken in milliseconds



67
68
69
70
71
 
# File 'lib/kotoshu/debug_mode.rb', line 67

def log_suggestions(word, suggestions:, time:)
  return unless enabled?

  logger&.debug_suggestions(word, suggestions: suggestions, time: time)
end

.measure_lookup(word) { ... } ⇒ Object

Measure and log a lookup.

Yields:

  • Block that performs the lookup

Returns:

  • (Object) —

    Block result



111
112
113
114
115
116
117
118
 
# File 'lib/kotoshu/debug_mode.rb', line 111

def measure_lookup(word)
  start = Process.clock_gettime(Process::CLOCK_MONOTONIC)
  result = yield
  elapsed = (Process.clock_gettime(Process::CLOCK_MONOTONIC) - start) * 1000

  log_lookup(word, result: result, time: elapsed)
  result
end

.measure_suggestions(word) { ... } ⇒ Object

Measure and log suggestions.

Yields:

  • Block that generates suggestions

Returns:

  • (Object) —

    Block result



124
125
126
127
128
129
130
131
 
# File 'lib/kotoshu/debug_mode.rb', line 124

def measure_suggestions(word)
  start = Process.clock_gettime(Process::CLOCK_MONOTONIC)
  result = yield
  elapsed = (Process.clock_gettime(Process::CLOCK_MONOTONIC) - start) * 1000

  log_suggestions(word, suggestions: result, time: elapsed)
  result
end

.time(label) { ... } ⇒ Object

Start a timing context.

Yields:

  • Block to time

Returns:

  • (Object) —

    Block result



98
99
100
101
102
103
104
105
 
# File 'lib/kotoshu/debug_mode.rb', line 98

def time(label)
  start = Process.clock_gettime(Process::CLOCK_MONOTONIC)
  result = yield
  elapsed = (Process.clock_gettime(Process::CLOCK_MONOTONIC) - start) * 1000

  logger&.info("#{label}: #{elapsed.round(3)}ms")
  result
end