Path Projection

Path Projection XML Report Format

Path Projection takes as input an XML file describing the program paths to visualize. The pathreport XML format is designed such that it can be used to mark up a textual path-based report.

Note that for a file to be properly recognized as an XML file by web browsers and servers, it should be named with the .xml extension.

XML prologue and document element

<?xml version="1.0" encoding="utf-8"?>
<pathreport xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en">
…
</pathreport>

A pathreport file begins with an XML prologue, and the <pathreport> document element. It is also placed in the XHTML namespace.

Additionally, a stylesheet can also be applied to the file just after the XML prologue. This make it easier to inspect the file in a web browser. An example is provided under corpus/report.css.

<?xml-stylesheet href="corpus/report.css" type="text/css"?>

Markup

pathreport files may contain one or more program paths. Three tags are used to describe program paths:

<path file="source file" name="function name">

marks text that corresponds to a continuous block of code (only functions now). It describes the beginning of a path at the top level (under <pathreport>), and nested path segments. The attributes file and name are required, and points to the name of the function and file it is located in (relative to the base of the source directory).

A <path> can contain any number of <detour> and <marker> tags.

<detour line="line number" name="reference name">

marks text that corresponds to a reference in some code (only call sites now). The parent <path> provides the context for this reference, e.g., the function in which the call site appears. Two additional attributes line and name are required to indicate the line in the containing function where the reference occurs and the name of the reference (which may be different from the function name, e.g., a function pointer).

Each <detour> tag must in turn contain exactly one <path> tag.

<marker role="roles" ...>

tags mark any other texts, such as function names, variable names, or line numbers, that point to code that may be interesting. The containing <path>s provide some context to place this marker in the source code, and required role attribute indicates the interpretation of the marker.

There are several different roles, some requiring additional attributes:

<marker role="name">foo</marker>

points to the function foo;

<marker role="line">x</marker>

points to line x (in file order) in the function pointed to by the parent <path>;

<marker role="indirect" line="x">foo</marker>

points to the line x (in file order) in the function foo;

<marker role="indirect" line="x" name="foo">bar</marker>

also points to the line x (in file order) in the function foo, but is useful to mark the text bar in the textual report;

<marker role="related">foo</marker>

makes foo a preset multiquery search term, and is useful for highlighting, e.g., all occurences of a variable foo along the path.

In addition, standard HTML and CSS may also be used to mark up or style the report.

Example

The following shows how to create a pathreport XML report by marking up a textual report with <path> and <detour>:

Textual report

XML report

Trace: In function a ( On line a:5, call b ( On line b:10, call c ( On line c:15, call d ) ) On line a:20, call e ( On line e:25, call f ) )

<?xml version="1.0" encoding="utf-8"?> <pathreport xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en"> Trace: In function <path file="foo.c" name="a">a ( On line <detour line="5" name="b">a:5, call <path file="foo.c"name="b">b ( On line <detour line="10" name="c">b:10, call <path file="foo.c" name="c">c ( On line c:15 , call d ) </path></detour> ) </path></detour> On line <detour line="20" name="e">a:20, call <path file="bar.c" name="e">e ( On line e:25, call f )</path></detour> )</path> </pathreport>