Class: Vedeu::Trace

Inherits:
Object
  • Object
show all
Defined in:
lib/vedeu/support/trace.rb

Overview

:nocov: This class currently provides the means to trace each method call which occurs inside Vedeu. This is very useful (to me!) for debugging. Running this will make your application less responsive, and the tests excruciatingly slow to run.

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(options = {}) ⇒ Trace

Returns a new instance of Vedeu::Trace

Parameters:

  • options (Hash) (defaults to: {}) 


36
37
38
 
# File 'lib/vedeu/support/trace.rb', line 36

def initialize(options = {})
  @options = options
end

Class Method Details

.call(options = {}) ⇒ void

This method returns an undefined value.

Parameters:

  • options (Hash) (defaults to: {})
  • option (Hash) —

    a customizable set of options



28
29
30
 
# File 'lib/vedeu/support/trace.rb', line 28

def self.call(options = {})
  new(options).trace
end

Instance Method Details

#classes ⇒ Set (private)

Returns the classes to be traced, without exceptions or ignored classes.

Returns:

  • (Set) 


146
147
148
 
# File 'lib/vedeu/support/trace.rb', line 146

def classes
  @classes ||= vedeu_classes - vedeu_exceptions - ignored_classes
end

#colour(klass, output) ⇒ Hash (private)

Returns:

  • (Hash) 


125
126
127
128
129
130
131
132
133
134
 
# File 'lib/vedeu/support/trace.rb', line 125

def colour(klass, output)
  {
    'Array'    => :yellow,
    'Fixnum'   => :cyan,
    'Hash'     => :blue,
    'NilClass' => :red,
    'String'   => :green,
    'Symbol'   => :magenta,
  }.fetch(klass, :white) { |colour| Vedeu::Esc.send(colour) { output } }
end

#count ⇒ String (private)

Returns the number of Vedeu classes/modules. (Useful for debugging.)

Returns:

  • (String) 


139
140
141
 
# File 'lib/vedeu/support/trace.rb', line 139

def count
  @count ||= "(#{classes.size}/#{vedeu_classes.size})"
end

#defaults ⇒ Hash (private)

The default values for a new instance of this class.

Returns:

  • (Hash) 


117
118
119
120
121
122
 
# File 'lib/vedeu/support/trace.rb', line 117

def defaults
  {
    trace: Vedeu::Configuration.trace?,
    event: 'call',
  }
end

#ignored_classes ⇒ Set (private)

TODO:

Make this configurable at runtime.

Returns a set of classes to ignore during tracing.

Returns:

  • (Set) 


173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
 
# File 'lib/vedeu/support/trace.rb', line 173

def ignored_classes
  Set.new [
    'Vedeu::Coercions',
    'Vedeu::Colour',
    'Vedeu::Common',
    'Vedeu::Configuration',
    'Vedeu::Esc',
    'Vedeu::Event',
    'Vedeu::Geometry',
    'Vedeu::Log',
    'Vedeu::Position',
    'Vedeu::Presentation',
    'Vedeu::Repository',
    'Vedeu::Stream',
    'Vedeu::Style',
    'Vedeu::Terminal',
    'Vedeu::Trace',
    'Vedeu::Translator',
  ]
end

#log_this(message) ⇒ String (private)

Writes the message to the log file.

Parameters:

  • message (String)

Returns:

  • (String) 


75
76
77
78
79
 
# File 'lib/vedeu/support/trace.rb', line 75

def log_this(message)
  Vedeu::Log.logger.debug(message)

  message
end

#options ⇒ Hash (private)

Returns:

  • (Hash) 


110
111
112
 
# File 'lib/vedeu/support/trace.rb', line 110

def options
  defaults.merge!(@options)
end

#trace ⇒ NilClass|String

TODO:

Deprecate, and use TracePoint instead.

Note:

Arguments to set_trace_func proc:

|event, file, line, id, binding, name|

Performs the trace operation. Building strings which include:

  • (class_count) a count of classes registered with Vedeu,

  • (classname) the class name being traced,

  • (id) the method name being traced,

  • (vars) any local variables belonging to the method.

Returns:

  • (NilClass|String) 


53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
 
# File 'lib/vedeu/support/trace.rb', line 53

def trace
  set_trace_func proc { |event, _, _, id, binding, name|
    if event == watched && id != :log && classes.include?(name.to_s)
      vars = variables(binding)

      if vars.empty?
        log_this(format('%s %-25s #%-20s', count, name, id))

      else
        log_this(format("%s %-25s #%-20s\n%s\n", count, name, id, vars))

      end
    end
  } if trace?
end

#trace? ⇒ Boolean (private)

Returns:

  • (Boolean) 


105
106
107
 
# File 'lib/vedeu/support/trace.rb', line 105

def trace?
  options[:trace]
end

#variables(binding) ⇒ String (private)

Provides inspection of the local variables set within the method being traced. Makes the log file extremely noisy, but very useful for hunting down bugs.

Parameters:

  • binding (Class)

Returns:

  • (String) 


87
88
89
90
91
92
93
94
95
96
97
 
# File 'lib/vedeu/support/trace.rb', line 87

def variables(binding)
  binding.eval('local_variables').each do |var|
    variable = Vedeu::Esc.green { var.to_s }
    value    = binding.local_variable_get(var)
    klass    = Vedeu::Esc.magenta { value.class.to_s }
    output   = (value.is_a?(Proc)) ? '#<Proc:...' : value.inspect
    content  = colour(value.class.to_s, output)

    format('%33s %-10s = %s %s', ' ', variable, klass, content)
  end.join("\n")
end

#vedeu_classes ⇒ Set (private)

Returns all the classes defined within Vedeu.

Returns:

  • (Set) 


153
154
155
156
157
 
# File 'lib/vedeu/support/trace.rb', line 153

def vedeu_classes
  @vedeu_classes ||= Vedeu.constants.collect do |c|
    Vedeu.const_get(c).to_s
  end.to_set
end

#vedeu_exceptions ⇒ Set (private)

TODO:

Vedeu should produce this set.

Returns all the exceptions defined within Vedeu.

Returns:

  • (Set) 


164
165
166
 
# File 'lib/vedeu/support/trace.rb', line 164

def vedeu_exceptions
  Vedeu::EXCEPTIONS.to_set
end

#watched ⇒ String (private)

Returns:

  • (String) 


100
101
102
 
# File 'lib/vedeu/support/trace.rb', line 100

def watched
  options[:event]
end