<commit_before># Day 3: Syntactic Editor Services

In this lab, you add a pretty-printer and syntactic editor services to your MiniJava editor.

## Overview

### Objectives

1. Extend generated folding rules with hand-written rules. 
You should include only structures, where folding is reasonable. 
2. Integrate generated pretty-printing rules and completion templates into your MiniJava editor.
Improve your syntax definition to support 
  * textual labels in these templates,
  * hiding optional placeholders,
  * multi-line templates and
  * consistent indentation.
3. Extend your editor with additional, hand-written completion templates.

### Submission

You need to submit your MiniJava project with a pull request against branch `assignment3` on GitHub. 
Your GitHub repository contains a step-by-step procedure how to file such a request. 
As part of your submission, we ask you to provide a short explanation of the organisation of your syntax definition in `MiniJava/syntax/README.md`. 
The deadline for submission is October 8, 17:59.

### Grading

You can earn up to 10 points for your folding patterns.
We will take the overall editor experience into account and
we will deduct points for too many (and by this unusable) folding options.

You can further earn up to 70 points for your improved syntax templates.
We will focus on readability of pretty-printed code and completion suggestions and 
on consistent indentations.

Finally, you can earn up to 20 points for hand-written completion templates.

## Detailed Instructions

### Anatomy of a Spoofax Project

Until now, you mainly worked on files in the `syntax` folder of your project. 
During this lab you will also edit files in the `editor` and `trans` folders.
So this is a good point to talk about the general structure of a Spoofax project.

First of all, every Spoofax project is an Eclipse plug-in project. 
This allows you to deploy your editor as a plugin using the Eclipse update site mechanism. 
Users do not need to have Spoofax installed for using your editor. 
You will find the typical administrative boilerplate code for such plug-ins in files 
`plugin.xml`, `build.properties`, `META-INF/MANIFEST.MF`, and `editor/java`.

The actual language definition is spread over three folders:

* `syntax` contains all syntax definition files, including the main file `MiniJava.sdf3`.
* `trans` contains all transformation files, including the main file `minijava.str`. 
* `editor` contains editor service definition files, including the main file `MiniJava.main.esv`,
  which you have seen already during the last lab.
  
In the `src-gen` folder, you will find files which were generated from your syntax definition. 
For each file `<name>.sdf3`, there are generated files

* `syntax/<name>.sdf`: an SDF2 definition which is equivalent to the SDF3 definition.
* `editor/<name>.generated.esv`: completion templates derived from SDF3 templates.
* `trans/<name>.pp.generated.str`: pretty-printing strategies derived from SDF3 templates.

You can find more generated files in `editor` and `include` folders:

* `editor/MiniJava-Folding.generated.esv`: folding patterns derived from your syntax definition.
* `include/MiniJava.def`: your complete syntax definition in SDF2.
* `include/MiniJava-Permissive.def`: a permissive version of the syntax definition, which supports error recovery.
* `include/MiniJava.tbl`: the parse table of your language.
* `include/MiniJava.str`: the signature for ASTs of your language.
* `include/MiniJava-parenthesize.str`: strategies to add parentheses to an AST according to the priorities of your language.
* `include/minijava.ctree` and/or `include/minijava.jar`: compiled Stratego code of your language.

### Preliminaries

Before you start with the actual assignment, you should make sure that

1. your syntax definition provides all start symbols needed by your test cases,
2. your context-free syntax is specified in templates of the form

        Sort             = <...>
        Sort.Constructor = <...>
        Sort             = [...]
        Sort.Constructor = [...]

3. your start symbol is set to `Program` or `Start` so that your editor accepts only complete MiniJava programs. 

### Folding Rules

Presentational editor services such as code folding and syntax highlighting are defined 
in `.esv` files in the `editor` folder.
When you build your editor and open a MiniJava file, you can see that the editor provides already some folding points.
These points are syntax-dependent and are specified by folding rules in `editor/MiniJava-Folding.generated.esv`.
All editor services follow the same basic structure: 
they have a derived file (`EntityLang-Folding.generated.esv`) 
and a custom definition file (`EntityLang-Folding.esv`). 
The first file is automatically generated from your syntax definition, each time the project is built.
You can use the second file to customize the editor. 

Folding rules indicate which syntactic constructs can be folded, and take one of the following forms:

    <Sort>.<Constructor>
    <Sort>._
    _.<Constructor>

The `(folded)` annotation can be used for constructs that should be folded automatically:

    _.Imports (folded)
<commit_msg>be more precise about esv start symbol<commit_after># Day 3: Syntactic Editor Services

In this lab, you add a pretty-printer and syntactic editor services to your MiniJava editor.

## Overview

### Objectives

1. Extend generated folding rules with hand-written rules. 
You should include only structures, where folding is reasonable. 
2. Integrate generated pretty-printing rules and completion templates into your MiniJava editor.
Improve your syntax definition to support 
  * textual labels in these templates,
  * hiding optional placeholders,
  * multi-line templates and
  * consistent indentation.
3. Extend your editor with additional, hand-written completion templates.

### Submission

You need to submit your MiniJava project with a pull request against branch `assignment3` on GitHub. 
Your GitHub repository contains a step-by-step procedure how to file such a request. 
As part of your submission, we ask you to provide a short explanation of the organisation of your syntax definition in `MiniJava/syntax/README.md`. 
The deadline for submission is October 8, 17:59.

### Grading

You can earn up to 10 points for your folding patterns.
We will take the overall editor experience into account and
we will deduct points for too many (and by this unusable) folding options.

You can further earn up to 70 points for your improved syntax templates.
We will focus on readability of pretty-printed code and completion suggestions and 
on consistent indentations.

Finally, you can earn up to 20 points for hand-written completion templates.

## Detailed Instructions

### Anatomy of a Spoofax Project

Until now, you mainly worked on files in the `syntax` folder of your project. 
During this lab you will also edit files in the `editor` and `trans` folders.
So this is a good point to talk about the general structure of a Spoofax project.

First of all, every Spoofax project is an Eclipse plug-in project. 
This allows you to deploy your editor as a plugin using the Eclipse update site mechanism. 
Users do not need to have Spoofax installed for using your editor. 
You will find the typical administrative boilerplate code for such plug-ins in files 
`plugin.xml`, `build.properties`, `META-INF/MANIFEST.MF`, and `editor/java`.

The actual language definition is spread over three folders:

* `syntax` contains all syntax definition files, including the main file `MiniJava.sdf3`.
* `trans` contains all transformation files, including the main file `minijava.str`. 
* `editor` contains editor service definition files, including the main file `MiniJava.main.esv`,
  which you have seen already during the last lab.
  
In the `src-gen` folder, you will find files which were generated from your syntax definition. 
For each file `<name>.sdf3`, there are generated files

* `syntax/<name>.sdf`: an SDF2 definition which is equivalent to the SDF3 definition.
* `editor/<name>.generated.esv`: completion templates derived from SDF3 templates.
* `trans/<name>.pp.generated.str`: pretty-printing strategies derived from SDF3 templates.

You can find more generated files in `editor` and `include` folders:

* `editor/MiniJava-Folding.generated.esv`: folding patterns derived from your syntax definition.
* `include/MiniJava.def`: your complete syntax definition in SDF2.
* `include/MiniJava-Permissive.def`: a permissive version of the syntax definition, which supports error recovery.
* `include/MiniJava.tbl`: the parse table of your language.
* `include/MiniJava.str`: the signature for ASTs of your language.
* `include/MiniJava-parenthesize.str`: strategies to add parentheses to an AST according to the priorities of your language.
* `include/minijava.ctree` and/or `include/minijava.jar`: compiled Stratego code of your language.

### Preliminaries

Before you start with the actual assignment, you should make sure that

1. your syntax definition provides all start symbols needed by your test cases,
2. your context-free syntax is specified in templates of the form

        Sort             = <...>
        Sort.Constructor = <...>
        Sort             = [...]
        Sort.Constructor = [...]

3. your start symbol in `editor/MiniJava.main.esv` is set to `Program` or `Start` so that your editor accepts only complete MiniJava programs. 

### Folding Rules

Presentational editor services such as code folding and syntax highlighting are defined 
in `.esv` files in the `editor` folder.
When you build your editor and open a MiniJava file, you can see that the editor provides already some folding points.
These points are syntax-dependent and are specified by folding rules in `editor/MiniJava-Folding.generated.esv`.
All editor services follow the same basic structure: 
they have a derived file (`EntityLang-Folding.generated.esv`) 
and a custom definition file (`EntityLang-Folding.esv`). 
The first file is automatically generated from your syntax definition, each time the project is built.
You can use the second file to customize the editor. 

Folding rules indicate which syntactic constructs can be folded, and take one of the following forms:

    <Sort>.<Constructor>
    <Sort>._
    _.<Constructor>

The `(folded)` annotation can be used for constructs that should be folded automatically:

    _.Imports (folded)

{'fraction_non_alphanumeric': 0.06456241032998565, 'fraction_numerical': 0.004973696795791487, 'mean_word_length': 4.217564870259481, 'pattern_counts': {'":': 0, '<': 23, '<?xml version=': 0, '>': 23, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 2}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '6927592', 'n_tokens_mistral': 2771, 'n_tokens_neox': 2620, 'n_words': 1392}