How to Play In

How to Play In

Basic play-in

To use Basic play-in, click the 'Basic Play-In' button.

Consequently, the play-in session starts. If a GUI exists it is launched, from which you can start play-in:

• Clicking an object in the GUI creates a diagram snippet reflecting the click.
  
• Use the Play-In toolbar to control some of the play-in operations, such as applying modality (hot/cold, monitor/execute):
  

• Once created, LSC construct properties can be modified via the properties view and the right-click menu:
  

Natural language play-in

With natural language (NL) play-in, you can write scenarios in controlled natural language. For example, "When the user clicks the button, the light state turns to on". NL play-in then creates an LSC for this scenario, and inserts the corresponding entities into the System Model, if they are not there yet.

NL play-in: the underlined words in the NL sentence entered by the user are translated into the LSC chart and the appropriate System Model entities.

NL Rules

The scenarios specified in controlled NL have to conform to the following rules:

1. A scenario must contain exactly one sentence.
2. The sentence should contain a clear subject, verb, object and possibly adjective.These are translated into LSC constructs, such as lifelines, messages, properties and property values.
3. Delimiters, like a comma, or words like 'then' or 'and' after each part of the sentence are important and must be included. For example:
   1. "when the user clicks the button, the display text changes to Hello"
   2. "when the user clicks the button then the display text changes to Hello"
4. Values that are composed from more than one word should appear in double quotes. Single word values can appear without quotes. For example:
   1. "when the user clicks the button, the display mode changes to alarm"
   2. "when the user clicks the button, if the display mode is "alarm", the display mode changes to "alarm minutes" "
5. Objects and methods cannot consist of more than one word (double quotes will not help here). By default, nouns are understood as objects, and verbs as methods. If there is other information from the system model, it will be integrated (e.g., if there is an object named 'walk', it can be understood as a noun or a verb). Also, non-words are by default nouns and are understood as objects or values. To use a non-word as a different construct, right click the word and set it using the right click menu. In the following example 'ReduceTemp' is not a noun, but rather a method. For the parse to recognize it, right click it, and set it to 'method'.
   1. "when the user clicks the button, the manager ReduceTemp."
6. Property values can be of type String, Integer or Boolean, and are inferred either automatically or by the programmer using the quick fix mechanism.
7. To refer to a specific object, use 'the'. To refer to a non-specific object, use 'a' or 'any'. For example:
   1. "when the user clicks the A_button, the display text changes to "Button A was clicked" ". This will create a static object 'A_button'.
   2. "when the user clicks a button, the button state changes to on". This will create a dynamic object 'button' that will bind at run time when clicked.
8. If the NL refers to an object that already appears in the system model, the exact name of the object should be used, as it appears in the system model.
9. Two basic phrases that add LSC constructs are a property change of an object and a method call.
   1. A sentence that describes a property that changes should include the <object name>, the <property name> and optionally the <new value>. For example:
      1. "when ..., the light state changes to on"  (light.state = on).
      2. "when ..., the display color changes to the selection color" (display.color = selection.color).
      3. "when the light state changes, the ..." (the trigger is a change of the value to anything. light.state = *). 
      4. A bad example is: "when ..., the light turns on", since "turns" is not recognized as a method. However, setting "turns" explicitly as a method, will make this sentence work, but it will generate a method call, e.g., light.turns(on), rather than the change of a property.
   2. A sentence that describes a method call should include the <object name> and the <method call>. For example:
      1. "when ..., the panel locks" (panel.lock()).
      2. "when the user clicks the button, ..." (button.click() triggered by the User source object).
      3. "when the dispenser makes tea, ..." (dispenser.make(tea)).
      4. A bad example is: "the heater temperature increases", since the heater.temperature is a property and cannot call the increase method.

Interactive NL-Play-In Interface

To use NL play-in, create an LSC project, or select an existing one, and click the 'NL Play-In' button.

This will cause the play-in session to start, and the 'NL Play-In' view will open. To play in, enter the LSC name and the requirement:

• LSC Name - the name of the LSC currently being played in.
• Requirement Text - the NL sentence defining the LSC.
• Add LSC - click this button to create the LSC when the requirement is complete.
• Online Parsing - this is a toggle button. When selected the text is parsed after each space entered. Otherwise, the text is parsed only when pressing Enter.
• Interact Enabled - this is a toggle button. When selected, interaction with the application GUI is interpreted as an NL snippet by the Show & Tell play-in module.

Quick fix mechanism

When NL play-in identifies problems in the requirement text, it activates a quick fix mechanism to mark them using a squiggly line and to prompt the user to fix them. 

A green squiggly line indicates a model warning or missing information. In some cases NL assigns defaults when information is missing.

To get more information on the error, hover over the underlined words with the mouse and a quickfix box will appear, describing the problem and offering possible solutions when they exist.

To select a solution, click on it and it will take effect:

A red squiggly line indicates an ambiguity; i.e., that there is more than one possible parse for the sentence. The user should disambiguate by selecting one of the offered possibilities. The selection can obviously have a significant effect on the created LSC.

To get more information about the error, hover over the underlined words with the mouse and a quickfix box will appear, describing the problem and offering possible solutions when they exist.

To select a solution, click on it and it will take effect. If no solution appears, or if you would like a different option from those appearing in the menu, edit the text to fix it yourself:

 

A black squiggly line indicates a grammatical error, which must be fixed before continuing. In most cases, this involves incorrect grammar, a missing determinant, or words that are misspelled or not-recognized. No spell checking is applied in the current implementation. In the example below, the error is caused by the unrecognized word "doubleClicks":

To fix a grammatical error, look for the missing determinant and correct the sentence. In case of an unrecognized word, select the word by double-clicking it, then right-click it and select the relevant alternative to define and insert the word into the system model as an object, property, method or value:

Once the errors are fixed, you can create the LSC by pressing ENTER, or by clicking the button at the view toolbar:

Statistical NL-Play-In Interface

In case you have a complete textual requirements document, the process of interactive NL play-in may be time consuming and tedious. Instead, PlayGo allows you to import a complete requirements document and transform it into LSCs in batch. Each sentence will be transform into a single LSC. Disambiguation decisions are made using a statistical model that is trained on previously analysed requirement documents. The statistical model is optimized based on two sources of information:

• content information, i.e., the grammatical structure and lexical items used in individual requirements.
• context information, i.e., the coherence of the model expressed in the complete document, as a whole.

The requirements document has to adhere to the following rules:

• Each line contains a single sentence.
• Each sentence expresses a single requirement / scenario.
• All sentences obey the same grammar restrictions as in the interactive NL play-in.
• The file should have the suffix .desc.

Uploading a requirements document

In order to upload a requirements document follow these steps:

1. Create a textual requirements document <filename>.desc that adheres to the format specified above. Locate the file in your LSC project.
2. Right-click the <filename>.desc file and select 'Import Description'. 
3. A <filename>.lsc files has been created under the same directory, containing a sequence of LSCs, each of which corresponds to one of the textual requirements. A system model for the entire system is created automatically.
   1. In case a <filename>.lsc file already exists in the same directory, you will be asked whether to override its contents.

Tuning the statistical model

The statistical model that is used for parsing requirements document may be tuned using the LSC project properties:

1. Right-click the LSC project, and select Properties->PlayGo->Play-in.
2. Select the StatisticalNL tab and choose a statistical grammar file:
   
   
   
3. Select one of the two parsing modes:
   1. Without context; i.e., applying the parser in a sentence-by-sentence mode.
   2. With context; i.e., applying the parser for parsing a complete requirements document.
      1. In case the "with context" option was selected, you can pre-define how many parse-candidates the model considers via the 'Number of candidates per requirements' box.
         NOTE: The number of candidates represents a tradeoff between system accuracy and parse time. The more candidates the model is allowed to consider, the higher the accuracy of the parser. However, if the number of candidates per sentence is too high, parsing performance may be negatively affected. A complete empirical investigation of this tradeoff may be found in .
4. Click 'OK'.

The statistical parser uses a pre-trained grammar based on a set of manually annotated requirements. Accuracy of the statistical parser may improve if you add more training examples for the statistical model. If you have a set of LSC examples that you would like to use for re-training the statistical parser, you can do so using the 'Train' button.

See also How to train a model for statistical play-in.

Learn from Examples

Examples of requirements written in natural language, can be found here:

- Wristwatch.

- Phone.

- Baby Monitor.

Show & Tell play-in

To use Show & Tell play-in, click the 'Show & Tell Play-In' button.

Consequently, the play-in session starts. If a GUI exists it is launched.
The 'NL Play-In' view is opened with the 'Interact Enable' button selected, in order to allow interaction with the GUI:


An interaction with the GUI (e.g., clicking a button) creates segment of NL text in the requirement text field of the 'NL Play-In' view.
If the interaction can be interpreted in more than one way, a squiggly line appears, indicating an error, and a quick fix dialog is displayed upon hovering. The error can be resolved using the quick fix dialog:

As in NL play-in, the LSC is created when pressing ENTER, or when clicking the button at the view toolbar.

System model play-in

With system model play-in, you can enter scenarios by selecting an object from the system model, right-clicking it and selecting the required operation. For example, to add an event from the user to an object, right-click the corresponding object's method and select 'Call Message'. As a result, the corresponding LSC snippet will be created:

To play in from the system model, create an LSC project, or select an existing one. In either case, the LSC project has to have a system model. If it doesn't, create a system model and click the 'Basic Play-In' button to start playing in:

You will be prompted to select a specification file name and location:

• Note that you can play in from the system model also using the 'NL Play-In' and 'Show & Tell Play-in' alternatives.