/xtext-protected-regions

Xtext Protected Regions

Primary LanguageXtend

Xtext Protected Regions

The project Xtext Protected Regions adds protected region support to Xtext, a very powerful language development (and generator) framework.

Supports

  • Eclipse Juno 4.2
  • Xtext 2.3

Installation

Eclipse Update site: http://danieldietrich.net/protectedregions/updates/releases/current

Changelog

2.0.2 – Bugfix for Issue #47 (reading file encoding)
2.0.1 – Bugfix for Issue #37 (parsing of escape sequences)
2.0.0 – Added Eclipse Juno/Xtext 2.3 support. Completely rewritten with Xtend.
1.0.1 – Added support for Xtext 2.1
1.0.0 – Initial version

Usage

Adding project dependencies

Given the Xtext sample project ‘MyDsl’ the protected region support is installed as follows:

Add the dependencies net.danieldaniel.protectedregions.core and net.danieldietrich.protectedregions.xtext to the MANIFEST.MF of the main plugin of the Xtext project where your code generator resides.

Configuring dependency injection via Google Guice

For standalone code generators add these lines to the XxxRuntimeModule.java:

@Provides
public JavaIoFileSystemAccess createJavaIoFileSystemAccess(ProtectedRegionJavaIoFileSystemAccess fsa, ParserFactory factory) {
  fsa.support().addParser(factory.javaParser(), ".java");
  fsa.support().addParser(factory.xmlParser(), ".xml", ".xsd");
  return fsa;
}

For eclipse based code generators add these lines to the XxxRuntimeModule.java:

@Provides
public EclipseResourceFileSystemAccess2 createEclipseResourceFileSystemAccess2(ProtectedRegionEclipseResourceFileSystemAccess2 fsa, ParserFactory factory) {
  fsa.support().addParser(factory.genericParser());
  return fsa;
}

Hint: Adding EclipseResourceFileSystemAccess2, the standalone generator can’t be run without adding additional plugin dependencies.

Declaring protected regions in your code

Now just begin to denote protected regions in the comments of your favorite language. Protected regions start with PROTECTED REGION ID(unique.id) ENABLED START and end with PROTECTED REGION END, where unique.id is a gobally unique id (in the scope of the project) and syntactically equivalent to a full qualified Java identifier . These regions are protected on subsequential generator calls, even if files move, are merged or renamed (content over containers).

For an in-depth description and more options (like generated regions) please take a look at the PRS Core documentation.

Configuring the generator

Xtext projects which are started in a seperate eclipse instance do just need a Guice provider for ProtectedRegionEclipseResourceFileSystemAccess2 (as described above).

Xtext standalone code generator, which is started manually via a main method, are configured like this:

1. Injecting FileSystemAccess

@Inject
privte JavaIoFileSystemAccess fsa;

With the adjusted RuntimeModule Google Guice provides here a ProtectedRegionJavaIoFileSystemAccess, the control center of PRS.

2. Defining the output path

fsa.setOutputPath([slot,] outputPath); // slot is optional

By calling setOutputPath(…) PRS parses all existing files in the given path and its subfolders, considering the parsers (file extension) filters and the optional filter of the file system access (see RuntimeModule).

Hint: A developer may want to generate the sources into a temp dir. Before and after setting output path(s) there may be manual implemented copy & clean tasks.

3. Writing the output

fsa.generateFile(fileName, [slot,] contents); // slot is optional

Before writing a file to the file system, the PRS file system access implementation substitutes protected regions which were collected in step 2.

Developer Guide

The developer guide is addressed to developers which want modify the Xtext PRS. Contributors are welcome :-)

Prequisites

The following software should be installed to your system:

  • JDK 6+ (The only feature used of Java 1.6 is the @Override annotation in conjunction with interface implementations.)
  • Eclipse (The JEE version is fine.)
  • Git (To clone (download) the project.)
  • Maven (To build the project.)

Please install the following plugins (via Marketplace) with Eclipse:

  • Maven Integration for Eclipse (m2e)
  • EGit – Git Team Provider (optional)

Download

To get a local copy of xtext-protectedregions you have to clone the project hosted on GitHub:

git clone git@github.com:danieldietrich/xtext-protected-regions.git

Setup Eclipse Workspace

Maven Tycho is used to build the plugins, feature and update site. In Eclipse select Import / Maven / Existing Maven Projects and navigate to the root of xtext-protectedregions cloned before. Download necessary plugins if asked for.

Build Process

To build an eclipse update site containing all artifacts, open a shell, jump to xtext-protected-regions/releng and type

mvn package

The binaries can be found in net.dd.prs.updatesite/target/site.

Documentation

The technical documentation of the Xtext PRS can be found here:

Samples

top