Skip to main content

Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.

Jump to: navigation, search

ESON

Revision as of 08:05, 13 November 2015 by Mike.vorburger.ch (Talk | contribs) (→‎How to contribute)

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. (It is also possible to use ESON to create instances of non-Xcore normal/classic *.ecore.)

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

The easiest is to use the the usual menu Help > Install New Software... Add... Name: ESON, Location: https://hudson.eclipse.org/xtext/job/eson/ws/git-repo/releng/org.eclipse.emf.eson.repository/target/repository/

Or you can download the p2 ZIP named something like org.eclipse.emf.eson.repository-*-SNAPSHOT.zip from https://hudson.eclipse.org/xtext/view/Eson/job/eson/ws/git-repo/releng/org.eclipse.emf.eson.repository/target/. This ZIP can then be installed offline using e.g. the usual menu Help > Install New Software... Add... Archive.. (NOT Local..).

Alternatively do use the Eclipse Installer (Oomph) and choose the ESON project; this will get the source, luke, and you'll have a workspace ready made to contribute to ESON itself! See "How to contribute" below.

Model

It's best to use the File > New > Example... > ESON to learn how to get started!

Eson1.png

EClass names can be fully qualified ("Library.Book {"), or import'd with the "use Library.* Book {" syntax. EObjects from other ESON can be similarly fully qualified ("author: lunar.loony"), or import'd with the "import lunar.* author: loony" syntax (this mechanism is based on Xtext's importedNamespace). (The "import" keyword should NOT currently be used for EClass, because its implementation as of 2015.05.19 only consults the Xtext index but does not consult the EPackage.Registry like the "use" keyword does, correctly.)

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.

Generators

Standard Xtext IGenerator support is one per language, registered in the respective *RuntimeModule. So you couldn't easily add an IGenerator for your ESON unless you wanted to patch core ESON sources. However, https://git.eclipse.org/r/#/c/48029/ is adding easy out-of-the-box support for IGenerators; these can be hosted in the run-time projects workspace next to the Xcore & Test ESON, registered via a src/META-INF/services/org.eclipse.xtext.generator.IGenerator, and thus don't need a separate development vs. hosted workspace. The example projects created by the wizard also illustrate JSON and XML generation from ESON. (Remaining major issue is correct support for static Ecore/Xcore models instead of dynamic EMF instances; watch https://git.eclipse.org/r/#/c/48031/.)

TODO: Support IGenerator in your Plug-In registered via new ESON Extension Point instead of via META-INF/services/org.eclipse.xtext.generator.IGenerator in runtime project; please raise a Bugzilla if you're interested in this.

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

Source code repository is http://git.eclipse.org/c/emf/org.eclipse.emf.eson.git/. Note branching strategy: master = stable (usually last released Xtext version), nightly = bleeding edge EMF & Xtext master (may be broken some times due to issues such as Xtext Bug 482033), Xtext-v* for maintenance of ESON on older Xtext releases.

Gerrit Code review on https://git.eclipse.org/r/#/q/project:emf/org.eclipse.emf.eson

Your contributions are more than welcome! Don't be shy.

Oomph

The Eclipse Installer (Oomph) is great and the recommended way to set up your development environment for contributing to ESON.

Please note bug 482099 re. switching over the ESON setup model from the original hosted within Oomph to the new one within ESON.

To see changes made to the org.eclipse.emf.eson.releng/ESON.setup in the workspace, remember that one first time you'll have to switch to make it use that, instead of the one from the remote Git repo which it originally used when installing (otherwise you just run the original Setup, without your newest local changes). This is done via "Import Projects..." in the drop-down of the Perform Setup Tasks reload action in the Oomph toolbar, or via the menu File > Import> Oomph > Projects into Workspace, and "Add user projects", then "Browse Workspace" to the local org.eclipse.emf.eson.releng/ESON.setup.

Note that as per this Oomph Forum discussion, it is recommended to set up separate installations for the 'master' vs. the 'nightly' streams.

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

Retrieved from "https://wiki.eclipse.org/index.php?title=ESON&oldid=393804"

Back to the top