realise

Generates text from lex rules and input data (JSON data or other data types).

Note

This function works in “Describe a JSON Object” projects only.

Parameters

The parameters are specified in pairs enclosed in parentheses to form a list of tuples: realise((mydata1,lex-rule-class1),(mydata2,lex-rule-class2))). You must enclose a tuple in brackets even if you only have one tuple. Each tuple is specified as follows:

(data JSON or other data type, lex-rule-class string)

The first item in a pair (tuple) is valid JSON data or another data type (e.g. string, list or integer). The second item in the pair is the value of the “classes” parameter in a lex rule and it is used to select the rule. If more than one lex rule has the same value for “classes”, text is generated from the first rule found in the file.

Lex Rules Files

Lex rules are contained in XML files, which can contain one or more lex rules. You can import lex rules files into your project using the Lex Rules View. An example of a complete file is shown below. Note the heading and closing tags.

<?xml version="1.0" encoding="UTF-8"?>
<EnglishLexRuleSet xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

    <S id="LexRule1" classes="StringInput">
        <Subj word="{{msg.data}}"/>
	<VP word="live"/>        
	<Obj word="Paris" preposition="in"/>
    </S>

    <S id="LexRule2" classes="TwoStrings">
        <Subj word="{{msg.data[0]}}"/>
	<VP word="live"/>        
	<Obj word="{{msg.data[1]}}" preposition="in"/>
    </S>
  
    <S id="LexRule3" classes="Abode">
        <Subj word="{{msg.forename}}"/>
	<VP word="live"/>
      	<Obj word="{{msg.location}}" preposition="in"/>
    </S>
       
</EnglishLexRuleSet>

The individual lex rules in this file are used for the examples below.

Examples using string input data

These examples use the following lex rule:

<S id="LexRule1" classes="StringInput">
    <Subj word="{{msg.data}}"/>
    <VP word="live"/>        
    <Obj word="Paris" preposition="in"/>
</S>

The input data is specified in this lex rule via the Groovy scriptlet "{{msg.data}}".

The value of “classes” in this lex rule is "StringInput", so you generate text from the rule by using “StringInput” as the second item in the tuple:

ATL in Script	Result
`[[realise(('Bill','StringInput'))]]`	Bill lives in Paris.
`[[realise(('Bill','StringInput'),('Jim','StringInput'))]]`	Bill lives in Paris. Jim lives in Paris.
`[[realise((('Bob','Bill','Ben'),'StringInput'))]]`	Bob, Bill and Ben live in Paris.
`[[realise(())]]`	Syntax Error

If your lex rule requires more than one data item, you can provide realise with a list of inputs. For example, you could use the following lex rule:

<S id="LexRule2" classes="TwoStrings">
    <Subj word="{{msg.data[0]}}"/>
    <VP word="live"/>        
    <Obj word="{{msg.data[1]}}" preposition="in"/>
</S>

In this rule both the Subject (Subj) and Object (Obj) components of the sentence require input data. The rule expects the input data to be in a list and refers to the required item in the list with array notation: "{{msg.data[0]}}" and "{{msg.data[1]}}".

This time the lex rule has classes="TwoStrings", so you generate text from the rule by using ‘TwoStrings’ as the second item in the tuple:

ATL in Script	Result
`[[realise((('Bill','London'),'TwoStrings'))]]`	Bill lives in London.

Examples using JSON input data

This example uses the following JSON data:

{
    "people": [
        {
            "forename": "John",
            "location": "London"
        },
        {
            "forename": "Anna",
            "location": "New York"
        },
        {
            "forename": "Peter",
            "location": "New York"
        }
    ]
}

and makes use of the following lex rule:

<S id="LexRule3" classes="Abode">
    <Subj word="{{msg.forename}}"/>
    <VP word="live"/>
    <Obj word="{{msg.location}}" preposition="in"/>
</S>

Notice that JSON data is specified explicitly in a lex rule by providing its key in the Groovy scriptlet, e.g. "{{msg.forename}}" and "{{msg.location}}".

This time the lex rule has classes="Abode", so you generate text from the rule by using ‘Abode’ as the second item in the tuple:

ATL in Script	Result
`[[realise((WholeJSON.people,'Abode'))]]`	John lives in London. Anna lives in New York. Peter lives in New York.

Note that realise outputs one sentence for each element in the input JSON array WholeJSON.people.

Tip

For a guide to using realise with other input data types, see More on the realise function.

For an introductory tutorial on lex rules, see Working with lex rules.