Module Synopsis:: Config

Configuration script module. There are a large number of command line options to control Synopsis, but there are many more options than it is feasable to implement in this fashion. Rather, Synopsis opts for the config file approach if you want full control over the process.

The problem

Synopsis is very modular, and it is desirable to separate the options from different modules - something achieved by the -W flag. The modules form a hierarchical structure however, with up to three levels of depth. Some modules are used rarely, and the user may want different sets of settings depending on what they are doing - eg: generating HTML or Docbook, parsing different sections of the code, etc. We tossed about various ideas of representing options in an related way, and came up with the idea of a Python script that builds an object hierarchy that mirrors that of the modules.

The Config Script

A config script is specified by passing the -c option to 'synopsis'. Options may be passed to the script via the -Wc option, as key=value pairs. For example:

synopsis -c config.py -Wc,formatter=C++

The script is interpreted as a Python source file, and the only requirement is that once loaded it have a global object called Config. This Config object is usually a class which is constructed with the options dictionary to retrieve an object with nested configuration objects. Every config object has at least one attribute 'name', which identifies the module the object configures.

If no config script is specified on the command line, the default class Base is used, defined in this Config module. It is recommended that the Config class in your config script derive from this Base class to extend it as you wish.

Modules

In many places modules or lists of modules can be specified to perform tasks. These may be selected in one of four ways:

1. From a list of built-in defaults for that task as a simple string (depends on attribute),

2. As a member of a module or package as a simple string (depends on attribute),

3. From anywhere via a tuple of two strings: (module, class-name); for example, to use the provided DOxygen Scope Sorter, you specify ('Synopsis.Formatter.HTML.doxygen', 'DOScopeSorter') or to use your own something like ('mymodules.py', 'ScopeSorter') - Note that ending the first string in '.py' forces it to be loaded from a file, something which cannot be achieved using the next method:

4. From anywhere via an absolute dotted reference, eg: 'Synopsis.Formatter.HTML.doxygen.DOScopeSorter'.

Of these methods, 1 or 2 are preferable for brevity and 4 for absolute references, unless a filename is needed in which case you need 3.