Project class

Update of /cvsroot/synopsis/Synopsis/docs/Manual In directory sc8-pr-cvs1:/tmp/cvs-serv22961 Modified Files: synopsis.xml Log Message: Lots more info about the Project file format. Index: synopsis.xml =================================================================== RCS file: /cvsroot/synopsis/Synopsis/docs/Manual/synopsis.xml,v retrieving revision 1.13 retrieving revision 1.14 diff -u -p -d -r1.13 -r1.14 --- synopsis.xml 16 Mar 2003 00:26:27 -0000 1.13 +++ synopsis.xml 8 Apr 2003 11:43:59 -0000 1.14 @@ -220,7 +220,7 @@ void func() The comment processors are all written in Python, and you can specify your own in a config file to perform custom processing, or to - deal with unusual comment styles. + deal with unusual comment styles. See the chapter on the Linker for more information on this. @@ -743,15 +743,19 @@ class struct: setattr(self, key, value) class Project: + # Instantiate an object: + my_object = struct(name = "foo", magic_number = 42) + + # And another one, this time formatted nicely: some_object = struct( name = "hi", some_list = [1, 2, 3], + # Here an attribute is a nested object: nested_object = struct( type = "foo", fred = "baz" ) - ) - + ) The new Project structure defines not only configuration for the @@ -795,9 +799,9 @@ class Project: Can take as input any number of ASTs (from eg: ParserAction, LinkerAction). Outputs the same ASTs, but stores the ASTs on disk so that they don't need to be regenerated each time if the - timestamps have not changed. There is a limitation in that the - timestamps are only checked on the input source files themselves, - not on their dependencies. This will be fixed in a later version. + timestamps have not changed. For C++ files all dependencies + (#included files) will have their timestamps checked. For other + languages only the actual source files will be checked. @@ -833,12 +837,69 @@ class Project: Linker and Formatter objects are described later in this manual, and are the same as the old config format just with a different syntax. - As mentioned, the main element of the config file is the - "class Project". It has a number of attributes, including a - string name, verbose flag, a list of actions, a list of channels, and a - default formatter to use if none is specified. The channels are the - connections between actions, and are simply tuple pairs of names of - actions. +

+ Project class + + class Project: + # attributes go here. Must be indented! + name = 'project name' # string - name of project + verbose = 0 # boolean + data_dir = './' # string - path (currently unused) + default_formatter = 'name' # string - the name of the default formatter to + # use if none is specified on the command line. + channels = [ <list of channels> ] + actions = [ <list of actions> ]The main element + of the config file is the "class Project". It has a number of + attributes, including a string name, verbose flag, a list of actions, + a list of channels, and a default formatter to use if none is + specified. The channels are the connections between actions, and are + simply tuple pairs of names of actions, e.g.: channels = [ + ('C++ Parser', 'File Cacher'), + ('File Cacher', 'Linker') + ] + + Be careful that the action names in the channels list match the + names of the actual Actions in the actions list. +

+ +

+ Action object + + An action object, part of the list of actions in Project, is a + list of attributes (not a struct!). The first 4 attributes are always + the same, but different Actions have different uses for the remaining + attributes (remember, a list has variable length). The following + example shows all action types: actions = [ + # string type, X/Y coords, string name, extra attributes... + ['SourceAction', 100, 100, 'Boost Sources', [ <list of SourceAction Rules> ] ], + ['ParserAction', 200, 100, 'C++ Parser', struct(key=val, key=val, ...) ], + ['CacherAction', 300, 100, 'File Cacher', 'directory' or None, 'file' or None ], + ['LinkerAction', 400, 100, 'Linker', struct(key=val, key=val, ...) ], + ['FormatAction', 500, 100, 'HTML Formatter', struct(key=val, key=val, ...) ] + ] + + As you can see, all types use the same format for the first four + attributes. The first is the type of action. The 2nd and 3rd are the X + and Y coordinates to use to display the action in the GUI. The 4th is + the name of the Action. + + For SourceActions the 5th attribute is a list of SourceAction + Rules (see the next section). + + For CacherActions the 5th and 6th attributes are directory name + and file name respectively. One and only one of these must be set (the + other must be None). If directory is set, then the inputs to the + action will be cached in the given directory and the outputs will be + the same as the inputs. If the file is set, then the action will have + no inputs, and one output which is loaded from the given file. Note + that this second mode of operation is not really caching but more like + loading, and can be used to load an AST from a file which you + don't have or want to use source code for. + + For all other Action types the 5th attribute is a Config object. + For information on these see the documentation for the relevant + chapters of this manual (Parsers, Linker and Formatters). +

SourceAction Rules @@ -933,6 +994,39 @@ class Project: + + All rules are processed in the order that they appear in the + list. The effect of a rule is to add remove files to/from a list. + Therefore to explicitly exclude a file, the exclude rule should be at + the end. + + Note that this is the opposite to permission type rules you + might be used to, since in this case we don't know what files + there are until a rule is processed. With permissions you know what + user/file you are checking permissions for so it's usually the + first matching rule which is used - hence exclusions are usually + placed first for permissions. + + Another special case is when you are using the + 'multiple_files' feature of the C++ parser - in this case the + first rule must be a Simple rule with the main filename (e.g.: + Python.h). This is documented at the end of the C++ Parser section. +

+ +

+ Command Line Usage + + To use the project file and generate output for the default + formatter (specified in the config), use a command line like so:$ synopsis -P project.synopsis + + You can specify a formatter to use other than the default + formatter like so:$ synopsis -P project.synopsis -Wc,formatter=MyFormatter + + Synopsis will ensure that all Actions connected to the formatter + are also executed. + + See the Boost demo for an example of how to use the project file + format.

@@ -954,8 +1048,6 @@ class Project:

C++ Parser - most advanced. SXR. XREF. UCPP, OCC - The C++ parser reads C++ source code and generates an AST. It is the most advanced Synopsis parser, using the following components:A modified version of UCPP by Thomas Pornin. The modifications are to @@ -1832,10 +1924,6 @@ class HTML (Base.Formatter.HTML): can change this text using the "short_title" option of the ModuleListing subobject. - XXX There are two types of tree you can use: a simple HTML tree, - or one that uses DHTML to open/close individual nodes, with little - graphics for the buttons. -

Options @@ -2883,4 +2971,4 @@ htmlPageClass = XRefPagesThe best way to figure this out is to study the existing Pages.

- + \ No newline at end of file