How to use Gymnast Generator
Gymnast is a framework for jumpstarting text editors for custom Domain Specific Languages, written by Chris Daly, and summarized in these slides.
Gymnast is being distributed along with Emfatic, as their developer communities overlap (at least, so far).
In the past, many improvements has been included in Gymnast. For example, JavaCC and Antlr lexer files can be autogenerated now instead of manually creating and adding them to the project. This article reflects those changes made to the Gymnast framework. Please refer to Grammar2Ecore for details on the generation of Java classes from grammar.
Where to download Gymnast from
Gymnast comprises two main parts (Runtime and Generator), each of which can in turn be divided into Core and User Interface. This section is all about using the Gymnast Generator to:
- configure options in that file
- autogenerate lexer files, and
- manually add the parser's
.jarto the (Build path or Plugin dependencies)
so that POJO-style CST classes can be generated and compiled. More details are discussed in the technical report Generation of Eclipse-based IDEs for Custom DSLs
Let's say we want to reproduce the steps to generate POJO CST classes for Emfatic.
- An Eclipse project should be created and a grammar file (emfatic.ast) is added, to look as shown in Figure 1.
- Dependent Plug-ins are added in the MANIFEST.MF file. Hence right clicking on the grammar file shows options like 'Generate .genmodel and Java', 'Generate JavaCC lexer file', 'Generate Antlrv2 lexer file' etc. Refer Figure 2.
Generation of lexer files
The grammar file can be checked for well-formedness by clicking 'Check Well-formedness' from the context menu. After checking for the well-formedness of the grammar, JavaCC and Antlr lexer files can be auto generated by clicking 'Generate JavaCC lexer file' and 'Generate Antlrv2 lexer file' from the context menu of the grammar file. This autogeneration of lexer files is one of the enhancements made to Gymnast. In this example, emfaticLexer.jj and emfaticLexer.g are JavaCC and Antlr lexer files respectively (Figure 3).
Generation of AST and Parser
After the generator is run (by rightclicking on
emfatic.ast and choosing "Generate AST") the result looks as in Figure
Not shown here is the added plugin dependency to
org.antlr, which can be installed as described in the next section.
Gymnast reports its operation on the console:
What if you target ANTLR instead of JavaCC
In that case, the code generated for the parsing infrastructure will depend on the ANTLR parser generator framework. The easiest way to install a plugin with ANTLR is to get it from the update site on SourceForge by following these steps: <p/>
- In Eclipse, go to Help -> Software Updates -> Find and Install....
- Select Search for new features to install and click on Next.
- Press the New Remote Site... button and enter the following values:
Choosing target parser
The choice of target parser is made with the option
parserGenerator = ". . ." (Figure 6). Unlike ANTLR, JavaCC requires no runtime library: all the code it needs gets generated.
Exploring the generated artifacts
The generated grammar files (for the ANTLR example the one highlighted in Figure 7) are not supposed to be messed up by the user, however in order to explore them the following Eclipse plug-ins prove useful:
- for JavaCC
- for ANTLR v2 grammars
- for ANTLR v3 grammars (although Gymnast Generator generates as of now only v2 grammar files)
- JikesPG Grammar Editor (it's planned for Gymnast Generator to generate JikesPG grammar files, see plugin org.eclipse.gymnast.generators.parser.lpg)
The generated POJO-style CST classes:
- exhibit useful patterns for later processing (visiting in particular)
- are independent from the chosen parser generator
The input-output relationship and the resulting code patterns are described by Gymnast's author, Chris J Daly, in an Eclipse Tech Panel Exchange presentation, available here.
The parser-generator-independent CST classes generated by Gymnast Generator implement
org.eclipse.gymnast.runtime.core.ast.ASTNode (Figure 8).
A sample POJO-style CST class is depicted in Figure 9, corresponding to the following grammar production.
sequence classDecl : (abstractModifier)? classKind name=ID (typeParamsInfo=typeParamsInfo)? ("extends" superTypes=commaListBoundExceptWild)? (COLON instClassName=boundExceptWildcard)? LCURLY classMemberDecls RCURLY ;
- Miguel Garcia
- Chris Daly