Developer's guide

For cite-effect, version 1.3

Notations

//+++	to do
//---	to deprecate
//???	to investigate
//patch[01]	(temporary?) bug fix number 01
//!!!	to remove before releasing (development only)

Logical view

Database design

Flat file is used instead of indexed database since sequential access is only necessary.

Split symbols/references files is used instead of merged files since resolving symbol ambiguity will take place before graph processing, and does not need the list of references.

Relevent referer-relationships (parser-dependent) :

file/function reads/writes/calls
//+++ file-includes
//+++ file/esuc/function-declares
//+++ class-implements/extends

Graph algorithms

To find homes of a referee: (the deepest node in each graph where all references occur, directly or indirectly)

select all parents of referee, starting from the graph roots, recursively, in direct line (do not walk loops); quit if empty
do recursively and once on each node, down the parents' tree:
- apply this step 2 to children of current node
- case no child: .homes_= empty
  case one child: .homes_= child.homes_
  case multiple children, there is no node common to all paths to referee: .homes_= empty
  case multiple children, there are nodes common to all paths to referee: .homes_= these common nodes
- append 'this' node to .homes_
replace each root by deepest home node= first in .homes_ list
remove duplicate in updated list of graph roots
add parents of referee, starting from the graph roots, recursively, this time walking loops

//+++ abortable parser

returns Id_ of token at given fpos
lexer returns ABORT token
parser detects 'expr ABORT' and ignores syntax error

//+++ IDE integration

max path/filename length used in output layout.

Coding style

Use 2-space indentation.
Have your editor place 2 hard-coded space characters instead of a tab character in source files.

Have each .cpp file refer to its .h file, and .h file refer to this .html file (pointing to the UML diagram).

Naming

To help refactoring, avoid natural language names for symbols. For example, use 'Parser_' rather than 'Parser', so that global name change will not affect occurence of 'Parser' in comments

Object deallocation

Use foo( Object param&) instead of foo( Object param*) when foo becomes responsible for deallocating the supplied object.

Use 'virtual prune_()' to allow virtual destructor code (C++ does not allow overriding destructor method).

Class documentation (optional)

To describe normal usage of a class and its objects, write in the header file '.h' the grammar rules for the valid sequences of method invocation. See for example common_.h.

Write the grammar using the Backus-Naur form (BNF) syntax. It can be extended with the following syntax :

'::<=' : this expresses that semantic constraint(s) reduces the set of possible sentences
'::*' : this 'product' operator allows describing 2 independent interfaces. It expresses that sentences generated by the left operand are mingled or interlaced with sentences from the right operand.