jsRealB (Version ) - Documentation

jsRealB est un réalisateur de texte pour l'anglais et le français écrit en JavaScript. Il peut être utilisé soit à l'intérieur d'une page web comme celle-ci dont tous les exemples sont réalisés dynamiquement, ou comme module Node.js.

jsRealB is a text realizer for French and English written in JavaScript. It can be used either within a web page such as this one whose examples are dynamically realized or as a Node.js module.

Si vous travaillez en Python, vous serez peut-être plus intéressé par pyrealb qui utilise la même notation pour la description des composants des phrases.

If you are working in Python, you might be more interested by pyrealb which uses the same notation for describing the sentence components.

Constituants

Constituents

Déclinaisons et conjugaisons

Declension and conjugation

Perfect and continuous tenses for verbs can obtained by setting the sentence type to .typ({perf:true}) or .typ({prog:true})

Pronoms

Pronouns

Les pronoms qui sont dans le lexique sont à la 1ère personne du singulier. Pour obtenir les autres, il faut spécifier la personne, le nombre et éventuellement le genre. Ce mécanisme s'applique aussi pour les pronoms me et moi-même et pour le déterminant mon.

Pronouns in the lexicon are at the first person singular. To get the other forms, the gender, the number and the person must be specified. The same option mechanism can be used for the pronouns mine and myself and for the determiner my.

Mise en forme

Formatting

Si l'ajout avant et/ou après un constituent correspond à un signe de ponctuation défini dans les règles, l'espacement approprié est ajouté avant et après le signe, sinon la chaîne est ajoutée telle quelle sans espacement.

If the content added before and/or a constituent is defined in the language rules, then the appropriate spacing is added before and after the punctuation sign, otherwise the content is added without spacing.

Position et pronominalization

Position and pronominalization

Modification du type de phrase

Sentence type modification

Les phrases sont construites à la forme active, mais il est possible d'en modifier le type pour obtenir des phrases négatives, progressives, interrogatives ou passives. Ces modifications sont de la forme S(...).typ({...}) Il est possible de combiner plusieurs modifications en spécifiant plusieurs paires clés-valeurs dans l'objet paramètre de .typ. L'utilisation de contractions en anglais telles que I'll pour I will ou can't pour cannot peut aussi être spécifiée de cette manière, mais cet indicateur est ignoré en français.

Ces modifications peuvent aussi être appliquées aux structures en dépendances.

Sentences are built at the active voice, but their type can be modified in order to get negative, progressive, interrogative or passive sentences. These modifications are indicated by S(...).typ({...}). Modifications can be combined by specifying multiple key value pairs in the object which is the parameter of .typ. The use of contractions such as I'll for I will or can't for cannot can also be specified in this way. This flag is ignored in French.

These modifications can also be applied to dependency structures.

Date

Date

Nombres

Numbers

On crée un nombre avec NO(...) dont le paramètre est soit un nombre entier ou réel ou une chaîne qui peut être analysée comme un nombre.

A number is created with NO(...) whose parameter is either a number (integer or real) or a string that can be parsed as a number.

JavaScript

JavaScript

loadEn(trace), loadFr(trace), load(lang,trace)

Ces fonctions indiquent la langue à utiliser pour les prochaines réalisations. Il est important d'en appeler au moins une avant de débuter la réalisation d'une phrase. lang doit être en ou fr. Si le paramètre trace est true, (il est false par défaut) un message apparaîtra sur la console à la fin du chargement du lexique et de règles du langage.

These functions sets the current realization language; one of them should be called before starting the realization process. lang must be en or fr. If the parameter lang is true, (it is false by default), a message is written on the console after the loading of the lexicon and language rules.

.realize(lang) / .toString()

Lance la réalisation d'un constituent, cette opération peut modifier la structure d'un ou plusieurs constituents. Si lang est spécifié, on appelle load(lang) avant la réalisation. Dans la grande majorité des cas la réalisation est plutôt obtenue par .toString() souvent appelée implicitement par le système lorsqu'une expression est utilisée dans un contexte de string. .realize() peut être utile lors de la mise au point dans certains environnements de programmation (e.g. Visual Studio Code) qui utilisent .toString() pour l'affichage et qui donc risque de changer la structure au cours de la mise au point. Pour éviter ces problèmes, il faut effectuer Constituent.debug=true; et .toString() affichera le source de l'expression, mais alors il faut demander la réalisation explicite avec .realize().

Launch the realization of a constituent which in some cases modifies the structure of one or more constituents. If lang is specified, load(lang) is called before the realization. In the majority of cases, realization is instead obtained with .toString() often called implicitely by the system when an expression is used in a string context. .realize() can be useful when debugging in some programming environments (e.g. Visual Studio Code) which call .toString() for displaying internal values and thus risk changing the constituents during debugging. To avoid theses situations, the following assignment Constituent.debug=true; can be used and .toString() will display the source of the expression. But then realization is obtained by calling .realize() explicitly.

.toSource(indent)

Cette fonction retourne une version chaîne d'une expression jsRealB, ceci peut être utile pour la mise au point d'une expression complexe. Si indent est spécifié (souvent 0) au premier appel à cette fonction, on obtient une expression indentée qui fait ressortir la structure de l'expression, si indent est absent, l'expression est sur une seule ligne.

This function returns a string version of a jsRealB expression, this can be useful for debugging complex expressions. When indent is set (often 0) the the first call, the string is on multiple lines and indented to highlight the underlying structure. When indent is not given, the returned string is a single line.

getLanguage()

Cette fonction retourne le langage courant de réalisation: "fr" pour le français et "en" pour l'anglais.

This function returns the current realization language: "fr" for French and "en" for English.

.clone()

Comme les options modifient le constituant dans toutes les utilisations subséquentes, il est souvent pratique de pouvoir garder la version originale pour la réutiliser et la modifier indépendamment. L'option clone() permet de copier un syntagme pour utilisation dans des contextes différents.

As options modify the constituent for all following use, it is often useful to keep the original constituent and modify it independently. The clone() option allows reusing a constituent in different contexts.

Une alternative à clone() est d'associer une fonction à une variable, ce qui créera une nouvelle expression à chaque appel. Ceci permet de paramétrer l'expression, comme le nombre dans l'exemple suivant, mais qui sera au singulier par défaut. L'utilisation d'une fonction fléchée (pommeFF) simplifie la notation.

AS an alternative to clone(), a function can be assigned to a variable. Each call to this function creates a new expression. This also allows parameterizing the expression, e.g. the number in the following example that is singular by default. The use of an arrow function (appleAF) simplifies the notation.

.add(element,position)

Ajout d'un nouveau syntagme element comme enfant à un syntagme existant. Le paramètre entier position est facultatif et spécifie la position (à partir de 0) dans le syntagme. Par défaut, l'élément est ajouté à la fin.

Add a new phrase element as a child of an existing phrase. The second optional parameter position is an integer that specifies its position (counting from 0). By default, the element is added as the last child.

.remove(position)

Suppression du constituant à la position spécifiée en comptant à partir de 0.

Remove the constituent at the given position starting from 0.

.nbConstituents()

Retourne le nombre de constituents de la Phrase ou Dependent actuel.

Returns the number of constituents in the current Phrase or Dependent

.nbConstituents()

Retourne la liste des constituents de la Phrase ou Dependent actuel.

Returns the list of constituents in the current Phrase or Dependent

Chargement dans une page web

Loading in a web page

Il suffit d'ajouter le script jsRealB.js du répertoire dist à la liste des scripts de la page. Ceci intègre déjà deux lexiques: français (plus de 52 500 entrées) et anglais (plus de 33  900 entrées). Comme indiqué à la section Extension du vocabulaire, il est facile d'ajouter de nouvelles entrées au lexique.

It is only a matter of adding the script jsRealB.js to the scripts used by the web page. This includes two lexicons: English (33 900 entries) and French (52 500 entries). As shown below in the Vocabulary extension section, it is possible to add new entries to the lexicon or to change it completely.

Le script jsRealB.js exporte un seul objet jsRealB dont les champs sont les fonctions de jsRealB qu'il est plus pratique d'ajouter à l'environnement global, sinon il faudra préfixer par jsRealB. tous les appels. Une manière pratique de le faire est avec l'expression Object.assign(globalThis,jsRealB) qui doit être exécutée avant toute fonction de jsRealB sans préfixe. En particulier les fonctions de chargement de dictionnaire et de règles: loadFr(...) ou loadEn(...).

The jsRealB.js script exports a single object jsRealB whose fields are the jsRealB functions which are more convenient to use when they are part of the global environment, otherwise jsRealB. should be added to each call. A simple way of doing this is by executing the expression Object.assign(globalThis,jsRealB) which should be executed before any jsRealB function call without prefix. In particular any language and rule change: loadFr(...) ou loadEn(...).

Comme jsRealB est construit avec de modules JavaScript, plutôt que d'utiliser l'élément HTML script, il est possible depuis un autre module d'accéder aux fonctions de réalisation en utilisant import "./dist/jsRealB.js"; qui a le même effet. Attention: import ne peut être utilisé que dans un script indiqué avec l'attribut type="module".

As jsRealB is built using JavaScript modules, instead of using the script HTML element, it is also possible to access the realizing function using import "./dist/jsRealB.js"; from a JavaScript modul which has the same effect. Caution: the calling script tag must have the attribute type="module".

Idéalement, vous installerez votre propre version de jsRealB à partir des sources du GitHub et vous la référencerez depuis l'élément script. Mais vous pouvez aussi télécharger une version déjà minifiée à partir de ce répertoire.

Ideally you should install your own version of jsRealB from the GitHub sources and you will refer to it using a script element. But you can also get minified versions from this directory.

Module Node.js

Node.js Module

jsRealB peut aussi être utilisé avec Node.js en important le module jsRealB avec import jsRealB from './jsRealB.js'; qui exporte le symbole jsRealB. On peut aussi accéder au module npm jsrealb (attention à la casse différente), avec import "jsrealb" si, au préalable, on l'a installé avec npm install jsrealb. L'accès aux constructeurs de syntagmes du module Node doit se faire de la façon suivante jsRealB.S(...) ce qui peut s'avérer laborieux. Il est donc plus pratique de définir les constructeurs dans le contexte global en exécutant l'expressions suivante:

The jsRealB versions can also be used with Node.js with an instruction such as import "./dist/jsRealB.js";. It is also possible to use the npm jsrealb (check for the differing capitalization), with import "jsrealb" if, beforehand, it has been installed on your machine with npm install jsrealb. Phrase constructors from the Node module must be called as jsRealB.S(...) which can be tedious. It is thus more convenient to define these constructors in the global namespace with the following expression:

Un script JavaScript peut vérifier s'il est utilisé comme module Node.js en consultant la variable booléenne isRunningUnderNode.

A JavaScript script can check if it used as Node.js module with the boolean variable isRunningUnderNode.

Un exemple simple d'utilisation du module Node.js est ce filtre Unix qui accepte une expression jsRealB sur une seule ligne et retourne sa réalisation en anglais.

A simple example of the use of the Node.js module is this Unix filter which transforms a jsRealB expression on a single line and returns the corresponding English realization.

Il est possible d'écrire des modules qui peuvent être exécutés en tant que module Node.js, mais aussi utilisés depuis un script dans une page web. Ce répertoire donne des exemples de patrons d'utilisation.

It is possible to write Node.js modules that can also be used from web page script. This directory shows some code patterns illustrating different use cases.

Gestion des lexiques

Lexicon Management

jsRealB intègre déjà deux lexiques assez détaillés: français (plus de 52 500 entrées) et anglais (plus de 34 200 entrées) qu'il est possible de consulter et de modifier à l'aide des fonctions suivantes. Lorsque lang ("en" ou "fr") est spécifié, la fonction s'applique au lexique de cette langue, sinon au lexique courant, celui du dernier appel à loadEn() ou loadFr().

jsRealB provides already two comprehensive lexicons: French (more than 52 500 entries) and English (more than 34 200 entries) that can be queried and modified with the following functions. When lang ("en" or "fr") is specified, the function is applied to the lexicon of this language, otherwise it applies to the current lexicon, the one of the last call to loadEn() or loadFr().

addToLexicon(lemma[,newInfos][,lang])

lemma est l'entrée de base et newInfos est l'information morphologique selon le format interne à jsRealB: un objet indiquant le ou les catégories possibles et pour chaque catégorie, des propriétés et la table de déclinaison ou conjugaison correspondantes. Par exemple, addToLexicon("jsRealB",{"N":{"g":"m", "pe":3, "tab": "nI"}) ajoutera le mot jsRealB comme nom masculin invariable au lexique courant. Cette fonction peut aussi être appelée avec un seul paramètre qui est un objet dont la clé est le lemme. L'exemple précédent peut donc s'écrire: addToLexicon({"jsRealB":{"N":{"g":"m", "pe":3, "tab": "nI"}}).

• Si le lemme et la catégorie existent déjà dans le lexique, alors l'entrée pour cette catégorie est remplacée par newInfos.
• Cette fonction retourne l'entrée modifiée pour lemma.
• Plus d'information (en anglais) sur le format des lexiques
• Pour déterminer les informations à ajouter, le plus simple est de copier les informations d'un mot du lexique qui se conjugue ou se décline de la même façon. L'IDE de jsRealB permet de consulter les informations du lexique.
• Pour enlever une entrée d'un lexique, il de mettre newInfos à null.

lemma is the basic form and newInfos is the morphologic information according to the internal jsRealB format: an object indicating one or many possible categories. For each category, properties and declension or conjugation are given. For example, addToLexicon("jsRealB",{"N":{"g":"m", "pe":3, "tab": "nI"}) will add the jsRealB as a masculine invariable word. This function can also be called with a single parameter: an object whose key is the lemma. The previous example could also have been written: addToLexicon({"jsRealB":{"N":{"g":"m", "pe":3, "tab": "nI"}}).

• If the lemma and category are already present in the lexicon, then the category of this entry is replaced by newInfos.
• This function returns the new modified lexicon entry for lemma.
• More information about the lexicon format
• In order to find the informations to add, the simplest way is to copy the lexicon information for a similar word already in the lexicon. The jsRealB IDE provides access to the lexicon information.
• To remove an entry, set newInfos to null.

getLemma(lemma[,lang])

Retourner les informations du lexique correspondant à lemma.

Return lexicon information to lemma.

updateLexicon(newLexicon[,lang])

Fusionner les entrées de newLexicon avec le lexique spécifié. Ceci ajoutera les nouvelles entrées et remplacera les entrées existantes par celles du nouveau lexique. La fusion est effectuée au niveau des entrées, mais non des catégories.

Merge the entries of newLexicon with the specified lexicon. This adds the new entries and replaces the existing entries by the ones of the new lexicon. Merging is done at the entry level, not at the category level.

getLanguage()

Retourne le langage de réalisation courant.

Returns the current realization language.

getLexicon()

Retourne le lexique courant.

Returns the current lexicon.

setQuoteOOV(value)

Lorsque cet identificateur est mis à true, les mots absents du lexique sont considérés comme des chaînes verbatim (i.e. Q(...) au lieu de susciter un avertissement et d'être affichés entre double crochets. Comme ceci empêche toute lemmatisation, accord ou transformation de phrases, il faut utiliser cet indicateur avec parcimonie.

When this flag is set to true, words that are not in the lexicon are considered as quoted strings (i.e. Q(...) instead of raising an warning and be displayed between double square brackets. As this prevents any lemmatization, agreement or sentence transformations, this flag should be used sparingly.

buildLemmataMap(lang)

Créer une table (une Map et non un objet Javascript). Chaque clé est une des formes déclinées ou conjuguées de tous les mots du lexique de la langue spécifiée. La valeur associée à une liste d'instances de Terminal qui sont réalisées par la clé.

Cette Map peut être utilisée pour de la génération inverse. Voici quelques appels suivis des résultats après ⇛

    const lemmataFr = buildLemmataMap("fr")
    lemmataFr.get("finies").map(e=>e.toSource()) ⇛ [A('fini').g("f").n("p"), V('finir').t("pp").g("f").n("p")]
    lemmataFr.get("crus").filter(e=>e.isA("N")).map(e=>e.toSource()) ⇛ [`N('cru').n("p")`]

Build a table (a Map, not a Javascript object). Each key is an inflected form of all the entries in the lexicon of the specified language. The associated value is a list of Terminal instances that are realized by the key.

This Map can be used for inverse generation. Here are examples of calls with the result shown after ⇛

    const lemmataEn = buildLemmataMap("en")
    lemmataEn.get("love").map(e=>e.toSource()) ⇛ [N('love'), V('love').t("b"), V('love').pe(1), V('love').pe(2), V('love').pe(1).n("p"), V('love').pe(2).n("p"), V('love').n("p")]
    lemmataFr.get("love").filter(e=>e.isA("N")).map(e=>e.toSource()) ⇛ [N('love')]

Sélection de variantes

Variant selection

oneOf(e1,e2,...)

où ei est est une valeur, choisit un ei au hasard. En jsRealB, ces éléments sont souvent des constructeurs correspondant à des structures de phrases différentes. Si e1 est un tableau alors la sélection est faite dans ce tableau, en ignorant les autres paramètres.

Pour éviter que tous les éléments soient évalués avant la sélection, il suffit de fonctionaliser l'expression en une fonction sans paramètre en la préfixant par ()=>, ce qui en fait une fonction fléchée. Une fois l'élément choisi, oneOf vérifie si la valeur est une fonction et si c'est le cas, il retourne le résultat de l'appel. Par exemple, oneOf(()=>N("amour"),()=>N("amitié")) permet de choisir entre les deux noms sans évaluer les deux constructeurs. Dans ce cas, très simple, il aurait été aussi possible d'écrire N(oneOf("amour","amitié")).

oneOf implante le "mode:once" de RosaeNLG: une alternative est choisie au hasard, mais en essayant de ne pas répéter la précédente. Lorsque toutes les alternatives ont été utilisées, le système recommence avec toutes les alternatives initiales, mais en évitant la dernière utilisée afin de ne pas se répéter.

where ei is a value, selects randomly a ei. In jsRealB, these elements are often constructors corresponding to different phrase structures. If e1 is an array, the selection is performed within this array, ignoring other parameters.

To avoid the evaluation of all elements before the selection, it is possible to functionalize a expression into a function with no formal parameter by prefixing it with ()=> which makes it an arrow function. Once the element is selected, oneOf checks if the value is a function and, if it is so, it returns the value of the called function. For exemple, oneOf(()=>V("love"),()=>V("like")) allows choosing between the two verbs without evaluating both constructors. In this simplistic case, this could have also been written as V(oneOf("love","like")).

oneOf implements the "mode:once" of RosaeNLG: it selects an alternative randomly, but tries not to repeat the same one. When all alternatives have been triggered, it resets but tries not run the last triggered alternative, avoiding repetitions.

choice(e1,e2,...)

Version de la fonction oneOf qui choisit une alternative sans tenir compte des choix précédents. C'est la méthode classique d'effectuer des choix aléatoires.

Version of oneOf that selects an alternative into account without taking previous choices. This is the classic implementation for making random choices.

mix(e1,e2,...)

permute ses paramètres, ce qui peut être utile pour varier l'ordre des éléments. Si e1 est un tableau alors la sélection est faite dans ce tableau, en ignorant les autres paramètres. Comme pour oneOf(...), pour éviter que tous les éléments soient évalués avant la sélection, il suffit de fonctionaliser l'expression en une fonction sans paramètre en la préfixant par ()=>, ce qui en fait une fonction fléchée. Pour chaque élément de la liste permutée, mix vérifie si sa valeur est une fonction et si c'est le cas, il le remplace par le résultat de l'appel.

shuffles its parameters, which can be useful to vary the order of elements. If e1 is an array, the selection is performed within this array, ignoring other parameters. As for oneOf(...), to avoid the evaluation of all elements before the selection, it is possible to functionalize a expression into a function with no formal parameter by prefixing it with ()=> which makes it an arrow function. For each element in the mixed list, mix checks if its value is a function and, if so, it inserts the value of the called function in the resulting list.

Traitement en JSON

JSON processing

Pour faciliter l'utilisation de jsRealB en sortie d'un système externe. Il est possible d'utiliser un format d'entrée JSON décrit dans ce document (en anglais) où sont décrites deux API permettant d'appeler un serveur jsRealB depuis un programme Python ou Prolog. Il est également possible d"obtenir une expression JSON correspondant à une expression jsRealB.

To simplify the use of jsRealB as output of an external system, a JSON input format has been defined. It is described in this document. in which two APIs are described for calling a jsRealB server from Python or Prolog. It is also possible to obtain the JSON expression corresponding to a given jsRealB expression.

Gestion des avertissements

Warning Management

Lorsque jsRealB détecte une erreur de réalisation, un avertissement est écrit sur la console JavaScript avec la fonction console.warn(). Le système réalise alors le lemme courant entouré de doubles crochets. Il est possible de modifier ce comportement afin de lever une exception au premier avertissement ou pour récupérer la liste des avertissements générés. Ce pourrait permettre de les afficher dans la page web, si la console JavaScript n'est pas accessible. Les fonctions suivantes permettent de gérer ces avertissements

When jsRealB detects a realization error, a warning is written on the JavaScript console using console.warn(). The lemma is then wrapped within double brackets. This behavior can be modified for raising an exception at the first warning or for getting back a list of warnings. It this then possible to display them in the web page if the JavaScript console is hidden. The following functions handle the warnings:

setExceptionOnWarning(val)

val est un booléen qui indique si oui ou non, une exception sera levée lors de l'émission d'un avertissement

val is a boolean indicating if an exception is raised when a warning is emitted.

resetSavedWarnings()

Réinitialiser la liste des avertissements.

Reset the list of warnings.

getSavedWarnings()

Récupérer la liste des avertissements, depuis le dernier appel à resetSavedWarnings sans modifier la liste. Une liste vide indique qu'aucun avertissement n'a été émis.

Get the list of warnings since the last call to resetSavedWarnings without changing the list. An empty list indicates that no warnings were emitted.

Informations sur l'implantation

Informations about the implementation

jsRealB_version

Indique le numéro de version de jsRealB, actuellement:

Gives the version number of jsRealB, currently:

jsRealB_dateCreated

Indique la date de la création de la version courante de jsRealB, actuellement:

Gives the creation date of the current jsRealB, currently:

isRunningUnderNode

Booléen qui indique si le script jsRealB a été appelé par Node.js.

Boolean indicating if the current jsRealB has been called by Node.js.

Informations complémentaires

More Information

• Document, en anglais, décrivant l'organisation de jsRealBDocument describing the organization of jsRealB
• Présentation de jsRealB - Février 2022 [enregistrement]Presentation of jsRealB (in French) - February 2022 [recording]
• Historique des versions et démonstrationsPrevious versions and demos
• Notebook ObservableObservable Notebook
• Edition et réalisation d'une expression jsRealBEdition and realization of a jsRealB expression
• Interactive Development Environment
• Tutoriel (en anglais)Tutorial
• Dépot GitHubGitHub repository
• Format des entrées de lexiques (en anglais)Format of the lexicon entries
• Publications:
  • Demo paper at ENLG-2015
  • Daoust, N., and G. Lapalme, JSreal: A Text Realizer for Web Programming, Language Production, Cognition, and the Lexicon - a Festschrift in honor of Michael Zock, Text, Speech and Language Technology, Vol 48: Springer, pp. 363-378, 2014. [PDF]