3.3.11 The dot_ast backend

dot is a format for describing graphs in terms of their edges and vertices. The tools in the Graphviz suite typeset dot files in a variety of output formats and using a variety of graph-layout algorithms. coNCePTuaL’s dot_ast backend outputs in dot format the abstract-syntax tree corresponding to a given coNCePTuaL program. As an example, dot_ast renders the one-line coNCePTuaL program ‘TASK 0 SLEEPS FOR 10 SECONDS’ as follows:

dot_ast is expected to be of particular use to backend developers, who can use it to help prioritize the methods that need to be implemented (i.e., implementing first the AST node types needed by in a trivial program, then those needed by successively more complex programs).

The dot_ast backend accepts the following options from the ncptl command line:

--format=dot_format

The programs in the Graphviz suite can output graphs in a variety of formats such as PostScript, SVG, and PNG. By default, the dot_ast backend outputs PostScript. The --format option specifies an alternate format to use. At the time of this writing, the Graphviz programs support the following formats: canon, cmap, dot, fig, gd, gd2, gif, hpgl, imap, ismap, jpeg, jpg, mif, mp, pcl, pic, plain, plain-ext, png, ps, ps2, svg, svgz, vrml, vtx, wbmp, and xdot. See the Graphviz documentation for more information about these formats.

--node-code=characters

To facilitate associating nodes in the AST with fragments of the coNCePTuaL program being graphed, the dot_ast backend provides a --node-code option that labels each node with the fragment of code to which it corresponds. The argument to --node-code is a number of characters at which to truncate the code fragment or ‘-1’ to inhibit truncation. The purpose of truncation is to prevent excessively large nodes from disturbing the graph layout. The <program> node (see Complete programs), for example, includes the complete program source code if not truncated.

--extra-dot=dot_code

The dot_ast backend’s --extra-dot option enables the user to inject arbitrary dot code into the generated file. For example, specifying --extra-dot="node [shape=Mrecord]"⁶ tells dot to use draw nodes as rounded rectangles and specifying --extra-dot='edge [color="green"]' colors all edges green. --extra-dot can be specified repeatedly on the command line; dot_ast concatenates all of the extra dot code with intervening semicolons.

--compress

Normally, every node of the AST is drawn. The --compress option makes the resulting dot graph more readable by eliding chains of single-child nodes. For example, --compress reduces the previous graph of ‘TASK 0 SLEEPS FOR 10 SECONDS’ to the following:

--no-lines

By default, each AST node indicates the lines in the program’s source code to which it corresponds. The --no-lines option suppresses the outputting of source-code line numbers.

--no-attrs

Every node in the AST has a type. Some nodes additionally have an attribute. dot_ast normally outputs attributes but --no-attrs prevents dot_ast from doing so.

--no-source

The complete source code corresponding to the AST is included in the generated dot graph unless --no-source is specified on the command line.

The DOT environment variable names the Graphviz program that dot_ast should run on the generated code. If DOT is not set, dot_ast uses whatever value was specified/discovered at configuration time (see configure), with the default being dot . By default, dot_ast produces dot code and runs this through the designated Graphviz program to produce a PostScript file (or whatever format is named by the --format option). If ncptl is run with either the --no-link or --no-compile options, it produces a dot file that should be run manually through dot or another Graphviz tool.