SimpleTrace 0.0.1

data/LICENSE

@@ -0,0 +1 @@
+This is released under the same terms as the Ruby license.

data/README

@@ -0,0 +1,4 @@
+This is a simple tracing library that is useful for debugging and light logging needs. See Sample1.rb for most common uses or consult RDOC.
+
+Steve Tuckner
+9/7/2005

data/lib/SimpleTrace.rb

@@ -0,0 +1,253 @@
+#
+# 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
+#
+class SimpleTracer
+	#
+	# build a new tracer object
+	#
+	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
+
+	#
+	# sets the width of the filename portion of the trace
+	#
+	def set_width(width)
+		@width = width
+	end
+
+	#
+	# 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
+	#
+	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
+
+	#
+	# debug is the same as trace however with the level first. trace is
+	# usually called with the string only (default trace level 1)
+	#
+	def debug(level, str)
+		trace(str, level)
+	end
+
+	#
+	# 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.
+	#
+	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
+
+	#
+	# this simple sets the current trace level and sets included files
+	#
+	def set_level_include(level, included_files)
+		@trace_level = level
+		@included_files = included_files
+	end
+
+	#
+	# This sets whether delete_log will actually delete the
+	# log file when called
+	#
+	def save_log_on_exit (sav = true)
+		@save_file = sav
+	end
+
+	#
+	# this deletes the log file if there is one and if the
+	# object was not directed to delete it
+	#
+	def delete_log
+		if @save_file == false
+			debug 5, "Delete the Log #{@filename}"
+			File.delete(@filename) if @filename
+		end
+	end
+
+	#
+	# this sets the filename for the output log
+	#
+	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
+
+	#
+	# 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.
+	#
+	def set_output_io(io)
+		@io = io
+	end
+
+	#
+	# calling this allows traces to go to the screen always even if it
+	# is being logged to a file or an io stream
+	#
+	def set_output_to_screen_always
+		@output_to_screen_always = true
+	end
+
+	#
+	# excludes particular functions from tracing output
+	#
+	def exclude_functions(functions)
+		@excluded_functions += functions
+	end
+
+	#
+	# excludes whole files from tracing output
+	#
+	def exclude_files(filenames)
+		@excluded_files += filenames
+	end
+
+	#
+	# 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.
+	#
+	def set_date_time_format(datetime_format_string)
+		@datetime_format_string = datetime_format_string
+	end
+
+	#
+	# 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
+	#
+	def indent
+		@indent_level += 2
+		if block_given? then
+			begin
+				yield self
+			ensure 
+				outdent
+			end
+		end
+	end
+
+	#
+	# outdents the tracing. This should correspond to an earlier
+	# indent call
+	#
+	def outdent
+		@indent_level -= 2
+	end
+end
+
+# define the $TRACE variable if not already defined
+if !$TRACE then
+	$TRACE = SimpleTracer.new
+end
+

data/samples/Sample1.rb

@@ -0,0 +1,65 @@
+
+require "SimpleTrace"
+
+#
+# This example of the simplest trace
+#
+
+s = SimpleTracer.new
+
+s.set_level 1				# tracing is off by default
+s.trace "hello world"
+
+#
+# This illustrates the different levels of trace
+#
+
+s.set_level 5
+s.debug 1, "this is a high level trace so it comes out"
+s.debug 5, "this is a mid level trace and it is at the trace level so it comes out"
+s.debug 9, "this is a low level trace and so this doesn't come out"
+
+
+#
+# This illustrates how the level can be set just for a block. This is useful when
+# running unit tests so that the level is set only for that failing test
+#
+s.debug 9, "this doesn't come out"
+s.set_level 9 do
+	s.debug 9, "but this does"
+end
+s.debug 9, "and this doesn't"
+
+#
+# This illustrates how the trace output can go to a file, or io stream and also
+# to the screen if that is wanted
+#
+s.set_output_filename("log.txt")
+s.debug 5, "this goes in the file"
+puts "Below is what went in the file"
+puts File.readlines("log.txt").join("\n")
+puts "Above is what went in the file"
+f = File.open("log.txt", "w")
+
+s.set_output_io(f)
+s.debug 5, "this goes to an io (which is a file)"
+f.close
+puts "Below is what went in the file from IO"
+puts File.readlines("log.txt").join("\n")
+puts "Above is what went in the file from IO"
+s.set_output_io(nil)
+
+s.set_output_filename("log.txt")
+s.set_output_to_screen_always
+s.debug 5, "this will be on the screen first, then in the file"
+puts "Below is what went in the file plus from IO"
+puts File.readlines("log.txt").join("\n")
+puts "Above is what went in the file plus from IO"
+
+#
+# You can change or elimate the date and time stamp
+#
+s.set_date_time_format("%M:%S")
+s.trace "Here is just a minutes and seconds trace"
+s.set_date_time_format(nil)
+s.trace "Here is one with no date or time stamp at all"

metadata

@@ -0,0 +1,39 @@
+--- !ruby/object:Gem::Specification 
+rubygems_version: 0.8.3
+specification_version: 1
+name: SimpleTrace
+version: !ruby/object:Gem::Version 
+  version: 0.0.1
+date: 2005-09-13
+summary: This module implements a simple tracing/logging scheme
+require_paths: 
+  - lib
+email: 
+homepage: 
+rubyforge_project: 
+description: 
+autorequire: SimpleTrace
+default_executable: 
+bindir: bin
+has_rdoc: false
+required_ruby_version: !ruby/object:Gem::Version::Requirement 
+  requirements: 
+    - 
+      - ">"
+      - !ruby/object:Gem::Version 
+        version: 0.0.0
+  version: 
+platform: ruby
+authors: []
+files: 
+  - "./LICENSE"
+  - "./README"
+  - lib/SimpleTrace.rb
+  - samples/Sample1.rb
+test_files: []
+rdoc_options: []
+extra_rdoc_files: []
+executables: []
+extensions: []
+requirements: []
+dependencies: []