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.
Les accords simples sont effectués entre les constituants d'un syntagme. Un constituant est considéré comme la tête avec lequel les autres sont accordés. La tête est déterminée de la façon suivante:
NP
: le premier N
ou NP
en tenant compte de la modification possible par un NO
, cet accord est propagé à une subordonnée interne au NP
;AP
: le premier A
;VP
: le premier V
;le verbe est accordé avec le sujet (le premier NP
ou Pro
de la phrase englobante);S
, SP
: accord avec le sujet, soit le premier NP
, N
,
Pro
ou CP
. Si le Pro
est un pronom relatif, le sujet de la subordonnée est utilisé. Des tests spécifiques permettent d'accorder le verbe être/be
ainsi que pour tenir compte des sujets coordonnés.Des options (section suivante) spécifiant le genre et le nombre l'emportent sur ces accords automatiques.
Simple agreements are dealt with between constituents of a phrase. A constituent is taken as the head with which others agree. The head is found as follows:
NP
: the first N
or NP
taking into account an eventual NO
, this agreement is propagated to an internal subordinate phrase;AP
: the first A
;VP
: the first V
; the verb agrees with its subject (the first NP
or Pro
in the enclosing sentence);S
, SP
: agrees with the subject, taken as the first NP
, N
,
Pro
or CP
. If the Pro
is a relative pronoun, the subject of the subordinate is taken. Specific tests take into account the verbs être/be
and the coordinate subjects.Options (next section) can override these automatic agreements.
Perfect and continuous tenses for verbs can obtained by setting the sentence type to .typ({perf:true})
or .typ({prog:true})
Le 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
.
.tn(..)
avec comme paramètre
""
: pour la forme tonique elle-mêmerefl
pour obtenir la forme réflexive (terminant en
-même
).c(..)
avec comme paramètre
nom
pour la forme nominativeacc
pour la forme accusative (complément d'objet direct)dat
pour la forme datif (complément d'objet indirect)nom
pour la forme réfléchieAfin de rester compatible avec la méthode de spécification précédente, les formes clitiques et toniques des pronoms doivent spécifier .pe(1)
pour le pronom moi
. Il en est de même pour les pronoms possessifs mien
et nôtre
ainsi que pour les déterminants possessifs mon
et notre
.
Le tableau suivant présente la forme obtenue au-dessus de la spécification jsRealB.
Le tableau suivant présente les pronoms possessifs qui s'accordent en genre et en nombre.
Les déterminants possessifs varient en genre et en nombre à partir de leur forme de base comme le montre le tableau suivant.
.tn(..)
with parameter
""
: for the tonic form itselfrefl
to get the reflexive form (ending with
self
).c(..)
with options:
nom
for the nominativeacc
for the accusative (direct object)dat
for the dative (indirect object)gen
for the genitive (noun complement)In order to stay compatible with the previous form of specification, when using tonic or clitic form,
pe(1)
must be specified for the pronoun me
.
The following table shows the realized form above the corresponding jsRealB expression.
Possessive determiners are specified by giving options for the number, the person,
the gender (when at the third person) and also if the owner (.ow(..)
)
is singular or plural. The following table shows the realization above its
jsRealB specification.
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.
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 type
. 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.
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 type
. 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.
DT
accepte en paramètre soit une date sous forme d'une chaîne de caractères ou un objet Javascript Date
.La chaine de caractères en entrée doit être dans un format reconnu par la méthode Date.parse()
, donc dans le format IETF-compliant RFC 2822 ou ISO8601.
Attention: Le comportement de l'objet Date()
diffère selon le navigateur. Il est fortement conseillé de fixer le fuseau horaire sinon il sera déterminé par le navigateur (voir ci-dessous).
DT(...)
takes as parameter either a date as a String
or a Date
javascript object.The input string must be a recognized format by Date.parse()
: either IETF-compliant RFC 2822 or ISO8601 format.
Warning: The behavior of Date()
depends on the browser. The timezone should be specified otherwise it might be given a different value according to the browser.
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. In English, numbers less than one hundred written in letters can also be used as input.
.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.
.toSource()
Cette fonction retourne une version chaîne d'une expression jsRealB, ceci peut être utile pour la mise au point d'une expression complexe. En passant 0 comme paramètre à ce fonction, on obtient une expression indentée qui fait ressortir la structure de l'expression.
This function returns a string version of a jsRealB expression, this can be useful for debugging complex expressions. But giving 0 as parameter of this function, the expression is indented to show the underlying structure.
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.
loadEn(trace), loadFr(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. Le paramètre (false
by default) est le suivant:
true
, 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. Its parameter, (false
by default) is :
true
, a message is written on the console after the loading of the lexicon and language tables.Il suffit d'ajouter le script jsRealB.js
à la liste des scripts de la page. Ceci intègre déjà deux lexiques de base: français (3 700 entrées) et anglais (5 200 entrées). Comme indiqué à la section Extension du vocabulaire, il est facile d'ajouter de nouvelles entrées ou même de remplacer complètement les dictionnaires par défaut.
It is only a matter of adding the script jsRealB.js
to the scripts used by the web page. This includes two basic lexicons: English (5 200 entries) and French (3 700 entries). As shown below in the Vocabulary extension section, it is possible to add new entries to the lexicon or to change it completely.
loadFr(...)
should be called before starting realizing French sentencesdevrait être appelé avant de réaliser des phrases en françaisloadEn(...)
should be called before starting realizing English sentences.devrait être appelé avant de réaliser des phrases en anglaisIdé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.
Des exemples d'intégration dans une page web peuvent être trouvés à la section Démonstrations de cette page
Examples of web page integration can be found at the Demonstrations section of this page
Node.js
Node.js
ModuleLes versions de jsRealB décrites à la section précédente peuvent aussi être utilisées avec node.js
en utilisant une instruction de la forme jsRealB=require("...")
The jsRealB versions can also be used with node.js
with an instruction like jsRealB=require("...")
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.
Trucs pratiques:
Useful tricks:
jsRealB.S(...)
ce qui peut s'avérer laborieux. Il est donc plus pratique de définir les constructeurs dans le contexte global (même si ceci pourrait être considéré comme une mauvaise pratique en génie logiciel) en exécutant le code suivant:jsRealB.S(...)
which can be tedious. It is thus more convenient (although it could be seen as bad software engineering practice) to define these constructors in the global namespace by executing the following code:for (var v in jsRealB) eval(v+"=jsRealB."+v);
node.js
avec le test suivant:node.js
module with the following:if (typeof module !== 'undefined' && module.exports) { ... }
jsRealB
intègre déjà deux lexiques de base: français (3 700 entrées) et anglais (5 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
has already two basic lexicons: French (3 700 entries) and English (5 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()
o 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({"tsunami":{"N":{"tab":["n1"]}}})
. 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
.
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({"tsunami":{"N":{"tab":["n1"]}}})
. If the lemma and category are already present in the lexicon, then the category of this entry is replaced by newInfos
.
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.
La fonction 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 une liste alors la sélection est faite dans cette liste, 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,
ofOne(()=>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é"))
.
The function oneOf(e1,e2,...)
where ei
is a value, selects randomly a ei
. In jsRealB
, these elements are often constructors corresponding to different phrase structures. If e1
is a list, the selection is performed within this list, 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"))
.
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). 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.. It is also possible to obtain the JSON expression corresponding to a given jsRealB
expression.
Lorsque jsRealB
détecte une erreur de réalisation, un avertissement est écrit sur la console 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. 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 keeping a list of warnings. 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.