The EBNF Grammar for Editor Specifications

An editor specification starts with an optional package declaration (it is strongly encouraged to really declare a package), followed by the declarations of the edge types (diagram components and relations of the SRHG, terminal and nonterminal edges of the HGM). The declaration of the constraint manager which is used in the editor's intelligent mode is optional, too. If this declaration is omitted, intelligent mode is not available for the specified editor. The actual diagram language specification consists of the reducer (lexical analysis) and the hypergraph grammar (used by syntactic and semantic analysis). Finally, complex operations may be specified in order to support syntax-directed editing.

Specification ::= ( PackageDef )? Declarations ( ConstraintMgr )? ( ModelClass )? Reducer Grammar ( Operations )? <EOF>

The package declaration for the generated files. If specified, all files are generated in this package. The directory of this package has a path which starts at the base directory. This is either the working directory or the base directory which has to be specified by using the -b option of the generator.

PackageDef ::= "package" QualifiedName ";"

The declaration of the edge types which are used in this specification. Declarations can be written down in any order.

Declarations ::= ( SRHGDeclaration | GrammarDeclaration )*

Edge types for the SRHG are either diagram components or relation edges. You can declare more that one component or relation edge in one declaration by separating declared edge types by commas.

SRHGDeclaration ::= ( "component" ComponentDeclaration ( "," ComponentDeclaration )* | "relation" RelationDeclaration ( "," RelationDeclaration )* | "link_edge" LinkDeclaration ( "," LinkDeclaration )* ) ";"

Each SRHG edge type is specified by its name and the edge arity (i.e., its number of tentacles) in brackets. Optionally, a supertype may be declared. This supertype has to be a declared type of the same kind (i.e., component, relation, or link) with an arity which is not less than the arity of the edge type which is just being declared.

SRHGEdgeDeclaration ::= Identifier "[" Integer "]" ( "isa" Identifier ( "," Identifier )* )?

A component edge declaration either defines a fixed or a variable number of attachment areas.

ComponentDeclaration ::= FixedComponentDeclaration | VarComponentDeclaration

A component edge declaration must specify exactly one implementation class, or no implementation class if this edge type is used as an (abstract) supertype.

FixedComponentDeclaration ::= SRHGEdgeDeclaration ( "{" QualifiedName "[" AttachDeclaration "]" "}" )?

A component edge declaration must specify exactly one implementation class, or no implementation class if this edge type is used as an (abstract) supertype.

VarComponentDeclaration ::= Identifier "[" "*" "]" ( "isa" Identifier ( "," Identifier )* )? "{" QualifiedName "{" Identifier ( "," Identifier )? "}" "}"

A relation edge declaration must specify at least one implementation, or no implementation if this edge type is used as an (abstract) supertype.

RelationDeclaration ::= SRHGEdgeDeclaration ( "{" RelationImplDeclaration ( "," RelationImplDeclaration )* "}" )?

A relation can be implemented in the form of an explicit skeleton class similar to a component skeleton class. Alternatively, the implementation declaration can specify only a static relation test method, which is indicated by paretheses around the attachment declarations instead of brackets. In this case, an anonymous implementation is automatically generated, which calls the specified static relation test method

RelationImplDeclaration ::= QualifiedName ( "(" AttachDeclaration ")" | "[" AttachDeclaration "]" )?

A link edge declaration must not specify an implementation class. Link edges may be declared as transient; those link edges are always removed from the srhg after the next reducing process

LinkDeclaration ::= SRHGEdgeDeclaration ( "transient" )?

An implementation declaration for a component or a relation edge must specify a list of connector names:

• For component edges, this list specifies the types of the corresponding connectors and thus the types of the corrsponding hyperedge tentacles. The length of this list has to correspond to the arity of the hyperedge type.
• For relation edges, this list has to consist of two connector types which have to be specified in some component edge declaration. The specified relation edge will only be created between nodes which are visited by tentacles of the specified type (but of course only if the test method of the specified class returns true.)

An attribute declaration list has a similar syntax as the declaration of member variables in Java. Type names may be qualified class names (if the class name is not qualified, the class is expected to exist in the package which has been specified in the package declaration). A special type name is Variable which specifies constraint variables.

AttributeDeclaration ::= "{" ( QualifiedName ( "[" "]" )? Identifier ( "," Identifier )* ";" )+ "}"

The optional constraint manager specification. Currently, only QOCA (use diagen.editor.param.QocaLayoutConstraintMgr as qualified name) and application specific layouters which have to be programmed manually (use diagen.editor.param.CustomizedConstraintMgr) are really supported.

ConstraintMgr ::= "constraintmanager" QualifiedName ";"

The optional specification of a diagram model class. Usually the default class diagen.editor.graph.GraphModel will be sufficient here, but you can use your own subclass instead, e.g. if you need to associate additional information with you diagrams

ModelClass ::= "model_class" QualifiedName ";"

The reducer (lexical analysis) consists of a list of reduction rules. Each rule has to be terminated by a semicolon.

Reducer ::= "reducer" "{" ( ReductionRule ";" )* "}"

Each reduction rule consists of an LHS, an arrow "==>", an RHS, an optional list of actions which are executed if this rule is applied, and an optional condition (boolean expressions, path expressions, etc.) which must hold if this rule is going to be applied. The LHS consists of a non-empty list of component or relation edges and, optionally, of negative contexts. The RHS consists of an optionally empty list of terminal edges and/or unification of nodes. LHS and RHS edges may be labeled by arbitrary identifiers which may be used in the action list to refer to the corresponding edges.

The semantics of such a rule are as follows:

• The LHS edges and the negative context specifications describe a hypergraph. The set of edges is explicitly specified in the corresponding lists. The node names which are used in the edge specifications, define the set of nodes. Nodes which are referred to by different edges, but which carry the same name, are considered to be the same node. The RHS also specifies a graph. However, nodes which carry the same label in the LHS and RHS are not considered to be equal.
• The rule is applied if the hypergraph which is specified by the LHS can be matched with a sub-hypergraph of the SRHG and none of the additionally specified negative context subgraphs can be matched, too. Furthermore, the optional logical condition must hold, too
• If the rule is applied, the corresponding RHS is added to the HGM; the SRHG is not modified by this rule. Nodes with the same label in the LHS and the RHS refer to corresponding nodes of the SRHG and the HGM. Therefore, the context hypergraph of the HGM, where the RHS has to fit in, is specified by those nodes of the rule which carry the same label in the LHS and RHS.
• If the rule is applied and the rule specifies unification of rules, the corresponding nodes of the HGM are unified. This has NO effect on the nodes of the SRHG.
• The specified actions are only executed if the rule is applied.

A negative context specifies a hypergraph together with an optional logical condition (boolean expressions, path expressions, etc.). A negative context is matched together with the LHS of a reduction rule. But this context does not apply, i.e., does not prevent application of a reduction rule, if the optional condition does not hold. The condition has access to nodes and hyperedges of this context as well as of the LHS of the corresponding reduction rule.

NegativeContext ::= "-" "{" ( ( Identifier ":" )? SRHGEdge )+ ( "where" LogicalExpr )? "}"

A reduction rule can assign values of LHS components to attributes of RHS terminal edges, it can call a static method, it can declare local constraint variables and it may add constraints to the constraint network that determines the layout.

ReducerAttributeActions ::= ( ReducerAttributeAssignment ";" )* ( MethodInvocation ";" )* ( LocalCVarDeclaration )* ( ConstraintDecl )?

If a reduction rule is applied, it may invoke a method of the specified LHS diagram component which is represented by its component hyperedge. The parameters of this method are LHS edges (of type diagen.hypergraph.Edge) . The return value of this method, if any, is then assigned to an attribute of an RHS terminal edge. Edges are referred to by labels which must have been declared in the LHS resp. RHS of the corresponding reduction rule.

ReducerAttributeAssignment ::= AttributeAccess "=" Identifier "." Identifier "(" ( RefOpEdge ( "," RefOpEdge )* )? ")"

An attribute of an edge is specified by the label of the edge which must have been declared before, a ".", and the name of the attribute. An attribute in angles indicates an array of corresponding attributes of all the rhs edges of a set production instance.

AttributeAccess ::= Identifier "." Identifier | "<<" Identifier "." Identifier ">>"

If a reduction rule is applied, it may unify nodes of the HGM. Nodes are referred to by node names which are used in the LHS of the rule. These LHS nodes must have been matched with SRHG nodes. However, these SRHG nodes are not unified, but their corresponding HGM nodes. Node unification does not have any effect on the SRHG.

UnifiedNodes ::= Node ( "=" Node )+

A grammar specification consists of the specification of the grammar's axiom, i.e., the starting edge type, and some productions. Currently, DiaGen only supports context-free hypergraph grammars with embeddings, i.e., each production is either a context-free one or an embedding production.

Grammar ::= "grammar" "{" StartingSymbol ( ContextfreeProduction | EmbeddingProduction )* "}"

The grammar's axiom is specified by a nonterminal hyperedge type. An attribute of this edge type can optionally be specified. The value of this attribute is then used as the semantic representation of the subhypergraph, i.e., subdiagram, that is derived from an instance of this starting edge (see method semantics() in class DiagramModelEvent)

StartingSymbol ::= "start" Identifier ( "<" Identifier ">" )? ";"

A context-free production's LHS consists of a single nonterminal edge. This edge may be labeled by an identifier which may be used to refer to this edge. You can specify multiple right-hand sides for a single LHS edge by using "|".

ContextfreeProduction ::= ( Identifier ":" )? NonterminalEdge "::=" ContextfreeRHS ( "|" ContextfreeRHS )* ";"

The RHS of a context-free production is a hypergraph which consists of terminal and nonterminal hyperedges and which is augmented by conditions, semantic actions, and layout constraints. Or it is a set of identically labeled edges which visit the same nodes with specified tentacles.

ContextfreeRHS ::= ExtendedRHS | SetRHS

The rhs of a set production consists of an optional multiplicity specification, a nonterminal edge, and optional attribute evaluation rules. The multiplicity specifies how often the specified edge has to occur. The edge is specified with named nodes and undetermined nodes (_). All edges which visit the same nodes with those tentacles which are specified by named nodes form the rhs of the reduction. The optional evaulation rules apply to each of these edges.

SetRHS ::= ( Integer "*" )? "<<" ( Identifier ":" )? Edge ">>" ( "<" Identifier ">" )? ( "sort_by" Identifier ( "," QualifiedName )? )? ( "{" ( EvaluationRule )* "}" )?

An embedding production embeds an edge (either terminal or nonterminal) into a context hypergraph which consists of terminal and nonterminal hyperedges and which is augmented by conditions, semantic actions, and layout constraints. The context hyperhraph must contain a "*" for specifying the embedding position. "*" has to be specified since the embedding edge has to be found by the parser as part of the context hypergraph. The embedded edge may be labeled by an identifier which may be used to refer to this edge.

EmbeddingProduction ::= "embed" ( Identifier ":" )? Edge "into" ExtendedRHS ";"

The RHS of a context-free production which is not a set production or the context hypergraph of an embedding production. It consists of a hypergraph with terminal and/or nonterminal edges, an optional "!" to enforce the test of the gluing condition (this test is omitted by default for error tolerant parsing), an optional condition that must hold if the RHS hypergraph is going to be reduced (either to the LHS if this belongs to a context-free production, or to some intermediate structure which is responsible for detecting embedding production instances). The optional list of actions is executed if the corresponding production is reduced. This list may contain constraints which are then added to the constraint system that determines the diagram's layout.

ExtendedRHS ::= RHS ( "!" )? ( "<" Identifier ">" )? ( "if" LogicalExpr )? ( "{" GrammarAttributeActions "}" )?

The plain RHS hypergraph of a context-free production or the plain context hypergraph of an embedding production. The hypergraph is specified by a list of hyperedges. The nodes are implicitly specified like in the LHS and RHS of a reduction rule. Edges may be labeled by arbitrary identifiers which can be used to refer to these edges.

The hyperedge list may be structured by brackets. The DiaGen hypergraph parser requires productions to be in extended Chomsky normalform, i.e., the RHS of a context-free production must not have more than two hyperedges. The DiaGen generator transforms each RHS into a suitable form if necessary. Brackets can be used to give hints to the generator which parts of the RHS should be reduced first. The generator implicitly adds brackets in a left-associative manner if no brackets or not all of them are specified.

A special hyperedge symbol is "*" which is used to represent the embedded hyperedge in an embedding production. The position of the "*" is crucial since the parser has to find the embedded edge as part of its context. The "*" therefore specifies when to search for the embedding edge relative to its context. Brackets can also be used to influence this search process.

RHS ::= ( ( Identifier ":" )? Edge | "*" | "[" RHS "]" )+

A production can have attritute evaluation rules, it can declare local constraint variables, and it may add constraints to the constraint network that determines the layout.

GrammarAttributeActions ::= ( EvaluationRule | LocalCVarDeclaration )* ( ConstraintDecl )?

An attribute evaluation rule is either a method call where the return value, if any, is assigned to an attribute or an attribute assignment. There is no prescribed order how to evaluate attributes (e.g., bottom-up or top down in case of a syntax tree). Any dependency between attributes can be specified. However, you can end up with circular dependencies which cannot be solved.

EvaluationRule ::= MethodCall ";" | AttributeAccess "=" ( MethodCall | AttributeAccess ) ";"

A method call which is used in an attribute evaluation rule may call a static method which is specified by its qualified name. If the class name of the corresponding class is not fully qualified, the class is expected to exist in the package which has been specified in the package declaration.

MethodCall ::= QualifiedName "(" ( AttributeAccess ( "," AttributeAccess )* )? ")"

The section which specifies complex editing operations. Each operation may make use of simple transformation rules on the SRHG which have to be specified in this section, too.

Operations ::= "operations" "{" ( ( OperatorRule | Operation ) ";" )* "}"

do-part to refer to the edges.

   rule outer arg:e(a) 
     call [res] = inner(arg) 
     return res; // could only return arg here
   

  forall [a,b,c]=rule(x,y,z) ( foo(a) | baz(b,c) )