# General Presentation

The Value Specification XText editor uses the XText technology.

The textual editor allow to create/edit some types of Value Specification:

- `org.eclipse.uml2.uml.LiteralBoolean`
- `org.eclipse.uml2.uml.LiteralUnlimitedNatural`
- `org.eclipse.uml2.uml.LiteralInteger`
- `org.eclipse.uml2.uml.LiteralReal`
- `org.eclipse.uml2.uml.LiteralNull`
- `org.eclipse.uml2.uml.LiteralString`
- `org.eclipse.uml2.uml.InstanceValue`
- `org.eclipse.uml2.uml.OpaqueExpression`

This fonctionnality is implemented through several plugins:

- org.eclipse.papyrus.uml.textedit.valuespecification.XText which contains the grammar of the Value Specification, the generated XText classes and the created class `UmlValueSpecificationScopeProvider` for the custom scoping of `org.eclipse.uml2.uml.InstanceValue` displaying the `org.eclipse.uml2.uml.InstanceSpecification` available in the model.
- org.eclipse.papyrus.uml.textedit.valuespecification.XText.ui which contains the generated XText ui classes and the implementation of `DefaultXTextDirectEditorConfiguration` for the Value Specification edition.
- org.eclipse.papyrus.uml.textedit.valuespecification.XText.utils which contains the utils classes for the XText edition of Value Specification and especially the `SetCommand` of the Value Specification in its container.
- org.eclipse.papyrus.uml.nattable.XText.valuespecification which contains the cell editor, the default cell editor configuration and the default cell manager for editing the Value Specification with the XText parser.
- org.eclipse.papyrus.infra.widgets which contains the created class `StyledTextReferenceDialog` that allows do define the component to edit the Value Specification in a widget in the properties view.
- org.eclipse.papyrus.uml.properties.XText which allow to define the editor for the XText parser in the properties view.
- org.eclipse.papyrus.uml.textedit.valuespecification.tests which contains all the JUnit tests for the XText parser.

# Parser definition

The default grammar of the XText parser for the Value Specification is the following:

`(visibility)? (name'=')? value`

The values accepted for the differents attributes are the following:

Attribute | Required | Values accepted
--- | --- | ---

visibility

No

- `+` (public)
- `#` (protected)
- `~` (package)
- `-` (private)

name | No | String representing an ID (i.e. XText grammar: `'^'?('a'..'z'|'A'..'Z'|'_') ('a'..'z'|'A'..'Z'|'_'|'0'..'9')*`)

value

Yes

- `true` or `false` (`LiteralBoolean`)
- positive integer or `*`(`LiteralUnlimitedNatural`)
- negative integer (`LiteralInteger`)
- double (`LiteralReal`)
- `null` (`LiteralNull`)
- String with quote (`LiteralSting`). The quote (') is essential for 2 reasons:
  - The XText parser cannot define the difference between the name representing an `InstanceSpecification` and a simple string value
  - A Non-valid value won't be defined as an `OpaqueExpression` without quote but always as a `LiteralString` value
- Instance Specification name (`InstanceValue`)
- `<Undefined>` or empty (`null`)

If the text filled is not compatible with the grammar of XText parser, an `OpaqueExpression` will be created.

The XText parser for Value Specification is not restrictive with the text filled, i.e. the different features setted on an existing Value Specification will be kept if possible.

For example: If an existing Value Specification is a `LiteralBoolean` named 'testBoolean' with the visibility 'public' and the value setted to `true`, the text `+testBoolean=false` and `false` have the same result: the value of `LiteralBoolean` existing will pass to `false` (the name and the visilibity don't change).

The XText parser reacts differently instead of the type of the Value Specification's container:

## Without defined type on Value Specification's container

If the type of Value Specification's container is not defined, the default behaviour will be applied.

Here, some examples:

Text filled | Namely | Created ValueSpecification
--- | --- | ---
Type | Visibility | Name | Value
+testInstanceValue=InstanceSpec1 | 'InstanceSpec1' is an `InstanceSpecification` existing in the model | `InstanceValue` | public | testInstanceValue | 'instance' attribute of `InstanceValue` is a reference to the existing `InstanceSpecification` named 'InstanceSpec1'
No `InstanceSpecification` exist in the model | `OpaqueExpression` | public | +testInstanceValue=InstanceSpec1 |
+testBoolean=true |  | `LiteralBoolean` | public | testBoolean | `true`
#testUnlimitedNatural=5 |  | `LiteralUnlimitedNatural` | protected | testUnlimitedNatural | 5
~testInteger=-8 |  | `LiteralInteger` | package | testInteger | -8
-testReal=12.34 |  | `LiteralReal` | private | testReal | 12.34
~testNull=null |  | `LiteralNull` | package | testNull | `null`
-testString="foo" |  | `LiteralString` | private | testString | foo
##testString="foo" |  | `OpaqueExpression` | public | ##testString="foo" |

## With defined type on Value Specification's container

If the type of Value Specification's container is setted, the same text filled will be have different behaviour depending to the type. In fact, the value filled must be consistent to the type, otherwise an `OpaqueExpression` will be created.

The different types corresponding to `LiteralSpecification` are the following:

LiteralSpecification | Types corresponding
--- | ---

`LiteralBoolean`

- JavaPrimitiveTypes::boolean
- EcorePrimitiveTypes::EBoolean
- EcorePrimitiveTypes::EBooleanObject
- PrimitiveTypes::Boolean
- XMLPrimitiveTypes::Boolean
- XMLPrimitiveTypes::BooleanObject

`LiteralUnlimitedNatural`

- PrimitiveTypes::UnlimitedNatural

`LiteralInteger`

- JavaPrimitiveTypes::int
- EcorePrimitiveTypes::EInt
- EcorePrimitiveTypes::EIntegerObject
- PrimitiveTypes::Integer
- XMLPrimitiveTypes::Int
- XMLPrimitiveTypes::Integer
- XMLPrimitiveTypes::IntObject

`LiteralReal`

- JavaPrimitiveTypes::double
- EcorePrimitiveTypes::EDouble
- EcorePrimitiveTypes::EDoubleObject
- PrimitiveTypes::Real
- XMLPrimitiveTypes::Double
- XMLPrimitiveTypes::DoubleObject

`LiteralString`

- EcorePrimitiveTypes::EString
- PrimitiveTypes::String
- XMLPrimitiveTypes::String

Here, some examples:

Text filled | Value Specification's container type | Created ValueSpecification
--- | --- | ---
Type | Visibility | Name | Value
+testBoolean=true | PrimitiveTypes::Boolean | `LiteralBoolean` | public | testBoolean | `true`
PrimitiveTypes::Integer | `OpaqueExpression` | public | +testBoolean=true |
-testUnlimitedNatural=8 | PrimitiveTypes::UnlimitedNatural | `LiteralUnlimitedNatural` | private | testUnlimitedNatural | 8
PrimitiveTypes::Integer | `LiteralInteger` | private | testUnlimitedNatural | 8
PrimitiveTypes::Real | `LiteralReal` | private | testUnlimitedNatural | 8.0
PrimitiveTypes::Boolean | `OpaqueExpression` | public | -testUnlimitedNatural=8 |
#testInteger=-6 | PrimitiveTypes::UnlimitedNatural | `OpaqueExpression` | public | #testInteger=6 |
PrimitiveTypes::Integer | `LiteralInteger` | protected | testInteger | 6
PrimitiveTypes::Real | `LiteralReal` | protected | testInteger | 6.0
PrimitiveTypes::Boolean | `OpaqueExpression` | public | #testInteger=6 |
-testReal=4.5 | PrimitiveTypes::Integer | `OpaqueExpression` | public | -testReal=4.5 |
PrimitiveTypes::Real | `LiteralReal` | private | testReal | 4.5

# Papyrus integration

## Direct editor configuration

The Direct Editor Condiguration allow to define a new cirect editor for Papyrus. This define the object type to edit and the editor configuration class used for the integration of editor. For the Value Specification XText editor, a default Direct Editor Configuration is already defined: `ValueSpecificationXTextDirectEditorConfiguration` which allow to manage the type `org.eclipse.uml2.uml.ValueSpecification`.

### Manage the default languages of created OpaqueExpression

To redefine the default languages used by created `OpaqueExpression` by the properties widget, a class extending the `ValueSpecificationXTextDirectEditorConfiguration` must be created and the method `getDefaultLanguages()` must be override.

Then, this created direct editor configuration must be referenced in the `org.eclipse.papyrus.extensionpoints.editors.DirectEditor` extension point with a higher priority than the default (Lowest).

## Properties integration

### Define the context and the xwt files

The context file allow to define the field available in the properties view. To define the field which will be displayed in the properties view with XText parser and completion, the `UMLStyledTextReferenceDialog` will be used.

This class contains a `UMLXTextReferenceValueEditor` which contains a `StyledText` for the text fill and `StyledTextXTextAdapter` to manage the XText parser and completion.

Here, an example of context and xwt file for the default value of property object:

In the PropertyEditor created, an attribute `directEditorConfiguration` will be implemented to define the direct editor configuration class to use for the edited object:

The context file must be referenced in the `org.eclipse.papyrus.views.properties.context` extension point:

## Cell of NatTable integration

### Define the cell editor configuration

A default cell editor configuration already exists for the Value Specification: `ValueSpecificationCellEditorConfiguration`. But to get the possible XText parser and completion in cell of NatTable, the cell editor configuration must be extended and the created class must be referenced in the `org.eclipse.papyrus.infra.nattable.celleditor.configuration` extension point with an inferior order than the others.

Here, an example:

### Define the cell manager

A default cell manager already exists for the Value Specification: `ValueSpecificationCellManager`. But to get the possible XText parser and completion in call of NatTable, the cell manager must be extended and the created class must be referenced in the `org.eclipse.papyrus.infra.nattable.cellmanager` extention point with an inferior order than the others.

Here, an example:

#### Manage the default languages of created OpaqueExpression

To redefine the default languages used by created `OpaqueExpression` by the cell editor, the method `getDefaultLanguages()` must be overridden in the class extended from `ValueSpecificationCellManager`.

Category:Papyrus

# Example

- The plugin `org.eclipse.papyrus.uml.textual.editors.example` provide an example of integration of this editor in the table and in the property view to edit the default value of a property.
- A video is available here https://www.youtube.com/watch?v=OERg0BUZmyU&feature=youtu.be