Generate Web Editor from ANTLR

Use this tutorial to get a standalone (in the sense not wired to any Java back-end) Web Editor written in HTML, CSS, and JavaScript. The editor is packaged in the form of an Eclipse plugin. The language is specified with ANTLR, a builder is provided to update the infrastructure on-the-fly. Simply edit the grammar with ANTLR v3 and save the specification, the infrastructure is kept up-to-date with the grammar.

The editor is based on Cloud9’s ACE editor (ajax.org).

Prerequisites

Before using the generator, make sure you have the following environment:

Eclipse Web Tools Platform (WTP),
DSL Forge Tooling installed.

The Pirate Robot example

We take a simplified example of the PirateRobot language. In this tutorial, we generate an editor for a very simple language for instructing actions to a robot: it can go up, down, jump, fight, etc. More information about the example can be found in modeling-languages.com

Here are the steps to get a text editor for the language:

In Eclipse, click File > New > Project …
Expand DSL Forge category,
Select Generate Web Editor from ANTLR,
Enter the project name, for example org.codingpark.piraterobot,
Enter the name of the language grammar, for example PirateRobot,
Finish!

New ACE/ANTLR Generator

Enter the project and the grammar names

The Generator outputs a parser and lexer, and does the wiring with ACE (language mode and a worker responsible for syntax validation). The grammar is localized in the “PirateRobot.g” file.

/*Generated by DSLFORGE*/

grammar Piraterobot;

options {
language=JavaScript;
output=AST;
ASTLabelType=CommonTree;
}

@lexer::header {
}

@parser::header {
}

rule_PlayModel:
actions+= rule_Action*
;

ID : (‘a’..’z’ | ‘A’..’Z’ | ‘_’) (‘a’..’z’ | ‘A’..’Z’ | ‘_’ | ‘0’..’9′)* ;

STRING : (‘”‘ (‘\\’ (‘b’|’t’|’n’|’f’|’r’|’u’|'”‘|’\”|’\\’)|~((‘\\’|'”‘)))* ‘”‘|’\” (‘\\’ (‘b’|’t’|’n’|’f’|’r’|’u’|'”‘|’\”|’\\’)|~((‘\\’|’\”)))* ‘\”);

COMMENT : (‘/*’ .* ‘*/’ | ‘//’ ~(‘\r’ | ‘\n’)*) { $channel = HIDDEN; } ;

WS: (‘ ‘|’\r’|’\t’|’\u000C’|’\n’) {$channel=HIDDEN;} ;

INT: (‘0’..’9′)+;

This grammar is a starting point, when you change the grammar and save the file, (1) the builder regenerates the parser on-the-fly under WebContent/ace/parser. Then you have to (2) synchronize the ACE modules with the grammar using the contextual menu action.

Both steps are illustrated below.

1. Customize the Grammar

Whenever the grammar file is modified, the ANTLR Builder generates automatically the parser and lexer for the laguage. If the grammar is correct, you should have something like this in the console output.

ANTLR Parser Generator Version 3.3 Nov 30, 2010 11:52:12.
Grammar: /org.codingpark.piraterobot/WebContent/parser/Piraterobot.g
BUILD SUCCESS
Total time: 196 ms

Otherwise, you’ll have the ANTLR errors:

line 27:37 mismatched input ‘)’ expecting ‘:’
line 28:9 mismatched input ‘?’ expecting ‘:’
line 28:34 mismatched input ‘=’ expecting ‘:’
line 28:39 mismatched input ‘)’ expecting ‘:’

ANTLR v3 Builder

2. Regenerate ACE modules

Once the parser/lexer regenerated by the incremental builder, the ACE mode and worker can be synchronized by right clicking on the grammar file and selecting Generate artefacts from ANTLR action. The action is accessible from the package explorer, and the ANTLR editor as well.

Generate ACE Artefacts

Run the Web Editor

Under Eclipse WTP, use the HTTP Preview server as a runtime server, for viewing the generated web project. The Preview server is embedded as test serer integrated with the workbench; a convenient way to check for errors before deploying on real servers.

To create the server, here are the steps:

In the Servers View, right-click then select New > Server.

In New Server wizard, under the Select the server type list, Under Basic, select HTTP Preview. Click Next.

Define New Server

In Add and Remove. Under Available projects, select the Web project and click Add button. Click Finish. The HTTP Preview server should be visible in the Servers view.

In the Project Explorer view, navigate to the Web project, right-click on the index file, Select Run As > Run on Server.

In the Server wizard, verify Choose an existing server is enabled. Under Select the server that you want to use, select your sever. Click Next.

The Add and Remove page opens. Verify the project is listed under Configured projects. Click Finish.

Supported Browsers

Chrome is preferred, as the Eclipse default browser doesn’t implement the Shared Worker specification; multithreading will work only between each editor and its language worker, however the global index will not be initialized.

Eclipse Internal Browser

Exploring the Web Editor project

The WebContent/ace folder contains the ACE files, mainly:

ace.js : this is the base script that manages all ACE modules. This script is kept as-is from the ACE repository, no need to tweak it.
ext-language_tools : this is the modules which manages the content assist popup. The original script has been adapted to the DSL editors
ext-searchbox : manages the search function (CRTL+F)
ext-tooltip : display the text hover
mode-language: ACE uses the so called “modes” to embed language-specific attributes, such as syntax highlighting, code folding, brace matching, etc.
worker-language : a JavaScript worker which manages the interaction between the generated parser and lexer, and the language mode.
eclipse-theme : contains the CSS theme of the editor.

In WebContent/ace/snippets, there is the templates file loaded by ACE Language Tools module, so that the templates appear in the content assist popup.

In WebContent/ace/parser package, there is the generated parser and lexer, and the ANTLR v3.3 library necessary to run the parser and lexer with JavaScript as target.