The Rigi graph editor, rigiedit, accepts as input a flat file of 3-tuples that 1) declare nodes by their types, 2) describe the relationships (directional arcs) between specific nodes, and 3) annotate a given node. The file format used is called Rigi Standard Format (RSF). The Rigi parser, rigiparse, produces RSF in two formats, unstructured and structured. An RSF file without structure lacks even the most rudimentary hierarchical graph format. The simplest structured graph has at least two hierarchical levels: the topmost consists of a single node named Root that is connected to all other nodes in the graph by level arcs, i.e., arcs that traverse between nodes at different levels in the hierarchy.
The parser can produce either RSF format but only use of the unstructured format is recommended because the unstructured file can be manipulated with utilities like the UNIX sort, sortrsf and htmlrsf. rigiedit is capable of reading the unstructured RSF and converting it into structured RSF. These utilities can have unexpected results when applied to structured RSF.
The sortrsf filter program is used primarily to sort an RSF file. The program also removes duplicate tuples. Duplicates are caused by merging the RSF output from multiple compilation units. They can also be generated inadvertently by the parser (although rigiparse does not emit duplicates, other parsers may). Furthermore, sortrsf can replace with a single multiarc arc two or more arcs of different types having a common node as their source and a common node as their destination. This capability is useful because rigiedit can represent only a single arc between a given source and destination.
RSF has a variant, a 4-tuple format, that is used by the htmlrsf program to position HTML links in the source files. For 4-tuples, sortrsf, can be used to remove duplicate tuples and, optionally, it can be used to strip the fourth element from each of the tuples. However, sortrsf can not be used to generate multiarc arcs.
The program is run as a filter.
It accepts input from stdin and writes its output to stdout.
Errors are reported to stderr. A typical command might be:
rigiparse pgm.c | sortrsf -lm > pgm.rsf
The following command line arguments are supported:
-h | displays a banner and a brief description of the command line options. |
-l | causes RSF attributes designated as loc to be concatenated. The loc attribute identifies the file and line number where a specific node, e.g., a given procedure, is defined in the source. Sometimes when the RSF is derived from more than one compilation unit, the parser may generate calculate discrepant locations for a given globally visible node. In these cases, the different loc attributes can be concatenated and shown as a single composite loc attribute. Note that loc tuples will always be 3-tuples. |
-m | generates a multiarc if two or more arcs of different arc types have a common source node and a common destination node. This command line argument operates on 3-tuples only. |
-4 | causes 4-tuples to be preserved. If there are 4-tuples in the RSF file but this command line argument is unspecified, the fourth component of the tuple is removed. If sortrsf is run with a -4 command line argument, 4-tuples are left unchanged. |
Line-based comments in the input RSF file can be represented with a hash "#" character. The comments are removed by sortrsf from the RSF stream and written to stderr.
The following is a C-language program.
/* example.c */ struct struct_t { int i; } sglobal; int func(struct struct_t *sarg) { struct struct_t sfunc = *sarg; return sfunc.i; } void main() { int j; struct struct_t smain, *psmain; smain.i = 3; psmain = &smain; j = func(psmain); sglobal.i = j; }
The program is parsed using the following command.
rigiparse example.c > tmp.rsf
The following is the output file from rigiparse.
type struct_t Data file struct_t example.c lineno struct_t 2 type func Function file func example.c lineno func 4 data func struct_t type main Function file main example.c lineno main 9 data main struct_t call main func data main struct_t
The RSF file is sorted with the following command.
sortrsf < tmp.rsf > srt.rsf
The following is the output file from sortrsf.
type func Function type main Function type struct_t Data call main func data func struct_t data main struct_t file func example.c file main example.c file struct_t example.c lineno func 4 lineno main 9 lineno struct_t 2
The RSF file is sorted with type at the top. The remaining tuples are sorted in ascending order. The duplicate data entry for main has been removed.
The following are runtime warnings and errors that may be reported by sortrsf to stderr.