doc/org.eclipse.gymnast.generator.doc.user/html/howto.html - emfatic/org.eclipse.emfatic - Git at Google

 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">

 <html>
 <head>
 	<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
 	<link rel="STYLESHEET" href="book.css" charset="ISO-8859-1" type="text/css">
 	<title>How to use Gymnast Generator</title>
 </head>

 <body>
 <h1>How to use Gymnast Generator</h1>

 <h2>Overview</h2>
 <p>
 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:

 <ol>
   <li>create <code>.ast</code> files</li>
   <li>configure options in that file</li>
   <li>manually add a lexer file, and</li>
   <li>manually add the parser's <code>.jar</code> to the (Build path or Plugin dependencies)</li>
 </ol>

 so that POJO-style CST classes can be generated and compiled. IDEs generated by
 IDEalize rely on such parsing infrastructure, as discussed in Sec. 2.3 of the technical report
 <i><a href="http://www.sts.tu-harburg.de/%7Emi.garcia/SoC2007/draftreport.pdf">Generation of Eclipse-based IDEs for Custom DSLs</a></i>.
 </p>


 <p>
 Let's say we want to reproduce the steps to generate POJO CST classes for Emfatic.
 An Eclipse project should be created and an .ast and a lexer file added, to
 look as shown in Figure 1(a) (more on that lexer file later).

 <p></p>
 <p></p>

 <table border="0" cellpadding="8">
 	<tr>
 		<td><img src="img-ch2/HowToUseGymnast1.PNG" ></td>
 	</tr>
 	<caption align="bottom"><b>Figure 1(a)</b> Before Gymnast Generator</caption>

 </table>
 <p></p>

 After the generator is run (by
 rightclicking on <code>emfatic.ast</code> and choosing "Generate AST") the result looks as in Figure
 1(b).

 <p></p>
 <p></p>

 <table border="0" cellpadding="8">
 	<tr>
 		<td><img src="img-ch2/HowToUseGymnast2.PNG" ></td>
 	</tr>
 	<caption align="bottom"><b>Figure 1(b)</b> After Gymnast Generator</caption>

 </table>
 <p></p>


 Not shown here is the added plugin dependency to <code>org.antlr</code>, which can be
 installed as described next.
 </p>

 <h2>What if you target ANTLR instead of JavaCC</h2>

 <p>
 <b>Installing ANTLR Eclipse</b>
 Your 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/>
 <ol>
 <li>In Eclipse, go to <i>Help -> Software Updates -> Find and Install....</i></li>

 <li>Select <i>Search for new features to install</i> and click on Next.</li>
 <li>Press the <i>New Remote Site...</i> button and enter the following values:</li>
      <ul>
 	name: ANTLR  <br/>
 	url: http://antlreclipse.sourceforge.net/updates
      </ul>

 <li>Now check the new ANTLR checkbox and click on Next.  </li>
 <li>Select version 3.0.5 of the feature <i>org.antlr.ui</i> and click on Next.</li>
 <li>Accept the licensing terms and click on Next and Finish.</li>
 <li>Click on <i>Install</i> when you see a pop-up message warning about unsigned features.</li>
 <li>When prompted, click on Yes to restart the workbench.</li>
 </ol>

 <h2>Choosing target parser, and providing the parser-dependent lexer file</h2>

 <p>
 The choice of target parser is made with the option <code>parserGenerator = ". . ."</code>
 (Figure 2). Unlike ANTLR, JavaCC requires no runtime library: all the code it
 needs gets generated.
 </p>
 <p>
 The lexer file (<code>emfaticLexer.g</code> in the ANTLR example) is actually constant for all
 <code>.ast</code>s we care to write. It can be copied from <code>org.eclipse.gymnast.generator.core.parser</code>
 (the file ending in <code>.g</code> is the ANTLR one, ending in <code>.jj</code> the JavaCC one) The
 only thing that needs updating are its filename (to match the name of the DSL in
 question) and, in the case of ANTLR, the first line in the lexer file (because such
 heading also contains the name of the DSL).
 </p>

 <p></p>
 <p></p>

 <table border="0" cellpadding="8">
 	<tr>
 		<td><img src="img-ch2/antlrOption.PNG" ></td>
 	</tr>
 	<caption align="bottom"><b>Figure 2</b> How to choose a parser</caption>

 </table>
 <p></p>

 <h2>Exploring the generated artifacts</h2>

 The generated grammar files (for the ANTLR example the one highlighted in
 Figure 3) are not supposed to be messed up by the user, however in order to explore
 them the following Eclipse plugins prove useful:

 <ul>
   <li><a href="http://sourceforge.net/projects/eclipse-javacc/">for JavaCC</a>
   </li>
   <li><a href="http://antlreclipse.sourceforge.net/">for ANTLR v2 grammars</a></li>
   </li>
   <li><a href="http://www.antlr.org/works/index.html">for ANTLR v3 grammars</a></li>
       (although Gymnast Generator generates as of now only v2 grammar files)
   </li>
   <li><a href="http://sourceforge.net/projects/jgedit">JikesPG Grammar Editor</a></li>
       (it's planned for Gymnast Generator to generate JikesPG grammar files, see plugin <code>org.eclipse.gymnast.generators.parser.lpg</code>)
   </li>
 </ul>

 <p></p>
 <p></p>
 <table border="0" cellpadding="8">
 	<tr>
 		<td><img src="img-ch2/generatedGrammarFile.PNG" ></td>
 	</tr>
 	<caption align="bottom"><b>Figure 3</b> Generated artifacts</caption>
 </table>
 <p></p>

 <h2>POJO-based CSTs</h2>

 The generated POJO-style CST classes:

 <ul>
 <li>exhibit useful patterns for later processing (visiting in particular)</li>
 <li>are independent from the chosen parser generator</li>
 </ul>


 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 <a href="http://www.sts.tu-harburg.de/~mi.garcia/SoC2007/GymnastSlides.pdf">here</a>.


 The parser-generator-independent CST classes generated by Gymnast Generator
 implement <code>org.eclipse.gymnast.runtime.core.ast.ASTNode</code> (Figure 4(a)).

 <p></p>
 <p></p>
 <table border="0" cellpadding="8">
 	<tr>
 		<td><img src="img-ch2/ASTNode.PNG" ></td>
 	</tr>
 	<caption align="bottom"><b>Figure 4(a) </b><code>ASTNode</code></caption>
 </table>
 <p></p>


 A sample
 POJO-style CST class is depicted in Figure 4(b), corresponding to the following
 grammar production:


 <table border="2" cellpadding="8">
 	<tr>
 		<td>
 <p class=MsoNormal style='text-autospace:none'><b><span style='font-size:8.0pt;
 font-family:"Courier New";color:red;background:yellow'>sequence</span></b><span
 style='font-size:8.0pt;font-family:"Courier New";color:black'> classDecl : (abstractModifier)?
 </span></p>

 <p class=MsoNormal style='text-autospace:none'><span style='font-size:8.0pt;
 font-family:"Courier New";color:black'>                     classKind name=ID </span></p>

 <p class=MsoNormal style='text-autospace:none'><span style='font-size:8.0pt;
 font-family:"Courier New";color:black'>                     (typeParamsInfo=typeParamsInfo)?</span></p>

 <p class=MsoNormal style='text-autospace:none'><span style='font-size:8.0pt;
 font-family:"Courier New";color:black'>                     (</span><b><span
 style='font-size:8.0pt;font-family:"Courier New";color:navy'>&quot;extends&quot;</span></b><span
 style='font-size:8.0pt;font-family:"Courier New";color:black'> superTypes=commaListBoundExceptWild)?
 </span></p>

 <p class=MsoNormal style='text-autospace:none'><span style='font-size:8.0pt;
 font-family:"Courier New";color:black'>                     (COLON instClassName=boundExceptWildcard)?
 </span></p>

 <p class=MsoNormal style='text-autospace:none'><span style='font-size:8.0pt;
 font-family:"Courier New";color:black'>                     LCURLY classMemberDecls
 RCURLY ;</span></p>

 </td></tr></table>


 <p></p>
 <p></p>
 <table border="0" cellpadding="8">
 	<tr>
 		<td><img src="img-ch2/ClassDecl.PNG" ></td>
 	</tr>
 	<caption align="bottom"><b>Figure 4(b) </b><code>ClassDecl</code></caption>
 </table>
 <p></p>


 </body>
 </html>
	<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">

	<html>
	<head>
	<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
	<link rel="STYLESHEET" href="book.css" charset="ISO-8859-1" type="text/css">
	<title>How to use Gymnast Generator</title>
	</head>

	<body>
	<h1>How to use Gymnast Generator</h1>

	<h2>Overview</h2>
	<p>
	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:

	<ol>
	<li>create <code>.ast</code> files</li>
	<li>configure options in that file</li>
	<li>manually add a lexer file, and</li>
	<li>manually add the parser's <code>.jar</code> to the (Build path or Plugin dependencies)</li>
	</ol>

	so that POJO-style CST classes can be generated and compiled. IDEs generated by
	IDEalize rely on such parsing infrastructure, as discussed in Sec. 2.3 of the technical report
	<i><a href="http://www.sts.tu-harburg.de/%7Emi.garcia/SoC2007/draftreport.pdf">Generation of Eclipse-based IDEs for Custom DSLs</a></i>.
	</p>


	<p>
	Let's say we want to reproduce the steps to generate POJO CST classes for Emfatic.
	An Eclipse project should be created and an .ast and a lexer file added, to
	look as shown in Figure 1(a) (more on that lexer file later).

	<p></p>
	<p></p>

	<table border="0" cellpadding="8">
	<tr>
	<td><img src="img-ch2/HowToUseGymnast1.PNG" ></td>
	</tr>
	<caption align="bottom"><b>Figure 1(a)</b> Before Gymnast Generator</caption>

	</table>
	<p></p>

	After the generator is run (by
	rightclicking on <code>emfatic.ast</code> and choosing "Generate AST") the result looks as in Figure
	1(b).

	<p></p>
	<p></p>

	<table border="0" cellpadding="8">
	<tr>
	<td><img src="img-ch2/HowToUseGymnast2.PNG" ></td>
	</tr>
	<caption align="bottom"><b>Figure 1(b)</b> After Gymnast Generator</caption>

	</table>
	<p></p>


	Not shown here is the added plugin dependency to <code>org.antlr</code>, which can be
	installed as described next.
	</p>

	<h2>What if you target ANTLR instead of JavaCC</h2>

	<p>
	<b>Installing ANTLR Eclipse</b>
	Your 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/>
	<ol>
	<li>In Eclipse, go to <i>Help -> Software Updates -> Find and Install....</i></li>

	<li>Select <i>Search for new features to install</i> and click on Next.</li>
	<li>Press the <i>New Remote Site...</i> button and enter the following values:</li>
	<ul>
	name: ANTLR <br/>
	url: http://antlreclipse.sourceforge.net/updates
	</ul>

	<li>Now check the new ANTLR checkbox and click on Next. </li>
	<li>Select version 3.0.5 of the feature <i>org.antlr.ui</i> and click on Next.</li>
	<li>Accept the licensing terms and click on Next and Finish.</li>
	<li>Click on <i>Install</i> when you see a pop-up message warning about unsigned features.</li>
	<li>When prompted, click on Yes to restart the workbench.</li>
	</ol>

	<h2>Choosing target parser, and providing the parser-dependent lexer file</h2>

	<p>
	The choice of target parser is made with the option <code>parserGenerator = ". . ."</code>
	(Figure 2). Unlike ANTLR, JavaCC requires no runtime library: all the code it
	needs gets generated.
	</p>
	<p>
	The lexer file (<code>emfaticLexer.g</code> in the ANTLR example) is actually constant for all
	<code>.ast</code>s we care to write. It can be copied from <code>org.eclipse.gymnast.generator.core.parser</code>
	(the file ending in <code>.g</code> is the ANTLR one, ending in <code>.jj</code> the JavaCC one) The
	only thing that needs updating are its filename (to match the name of the DSL in
	question) and, in the case of ANTLR, the first line in the lexer file (because such
	heading also contains the name of the DSL).
	</p>

	<p></p>
	<p></p>

	<table border="0" cellpadding="8">
	<tr>
	<td><img src="img-ch2/antlrOption.PNG" ></td>
	</tr>
	<caption align="bottom"><b>Figure 2</b> How to choose a parser</caption>

	</table>
	<p></p>

	<h2>Exploring the generated artifacts</h2>

	The generated grammar files (for the ANTLR example the one highlighted in
	Figure 3) are not supposed to be messed up by the user, however in order to explore
	them the following Eclipse plugins prove useful:

	<ul>
	<li><a href="http://sourceforge.net/projects/eclipse-javacc/">for JavaCC</a>
	</li>
	<li><a href="http://antlreclipse.sourceforge.net/">for ANTLR v2 grammars</a></li>
	</li>
	<li><a href="http://www.antlr.org/works/index.html">for ANTLR v3 grammars</a></li>
	(although Gymnast Generator generates as of now only v2 grammar files)
	</li>
	<li><a href="http://sourceforge.net/projects/jgedit">JikesPG Grammar Editor</a></li>
	(it's planned for Gymnast Generator to generate JikesPG grammar files, see plugin <code>org.eclipse.gymnast.generators.parser.lpg</code>)
	</li>
	</ul>

	<p></p>
	<p></p>
	<table border="0" cellpadding="8">
	<tr>
	<td><img src="img-ch2/generatedGrammarFile.PNG" ></td>
	</tr>
	<caption align="bottom"><b>Figure 3</b> Generated artifacts</caption>
	</table>
	<p></p>

	<h2>POJO-based CSTs</h2>

	The generated POJO-style CST classes:

	<ul>
	<li>exhibit useful patterns for later processing (visiting in particular)</li>
	<li>are independent from the chosen parser generator</li>
	</ul>


	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 <a href="http://www.sts.tu-harburg.de/~mi.garcia/SoC2007/GymnastSlides.pdf">here</a>.


	The parser-generator-independent CST classes generated by Gymnast Generator
	implement <code>org.eclipse.gymnast.runtime.core.ast.ASTNode</code> (Figure 4(a)).

	<p></p>
	<p></p>
	<table border="0" cellpadding="8">
	<tr>
	<td><img src="img-ch2/ASTNode.PNG" ></td>
	</tr>
	<caption align="bottom"><b>Figure 4(a) </b><code>ASTNode</code></caption>
	</table>
	<p></p>


	A sample
	POJO-style CST class is depicted in Figure 4(b), corresponding to the following
	grammar production:


	<table border="2" cellpadding="8">
	<tr>
	<td>
	<p class=MsoNormal style='text-autospace:none'><b><span style='font-size:8.0pt;
	font-family:"Courier New";color:red;background:yellow'>sequence</span></b><span
	style='font-size:8.0pt;font-family:"Courier New";color:black'> classDecl : (abstractModifier)?
	</span></p>

	<p class=MsoNormal style='text-autospace:none'><span style='font-size:8.0pt;
	font-family:"Courier New";color:black'> classKind name=ID </span></p>

	<p class=MsoNormal style='text-autospace:none'><span style='font-size:8.0pt;
	font-family:"Courier New";color:black'> (typeParamsInfo=typeParamsInfo)?</span></p>

	<p class=MsoNormal style='text-autospace:none'><span style='font-size:8.0pt;
	font-family:"Courier New";color:black'> (</span><b><span
	style='font-size:8.0pt;font-family:"Courier New";color:navy'>"extends"</span></b><span
	style='font-size:8.0pt;font-family:"Courier New";color:black'> superTypes=commaListBoundExceptWild)?
	</span></p>

	<p class=MsoNormal style='text-autospace:none'><span style='font-size:8.0pt;
	font-family:"Courier New";color:black'> (COLON instClassName=boundExceptWildcard)?
	</span></p>

	<p class=MsoNormal style='text-autospace:none'><span style='font-size:8.0pt;
	font-family:"Courier New";color:black'> LCURLY classMemberDecls
	RCURLY ;</span></p>

	</td></tr></table>


	<p></p>
	<p></p>
	<table border="0" cellpadding="8">
	<tr>
	<td><img src="img-ch2/ClassDecl.PNG" ></td>
	</tr>
	<caption align="bottom"><b>Figure 4(b) </b><code>ClassDecl</code></caption>
	</table>
	<p></p>


	</body>
	</html>