Changes between Initial Version and Version 1 of Trace

Timestamp:

05/04/10 14:23:52 (15 years ago)

Author:

hopscc

Comment:

--

Trace

@@ +1 @@
+= Trace = 
+
+Display an execution trace for  
+    * a point of execution or
+    * an expression or expressionlist or
+    * all args and locals in the current method 
+or enable or disable subsequent trace output.
+
+Tracing an expression or expressionlist is unlike a print of the same expression in that 
+   * The display format is different; 
+     trace generates expression-text = expression-value for each expression
+   * Position information (filename, line number, declaring class and method) of the trace line is printed
+   * Traces can be suppressed on a build by a cobra commandline argument
+        {{{ cobra -include-traces:no ...}}}
+
+traces are useful for debugging (displaying interim expression values) and 
+logging a point of execution( e.g. indicating that code in a code block is being executed).
+
+
+A simple '''trace'''' statement with no arguments gives just the position info
+of the trace statement - the filename, line number, declaring class name
+and declaring method name that the trace is located in. [[BR]]
+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.
+
+== Grammar ==
+{{{
+trace
+trace <expr1>, <expr2>, ... <expr3>
+trace all
+trace off
+trace on
+
+}}}
+
+
+== Examples ==
+
+{{{
+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: at Foo.cobra:7; in Foo.computeStuff
+trace: this=Foo; x=4; y=2; at Foo.cobra:10; in Foo.computeStuff
+trace: this=Foo; _z=8; at Foo.cobra:11; in Foo.computeStuff
+}}}
+
+== Notes ==
+
+Needs a way to display just the expression (suppress position info).
+
+See also [http://cobra-language.com/docs/manual/basic-statements/trace.html manual: trace statement documentation]