Changes between Version 3 and Version 4 of TraceStatement

Timestamp:

12/20/10 02:31:33 (14 years ago)

Author:

todd.a

Comment:

--

TraceStatement

@@ -1 @@
-The '''assert''' statement is used to verify an expected condition during runtime.
+The '''trace''' statement is a debugging aid to log points of execution in the source code and/or values of expressions.
 
 === Grammar ===
 {{{
-assert <condition>[, <info>]
+trace
+trace <expr1>, <expr2>, ... <expr3>
+trace all
+trace off
+trace on
 }}}
 
-If the condition is true, execution proceeds. Otherwise, an '''AssertException''' is raised. Assertions can be turned off at runtime with:
+A simple '''trace''' gives the filename, line number, declaring class name and declaring method name that the '''trace''' is located in. If the current object's class is a subclass of the declaring class then the subclass name is reported as well.
+
+When given one or more expressions, '''trace''' gives the same information plus the source code and value of each expression.
+
+The '''trace all''' statement is a convenience for logging '''this''', every method argument and every local variable.
+
+The '''trace off''' statement turns off the subsequent trace statements in the declaring method. The '''trace on''' statement turns them back on.
+
+Sprinkling '''trace''' statements in methods can help diagnose bugs by showing program flow and values during execution, as seen here:
+
 {{{
 #!cobra
-CobraCore.willCheckAssert = false
+class Foo 
+
+    var _z as int 
+
+    def computeStuff(x as int, y as int)
+        if x > y
+            trace return 
+        _z = x * y 
+        trace all 
+        trace _z 
+}}}
+{{{
+trace: this=Foo; x=2; y=4; at Foo.cobra:10; in Foo.computeStuff
+trace: this=Foo; _z=8; at Foo.cobra:11; in Foo.computeStuff
 }}}
 
-Assertions are useful for catching errors early when they are easier to diagnose. They also enable subsequent code to operate under the condition expressed by the assertion. Furthermore, they are source of technical documentation.
-
-The message of the '''!AssertException''' includes information to assist in debugging the assertion including:
-
- * the filename and line number where the assert statement appeared
- * the info argument, if provided
- * a full breakdown of the condition's subexpressions and their values
-
-The breakdown of the condition is significant because it not only aids troubleshooting, but largely eliminates the need to specify the '''info''' argument. For example, rather than:
+An alternative to a trace would be a print statement:
 {{{
 #!cobra
-assert obj.foo > bar, 'obj=[obj], obj.foo=[obj.foo], bar=[bar]'
+...
+print 'trace: x=[x]; y=[y]' 
 }}}
 
-This is sufficient:
+But that won't report source information such as line number, and writing such a print statement is more work than:
+
 {{{
 #!cobra
-assert obj.foo > bar
+trace x,y
 }}}
 
-...because if the assertion fails, the values of '''obj''', '''obj.foo''' and '''bar''' will be given in the exception's '''message'''. Note that reporting the subexpression values causes the subexpressions to execute a second time, so the reported values can be misleading due to side-effects. In practice, this is rare.
+Also, '''trace''' statements are easy to locate and remove—or turn off via '''trace off'''—while leaving application '''print''' statements in tact. And '''trace''' output is flushed with each trace, by default.
 
-Developers often disable assertions in production software, presumably for a speed boost. But in practice, the overhead of assert statements is often so small as to not be noticeable. Since assertions offer the benefit of easier failure analysis, they should generally be left on. At the same time, providing a switch to turn them off can be prudent because the assertions themselves can be buggy (meaning the assertion fails, but does indicate an actual problem with the program because the condition was poorly formulated).
+Note that the '''trace''' statement is backed by a supporting class called '''Tracer''':
 
-Strongly consider using '''require''' instead of '''assert''' when verifying the state of the object at the very beginning of a method or property, or verifying the state of the parameters. 
-Strongly consider using '''ensure''' instead of '''assert''' when verifying the state of the object at the very ending of a method or property, or verifying the state of the return value.
 {{{
 #!cobra
-# Example 1 
-assert x > y 
+class Tracer 
+    inherits Object
+    """ 
+    Used to implement the trace statement. 
+    """ 
 
-# Example 2 
-assert node # as in, the node is not nil 
+    cue init 
+        """ 
+        Initializes the tracer with Console.out as the destination. 
+        """ 
 
-# Example 3 
-assert customers.count # as in, the count is not zero 
+    cue init(dest as System.IO.TextWriter) 
 
-# Example 4 
-assert name.length 
+    pro isActive as bool 
+        """ 
+        When false, the `trace` methods will produce no output. 
+        """ 
+
+    pro willAutoFlush as bool 
+        """ 
+        When true, `destination.flush` is invoked after every trace. 
+        Defaults to `true`. 
+        """ 
+
+    pro destination as String 
+        """ 
+        The TextWriter where all trace output is sent to. 
+        """ 
+
+    pro separator as String 
+        """ 
+        The separator string used between items of both name/value pairs and source information. 
+        Default is '; '. 
+        """ 
+
+    pro prefix as String 
+        """ 
+        The prefix string used at the beginning of every trace. 
+        Default is 'trace: '. 
+        """ 
+
+    def trace(source as SourceInfo) 
+
+    def trace(source as SourceInfo, nameValues as vari Object)
+        require nameValues.length % 2 == 0 
 }}}
+
+You can get access to the current tracer with the shared property, '''CobraCore.tracer'''. In fact, you can use that same property to set the Tracer instance that the trace statements use, although modifying the default instance is normally sufficient. For example:
+
+{{{
+#!cobra
+    class Program 
+        def main is shared
+        tracer = CobraCore.tracer 
+        tracer.prefix = '' 
+        tracer.separator = ', ' 
+        tracer.destination = File.createText('trace.text') 
+}}}
+
+Don't confuse '''trace on/off''' with '''Tracer.isActive'''. The '''trace on/off''' statements are purely compile-time directives that affect only the method that contains them. The '''Trace.isActive''' property is purely a run-time property and will deactive the output of all trace statements when set to '''false'''.