Freon Documentation (version 0.5.0)

What is Projectional Editing?

The essential characteristic of projectional editing is that the user manipulates the Abstract Syntax Tree (AST) directly. In contrast, the traditional manner of editing is that a user manipulates a text-string, which is then (re)parsed into a (changed) AST.

For a generic view on projectional editing see this page on Wikipedia.

Projectional workflow

The overall flow in a projectional editor generated by Freon is shown in this figure.

Image 'projection-overview.png' seems to be missing
Figure 1. General flow of projectional editing
  1. The model/AST is mapped to a visual presentation (the projection).
  2. The projection is shown to the user.
  3. The user performs an action on the projection.
  4. The action on the projection is mapped to an action on the model/AST.
  5. (or 1 again) The changed model/AST is (re)mapped to a visual representation.

Support For Expressions

Editing expressions in a projectional editor is a well-known challenge. The representation of an expression in the AST is highly structured. Yet, because its appearance to the user looks textual, users expect that the editing behavior resembles classical text editing as much as possible.

In Efficiency of Projectional Editing: A Controlled Experiment the authors express the problem as follows.

Editing expressions with their fine-grained tree structure is one of the major challenges in a projectional editor. The inability to insert and remove parentheses in arbitrary places (and then refactor the treestructure according to the precedence expressed by the parentheses) is an example.

[Markus Voelter a.o., Efficiency of Projectional Editing]

For this reason, Freon has in-build support for expressions. There is extra functionality to be able to add an expression before or after an existing expression. Secondly, the AST of any binary expression is automatically balanced.

Adding to an Existing Expression

Image 'expressions-problem.png' seems to be missing
Figure 2. Editing expressions

In the above figure, when the user types a + symbol after the **, it is not enough to simply add the + in the AST.

  • First of all, a placeholder should be added to make the expression structurally correct, so we should see something like
    • a * ... + b.
  • Doing so will lead to the second AST shown.
  • But … this AST is not balanced right!
    • When adding parenthesis to show the AST, this will look like a * (... + b)
    • But the user (using his knowledge of priorities of ** and +) will read (a * ...) + b.
  • Therefore, the AST needs to be re-balanced to take the priorities of the multiplication and addition into account. This re-balancing leads to the third AST show, where the structure of the AST properly reflects what the user understands.

Freon understands this kind of tree balancing and will automatically apply them while editing expressions.


Typical user actions are to create a new element in the AST, to change the content of an element, or to delete an element.

Certainly, these changes may need to be persisted. When the user triggers the menu actions save unit or open unit the AST is pushed to or retrieved from a server.

Image 'projection-overview.png' seems to be missing
Figure 3. General flow of projectional editing