Value mixin

This is the documentation for 1.5.2 version, which is not the latest version. Consider upgrading to 3.4.0.

The value(obj, params) mixin is the entry point to insert a value in a text. Its behavior depends of the type of obj.

value is the entry point of many RosaeNLG features. Don’t miss it!

Structured object

When it is a structured object, you have to define how to transform it into text: see referring expressions.

String

When it is a string, it will be output as is. You can protect it from untimely capitalization etc. using protectString.

Additional parameters:

  • represents to assign the gender of the word to the representant (in French).

  • det to add a determiner; current determiners are DEFINITE, INDEFINITE and DEMONSTRATIVE. In English (and Italian), for DEMONSTRATIVE, use dist with NEAR (default) for this/these and FAR for that/those.

  • case to indicate the case (German only); current cases are NOMINATIVE and GENITIVE.

  • adjectives: can take multiple forms:

    • use adj:'nice' to indicate a single adjective

    • or multiple ones: adj:['nice','big']

    • in French and Italian, default position of the adjective is after the noun: les gâteaux délicieux, but not always: les bons gâteaux. Set adjPos to BEFORE or AFTER to change the position of the adjective.

    • when you wish to have some adjectives before the noun and some other adjectives after, you can use the full form: #[+value('vache', {det:'INDEFINITE', adj:{ BEFORE: ['beau', 'intelligent'], AFTER: ['brun'] } })] will generate une belle et intelligente vache brune

  • owner to indicate an owner. See third possession.

  • in Italian, you can add a possessive adjective: #[+value('gioiello', {det: 'DEFINITE', possessiveAdj:'mio'})] (you could also use adj directly for it but possessive adjectives are automatically placed properly)

In German, #[+value('Gurke', {case:'GENITIVE', det:'DEFINITE', adj:'alt'})] will output der alten Gurke.

outputs un vieil homme / un vieux Hollandais

Same in Italian:

outputs specchi belli / begli specchi

Table 1. All those 4 constructions do exactly the same thing

Just plain text, and setting gender directly:

| cette bague
- setRefGender(PRODUIT, 'F');

Just plain text, and using the dictionnary to set the gender (French or German):

| cette bague
- setRefGender(PRODUIT, 'bague');

Using value with represents option (and dictionnary lookup):

| cette #[+value('bague', {represents: PRODUIT})]

Using value with represents and det options (and dictionnary lookup):

| #[+value('bague', {represents: PRODUIT, det: 'DEMONSTRATIVE'})]
When some words or expressions are not in the dictionnary, you can indicate explicitely the gender: #[+value('OnePlus 5T', {represents: PRODUKT2, gender:'N', det: 'DEFINITE'})] will output das OnePlus 5T in German.

String with simplified syntax

A simplified syntax can be used to indicate a determiner, an adjective and a gender, with #[+value('<…​>')].

This feature is still quite young. It is mostly useful in French, German and Italian (less in English).
Table 2. Examples
Classic syntax Simplified syntax

#[+value('caméra', {det:'DEFINITE', adj:'vieux', adjPos:'BEFORE'})]

#[+value("<la vieille caméra>")]

#[+value('gâteau', {det:'INDEFINITE', adj:'délicieux', number:'P'})]

#[+value("<des gâteaux délicieux P>")]

#[+value('homme', {det:'INDEFINITE', adj:'beau', adjPos:'BEFORE'})]

#[+value('<une beau hommes>')]

#[+value('bague', {det:'DEMONSTRATIVE', adj:'exquis', adjPos:'BEFORE', represents: PRODUIT})]

#[+value('<cette exquis bague>', {represents: PRODUIT})]

#[+value('Gurke', {case:'GENITIVE', det:'DEFINITE', adj:'alt'})]

#[+value("<der alte Gurke>", {case:'GENITIVE'})]

#[+value('Telefon', {case:'ACCUSATIVE', det:'DEFINITE', adj:'neu'})]

#[+value('<der neu Telefon>', {case:'ACCUSATIVE'})]

#[+value('house', { det:'DEMONSTRATIVE', dist:'FAR'})]

#[+value('<that house>')]

#[+value('torta', {adj:'delizioso', adjPos:'BEFORE', number:'P'})]

#[+value("<delizioso torta P>")]

Guidelines:

  • Supported determiners are definite articles (le la les), indefinite articles (un une des), and demonstrative pronouns (ce cet cette ces).

  • Nothing is deducted from the specific article you choose. <la arbre> is the same as <le arbre>.

  • Adjectives must be in dictionnary.

  • Adjective can be before or after the noun (put it a the proper place!), and is optional.

  • Determiner is optional.

  • If nouns are not in the dictionnary, you must provide a gender (M or F). For instance #[+value('<la bon schwarzwald F>')] will output la bonne schwarzwald.

  • You can add a number at the end (S or P).

  • The parser will raise an error at runtime if the expression is not properly parsed.

  • You can add further parameters (like {represents: …​}).

  • The parser can be confused in some cases. For instance, in <le beau hâbleur>, hâbleur can be both an adjective and a noun, and beau too - even if in this situation it is quite clear that beau is the adjective and hâbleur the noun.

  • The simplified syntax does not work for inside the browser (neither for compilation nor for simple rendering) because it would require to embed too much linguistic resources.

Date

When it is a date, the moment lib will be used to format it. You should put a parameter to indicate how to format it:

will output April 14, 1980 in English.

See displaying dates with moment.js for options.

The date has to be a real standard javascript date, not a string. If you have a string parse it before, using new Date(string) or util.moment.

Number

When it is a number, you have various options:

  • by default it will format the number accordingly to the locale: 562407 will output 562,407 in en_US, 562 407 in fr_FR (thanks to format-number-french lib)

  • set AS_IS flag to true to avoid this (available in any language)

  • set TEXTUAL flag to true to transform the number into text: #[+value(5500, {'TEXTUAL':true })] will output five thousand five hundred

  • set ORDINAL_NUMBER flag to true to to transform the number into an ordinal number: #[+value(21, {'ORDINAL_NUMBER':true })] will output 21st

  • set ORDINAL_TEXTUAL flag to true to to transform the number into an ordinal text: #[+value(20, {'ORDINAL_TEXTUAL':true })] will output twentieth

  • use FORMAT to set a format directly used by numeral. See numeral.js formats. Very practical for currencies, %, etc.

numeral takes into account the locale: +value(104000, {'FORMAT': '0a$'}) will output 104k€ (yes, €!) when generating French.
Table 3. Number formatting support depending on languages
Feature en_US fr_FR de_DE it_IT

Default: standard number formatting

yes

yes

yes

yes

TEXTUAL

yes

yes (but doesn’t work with decimal numbers)

yes (doesn’t work with decimal numbers)

yes (doesn’t work with decimal numbers, and up to 30)

ORDINAL_NUMBER

yes

yes

yes

yes

ORDINAL_TEXTUAL

yes

yes (up to 100)

yes (up to 100)

FORMAT