prog::tcov

Report on test coverage (passed program lines)

Use only in the MuPAD Notebook Interface.

This functionality does not run in MATLAB.

Syntax

prog::tcov(Reset)
prog::tcov(<stmt>, Write = fname)
prog::tcov(Append = fname)
prog::tcov(<stmt>, Info, <Summary>, <Lines>, <Hidden>, <Unused>, <All>)
prog::tcov(<stmt>, Annotate, <Path = pname>, <Comment = comment>)
prog::tcov(<stmt>, Export = fname, <Annotate>, <Path = pname>, <Comment = comment>, <Graphical>)

Description

prog::tcov inspects the data on the statements executed in library code. MuPAD® collects these data if you start the MuPAD engine with the option -t. To set different options for starting the MuPAD engine, use the Arguments field in the Engine dialog.

You can use prog::tcov in two different modes:

  • With a given first argument stmt, prog::tcov resets all tcov information, evaluates the statement, and shows all debug node passes for this statement during the evaluation. prog::tcov(stmt) clears all information about the debug node passes of current session.

  • Without the first argument stmt, prog::tcov shows the debug node pass information collected by the MuPAD engine during the whole session.

You can display the logged debug node passes on the screen or export the data to an HTML file. You also can save the data about the debug node passes to a file, which enables you to read or recover a whole session state later.

prog::tcov can produce annotated source files containing the information collected by prog::tcov and the MuPAD source code.

Environment Interactions

prog::tcov can produce screen outputs.

If you use the Annotate option, prog::tcov creates new files. For some operating systems creating new files might require special permissions.

Examples

Example 1

To use prog::tcov, start the kernel in tcov mode with option -t.

The outputs in the following examples are cropped in this documentation.

The following example shows a short procedure created and called inside prog::tcov. The line numbers correspond to the ones in the Debugger:

f:=                  // 1
proc(a, b)           // 2
begin                // 3
  if a > b then      // 4
    return(a)        // 5
  else               // 6
    return(f(b, a))  // 7
  end_if             // 8
end_proc:            // 9

prog::tcov returns all the lines passed during the evaluation of f:

prog::tcov(f(2, 1), Info, Lines)
   File: /tmp/debug0.5932  Use index: 50% 
     Nodes: 2/4 (0 hidden)   Passes: 2          Line       4,0:  
  1 pass          Line       5,0:     1 pass 
prog::tcov(f(1, 2), Info, Lines)
   File: /tmp/debug0.5932  Use index: 75%       Nodes:
3/4 (0 hidden)   Passes: 4          Line       4,0:     2 passes 
        Line       5,0:     1 pass          Line       7,0:     1
pass 

Example 2

The following example shows the logging of passes during a session. Before running this example, define the function f from Example 1.

If you start the kernel with the option -v, the expose command shows the debug nodes with pass information.

prog::tcov(Reset) resets all tcov information:

prog::tcov(Reset):
prog::tcov(Info)
SUMMARY   Files 
   : 1 in 1 libraries   Nodes     : 0/4 (0 hidden)   Use index : 0%
  Passes    : 0 (~  0.00 passes per all nodes) 

If you call the function f twice, the number of passes doubles:

f(1, 2): f(1, 4): prog::tcov(Info)
   File: /tmp/debug0.5932  Use index: 75% 
     Nodes: 3/4 (0 hidden)   Passes: 8          Line       4,0:  
  4 passes          Line       5,0:     2 passes          Line   
   7,0:     2 passes 

To see the passes, expose the function f:

expose(f)
 
proc(a, b)     name f;   begin     // /tmp/debug0.5932:4,0 [4 passes];
    if b < a then       // /tmp/debug0.5932:5,0 [2 passes];   
   return(a)     else       // /tmp/debug0.5932:7,0 [2 passes];  
    return(f(b, a))     end_if;     // /tmp/debug0.5932:9,0 [0 passes]
  end_proc 

You can write the tcov data to a data file:

prog::tcov(Write = "tcov_example.dat"):

To delete the information about the previous passes, use the Reset option:

prog::tcov(Reset):
prog::tcov(Info)
SUMMARY   Files 
   : 1 in 1 libraries   Nodes     : 0/4 (0 hidden)   Use index : 0%
  Passes    : 0 (~  0.00 passes per all nodes) 

To retrieve the former state, use the Append option:

prog::tcov(Append = "tcov_example.dat"):
prog::tcov(Info, Summary)
SUMMARY
  Files     : 1 in 1 libraries   Nodes     : 3/4 (0 hidden)   Use
index : 75%   Passes    : 8 (~  2.00 passes per all nodes) 

Also, you can use the Append option to add the passes:

prog::tcov(Append = "tcov_example.dat"):
prog::tcov(Info, Summary)
SUMMARY
  Files     : 1 in 1 libraries   Nodes     : 3/4 (0 hidden)   Use
index : 75%   Passes    : 16 (~  4.00 passes per all nodes) 

Example 3

The following example presents incomplete pieces of code. Note that you cannot execute this example without additional code lines.

Suppose, you have a source file with the following function:

 1:  f := proc(a, b)
 2:       begin
 3:         if a > b then
 4:           return(a)
 5:         elif a = b then return(0)
 6:         else
 7:           f(b, a)
 8:         end_if
 9:       end_proc:

Before executing this source file, read the commands. After reading commands, all the objects defined in the source file are available in the notebook. Calling the function f several times and creating the annotated source file, you get:

ff(2, 1): // passing lines 3 and 4
f(1, 1): // passing lines 3 and 5 twice
         // because line 5 has two debug nodes
f(1, 2): // passing lines 3, 5, and 7 and 
         // recursively 3 and 4, leave via line 9
         // because the statement in line 7 has no return
prog::tcov(Annotate)

The annotated source file uses the same path as the source file and looks like this:

// Generated by prog::tcov session

 1:  f := proc(a, b)
 2:       begin
 3:4         if a > b then
 4:2           return(a)
 5:2         elif a = b then return(
 5:1                                0)
 6:          else
 7:1           f(b, a)
 8:          end_if
 9:1       end_proc:

Note that the line 5 contains two debug nodes and appears in two lines. The line splits where the second debug node starts.

For better readability of the annotated source files, use the HTML export.

Parameters

stmt

Any MuPAD statement or MuPAD expression

fname

A file name given as a string

pname

A directory name given as a string

comment

Any string

Options

Reset

Reset the number of passes at each debug node to 0.

Write

Option, specified as Write = fname

This option allows you to write the information about all debug node passes of the current session to the file fname. You can use this file for external analysis (see the Algorithms section) or to recover or merge the information collected by prog::tcov (see the Append option).

Append

Option, specified as Append = fname

Append all information about debug node passes from the file fname to the current session.

This option allows you to merge the data generated during several sessions.

Info

Display the information about debug node passes.

Summary

Display only a short summary.

Lines

Display each pass through a debug node.

Unused

Display all code lines with debug nodes, including unpassed ones.

Hidden

This option allows you to display the hidden debug nodes. A hidden debug node is a node in a procedure with the noDebug option.

All

Display unpassed and hidden debug nodes.

Export

Option, specified as Export = fname

This option allows you to display the debug node passes information in summary for all read source files and for all individual source files.

The information is ordered according to the names of the directories containing the source files. Directory names can be folded.

You can see the list of all the files of a library below each library name.

Each file name presents a link that points to the annotated source file.

You can select graphical indices. Each point leads to the related line in the annotated source file.

Annotate

This option allows you to rewrite each executed MuPAD source file filename.mu as filename.tcov with an annotation at the beginning of each line. The annotation contains the line number of a debug node and the number of passes of this line, followed by the source code.

In text mode the line containing several debug nodes splits so that each line contains one debug node (see Example 3).

The new files have the extension '.tcov' instead of '.mu'. See also option Path.

If this option is used together with Export, prog::tcov creates the annotated source files as HTML files with the extension .tcov.html. The line colors depend on the passes.

Path

Option, specified as Path = pname

This option allows you to specify a path pname to the annotated source files and the exported status file. If you do not specify the path, prog::tcov creates the files in the same directory where the source files are.

Comment

Option, specified as Comment = comment

This option allows you to write the string comment on the first line of each annotated source file (see the option Annotate) or in the header of an exported HTML file (see the option Export).

Graphical

Show a graphical index for each source file in an HTML export file.

Return Values

prog::tcov returns the void object null() of type DOM_NULL.

Algorithms

To be able to use the prog::tcov function, start the MuPAD engine with option -t. Use the Arguments field in the Engine dialog to set this option.

If you start the kernel using both options -v and -t, the function expose shows information about the debug node and passes (see Example 2).

The functionality of prog::tcov depends on the internal debugger. For details, see the help page for the debug command.

Some special considerations:

  • If the MuPAD library is read from a tar archive (file lib.tar), prog::tcov excludes from inspection all the files from this archive. The output of prog::tcov also includes the call of prog::tcov itself and some other MuPAD utility function passes.

  • prog::tcov counts only the lines containing a "debug node".

When called with the option Write or the option Append, prog::tcov creates a data file using the following format: "filename":fileindex:. For each read MuPAD source file, "filename" is the name of the source file and fileindex is a numerical index. For temporary files, the index is negative:

  • -1:-1:

The colon separates the first and the second parts:

  • fileindex:line:column:hidden:passes:unused:

For each debug node, fileindex corresponds to the first part, line and column determine the start of the debug node in the source file, hidden is 1 for hidden nodes, otherwise 0, passes is the number of passes, unused is an empty and currently unused string.

See Also

MuPAD Functions

Was this topic helpful?