The CONDELA - III Compiler :  COnnection Network DEfinition LAnguage

This is the Manual of Condela (Version 1.0)

     --==* Table of Contents  *==--

	1. General Information
	2. Statements
	3. Underlying C-statements
	4. Syntax of Condela
	5. Diagnostics

1. General Information
======================

  A Condela program consists of two successive parts. The first part
defines data objects and constants and declares network topologies and
symbolic types. The second part consists of procedures that modify
data.
  Condela is in the scope of the variables similar to C, but unlike C
Condela is not case-sensitive. Comments are written within /* and */,
nested comments are allowed.
  Within %C and %endC directives you may include C-code in your
Condela- program. After the %include "filename.con" directive,
compilation continues in the named file. Nested %include directives
are allowed to a maximum of 11 levels.
  Like in C no nested procedures are allowed. Local variables are
possible but unlike Pascal-constants constants are in Condela
implemented with C-macros. Therefore you should not redefine a global
constant locally in a procedure because that overwrites the original
definition after the static definition of that procedure.

  The data types of Condela are real, integer, boolean, vector, unit,
and unit-selection, the data types real, integer and boolean behave in
the usual manner. The data type vector may be regarded as a dynamic
array of real and objects of that type can be used with range-lists.
For example if v is a vector you can use v[0..3,7..vmax] as well; the
resulting vector consists only of those elements whose indices are
within the range list. The data type unit is used to access the
components of a single unit. The data type unitselection is used to
access groups of units.

2. Statements
=============
2.1 Assignment
--------------

		Variable ':=' Expression [ ':' NULL | ':' NIL ]
	or	Variable ':=' UnitSelection [ ':' Ident ]

  This statement (as expected) assigns a value to a variable. If the
Expression (and the variable) is of type VECTOR you may specify with
the ": NULL" extension (unless the target-vector has no rangelist)
that unaffected Elements are set to 0; i.e. if the target vector is
longer than the source vector the remaining elements of the target
vector are set to 0. The extension ": NIL" just specifies the default
action that leaves these elements unchanged.
  In the the second form, a unit-selection is assigned to a Variable
of type USEL. This assignment makes the code more readable and faster.
But if you assign units that are inside a POOL, the order of that
units are fixed inside that variable.
  If you specify ": Ident" after the unit-selection, the resulting
object is of type VECTOR an can only be assigned to other Vectors.
The elements of that vector consists of the components with the name
"Ident" of the all units in the unit-selection (The order is made up
by the order of the parts of the unit-selection).

  The colon after the unit-selection indicates that you are using the
components as a vector. There are no restrictions concerning the
unit-selections, they can overlap and they may consist of units of
different layers or networks (in a future Version thay can even be of
different types).

2.2 Control Statements
----------------------

	APPLY ProcedureCall TO UnitSelection [ To UnitSelection ]

  With this statement the Unit-selection that followed the first TO
-term  will be modified with the Function (i.e. procedure) that
followed the APPLY keyword.  The procedure used in this statement is
usually implemented in C, and it takes as last argumment a
unit-selection (The C-type USEL). See the function ff() in the file
condela.c for an example of the usage of this functions.


	CASE Expression OF Cases [ ELSE { Statement ';' } ] END
	Cases -> [ ExpressionList ':' { Statement ';'}
		   { '|' ExpressionList ':' { Statement ';'}}]

  The case-statement is direct translated into C and is a semantic
generalization of the IF statement (semantically equal to the MODULA-2
Case). 


	CONNECT UnitSelection TO UnitSelection
		[ TYPE Ident ]
		INIT Expression	[ NUDUPLICATES ]

  This statement establishes a connection from every unit of the first
unit-selection to every unit of the second unit-selection. You can
specify the type of the connection by naming an identifier after the
TYPE keyword (in the present implementation there is only one type of
connection so the usage of any identifier is not changing anything.
  A special component defined by the description of the function
connect$() (defined in condela.c) is initialized by the expression
after the INIT keyword.  The keyword NUDUPLICATES specifies if
duplicate connections are allowed (in the present implementation the
this keyword is not used by the function connect$()).


	CONTINUE

  This statement causes a jump to the end of the loop, it is
translated into a C- continue; statement.


	CREATE Ident { '<' SimpleExpression '>' }

  After this statement internal memory is allocated to the network
(which also can have several dimensions).


	EXITLOOP

  This statement exits the current loop, it is translated into a C-
break; statement.


	EXTEND Ident { '.' Ident |  '<' RangeList '>' }
	BY (( '[' SimpleExpression ']' )+ | '(' SimpleExpression ')' )

  Sorry but this statement is not yet implemented. It will extend the
number of pool komponents of the given layer by a number that is
returned by the SimpleExpression if the option with the round brackets
is used (eg.: EXTEND p.in_layer BY (10) will add 10 units to the pool
in the layer 'in_layer' of the network p)
If the other option is used (eg. EXTEND p.in_layer BY [4]) a number of
units will be added to the first dimension of the layer in_layer of
the network p. If a network is defined as follows:
	TOPOLOGY t = field [10];
		 u = FIELD [5][5];
	VAR	 p NETWORK OF t;	
		 q NETWORK OF u;
then the index-range for i in the field of units p[i] is from 0 to 9.
After the statement 'EXTEND p BY [6];' the index-range for i is from 0
to 15. Similarly after the statement 'EXTEND p BY [3][5];' the index-
range for i (in the expression p[i][j]) will be from 0 to 7 and for j
from 0 to 9.


	FOR Variable FROM Expression1 TO Expression2
	[ BY Expression3 ] DO { Statement ';' } END

  This is the standard FOR- loop. First the Variable is initialized
with Expression1, then the end-test ist evaluated: if the value of the
loop-variable is less or equal to Expression2 the Statements that
followed the DO- keyword are executed.  Then the loop-variable is
incremented by the value of expression3 (when omitted: 1); then the
end-test is evaluated again.


	FOR Variable IN UnitSelection DO { Statement ';' } END

  This is a specialized FOR- loop that iterates as many times as there
are units in the unit-selection. The control variable subsequently
refers to all units in the selection and can be referenced within the
FOR block as if it where a unit. To access components of a unit
variable use the following syntax:
	loop_var.unit_component := 0.32;


	IF Expression1 THEN { Statement ';' }
	{ ELSIF Expression THEN { Statement ';' } }
	[ ELSE { Statement ';' } ] END

   A standard IF statement: if Expression1 returns true (any nonzero
value) then the statements following the THEN- keyword are executed.
If Expression1 returns false (= 0) then the subsequent Expressions
after the ELSIF- keywords are tested and their statements are
executed. If all the tests fail then the statements following the
ELSE- keyword are executed.


	LOOP ( FOREVER | Expression TIMES ) { Statement ';' } END

  This loop iterates Expression times or forever. The loop can be
exited with the BREAK- statement.


	ProcedureCall

  A standard C- like procedure call.


	REPEAT { Statement ';' } UNTIL Expression

  This loop iterates as long as Expression is false (= 0), at least
once.


	RETURN [ Expression ]

  The statement transforms control the the calling procedure, and
returns the value of Expression.


	WHILE Expression DO { Statement ';' } END    

This loop iterates as long as Expression is true (any nonzero value).
The loop-test is done at the beginning of every iteration.

3. Underlying C-statements
==========================

  In the present implementation, the connections are built by the procedure
connect$() and connect_u$(). These Procedures should not be used as a
normal procedure call. A call of that procedure is generated by the Condela
compiler at the CONNECT- statement. A Unit-selection is implemented like
(lisp) List with pointers. This Method guarantees the dynamic extensibility
of units in the Layers.  The code
            VAR my_selection : USEL;
            ...
            my_selection := { mynet[0..3] };

results in the following data structure:

my_selection--,
              |
              V
            ,-----------,  ,-----------,  ,-----------,  ,------------,
            | p  u_next-|->| p  u_next-|->| p  u_next-|->| p  u_next=0|
            `-+---------'  `-+---------'  `-+---------'  `-+----------'
              |              |              |              |
  - - - -     V              V              V              V         - -
           ,-------------------------------------------------------,
           |             |              |              |           |
           `-------------------------------------------------------'
                   ^
                   |
        ,--------, |
mynet-->|  fld --|-'
        | pool=0 |
        `--------'

	Figure 3.1

  The unit-selections are implemented as lists to get the flexibility to
add units of different LAYERs or NETWORKs to a unit-selection The pointer
structure in the lower part of figure 3.1 is installed by the CREATE
-statement and the upper part is done by the assignment of the
unit-selection to the variable of type "USEL" in the previous paragraph.
The connections are implemented as follows: the statement

            CONNECT  { mynet[0..1] } TO { nonet[0..1] } INIT random$();

creates the following data Structure (if not previously connected):

          ,--------,
nonet --> |  fld --|-,
          | pool 0 | |
          `--------' |    ,-----------------------------------,
                     V    V                                   |
         ,-----------------------------------------------,    |
         |                       |                       |    |
         | c_from.               |  c_from.              |<---+------,
         `-------+-----------------------+---------------'    |      |
              ^  |                    ^  |                    |      |
              |  |                    |  |                    |      |
   ,----------'  |       ,------------'  |     ,--------------'      |
   |  ,----------'       |  ,------------'     |                     |
   |  V                  |  V                  |                     |
,--+--------------,   ,--+--------------,   ,--+--------------,   ,--+--------------,
|c_to    to_next--|-->|c_to             |   |c_to    to_next--|-->|c_to             |
|c_from. from_next|-, |c_from. from_next|-, |c_from.          |   |c_from.          |
`------+----------' | `------+----------' | `------+----------'   `------+----------'
    ^  |            |        |            |    ^   |                ^  ^ |
    |  `------,     |        |            `----+---+----------------+--' |
    `-------, |     `--------+-----------------'   |                |    |
            | V              V                     V                |    |
         ,--+------------------------------------------,            |    |
         | c_to                 |                c_to--+------------'    |
         |                      |                      |                 |
         `---------------------------------------------'                 |
                     ^                          ^                        |
                     |                          |                        |
          ,--------, |                          `------------------------'
mynet --> |  fld --|-'
          | pool 0 |
          `--------'

	Figure 3.2

  In Figure 3.2 you see the four middle Boxes that are of type WEIGHT
and the components to_next and from_next are nil if not mentioned in
the picture. This structure guarantees that every unit "knows" where
it is connected from and to. The allocation of the memory for the
WEIGHTs is done by the procedures connect_u$() and connect$(). See the
file units.h for the C-definition of the units, unit- selections and
weights.

4. Syntax of Condela
====================

  The following section describes the syntax of Condela in EBNF (i.e.
Extended Backus-Naur Form) The meta-symbols of EBNF are as follows:

	->	"is defined as"
	|	"or", the left or right part of the expression is used
	[]	everything written in square Brackets is optional
	{}	everything written in curly brackets may be omitted or
		arbitrarily repeated
	()+	everything written within this construct may occur as
		many times as appropriate, at least once.
	''	symbols written in single quotes are "terminal" and
		stand for themselves
	++++++	verbal description of the syntax

  Uppercase words are also terminal and denote keywords of Condela.
Mixed uppercase and lowercase words are meta-symbols that extend to
some other syntactic form. The Starting symbol is "CompilationUnit"
that derivate a complete program.
  The operator precedence, that is not defined by this form of
grammar, is like in C, while precedence 5 is highest an 1 is lowest.

	operator	precedence
	-		5
	+ - 		4
	* /		3
	= < <= > >= #	2
	not		1

 An empty line denote the end of that grammar Rule.


CompilationUnit	->	[ MODULE Ident ';']
			[ UNIT '=' Ident ';' ] [ WEIGHT '=' Ident ';' ]
			{ DataDeclaration | NetDeclaration } { ProcDeclaration }
			
DataDeclaration ->	CONST { Ident '=' Expression ';' }
		|	TYPE { Ident '=' Type ';' }
		|	VAR { IdentList ':' Type ';' }
			
Type ->			SimpleType
		|	ARRAY ( '[' Expression ']' )+ OF Type
		|	OVERLAY  { IdentList ':' Type ';' } END
		|	RECORD { IdentList ':' Type ';' } END
		|	ENUM IdentList END
		|	POINTER TO SimpleType
		|	NETWORK { '<' SimpleExpression '>' } OF Ident
			
SimpleType ->		BOOLEAN
		|	CHAR
		|	STRING
		|	INTEGER
		|	REAL
		|	VECTOR
		|	USEL
		|	Ident
		|	UNIT [ OF Ident ]
			
NetDeclaration ->	TOPOLOGY { Ident [ '=' [ FieldDef ]
					       [ PoolDef ]
					       { LayerDef } ] ';' }

FieldDef ->		FIELD ( '[' Expression ']' )+ [ OF Ident ] ';'

PoolDef ->		POOL  '(' Expression ')' [ OF Ident ] ';'

LayerDef ->		LAYER Ident { '<' SimpleExpression '>' } OF LayerStruct ';'
			
LayerStruct ->		[ FieldDef ] [ PoolDef ] { LayerDef } ] END
		|	Ident

ProcDeclaration ->	PROCEDURE Ident '(' [ FormalParameter ] ')' [ ':' SimpleType ] ';'
			{ DataDeclaration }
			BEGIN { Statement ';' } END ';'

FormalParameter ->	[ VAR ] IdentList ':' SimpleType
		|	FormalParameter ';' [ VAR ] IdentList ':' SimpleType

Statement ->		EXITLOOP
		|	CONTINUE
		|	FOR Variable FROM Expression TO Expression
			[ BY Expression ] DO { Statement ';' } END
		|	FOR Variable IN UnitSelection DO { Statement ';' } END
		|	IF Expression THEN { Statement ';' }
			[ ELSIF Expression THEN { Statement ';' } ]
			[ ELSE { Statement ';' } ] END
		|	CASE Expression OF Cases [ ELSE { Statement ';' } ] END   
		|	LOOP ( FOREVER | Expression TIMES )
			{ Statement ';' } END
		|	REPEAT { Statement ';' } UNTIL Expression
		|	WHILE Expression DO { Statement ';' } END    
		|	RETURN [ Expression ]
		|	Variable ':=' ( Expression [ ':' NULL | ':' NIL ] |
					UnitSelection [ ':' Ident ] )
		|	ProcedureCall
		|	APPLY ProcedureCall TO UnitSelection
			[ To UnitSelection ]
		|	CONNECT UnitSelection TO UnitSelection
			[ TYPE Ident ] INIT Expression [ NUDUPLICATES ]
		|	CREATE Ident { '<' SimpleExpression '>' }
		|	EXTEND Ident { '.' Ident |  '<' RangeList '>' }
			BY ( '[' SimpleExpression ']' )+ | '(' SimpleExpression ')' )

Cases ->		[ ExprList ':' { Statement ';' } ]
		|	Cases '|' [ ExprList ':' { Statement ';' } ]

ProcedureCall ->	Ident '(' [ ExprList ] ')'

RangeList ->		SimpleExpression [ '..' SimpleExpression ]
		|	',' SimpleExpression [ '..' SimpleExpression ]

IdentList ->		Ident
		|	IdentList ',' Ident

Variable ->		Ident { '.' Ident | '[' RangeList  ']' | '->' Ident }

ExprList ->		Expression
		|	ExprList ',' Expression

Expression ->		Expression '='  Expression
		|	Expression '#'  Expression
		|	Expression '<'  Expression
		|	Expression '>'  Expression
		|	Expression '<=' Expression
		|	Expression '>=' Expression
		|	Expression AND  Expression
		|	Expression OR   Expression
		|	NOT Expression
		|	SimpleExpression

SimpleExpression ->	SimpleExpression '+' SimpleExpression
		|	SimpleExpression '-' SimpleExpression
		|	SimpleExpression '*' SimpleExpression
		|	SimpleExpression '/' SimpleExpression
		|	SimpleExpression MOD SimpleExpression
		|	'-' SimpleExpression
		|	'(' Expression ')'
		|	Factor

Factor ->		BoolConst
		|	Number
		|	'"' { A_Printable_Char } '"'
		|	''' A_C_Char '''
		|	Variable
		|	ProcedureCall

BoolConst ->		TRUE | FALSE

Number ->		{ Digit } '.' ( Digit )+ [ Exponent ]
		|	( Digit )+ '.' { Digit } [ Exponent ]
		|	( Digit )+ [ Exponent ]

Exponent ->		( 'e' | 'E' ) [ '+' | '-' ] ( Digit )+

Ident ->		Letter { Char }

Letter ->		'a' | 'b' | 'c' | 'd' | 'e' | 'f' | 'g' | 'h' | 'i' | 'j'
		|	'k' | 'l' | 'm' | 'n' | 'o' | 'p' | 'q' | 'r' | 's' | 't'
		|	'u' | 'v' | 'w' | 'x' | 'y' | 'z' | 'A' | 'B' | 'C' | 'D'
		|	'E' | 'F' | 'G' | 'H' | 'I' | 'J' | 'K' | 'L' | 'M' | 'N'
		|	'O' | 'P' | 'Q' | 'R' | 'S' | 'T' | 'U' | 'V' | 'W' | 'X'
		|	'Y' | 'Z' | '_' | '$'

Char ->			Letter | Digit

Digit ->		OctDigit | '8' | '9'

OctDigit ->		'0' | '1' | '2' | '3' | '4' | '5' | '6' | '7'

A_Printable_Char ->	+++1 ASCII-character with codes ranging from 40 to 176 (octal)+++

A_C_Char ->		A_Printable_Char
		|	'\' OctDigit
		|	'\' OctDigit OctDigit
		|	'\' OctDigit OctDigit OctDigit
		|	'\\'
		|	'\n'
		|	'\b'
		|	'\f'
		|	'\r'
		|	'\t'


5. Diagnostics
==============

 1   error 	"Error in Expression"
		within an expression vectors may only combined with other
		vectors or multiplied with scalar values.

 2   error	"Integer expression expected"
		The Size of an array must be integer.

 3   error	"Error in statement"
		The statements CONTINUE and BREAK can only be used within
		loops.

 4   warning	"Identifier already declared"
		An identifier can only be declared once.

 5   warning	"Undeclared type identifier"
		An undeclared type was used (you can also use C-types)

 6   error	"Procedure already defined"
		A procedure can only be declared once.

 7   error	"Duplicate identifier"
		You can't declare different objects with the same
		identifier. 

 8   warning	"Number of arguments doesn't match description"
		You didn't use the right number of parameters in
		procedure call of a (condela) defined procedure.

 9   error	"Operands are not assignment compatible"
		You can only assign expressions to variables of the
		same type, i.e. if v is defined as a VECTOR then
		v[0..0] if of type VECTOR but v[0] is of type REAL.

10   error	"Wrong vector component"
		Valid VECTOR- components are vlen and vloc, the latter
		is a pointer to REAL.

11   error	"Parameter must not be a constant"
		you can't use a constant if a VAR- parameter is
		declared at that point in a parameterlist of a
		procedure call

12   error	"Array subscript must not be a rangelist"
		Range lists are only allowed with VECTORs NETWORKs and
		LAYERs, but not with ARRAYs.

13   error	"Nonexistent record/overlay component"
		You are using a undefined component of a RECORD.

14   error	"Undeclared identifier"

15   error	"Array subscript not allowed"
		An Index is only allowed at ARRAYs or VECTORs.

16   error	"Cannot assign a constant"
		Constants can not be modified, they are implemented as C-
		macros. 

17   error	"Cannot compare a vector"
		You may only test VECTORs on equality.

18   error	"Undeclared layer id"
		Layer have to be declared to reserve memory space at the
		creation time.

19   error	"Net description expected"
		A net description must follow if a '=' follows the
		Identifier. If an identifier (after a TOPOLOGY) is declared
		without any units, an empty POOL is asumed.

20   error	"Illegal recursive Net declaration"
		A sub-layer must not be named after the outer layer.

21   error	"Illegal usage of a network-type"
		A network-type must not be redeclared.

22   error	"Illegal declaration of a network component within a record
		or union" To simplify the implementation, you are not
		allowed to use a NETWORK variable within a RECORD.

23   error	"Illegal dynamic network declaration, number of dimensions
		does not match" 

24   error	"Constant expression expected"
		The number of elements in a LAYER must be known at
		compile-time.

25   error	"Undeclared network id"
		A networkident has to be declared.

26   error	"Layer has no dimension"
		The usage of an index for a layer is only allowed if
		the layer was defined with an dimension.

27   error	"Layer has no pool component"
		In every layer the POOL components must be defined, if
		they are used.

28   error	"Layer has a smaller dimension of field components"
		In every FIELD you have to use the correct number of
		indices.

29   error	"Variable is not of type UNIT"
		A "FOR i IN" loop requires the control variable to be of
		type UNIT.

30   warning	"Arguments of the initialization function are ignored"
		The Function that initializes the weights (in the
		CONNECT statement) must not accept any arguments.

31   warning	"Preprocessor-directive ignored"
		You can not use nested %C directives. The C compiler does
		not support this directives.

32   error	"Incomplete description of a Unitselection"
		You can not omit a layer or a unit description inside
		a unit-selection.

33   error	"Layer has a smaller dimension"
		A Layer was used with a too big number of indices, the
		number of indices used, must correspond to the number
		of dimensions.

34   error	"Illegal Unitselection"
		A symbolic unit-selection cannot be used with names of
		LAYERs.

36   error	"Unable to open include-file"
		The include file was not found.

37   error	"Too many nested includes"
		You may nest %include directives only to a maximal
		depth of 11.

38   warning	"Unexpected end of comment"
		The sequence */ may only follow the sequence /* to end
		the comment.

39   warning	"Illegal character in program;(ignored)"
		The caracters !, $, %, &, ', ?, @, \, ^, ` and ~ are
		only allowed within comments or between %C and %ENDC
		directives.

41   error	"Illegal nested unitselection"
		A variable that was defined as an USEL must not be
		used within the brackets { and } of a definition of a
		unit-selection.

42   warning	"Unexpected procedure identifier"
		A name of a procedure should not be used as a parameter
		unless declared by a C- declaration.

43   error	"Illegal Preprocessor-directive"
		You must not use the %include directive inside C-code
		that is written between %C and %ENDC directives, use
		#include "filename" instead (the # sign must be in the
		first column).
