API du paquet publicodes

Attention

Publicodes est encore en version beta, et l'API peut-être sujette à des changements cassants lors de prochaines versions.

new Engine(rules)

Crée un moteur d'évaluation avec les règles publicodes données en argument.

Arguments

• rules : les règles publicodes utilisées. Ces dernières doivent être sous la forme d'un objet javascript respectant la syntaxe publicodes. Elle peuvent aussi être sous la forme de règles publicodes déjà parsées.
• options : les options de configuration du moteur
  • allowOrphanRules : par défaut, le moteur lève une erreur si une règle est orpheline (c'est-à-dire que sa règle parente n'existe pas). Pour désactiver cette vérification, il suffit de mettre ce paramètre à true.
  • logger : un logger permettant de spécifier le traitement des logs. Par défaut, les logs sont affichés dans la console. Par exemple, pour afficher seulement les erreurs, il suffit d'utiliser : logger: { log: (_) => {}, warn: (_) => {}, error: console.error }.
  • getUnitKey : permet de spécifier une fonction de normalisation des unités. Par défaut, les unités ne sont pas normalisées.

publicodes n'accepte plus en entrée une chaîne de caractères YAML, car le parser YAML alourdissait beaucoup la biblitothèque

Retourne Un moteur d'évaluation qui expose les fonctions suivantes :

• setSituation
• evaluate
• getRule
• getParsedRules

method engine.setSituation(situation)

Permet de spécifier une situation en entrée. Toutes les prochaines évaluations seront effectuées en se basant sur ces valeurs plutôt que les valeurs présentes dans la base de règles.

C'est le point d'entrée principal pour adapter les calculs de règles générales à une situation particulière. La situation est gardée en mémoire, et chaque appel à setSituation remplace la situation précédente. Le moteur contient donc un état interne. Cela permet d'obtenir de meilleures performances, avec une gestion plus fine du cache de calcul.

Arguments

• situation : un objet javascript qui associe le nom complet d'une règle à sa valeur. Cette valeur peut être n'importe quelle expression publicodes bien formée. Elle sera évaluée par le moteur. Cela permet de spécifier des nombres avec unité, des expressions, des références vers d'autres règles ou même d'utiliser des mécanismes.

• options : Paramètres optionnels sous forme d'objet

  • keepPreviousSituation : par défaut, l'appel à setSituation écrase la situation précedemment renseignée. Pour faire une mise à jour en gardant l'état en cours, il suffit de mettre ce paramètre à true.

Retourne L'objet engine (this) sur lequel la fonction a été appelée, afin de pouvoir utiliser une écriture chaînée (engine.setSituation(situation).evaluate()).

method engine.evaluate(expression)

Évalue l'expression dans le contexte du moteur (règle et situation).

Pour des raisons de performance, les résultats intermédiaires sont enregistrés dans un cache. Par conséquent, les appels suivants seront plus rapides.

Arguments

• expression: la valeur à évaluer. Cela peut-être n'importe quelle expression publicodes bien formée (expression arithmétique, mécanisme, réference vers une règle).

Retourne

Un objet javascript de type EvaluatedNode contenant la valeur calculée.

• missingVariables: contient les règles dont la valeur est manquante dans la situation
• nodeValue: la valeur calculée (type string, number, boolean, ou null)
• unit: si nodeValue est un nombre, contient l'unité associée

function formatValue(evaluatedNode, [options])

Formate la valeur evaluée.

Arguments

• evaluatedNode : l'objet retourné lors de l'appel à la fonction d'évaluation du moteur evaluate(expression)
• options : configuration pour le formatage
  • language: le langage utilisé pour le formatage (par défaut fr)
  • precision: le nombre de chiffre après la virgule pour le formatage des nombres (par défaut 2)
  • displayedUnit: l'unité à afficher pour le formatage des nombres. Outrepasse l'unité définie dans le calcul (on peut donc forcer l'unité affichée à une autre que celle retournée par le calcul, même si elle ne sont pas compatibles)

Retourne

La chaîne de caractère correspondant à la valeur bien formatée.