trace - Maple Programming Help

Online Help

All Products    Maple    MapleSim


Home : Support : Online Help : Programming : Debugging : trace

trace

trace procedures in order to debug them

untrace

turn off tracing

 

Calling Sequence

Parameters

Description

Examples

Compatibility

Calling Sequence

trace(f, options)

trace(f, g, h, ..., options)

untrace(f)

untrace(f, g, h, ...)

debug(f, options)

debug(f, g, h, ..., options)

undebug(f)

undebug(f, g, h, ...)

Parameters

f, g, h, ...

-

name(s) of procedure(s) to be traced

Description

• 

The trace function is a debugging tool for tracing the execution of the procedure(s) f, g, h, and so forth.

• 

A module may be given in place of a procedure name. If the module has a ModuleApply procedure, this procedure will be traced. Otherwise, all the exports of the module are traced. This process is recursive, so all exported procedures in all submodules are also traced.

• 

During execution, the entry points, the results of the statements that are executed (see below), and the exit points of the traced procedure(s) are printed. At entry points, all passed positional arguments (declared and undeclared) are displayed; note that default values are not displayed. At exit points, the returned function value is displayed.

• 

The amount of information displayed during tracing depends on whether the top-level expression being evaluated (some part of which is presumably being traced) was terminated with a colon or a semicolon. If terminated with a colon (":"), only entry and exit points of the traced procedure(s) are printed. If terminated with a semicolon (";"), the results of the statements that are executed are also printed.

• 

Each entry point is printed with a left brace ("{") at the beginning of the line, and each exit point is printed with a right brace ("}") at the end of the line. If you are viewing trace output with a text editor that has a delimiter-matching function, you can use this to jump back and forth between corresponding entry and exit points.

• 

When tracing recursive procedures, it is sometimes useful to only trace the top few calls to the procedure. The depth=integer option limits tracing to the specified number of nested calls of the function(s) being traced, where a depth of 1 signifies just the top-level call.

• 

The untrace function turns off the tracing of the specified procedures.

• 

The trace (untrace) function returns an expression sequence of the names of the procedures for which tracing was turned on (off).

• 

A special syntax, similar to that used for stopat and unstopat, may be used for tracing local procedures in modules. If a module m has a local variable g that is a procedure, then you can trace g by issuing the command trace( m::g ). Similarly, tracing of g can be turned off with the call untrace( m::g ). Note that, in this call, the expression g must be of type symbol and must be global in scope. (This special way of referring to locals of a module is recognized only when used with debugging related utilities. It is not a general syntax for referring to module locals.)

• 

Note that it is not possible to trace any function which has special evaluation rules, namely any of: assigned, eval, evalhf, evalf, evaln, seq, userinfo. However, when tracing a procedure that calls evalf, any traceable code that is executed by evalf is traced.

• 

The trace function will silently ignore any argument which is not the name of a traceable procedure. In particular, it is possible to invoke trace(anames()) to cause tracing of all procedures which correspond to currently-assigned names even though many of the names in anames() may not be assigned procedures.

• 

The names debug and undebug are alternate names for trace and untrace.

• 

The display of assignments during tracing can be controlled by three kernelopts options, traceincidentalassign, tracesplitmulassign, and traceshowspecassign.

  

By default, assignments that occur as side-effects of calls to Maple built-in functions, such as assign or the three-argument form of member, are shown during tracing. Setting kernelopts(traceincidentalassign=false) will suppress the display of such incidental assignments.

  

Setting kernelopts(tracesplitmulassign=true) will cause multiple assignments (for example, a,b := c,d;) to be displayed individually. For multiple assignments of many variables, or with complicated right-hand sides, this is often easier to read.

  

Setting kernelopts(traceshowspecassign=true) causes some assignments to display in a distinctive way:

• 

Operator assignments that don't actually take place (for example, the second assignment in a := false; a and= b;) will be displayed using the symbol &:= instead of :=.

• 

Some assignments do not actually assign to the variable on the left-hand side of the assignment statement, but instead assign into the value that the variable currently has. For example, if the value of A is an Array, then the assignment A[2] := x; or the operator assignment A ,= y assign into the Array, but A itself is not changed (that is, A continues to refer to the same, now modified, Array or table). Such assignments are then displayed using the symbol &[]= instead of :=.

• 

Except as described otherwise below, operator assignments such as x += y; are displayed as x := finalValue, where finalValue refers to the value that was assigned to x (x + y in this case).

Examples

f := proc(x) local y; y := x * 2; g(x) / 4; end proc;

f:=procxlocaly;y:=2*x;1/4*gxend proc

(1)

g := proc(x) local z; z := x^2; z * 2; end proc;

g:=procxlocalz;z:=x^2;2*zend proc

(2)

tracef,g

f,g

(3)

f3

{--> enter f, args = 3
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                y := 6

{--> enter g, args = 3
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                z := 9

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  18

<-- exit g (now in f) = 18}
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  9/2

<-- exit f (now in `mpldoc/process_example`) = 9/2}

92

(4)

f3&colon;

{--> enter f, args = 3
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                y := 6

{--> enter g, args = 3
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                z := 9

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  18

<-- exit g (now in f) = 18}
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  9/2

<-- exit f (now in `mpldoc/process_example`) = 9/2}

m := module()
  export f;
  local g;
  g := proc( x )
    local y;
    y := 2 * x;
    y
  end proc;
  f := x -> g( x / 3 );
end module:

tracem::g

g

(5)

m:-f2

{--> enter g, args = 2/3
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               y := 4/3

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  4/3

<-- exit g (now in f) = 4/3}

43

(6)

untracem::g

g

(7)

m:-fs

2s3

(8)

Compatibility

• 

The depth option was introduced in Maple 2017.

• 

For more information on Maple 2017 changes, see Updates in Maple 2017.

See Also

assigned

debugger

eval

evalf

evalhf

evaln

LinearAlgebra[Trace]

module

module[export]

module[local]

seq

Trace

tracelast

userinfo