Class: Vedeu::Trace

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

Overview

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

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



30
31
32
 
# File 'lib/vedeu/support/trace.rb', line 30

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

Instance Method Details

#class_colour ⇒ Hash (private)

Returns:

  • (Hash) 


129
130
131
132
133
134
135
136
137
138
 
# File 'lib/vedeu/support/trace.rb', line 129

def class_colour
  {
    'Array'    => :yellow,
    'Fixnum'   => :cyan,
    'Hash'     => :blue,
    'NilClass' => :red,
    'String'   => :green,
    'Symbol'   => :magenta,
  }
end

#class_count ⇒ String (private)

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

Returns:

  • (String) 


143
144
145
 
# File 'lib/vedeu/support/trace.rb', line 143

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

#classes ⇒ Set (private)

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

Returns:

  • (Set) 


150
151
152
 
# File 'lib/vedeu/support/trace.rb', line 150

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

#defaults ⇒ Hash (private)

The default values for a new instance of this class.

Returns:

  • (Hash) 


121
122
123
124
125
126
 
# File 'lib/vedeu/support/trace.rb', line 121

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) 


177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
 
# File 'lib/vedeu/support/trace.rb', line 177

def ignored_classes
  Set.new [
    # 'Vedeu::API',
    # 'Vedeu::Application',
    # 'Vedeu::Background',
    # 'Vedeu::Bindings',
    # 'Vedeu::Border',
    # 'Vedeu::BoundingArea',
    # 'Vedeu::Buffer',
    # 'Vedeu::Char',
    # 'Vedeu::Chars',
    'Vedeu::Coercions',
    'Vedeu::Colour',
    'Vedeu::Common',
    # 'Vedeu::Composition',
    # 'Vedeu::Compositor',
    # 'Vedeu::Config::API',
    # 'Vedeu::Config::CLI',
    'Vedeu::Configuration',
    # 'Vedeu::Console',
    # 'Vedeu::ContentGeometry',
    # 'Vedeu::Coordinate',
    # 'Vedeu::Cursor',
    # 'Vedeu::DisplayBuffer',
    # 'Vedeu::DSL::Border',
    # 'Vedeu::DSL::Colour',
    # 'Vedeu::DSL::Composition',
    # 'Vedeu::DSL::Geometry',
    # 'Vedeu::DSL::Interface',
    # 'Vedeu::DSL::Keymap',
    # 'Vedeu::DSL::Line',
    # 'Vedeu::DSL::Menu',
    # 'Vedeu::DSL::Stream',
    # 'Vedeu::DSL::Style',
    # 'Vedeu::DSL::Text',
    # 'Vedeu::DSL::Use',
    # 'Vedeu::DSL::View',
    'Vedeu::Esc',
    'Vedeu::Event',
    # 'Vedeu::Focus',
    # 'Vedeu::Foreground',
    'Vedeu::Geometry',
    # 'Vedeu::Grid',
    # 'Vedeu::Group',
    # 'Vedeu::Input',
    # 'Vedeu::Interface',
    # 'Vedeu::Interfaces',
    # 'Vedeu::Keymap',
    # 'Vedeu::Keys',
    # 'Vedeu::Key',
    # 'Vedeu::Launcher',
    # 'Vedeu::Line',
    # 'Vedeu::Lines',
    'Vedeu::Log',
    # 'Vedeu::Mapper',
    # 'Vedeu::Menu',
    # 'Vedeu::Menus',
    # 'Vedeu::Model',
    # 'Vedeu::Model::Collection',
    # 'Vedeu::MoveCursor',
    # 'Vedeu::Node',
    # 'Vedeu::Output',
    'Vedeu::Position',
    # 'Vedeu::PositionValidator',
    'Vedeu::Presentation',
    # 'Vedeu::Read',
    # 'Vedeu::Refresh',
    # 'Vedeu::Render',
    'Vedeu::Repository',
    # 'Vedeu::Sentence',
    'Vedeu::Stream',
    # 'Vedeu::Streams',
    'Vedeu::Style',
    'Vedeu::Terminal',
    # 'Vedeu::Text',
    # 'Vedeu::ToggleCursor',
    'Vedeu::Trace',
    'Vedeu::Translator',
    # 'Vedeu::Traps',
    # 'Vedeu::Trigger',
    # 'Vedeu::View',
    # 'Vedeu::Viewport',
    # 'Vedeu::Visible',
    # 'Vedeu::Write',
    # 'Vedeu::Writer',
  ]
end

#log_this(message) ⇒ String (private)

Writes the message to the log file.

Parameters:

  • message (String)

Returns:

  • (String) 


73
74
75
76
77
 
# File 'lib/vedeu/support/trace.rb', line 73

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

  message
end

#options ⇒ Hash (private)

Returns:

  • (Hash) 


114
115
116
 
# File 'lib/vedeu/support/trace.rb', line 114

def options
  defaults.merge!(@options)
end

#trace ⇒ NilClass|String

TODO:

Deprecate, and use TracePoint instead.

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) 


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

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

      if vars.empty?
        log_this(sprintf("%s %-25s #%-20s",
          class_count, classname, id))

      else
        log_this(sprintf("%s %-25s #%-20s\n%s\n",
          class_count, classname, id, vars))

      end
    end
  } if trace?
end

#trace? ⇒ Boolean (private)

Returns:

  • (Boolean) 


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

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) 


85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
 
# File 'lib/vedeu/support/trace.rb', line 85

def variables(binding)
  entries = []
  binding.eval('local_variables').each do |var|
    variable = var.to_s
    value    = binding.local_variable_get(var)
    valclass = value.class.to_s
    output   = (value.is_a?(Proc)) ? '#<Proc:...' : value.inspect

    content  = Esc.send(class_colour.fetch(valclass, :white)) { output }

    entries << sprintf("%33s %-10s = %s %s", " ",
                                             Esc.green { variable },
                                             Esc.magenta { valclass },
                                             content)
  end
  entries.join("\n")
end

#vedeu_classes ⇒ Set (private)

Returns all the classes defined within Vedeu.

Returns:

  • (Set) 


157
158
159
160
161
 
# File 'lib/vedeu/support/trace.rb', line 157

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) 


168
169
170
 
# File 'lib/vedeu/support/trace.rb', line 168

def vedeu_exceptions
  Vedeu::Exceptions.to_set
end

#watched ⇒ String (private)

Returns:

  • (String) 


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

def watched
  options[:event]
end