Verbs

This is the documentation for 3.2.3 version, which is not the latest version. Consider upgrading to 4.3.0.

A proper NLG system is able to make conjugations. Classic structures are subject/verb or subject/verb/adjective.

Supported persons are 3rd person singular & plural only.

Before anything we need to define what subjects can be.

Subjects

A subject has to have a gender and a number. A simple way to define a subject is to use an existing js object and to affect it a gender and a number.

var PRODUCT = {something: 'somehow'};
setRefGender(PRODUCT, 'M');
setRefNumber(PRODUCT, 'P');
in French, German, Italian and Spanish, setRefGender(PRODUCT, 'bague'); will look for bague in the dictionnary and set PRODUCT gender to F. Same as setRefGender(PRODUCT, 'F'); here.

If you don’t want to bother with objects because they don’t exist or are too insignificant to be really created, you can ask the system to provide anonymous subjects:

var subjS = getAnonymous('M', 'S');

getAnonymous(gender, number) will create an anonymous object and record is with the right gender and number. There are shortcuts: getAnonMS(), getAnonMP(), getAnonFS(), getAnonFP().

At last, you can use complex structure like referring expressions to define your subjects.

Instead of a single element, you can put a list of subjects. A random subject will be chosen in that list. This is useful when the subject is a noun.

Conjugate verbs subjectVerb and verb

Use subjectVerb(subject, verb) to agree a verb with a subject. +subjectVerb(PRODUCT, 'shine') will output the ring shines.

verb(subject, verb) will just output the agreed verb but not the subject. +verb(PRODUCT, 'shine') will output shines.

Instead of putting directly a verb (like shine), you can add extra parameters for the verb, typically the tense. +subjectVerb(PRODUCT, {verb:'shine', tense:'PAST'}) will output the ring shined.

You can as well put a list of verbs. A random verb will be chosen in the list: #[+verb(SOME_SUBJECT, ['sleep', 'eat', 'go'])] or #[+verb(SOME_SUBJECT, {verb: ['sleep', 'eat', 'go']})].

subjectVerb and verb also accept a last optional param which is transmitted as is to the subject. For instance, +subjectVerb(PRODUCT, 'shine', {REPRESENTANT: 'refexpr'}) will force the referring expression representation of the product, thus outputting something like it shines.

Tenses are language specific, as well as some other parameters (e.g. the auxiliary in French). See specific parameters for:

There are "universal tenses" which you can use independantly of the language, see Universal tenses table.

Conjugate verbs and agree adjectives with subjectVerbAdj

Use subjectVerbAdj(subject, verbInfo, adjective) to directly generate a subject, a conjugated verb and an agreed adjective. #[+subjectVerbAdj(PRODUCT, 'être', 'luxueux')] will output la bague est luxueuse.

adjective can be a list of adjectives. A random synonym will be chosen in that list.

subjectVerbAdj also accepts a last optional parameter that is transmitted as is to the subject.

For instance, #[+subjectVerbAdj('lampe', 'être', ['somptueux', 'beau', 'lumineux'], {det:'DEFINITE'})] will output la lampe est somptueuse, la lampe est lumineuse, or la lampe est belle.

Also see agree adjectives.

You can put a list of nouns as the subject as well. #[+subjectVerbAdj(['lampe', 'génie'], 'être', ['somptueux', 'beau'], {det:'DEFINITE'})] will generate le génie est somptueux, la lampe est somptueuse, la lampe est belle, le génie est beau.

Silent the subject with noSubject

subjectVerb and subjectVerbAdj output the subject. To silent it (like in verb), use the noSubject flag. #[+verb(PERS, 'chanter')] is the same as #[+subjectVerb(PERS, 'chanter', {noSubject:true} )].

Universal Tenses

"Universal tenses" have a meaning for multiple languages. You may use them instead of their "local" name.

For most usages, it is recommended to favor local name.
Table 1. English specific
Universal tense English French German Italian Spanish

UNIVERSAL_PRESENT

SIMPLE_PRESENT

PRESENT

PRASENS

PRESENTE

INDICATIVE_PRESENT

UNIVERSAL_PERFECT

PERFECT_PRESENT

PASSE_COMPOSE

PERFEKT

PASSATO_PROSSIMO

INDICATIVE_PERFECT

UNIVERSAL_PLUPERFECT

PERFECT_PAST

PLUS_QUE_PARFAIT

PLUSQUAMPERFEKT

TRAPASSATO_PROSSIMO

INDICATIVE_PLUPERFECT

UNIVERSAL_FUTURE

SIMPLE_FUTURE

FUTUR

FUTUR1

FUTURO_SEMPLICE

INDICATIVE_FUTURE

UNIVERSAL_PAST

SIMPLE_PAST

IMPARFAIT

PRATERITUM

IMPERFETTO

INDICATIVE_PRETERITE_PERFECT