Skip to main content
Jump to: navigation, search

Difference between revisions of "ESON"

m (Introduction)
(explain import vs. use)
Line 21: Line 21:
 
Note that you don't have to have the usual separate development vs. run-time hosted Eclipse instances and separate workspaces. It's most convenient to write an Xcore meta model and some test ESON model instance in two Plug-in projects in a single workspace. The *.xcore and the (test) *.eson must be in different projects, so that Xtext's Index Builder can process them in the right order. Note that both the Xcore and the ESON must be in a folder typically named "model/" which is NOT on the Classpath of the respective project (due to some... Xtext limitation; otherwise you'll get "Couldn't resolve reference to EClass ..." even though the Xcore IS on the Classpath of the ESON test project).
 
Note that you don't have to have the usual separate development vs. run-time hosted Eclipse instances and separate workspaces. It's most convenient to write an Xcore meta model and some test ESON model instance in two Plug-in projects in a single workspace. The *.xcore and the (test) *.eson must be in different projects, so that Xtext's Index Builder can process them in the right order. Note that both the Xcore and the ESON must be in a folder typically named "model/" which is NOT on the Classpath of the respective project (due to some... Xtext limitation; otherwise you'll get "Couldn't resolve reference to EClass ..." even though the Xcore IS on the Classpath of the ESON test project).
  
Due to a TODO bug, currently only Ecore/Xcore package names without any dots work (hopefully fixed soon, watch https://git.eclipse.org/r/#/c/47925/).
+
EClass names can be fully qualified ("Library.Book {"), or use a Java-like import ("import Library.* Book {"; see screenshot; this mechanism is based on Xtext's importedNamespace). The "use Library.*" syntax is deprecated and should not be used in new ESON models.
 +
 
 +
Due to a bug, currently only Ecore/Xcore package names without any dots work (hopefully fixed soon, watch https://git.eclipse.org/r/#/c/47925/).
  
 
''TODO: Investigate and build example how to set-up non-plugin simple (Maven/Gradle) Java projects with Xcore/ESON.''
 
''TODO: Investigate and build example how to set-up non-plugin simple (Maven/Gradle) Java projects with Xcore/ESON.''

Revision as of 11:03, 15 May 2015

ESON - EMF Simple Object Notation

Introduction

ESON is a textual syntax for EMF models; like XMI is a XML-based syntax, ESON is a more human readable notation. It complements Xcore, which as a textual syntax for Ecore can define your EClass & Co.while ESON can represent their instances.

ESON is implemented based on Xtext, and *.eson files are thus truly textual representations; for example, changes made to your EObject are applied incrementally and preserve comments in or the formatting of the text. Crucially, users of ESON do *NOT* require any Xtext know-how or code generation for their Ecore models, because ESON is fully dynamic.

How to use

Install

Install it from https://hudson.eclipse.org/xtext/job/eson/lastSuccessfulBuild/artifact/targetPlatform/

Model

Try File > New > Example... > ESON!

Eson1.png

Note that you don't have to have the usual separate development vs. run-time hosted Eclipse instances and separate workspaces. It's most convenient to write an Xcore meta model and some test ESON model instance in two Plug-in projects in a single workspace. The *.xcore and the (test) *.eson must be in different projects, so that Xtext's Index Builder can process them in the right order. Note that both the Xcore and the ESON must be in a folder typically named "model/" which is NOT on the Classpath of the respective project (due to some... Xtext limitation; otherwise you'll get "Couldn't resolve reference to EClass ..." even though the Xcore IS on the Classpath of the ESON test project).

EClass names can be fully qualified ("Library.Book {"), or use a Java-like import ("import Library.* Book {"; see screenshot; this mechanism is based on Xtext's importedNamespace). The "use Library.*" syntax is deprecated and should not be used in new ESON models.

Due to a bug, currently only Ecore/Xcore package names without any dots work (hopefully fixed soon, watch https://git.eclipse.org/r/#/c/47925/).

TODO: Investigate and build example how to set-up non-plugin simple (Maven/Gradle) Java projects with Xcore/ESON.

Editor UI

The ESON Editor shows the DSL source on the left, and a tree view of the model on the right. The Properties view allows to edit the currently selected node. Changes in any of these 3 parts are live auto synchronized to the other (without saving).

Double clicking on the background in source on the left or the tree on the right maximizes and hides the respective other part, double clicking it again restores the default split sash presentation.

The traditional read-only Outline view is intentionally disabled, to avoid end-user confusion with the right-hand side of the editor.

Programmatically

Using ESON, any *.eson file can be loaded as a normal EMF resource. An instance of your "real" EMF model described by the ESON will be available in getContents().get(1); the get(0) will give you the internal Xtext representation which typically you won't be interested in. This resource has bi-directional synchronization of changes made to either of these two models - so you can use it like a "normal" EMF model, save it, and the ESON will be correctly updated.

Known Issues, Curiosum & Noteworthy

The UI (default Tree Editor & Properties) does not yet support the usual add/remove + picker for multiplicity many references, only single ones. This is a UI limitation, the "back-end" (the code which synchronizes the two models) already supports it (DS-8674).

ESON supports EClass, EAttribute etc. names with dots in them (that is dots in the actual name, not dots to separate the name from the EPackage/s). Similarly, names (IDs) can consist of only numbers, or start with numbers. While neither is valid in standard ECore, it was added to ESON to support a particular use case.

How to contribute

Support Forum / Mailing List via Google Group https://groups.google.com/forum/#!forum/eclipse-emf-eson-dev

Src: http://git.eclipse.org/c/emf/org.eclipse.emf.eson.git/ ("Pull Requests" via Gerrit more than welcome!)

The Eclipse Installer (based on Oomph) is great to get it all set up.

History

ESON was originally born as https://code.google.com/a/eclipselabs.org/p/efactory/, later re-incarnated on https://github.com/vorburger/efactory, and as of 2014-12 the project has been formally accepted and integrated as a sub-project of the official Eclipse Modeling Framework (EMF) on eclipse.org.

Further Documentation

TBD Transfer, and update, old documentation from https://github.com/vorburger/efactory/blob/eclipse.org/org.eclipse.emf.eson.help/help/concepts.mediawiki

Older doc: http://git.eclipse.org/c/emf/org.eclipse.emf.eson.git/plain/README.md

Back to the top