This page is currently under construction. Please have a look at the tutorials for an up-to-date documentation.

Melange Workbench

Installation

First method (recommended)
The Gemoc Studio is a specialized Eclipse embedding a ready-to-use Melange.
You can retrieve it here

Second method
Melange and its depedencies can be installed manually in an existing Eclipse.

1. First you need an Eclipse Mars. Take the Eclipse Modeling Tools version since Melange is based on EMF.
   Download Eclipse Mars
2. Melange depends on Xtext to run.
   Get Xtext 2.8 and add it with the update site (Menu Help > Install new software...).
3. The last dependency is EMF Compare.
   Get the lastest release and install it with the update site (Menu Help > Install new software...).
4. And finally Melange & Kermeta 3
   Add the update site (Menu Help > Install new software...) and check DiverSE Commons, Kermeta3 & Melange.

Create new project

1. Open the menu File > New > Project... and select Melange > Melange Project, then click Next.
2. Fill the project name and click Next.
3. Check Create a plug-in using one of the templates and select Simple Melange project, then Next.
4. Fill the package name, and change language name to MyFSM. Browse the location to select an .ecore file if you have an EMF project, then Finish.

Language view

The Language Registry displays the list of usable Languages in the current Eclipse.

Identifier : The qualified name
URI : The URI of the root EPackage
Description : Short text about the Language
Exact Type : The identifier of the ModelType generated from this Language
Implements : The ModelTypes matching the Exact type
Contributor : The providing plugin

It is accessible in the menu Window > Show View > Other... and select Melange > Language Registry

ModelType view

The Model Type Registry displays the list of usable ModelTypes in the current Eclipse.

Identifier : The qualified name
URI : The URI of the root EPackage
Description : Short text about the ModelType
Subtype of : Matching this ModelTypes
Contributor : The providing plugin

It is accessible in the menu Window > Show View > Other... and select Melange > Model Type Registry

Melange Resource

Melange provides an implementation of EMF Resource able to cast a model to a ModelType

Get a MelangeResource

An initialisation step is required before using a MelangeResource

StandaloneSetup.doSetup()

The class StandaloneSetup is generated by a right click > Generate All on a .melange file
The call to doSetup() will register the “melange:/” URI protocol and configure the mapping between Languages and ModelType for the adaptation layer.

val ResourceSet rs = ...
val melangeRes = rs.getResource(URI.createURI("melange:/<type>/<path>/[?<query>]"),true) as MelangeResource

The MelangeResource is obtained as usual from an EMF ResourceSet by using an URI but starting with melange:/

MelangeResource API

The MelangeResource provides specific operations:

• Get the loaded model

  
  def Resource getWrappedResource()
  

• Configure the MelangeResource to have instance of ModelType’s class when calling getContent()

  
  def void cast(String modelTypeID)
  

• Configure the MelangeResource to use a copy of the wrapped resource conform to the given Language

  
  def void downcast(String languageID)
  

Examples:

Let’s consider a language “MiniFsm” and a language “MelangedLang” inheriting the first one.

Vanilla:

val melangeRes = rs.getResource(URI.createURI("melange:/file/model/SampleMiniFsm.xmi"),true) as MelangeResource
val content = melangeRes.getContent()

content is a list of EObject instance of MiniFsm

Cast:

val melangeRes = rs.getResource(URI.createURI("melange:/file/model/SampleMiniFsm.xmi"),true) as MelangeResource
melangeRes.cast("fr.inria.diverse.melanger.MiniFsmMT")
val content = melangeRes.getContent()

content is a list of EObjectAdapter instance of MiniFsmMT, which contain and delegate to elements of the loaded model

Downcast:

val melangeRes = rs.getResource(URI.createURI("melange:/file/model/SampleMiniFsm.xmi"),true) as MelangeResource
melangeRes.downcast("fr.inria.diverse.melanger.MelangedLang")
val content = melangeRes.getContent()

content is a list of EObject instance of MelangedLang, which are copies of the elements of the loaded model

Both:

val melangeRes = rs.getResource(URI.createURI("melange:/file/model/SampleMiniFsm.xmi"),true) as MelangeResource
melangeRes.downcast("fr.inria.diverse.melanger.MelangedLang")
melangeRes.cast("fr.inria.diverse.melanger.MiniFsmMT")
val content = melangeRes.getContent()

content is a list of EObjectAdapter instance of MiniFsmMT, which contain and delegate to elements copied from the loaded model

Melange URI:

The Melange Resource uses its own URI scheme melange: which is of the form:

melange:/<type>/<path>/[?<query>]

<type> : specify the type of the container of the model
It accepts:

• resource : the model is inside a project in the workspace. The first segment of the path is the name of the project.
• plugin : the model is contained in an Eclipse plugin. The first segment of the path is the name of the plugin
• file : the model is an ordinary file on the disk

<query> : specify how we want to see the model
It accepts:

• mt=<modelTypeIdentifier> : Add an adaptation layer to see model’s elements as ModelType’s elements
• lang=<languageIdentifier> : Do a copy of the model to have an instance of the Language.

Examples:

• Cast to an ExactType

  
  melange:/file/input/dummie.xmi?mt=family.FlatFsmMT
  

• Upcast to a super ModelType

  
  melange:/file/input/timeddummie.xmi?mt=family.FlatFsmMT
  

• Downcast to a sub ModelType

  
  melange:/file/model/SampleMiniFsm.xmi?lang=fr.inria.diverse.melanger.MelangedLang&mt=fr.inria.diverse.melanger.MelangedLangMT
  

Melange menu

On a right click on a .melange file you have access to this menu containing theses commands:

• Generate All
  Generate Language Runtime, Adapters, Interfaces and Plugin.xml
• Clean All
  Delete generated artifacts
• Generate Language Runtime
  Generate new Eclipse projects for all Languages. A new project contains the .ecore merging the multiple Domain models of the Language. It also contains copies of inherited Aspects but applying on the new .ecore file (which has classes in another namespace).
• Generate Adapters
  Generates adaptation classes to see a model as an instance of a compatible Language.
• Generate Interfaces
  Generate the ModelTypes as .ecore file. It represents the merge of Domain models and semantics of the Language.
• Generate Plugin.xml
  Generate extension points in the plugin.xml file. They are used at runtime to get informations about defined Languages.

Create the semantic

Melange rely on Kermeta 3 to define the semantic for a Language. It is a set of Aspects reopening classes to add operations and properties.

To create a new project for the semantic:
1. Open the menu File > New > Project... and select Kermeta 3 > K3 Project
Fill the name of your project and click on Finish
2. Open the META-INF/MANIFEST.MF and in the dependencies tab add the project containing the domain model
3. Create a new file “Aspects.xtend” in this package (right click New > File) and open it.
4. Declare the containing package and import the annotation from Kermeta 3 that we will use to define aspect.

package org.sample.simplefsm;

import fr.inria.diverse.k3.al.annotationprocessor.Aspect

1. We want to define behavior on elements of our model. Kermeta 3 allows us to add new properties and operations in existing classes without extending them.
   All we just need to do is writing a new class and using the K3’s annotation to weave it on the base class.

For example for the class StateMachine:

@Aspect(className=StateMachine)
class StateMachineAspect {
	State currentState

	def void init(){
		currentState = _self.states.findFirst[InitialState]
	}
}

With the @Aspect we re-open the class “StateMachine” to add a method init() implementing a behavior and a new attribute ‘currentState’.

More details about Aspects are available in the K3 documentation

Melange editor

Melange is a Language designing tool. Through a .melange file you can define a Language as an assembly of abstract syntaxes with operational semantics and also as a composition of Languages. To do so, Melange is provided with a textual Languages editor.

A .melange file start with

package your.language.namespace

and contains a list of Language and Transformation definitions.

Language

Language name must start with an uppercase.

a basic Language.

language FiniteStateMachineClassic {

	/*
	 * Declare abstract syntax
	 */
	syntax "platform:/resource/fr.inria.diverse.examples.fsm.metamodel.composite/model/fsm.ecore"
	
	/*
	 * Declare semantic
	 */
	with finitestatemachines.composite.classic.StateMachineAspect
	with finitestatemachines.composite.classic.StateAspect
	with finitestatemachines.composite.classic.CompositeStateAspect
	with finitestatemachines.composite.classic.TransitionAspect
}

A Language definition accept theses keywords:

• syntax
  Link your language to your Domain Model. The path to your model follows the Eclipse platform URLs convention: platform:/resource/<path to the .ecore file>.
  It is mandatory to have a .genmodel file in the same location of the .ecore file.
  If the name or the location is different you have to specify the file with the keyword genmodel

language FiniteStateMachineClassic {

	syntax "platform:/resource/fr.inria.diverse.examples.fsm.metamodel.composite/model/fsm.ecore" genmodel "platform:/resource/fr.inria.diverse.examples.fsm.metamodel.composite/model/fsm.genmodel"

}

This operator support renaming, see merge operator for more details.

• with
  Link an Aspect to your language. with is followed by the name of a Java class. Melange support wildcard character for this operator. Typing in your language with some.package.name.* will import all classes under this namespace.
• inherits
  The keyword inherits allows you to define a Language as an extension of another. It means the abstract syntax and the semantics of the inherited Language are copied in your Language.
• merge
  This operator allows you to import languages and merge them in your new language. The resulting language will contains all elements from merged languages. If elements from differents languages have the same qualified name, they are merged into one element with all properties. Note that names of the packages must be the same in all merged languages since this operator works on qualified name.

language FSMextended{
	merge FiniteStateMachineClassic
	merge CompositeState
}

This operator support renaming. It allows to rename EPackage, EClass and EOperation from the Language target by the operator. The renaming operations are performed before appling the merge.

language Graph {
	merge FiniteStateMachineClassic renaming {
		//Rename package
		'fsm' to 'root' {
			//Rename classes 'State' and 'Transition'
			'State' to 'node' {
				//Rename attribute
				'name' to 'id'
			}
			'Transition' to 'edge'
		}
	}
}

• slice
  This operator behave as the Merge operator but allows you to select a part of the imported language.The Slice operator get a Language and a list of Classes as arguments. From each Class in paramters, the Slicer will explore the Language and keep only super Classes, and referenced classes recursively.

language JavaLoop{
	slice JavaLanguage on ['ForLoop', 'WhileLoop', 'DoWhileLoop', 'ForEachLoop']
}

In this example we slice a metamodel defining the Java language to keep only the loop feature. The resulting language will contains the four loop Classes and the related Expression and Statement Classes. The slicer will not keep the sub Classes of Expression and Statement. This usage of the slice can be combined with the merge operator to get Expression and Statement from others metamodels to improve the new ‘LoopLanguage’.

This operator support renaming, see merge operator for more details.

• exactType
  When you define a Language, its ModelType is automatically created and named after the name of the Language with the suffix ‘MT’.
  You can rename it by adding exactType in the Language definition followed by the new name.
• xtext
  Link your language to an Xtext project
• ecl
  Link your language to your ECL project. The intended format for the path to your .ecl file is: “/<path to the .ecl file>”

ModelType

In Melange Languages are typed. Their exactType are their default type but you can create news one, independantly of languages thanks to the keyword modeltype.

modeltype FsmMt{
	syntax "platform:/resource/fr.inria.diverse.examples.fsm.metamodel.composite/model/fsm.ecore"
}

Like for Language we use the keyword syntax to locate an .ecore file. This Ecore will define the model type.

Outline

The outline view is available when you open a .melange file. It gives an overview of the file content.

Content assist

You can press Ctrl+Space to have the content assist in the Melange editor.

• In language { … }
  – Create a Domain Model Project –
  Create a new EMF project and upadte the syntax of your language.
  – Create a DSA Project –
  Create an new K3 project. Based on the syntax of your language, it automatically creates Aspects for each class of your Domain. Theses Aspects are also added in your Language.
  – Import existing DSA project –
  Automatically imports all Aspects from a K3 project.
• After syntax
  Display the list of available .ecore files in your workspace and update syntax with the path to the selection.
• After with
  Display the list of accessible Java classes from your project dependencies. K3 Aspects are displayed first.
• After ecl
  Display the list of available .ecl files in your workspace and update ecl with the path to the selection.

Comments

// Melange support single-line comments

/*
 * And also
 * block comments
 */