trace      [`log | `err | `if | `on | `off]  '/'  <trace arguments>
trace       {Quote | {[@] Name [Subscript]  ['|' Format]}} , ...
trace`err  [{Quote | {[@] Name [Subscript]  ['|' Format]}} , ...]
trace`log  [ Path ]

trace`if    Condition  {Quote | {[@] Name [Subscript] ['|' Form]}} , ...
trace`on   [Condition]
trace`off  [Condition]

Traces are primarily used to print debugging information. They format and print variables and quoted text. Each Trace output line is preceded by the name of the module in which the Trace command was coded followed by "@", the line number, and a colon.

<method>@<line>:  <variable>=<value> ...

trace  "status", Name, x|'=#h#', x|d#, @x

output line:  my.method@42: status Name="X" X=#F0 X=240 @X=#c5fee0

You can direct output to either the Standard Error stream or to a log file. When tracing to a log file each trace command opens the file, appends the trace output, and then closes the file. This way trace output is not lost in the event of a program crash or hardware failure.

The variable may be a simple variable, a field, or a single array element. The output value will be preceeded by the name of the variable followed with an equal sign. Arguments use the same syntax as the Print command. A quoted argument is written as an unformatted literal string.

By placing an '@' sign before an argument the address of the item gets printed in decimal. If the item is a pointer then the value of the pointer is printed. Unless an integer format is specified the value is printed in hexadecimal ("#h#").

trace  @variable`field[ index ]

output line:  my.method@42:  @variable`field[3]=#c6fedc

When the argument is a pointer, but is coded without a leading '@' sign then the object it references is printed. If the pointer is set to a constant (@0 through @65535) then the value is printed in decimal with a leading '@' sign.

trace  variable`field, count

output line:  my.method@42:  @variable`field=@10 item=99

If the Trace verb is followed by a forward slash then the command is ignored as a comment. This way you can leave traces at key spots in the code and they will have no effect. Then while debugging select traces can be activated by removing the slash.

Tracing can be conditionally disabled or enabled. When your program starts traces are initially enabled. Without a condition the traces can be turned on and off. With a condition, when true then the trace command is executed.

It is a good idea to disable all traces at the start of a program that is to be released. Care should be taken to avoid tracing sensitive security information, even while debugging a program. This ensures that secrets are not unintentionally leaked.

Although traces generate output, they are excluded from the restriction on I/O commands within functions and pure methods. They are treated as if they are benign. They are also the only executable command that can be coded before a precondition.

trace  {Quote | {[@] Name [Subscript] ['|' Form]}} , ...

If tracing is enabled then format and write the arguments.

If there is an active log file append output to the log file;
   otherwise write to the Standard Error stream.


trace [`log | `err | `if | `on | `off] / <trace arguments>

A slash before the arguments causes the trace command to be ignored; no actions are taken.

The arguments are still validated by the compiler.


trace`log [Path]

The Path is a string expression.

If empty or no path is coded then subsequent traces are written to the Standard Error output.
   Tracing is neither enabled nor disabled.

Otherwise, begin logging traces to the file path argument and tracing is enabled.
   If another log file is currently active, going forward use the new log file instead.


trace`err [{Quote | {[@] Name [Subscript] ['|' Form]}} , ...]

Format and write any arguments to the Standard Error stream.

Enable subsequent Trace commands.

If a log file was active, going forward output goes to the Standard Error output.


trace`if Condition {Quote | {[@] Name [Subscript] ['|' Form]}} , ...

If tracing is enabled and the condition is met format and write the arguments.

If there is an active log file append output to the log file;
   else write it to the Standard Error stream.


trace`on [Condition]

If there is no condition or the condition is met then enable subsequent tracing. 


trace`off [Condition]

If there is no condition or the condition is met then disable all further tracing.