From e7e8d93a6b551461a4bcebd1174e41d39600ea0e Mon Sep 17 00:00:00 2001 From: Nicolas Thouvenin Date: Mon, 20 Jan 2025 17:26:16 +0100 Subject: [PATCH] =?UTF-8?q?docs:=20=E2=9C=8F=EF=B8=8F=20improve=20some=20p?= =?UTF-8?q?ages?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/_sidebar.md | 6 +++--- docs/coding-ini.md | 44 +++++++++++++++++++++++----------------- docs/coding-statement.md | 18 ++++++++-------- docs/index.html | 16 +++++++++++++-- 4 files changed, 51 insertions(+), 33 deletions(-) diff --git a/docs/_sidebar.md b/docs/_sidebar.md index ef7d626f..660509f4 100644 --- a/docs/_sidebar.md +++ b/docs/_sidebar.md @@ -7,9 +7,9 @@ - Fonctionnement - - [d’une instruction](coding-statement.md) - - [d’un fichier .ini](coding-ini.md) - - [d’un sous flux](coding-sub-pipeline.md) + - [Instruction](coding-statement.md) + - [Fichier .ini](coding-ini.md) + - [Sous flux](coding-sub-pipeline.md) - Plugins diff --git a/docs/coding-ini.md b/docs/coding-ini.md index dbcb2e5e..d14ee3aa 100644 --- a/docs/coding-ini.md +++ b/docs/coding-ini.md @@ -1,18 +1,24 @@ # Fonctionnement d’un fichier .ini -## Présentation +Par nature un fichier `.ini` est descriptif, il est composé d'une liste de [sections]. Chaque section possède éventuellement des paramètres décrit avec un nom et une valeur. `ezs` considère chaque section comme une instruction, les listes des sections comme l'ordonnancement d'une suite de traitements. -Par nature un fichier `.ini` est descriptif, il permet facilement d’ordonnancer -une suite de traitements. +Les paramètres des section sont les paramètres des instructions. Dans un fichier .ini standard, les paramètres sont des valeurs statiques mais `ezs` propose également un paramétrage dynamique et contextuel des traitements. Cela permet d’adapter les traitements aux données reçues ou de paramétrer les traitements avec des variables d’environnement Toutes les valeurs des paramètres d’une section peuvent être dynamiques ou statiques. -Néanmoins il est très rarement possible de décrire une chaîne de traitements -sans un paramétrage dynamique et contextuel des traitements. +## Nom de l'instruction -Pour permettre d’adapter les traitements aux données, de paramétrer les -traitements grâce à des variables d’environnement, `ezs` propose de calculer les -valeurs des paramètres via un chaînage de fonctions (macros) prédéfini. +Le nom de chaque section du fichier .ini correspond au nom d'une fonction de traitement ([une instruction](statement)). + +Les fonctions disponibles varient en fonction des [plugins](plugin) qui sont installés et déclarés en début de fichier. Par défaut, seules fonctions [core](plugin-core) sont disponibles. + +Pour charger d'autres fonctions on utilisera l'instruction `[use]`. Exemple: + +```ini +[use] +plugin = basics +plugin = analytics +``` +Dans cette exemple, on chargera les plugins [basics](plugin-basics) et [analytics](plugin-analytics) ce qui permettra d'utiliser dans le fichier .ini toutes les fonctions de ces deux plugins. -Toutes les valeurs des paramètres d’une section sont dynamiques. ## Valeurs statiques @@ -55,9 +61,9 @@ param4 = fix('Voici ', 'valeur', ' ', 'concaténée').join('') ## Valeurs dynamiques -Il est possible de calculer une valeur à partir de l'item courant (objet JSON reçu). Pour cela `ezs` utilise le mécanisme de chaînage de fonctions proposé par [lodash](https://lodash.com/docs/4.17.15#chain). +`ezs` propose de définir dynamiquement les valeurs des paramètres via un chaînage de fonctions (macros) prédéfini. Il est possible de calculer une valeur à partir de l'item courant (objet JSON reçu). Pour cela `ezs` utilise le mécanisme de chaînage de fonctions proposé par [lodash](https://lodash.com/docs/4.17.15#chain). -Toutes les fonctions chaînables dans lodash sont utilisables. La valeur initiale de la chaine est l'objet courant sur lequel on peut appliquer des fonctions lodash de transformation. +Toutes les fonctions chaînables dans lodash sont utilisables. La valeur initiale de la chaîne est l'objet courant sur lequel on peut appliquer des fonctions [lodash](https://lodash.com/docs/) de transformation. `ezs` propose quelques fonctions supplémentaires : fix(), env(), self(), prepend(), append() @@ -70,7 +76,7 @@ param1 = get('nom_du_champ').split('--').head() ``` Ici, `get('nom_du_champ')` récupère la valeur du champ `nom_du_champ` dans l'objet qui sera utilisé par l'instruction [STATEMENT] . C'est l'équivalent du JavaScript `_.get(obj, 'nom_du_champ')`. Voir [la documentation de lodash](https://lodash.com/docs/4.17.15#get). -En interne, pour l'exemple précédent `ezs` exécute l'instruction lodash suivante : +En interne, pour l'exemple précédent `ezs` exécute l'instruction lodash suivante : ```js _.chain(objet_courant).get('nom_du_champ').split('--').head().Value() ``` @@ -106,7 +112,7 @@ Cette fonction spécifique à `ezs` permet de récupérer la valeur d'une variab #### Variables d'environnement externes ```bash $ MA_VARIABLE=valeur externe -$ ezs script.ini < input +$ ezs script.ini < input ``` *script.ini :* @@ -117,7 +123,7 @@ param2 = env('PATH') ``` #### Paramètres à l'exécution ```bash -$ ezs -p param1=val1 -p param2=val2 script.ini < input +$ ezs -p param1=val1 -p param2=val2 script.ini < input ``` *script.ini :* @@ -145,7 +151,7 @@ param2 = env('options.deux') ### Paramètres de l'URL -Dans le cas d'un serveur `ezs` les paramètres de requetes HTTP reçues en entrée du script .ini sont disponibles à travers les variables d'environement. +Dans le cas d'un serveur `ezs` les paramètres de requetes HTTP reçues en entrée du script .ini sont disponibles à travers les variables d'environement. Par exemple, pour la requete : POST /v1/exemple/?param1=val1¶m2=val2 ```ini @@ -154,13 +160,13 @@ param1 = env('param1') param2 = env('param2') ``` -Il est également possible d'accèder aux entetes et aux paramètres de la requete HTTP . Exemple : +Il est également possible d'accèder aux entetes et aux paramètres de la requete HTTP . Exemple : ```ini [STATEMENT] param1 = env('headers.x-token') param2 = env('request.pathName') ``` - + ### Pour accéder à l'objet courant: self() @@ -171,10 +177,10 @@ Cette fonction permet de récupérer la valeur de l'objet qui sera envoyée en e param1 = self().omit('secret') ``` -Il peut être parfois utilise d'accèder à l'objet courant sous forme d'une variable. Le mot clé réservé `self.` permet d’accéder en lecture à l’objet courant. +Il peut être parfois utilise d'accèder à l'objet courant sous forme d'une variable. Le mot clé réservé `self.` permet d’accéder en lecture à l’objet courant. Idéalement cela permet de récupérer la valeur d’un champ pour l’utiliser comme paramètre d’une fonction. ```ini [STATEMENT] param1 = get('mapping').filter({'English name': self.enLabel}).first().get('alpha-2 code') -``` \ No newline at end of file +``` diff --git a/docs/coding-statement.md b/docs/coding-statement.md index a668655a..979fc978 100644 --- a/docs/coding-statement.md +++ b/docs/coding-statement.md @@ -1,6 +1,6 @@ # Fonctionnement d’une instruction -## Présentation +## Fonction La fonction est exécutée pour chaque élément du flux d'entrée, plus une dernière fois pour indiquer qu'il n'y a plus d’élément à traiter. À chaque fois, elle @@ -11,24 +11,24 @@ reçoit deux paramètres : `data` & `feed`. Chaque fonction possède un `scope` lui donnant accès à des fonctions dédiées. Le `scope` est partagé entre chaque appel pour chaque élément. -## data +### data Contient la valeur de l'élément courant du flux, pour un flux texte ou binaire, `data` contiendra un `chunk`. Pour un flux d’objets `data` contiendra un objet JavaScript. -## feed +### feed Est un objet permettant de contrôler le flux en sortie de la fonction. Il permet de générer zéro, un ou N élément(s) en sortie. L'objet `feed` propose les fonctions suivantes : -### feed.write(something) +#### feed.write(something) Permet d'envoyer un élément dans le flux de sortie. Cette fonction peut être exécutée plusieurs fois. -### feed.flow(stream, [callback]) +#### feed.flow(stream, [callback]) Permet d'envoyer le contenu d'un *stream* à l'élément suivant. @@ -39,20 +39,20 @@ appel à `feed.end()`. Cette fonction peut être exécutée plusieurs fois. -### feed.end() +#### feed.end() Permet de fermer le flux pour l’élément courant. -### feed.send(something) +#### feed.send(something) Permet d’enchaîner `feed.write` et `feed.end` en une seule fonction. -### feed.close() +#### feed.close() Permet de fermer définitivement le flux de sortie, plus aucun élément ne pourra être envoyé. -### feed.stop(withAnError) +#### feed.stop(withAnError) Permet de fermer le flux de sortie en précisant l'erreur ayant provoqué l’arrêt impromptu, plus aucun élément ne pourra être envoyé. diff --git a/docs/index.html b/docs/index.html index 12c1cc0e..2410c3b1 100644 --- a/docs/index.html +++ b/docs/index.html @@ -11,14 +11,13 @@
- + + + +