Synopsis - Design Overview

The Synopsis project is a work in progress. It provides a variety of APIs that operate at different levels of granularity. The part summarized on this page is quite stable and userful for end-users. Other features are being worked on, but these are not yet ready for production use. To find information about the full feature set that is currently being worked on, you may want to read the Synopsis Developer's Guide.

Synopsis centers around a python script that is highly customizable through a set of modules. There are three modules which encapsulate parsing, linking and formatting. There is also a GUI under development to allow interactive configuration and viewing of the results. The system is best viewed in the following diagram:

component diagram

The backbone of the tool is the AST (abstract syntax tree). It is generated by the parser, manipulated by the linker, and converted to a document by the formatter. The abstract tree is a common representation, having the features needed for all the supported languages. Here is a hierarchy similar to what is currently used:

abstract syntax tree class diagram

There are two modes of using Synopsis. The first uses 'make' or similar to repeatedly call Synopsis for each stage in the process. Note that the division into stages is only to allow storing intermediate results to disk. This mode allows easy integration with an existing autoconf/make build system. Depending on the command line arguments, the process involves one or more of: parsing, linking and formatting. The input files and/or the output file may be AST storage files, allowing the use of storage files to only update changed parts of the AST. Here is the data flow:

data flow diagram

The second mode is still under development, but removes the need to use make by representing the concept of dependancies, intermediate storage (cached ASTs) and the three module types (parser, linker and formatter) in a new configuration format. This is the mode natively supported by the GUI, which is also under development.