Class: SimpleTracer

Inherits:
Object
  • Object
show all
Defined in:
lib/SimpleTrace.rb

Overview

SimpleTrace is a very simple tracing facility that will output the file and line number and date/time when a trace came out.

It allows:

  • logging to a file or an io stream

  • filtering traces by the file that they are in or by the function that they are in

  • it can be turned on and off at run time

  • always accessible is a global $TRACE variable for tracing (you can choose to use it or not)

A simple example:

  • s = SimpleTracer.new

  • s.set_level 5

  • s.trace “hello” ==> outputs: [file.rb:3 ] [09-07-2005 06:43:00] hello

Instance Method Summary collapse

Constructor Details

#initialize ⇒ SimpleTracer

build a new tracer object



22
23
24
25
26
27
28
29
30
31
32
 
# File 'lib/SimpleTrace.rb', line 22

def initialize
	@trace_level = 0
	@width = 25
	@excluded_functions = []
	@excluded_files = []
	@output_to_screen_always = false
	@datetime_format_string = "%m-%d-%Y %H:%M:%S"
	@save_file = false
	@filename = nil
	@indent_level = 0
end

Instance Method Details

#debug(level, str) ⇒ Object

debug is the same as trace however with the level first. trace is usually called with the string only (default trace level 1)



120
121
122
 
# File 'lib/SimpleTrace.rb', line 120

def debug(level, str)
	trace(str, level)
end

#delete_log ⇒ Object

this deletes the log file if there is one and if the object was not directed to delete it



164
165
166
167
168
169
 
# File 'lib/SimpleTrace.rb', line 164

def delete_log
	if @save_file == false
		debug 5, "Delete the Log #{@filename}"
		File.delete(@filename) if @filename
	end
end

#exclude_files(filenames) ⇒ Object

excludes whole files from tracing output



211
212
213
 
# File 'lib/SimpleTrace.rb', line 211

def exclude_files(filenames)
	@excluded_files += filenames
end

#exclude_functions(functions) ⇒ Object

excludes particular functions from tracing output



204
205
206
 
# File 'lib/SimpleTrace.rb', line 204

def exclude_functions(functions)
	@excluded_functions += functions
end

#indent ⇒ Object

indents the level for tracing output. This is useful for recursive tracing. If a block is given then an outdent is done automatically at the end of the block



229
230
231
232
233
234
235
236
237
238
 
# File 'lib/SimpleTrace.rb', line 229

def indent
	@indent_level += 2
	if block_given? then
		begin
			yield self
		ensure 
			outdent
		end
	end
end

#outdent ⇒ Object

outdents the tracing. This should correspond to an earlier indent call



244
245
246
 
# File 'lib/SimpleTrace.rb', line 244

def outdent
	@indent_level -= 2
end

#save_log_on_exit(sav = true) ⇒ Object

This sets whether delete_log will actually delete the log file when called



156
157
158
 
# File 'lib/SimpleTrace.rb', line 156

def save_log_on_exit (sav = true)
	@save_file = sav
end

#set_date_time_format(datetime_format_string) ⇒ Object

sets the date and time format strings for trace output the format strings us strftime % vars and if they are both nil, then no date or time is put out at all.



220
221
222
 
# File 'lib/SimpleTrace.rb', line 220

def set_date_time_format(datetime_format_string)
	@datetime_format_string = datetime_format_string
end

#set_level(level) ⇒ Object

this sets the current level of tracing and can be called either with or without a block. Without a block it sets the level permanently with a block it sets the level for the duration of the block and then reverts to the last level.



130
131
132
133
134
135
136
137
138
139
140
141
142
 
# File 'lib/SimpleTrace.rb', line 130

def set_level(level)
	if block_given? then
		save_level = @trace_level
		begin
			@trace_level = level
			yield
		ensure
			@trace_level = save_level
		end
	else
		@trace_level = level
	end
end

#set_level_include(level, included_files) ⇒ Object

this simple sets the current trace level and sets included files



147
148
149
150
 
# File 'lib/SimpleTrace.rb', line 147

def set_level_include(level, included_files)
	@trace_level = level
	@included_files = included_files
end

#set_output_filename(filename) ⇒ Object

this sets the filename for the output log



174
175
176
177
178
179
180
181
182
183
 
# File 'lib/SimpleTrace.rb', line 174

def set_output_filename(filename)
	@filename = filename
	File.open(@filename, "w") {}
=begin
	@io = File.new(filename, "w")
	if !@io then
		raise "Can't open trace file '#{filename}'"
	end
=end
end

#set_output_io(io) ⇒ Object

this sets the io stream to output traces to. It is up to the caller to open (before tracing starts) and close (after tracing ends) this io stream.



189
190
191
 
# File 'lib/SimpleTrace.rb', line 189

def set_output_io(io)
	@io = io
end

#set_output_to_screen_always ⇒ Object

calling this allows traces to go to the screen always even if it is being logged to a file or an io stream



197
198
199
 
# File 'lib/SimpleTrace.rb', line 197

def set_output_to_screen_always
	@output_to_screen_always = true
end

#set_width(width) ⇒ Object

sets the width of the filename portion of the trace



37
38
39
 
# File 'lib/SimpleTrace.rb', line 37

def set_width(width)
	@width = width
end

#trace(str, level = 1) ⇒ Object

The actual tracing routine. The parameters are only a string and a trace level. If level is less than the current trace level then it is output



46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
 
# File 'lib/SimpleTrace.rb', line 46

def trace(str, level=1)
	#old_dollar_equal = $=
	#$= = false
	
	if @trace_level >= level then
		#puts "caller = '#{caller.inspect}'"
		m = /([\w_]+\.rb):(\d+)(:in `(.*)')?/.match(caller[0])
		#puts "m[1] = '#{m[1]}'"
		if m then
			line = m[2].to_i
			if /SimpleTrace\.rb$/.match(m[1]) then
				m = /([\w_]+\.rb):(\d+)(:in `(.*)')?/.match(caller[1])
				line = m[3].to_i
			end
			filename = m[1]
			if m[4] then
				function = m[5]
			else
			  	function = "$TOP_LEVEL$"
			end

#if $BOB then
#	print "@width = #{@width}, str = '#{str}', m[1] = '#{m[1]}', m[2] = '#{m[2]}'\n"
#end	
			if @datetime_format_string then
				t = Time.now.strftime(" [#{@datetime_format_string}] ")
			else
				t = " "
			end
			
			str = sprintf "[%-#{@width}s]%s%s", "#{m[1]}:#{m[2]}", t, str

			if @included_files then
				return unless @included_files.include?(filename)
			else
				if @excluded_functions.include?(function) then
					return
				end

				if @excluded_files.include?(filename) then
					return
				end
			end
		end				

		if @filename then
			File.open(@filename, "a") {|f| f.print str, "\n"}
		end
		
		if !@filename || @output_to_screen_always then				
			STDOUT.puts(str)
			STDOUT.flush
		end

		if @io then
			@io.print str, "\n"
			@io.flush
		end
=begin

		if !@io || @output_to_screen_always then				
			print str, "\n"
			$stdout.flush
		end
=end	
	end
ensure
	#$= = old_dollar_equal
end