Parsing source code

The synopsis executable is a convenience frontend to the larger Synopsis framework consisting of AST-related types as well as processor classes.

While the full power of synopsis is available through scripting (see Chapter 3, Scripting and extending synopsis), the most frequent use cases are captured in the synopsis executable.

Let's assume a simple header file, containing some declarations:

#ifndef Path_h_
#define Path_h_

//. A Vertex is a 2D point.
struct Vertex
{
  double x; //.< the x coordinate
  double y; //.< the y coordinate
};

//. Path is the basic abstraction
//. used for drawing (curved) paths.
class Path
{
public:
  virtual ~Path() {}
  //. Draw this path.
  virtual void draw() = 0;
  // temporarily commented out...
  // bool intersects(const Path &);
private:
};

#endif

        

Process this with

synopsis -p Cxx -f HTML -o Paths Path.h

to generate an html document in the directory specified using the -o option, i.e. Paths.

The above represents the simplest way to use synopsis. A simple command is used to parse a source file and to generate a document from it. The parser to be used is selected using the -p option, and the formatter with the -f option.

If no formatter is specified, synopsis dumps its internal representation to the specified output file. Similarly, if no parser is specified, the input is interpreted as an IR dump. Thus, the processing can be split into multiple synopsis invocations.

Each processor (including parsers and formatters) provides a number of parameters that can be set from the command line. For example the Cxx parser has a parameter base_path to specify a prefix to be stripped off of file names as they are stored in synopsis' internal representation. Parser-specific options can be given that are passed through to the parser processor. To pass such an option, use the -Wp, prefix. For example, to set the parser's base_path option, use

synopsis -p Cxx -Wp,-base_path=<prefix> -f HTML -o Paths Path.h