= 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 ==

{{{
#!cobra
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]