Verbs

This is the documentation for 1.18.0 version, which is not the latest version. Consider upgrading to 3.4.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:

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} )].