diff --git a/docs/source/Explanation/CommandLineGuide.rst b/docs/source/Explanation/CommandLineGuide.rst index 0651bfa0f..ab04cd3af 100644 --- a/docs/source/Explanation/CommandLineGuide.rst +++ b/docs/source/Explanation/CommandLineGuide.rst @@ -949,7 +949,7 @@ So: - .*CAP.* means any sequence of characters with CAP somewhere in it. - - .*cap means any sequence of characters that ends with CAP. In the case + - .*cap$ means any sequence of characters that ends with CAP. In the case where multiple portions of the string could match, the longest one is selected. - .*?cap same as above, but *non-greedy*, meaning the shortest match is chosen. @@ -971,9 +971,10 @@ accept, reject and accept_unmatch - **baseUrl_relPath (default: False)** The **accept** and **reject** options process regular expressions (regexp). -The regexp is applied to the the notification message's URL for a match. +They are interpreted in order, and the first matching **accept** or **reject** +rule wins. -If the notification message's URL of a file matches a **reject** pattern, the notification message +If the filtered value for a notification message matches a **reject** pattern, the notification message is acknowledged as consumed to the broker and skipped. One that matches an **accept** pattern is processed by the component. @@ -999,8 +1000,32 @@ sequence #2:: reject .*\.gif -In sequence #1, all files ending in 'gif' are rejected. In sequence #2, the accept .* (which -accepts everything) is encountered before the reject statement, so the reject has no effect. +In sequence #1, all files whose filtered value matches ``.*\.gif`` are rejected. In sequence #2, the +``accept .*`` rule is encountered first and accepts everything, so the later reject statement has no effect. + +Python flows build a temporary filtering string from ``baseUrl + relPath``. When +a ``sundew_extension`` header is present, and the URL has fewer than three +colons, that temporary filtering string may have ``:`` +appended for legacy compatibility. The notification URL itself is not modified. +The C components do not append the separate ``sundew_extension`` header: +``cpost`` filters the pathname and ``cpump`` filters ``relPath``. + +Because Python flow matching starts at the beginning of the filtering string, +filters that look for text anywhere in that string usually begin with ``.*``. +There is no implicit ``.*`` at the end of the pattern. For example:: + + accept .*\.csv$ + # matches only a filtered value ending in .csv + + accept .*\.csv:.* + # matches a Python flow filtering string with a Sundew extension after .csv + + accept .*\.csv$|.*\.csv: + # matches either a plain .csv ending or a .csv followed by an extension boundary + +Prefer filtering on the path when possible. Treat ``sundew_extension`` as legacy +compatibility metadata and include it in filters only when the path alone is not +specific enough. It is best practice to use server side filtering to reduce the number of notification messages sent to the component to a small superset of what is relevant, and perform only a fine-tuning with the @@ -1136,10 +1161,10 @@ The option *path* defines where to get the files on the server. Combined with **accept** / **reject** options, the user can select the files of interest and their directories of residence. -The **accept** and **reject** options use regular expressions (regexp) to match URL. +The **accept** and **reject** options use regular expressions (regexp) to match the filtered value. These options are processed sequentially. -The URL of a file that matches a **reject** pattern is not published. -Files matching an **accept** pattern are published. +Files whose filtered value matches a **reject** pattern are not published. +Files whose filtered value matches an **accept** pattern are published. The path can have some patterns. These supported patterns concern date/time . They are fixed... @@ -1573,7 +1598,7 @@ at its sendTo. It is tagged to the **accept** options defined after it. If another sequence of **directory**/**accept** follows in the configuration file, the second directory is tagged to the following accepts and so on. -The **accept/reject** patterns apply to notification message notice url as above. +The **accept/reject** patterns apply to the notification message filtering string as above. Here is an example, here some ordered configuration options : :: @@ -1856,11 +1881,14 @@ sequence #2:: .. note:: - FIXME: does this match only files ending in 'gif' or should we add a $ to it? - will it match something like .gif2 ? is there an assumed .* at the end? + Patterns are regular expressions. Python flows use Python ``re`` patterns + and call ``Pattern.match()`` against the filtering string. The C components + use POSIX regular expressions with ``regexec()``. There is no implicit + ``.*`` at the end of a pattern, so use ``$`` when the match must reach the + end of the filtered value. -In sequence #1, all files ending in 'gif' are rejected. In sequence #2, the +In sequence #1, all files whose filtered value matches ``.*\.gif`` are rejected. In sequence #2, the accept .* (which accepts everything) is encountered before the reject statement, so the reject has no effect. Some options have global scope, rather than being interpreted in order. for thoses cases, a second declaration overrides the first. diff --git a/docs/source/Reference/sr3_options.7.rst b/docs/source/Reference/sr3_options.7.rst index 68b6397d9..ed9913bf8 100644 --- a/docs/source/Reference/sr3_options.7.rst +++ b/docs/source/Reference/sr3_options.7.rst @@ -93,11 +93,14 @@ sequence #2:: .. note:: - FIXME: does this match only files ending in 'gif' or should we add a $ to it? - will it match something like .gif2 ? is there an assumed .* at the end? + Patterns are regular expressions. Python flows use Python ``re`` patterns + and call ``Pattern.match()`` against the filtering string. The C components + use POSIX regular expressions with ``regexec()``. There is no implicit + ``.*`` at the end of a pattern, so use ``$`` when the match must reach the + end of the filtered value. -In sequence #1, all files ending in 'gif' are rejected. In sequence #2, the +In sequence #1, all files whose filtered value matches ``.*\.gif`` are rejected. In sequence #2, the accept .* (which accepts everything) is encountered before the reject statement, so the reject has no effect. Some options have global scope, rather than being interpreted in order. For thoses cases, the last declaration overrides the @@ -308,9 +311,10 @@ accept, reject and acceptUnmatched - **acceptUnmatched (default: True)** The **accept** and **reject** options process regular expressions (regexp). -The regexp is applied to the the notification message's URL for a match. +They are interpreted in order, and the first matching **accept** or **reject** +rule wins. -If the notification message's URL of a file matches a **reject** pattern, the notification message +If the filtered value for a notification message matches a **reject** pattern, the notification message is acknowledged as consumed to the broker and skipped. One that matches an **accept** pattern is processed by the component. @@ -336,18 +340,43 @@ sequence #2:: reject .*\.gif -In sequence #1, all files ending in 'gif' are rejected. In sequence #2, the accept .* (which -accepts everything) is encountered before the reject statement, so the reject has no effect. +In sequence #1, all files whose filtered value matches ``.*\.gif`` are rejected. +In sequence #2, the ``accept .*`` rule is encountered first and accepts +everything, so the later reject statement has no effect. + +Python flows build a temporary filtering string from ``baseUrl + relPath``. When +a ``sundew_extension`` header is present, and the URL has fewer than three +colons, that temporary filtering string may have ``:`` +appended for legacy compatibility. The notification URL itself is not modified. +The C components do not append the separate ``sundew_extension`` header: +``cpost`` filters the pathname and ``cpump`` filters ``relPath``. + +Because Python flow matching starts at the beginning of the filtering string, +filters that look for text anywhere in that string usually begin with ``.*``. +There is no implicit ``.*`` at the end of the pattern. For example:: + + accept .*\.csv$ + # matches only a filtered value ending in .csv + + accept .*\.csv:.* + # matches a Python flow filtering string with a Sundew extension after .csv + + accept .*\.csv$|.*\.csv: + # matches either a plain .csv ending or a .csv followed by an extension boundary + +Prefer filtering on the path when possible. Treat ``sundew_extension`` as legacy +compatibility metadata and include it in filters only when the path alone is not +specific enough. It is best practice to use server side filtering to reduce the number of notification messages sent to the component to a small superset of what is relevant, and perform only a fine-tuning with the client side mechanisms, saving bandwidth and processing for all. More details on how to apply the directives follow: -The **accept** and **reject** options use regular expressions (regexp) to match URL. +The **accept** and **reject** options use regular expressions (regexp) to match the filtered value. These options are processed sequentially. -The URL of a file that matches a **reject** pattern is not published. -Files matching an **accept** pattern are published. +Files whose filtered value matches a **reject** pattern are not published. +Files whose filtered value matches an **accept** pattern are published. Again a *rename* can be added to the *accept* option... matching products for that *accept* option would get renamed as described... unless the *accept* matches one file, the *rename* option should describe a directory into which the files @@ -735,10 +764,10 @@ Combined with **accept** / **reject** options, the user can select the files of interest and their directories of residence (see the **mirror** option for more directory settings). -The **accept** and **reject** options use regular expressions (regexp) to match URL. +The **accept** and **reject** options use regular expressions (regexp) to match the filtered value. These options are processed sequentially. -The URL of a file that matches a **reject** pattern is never downloaded. -One that matches an **accept** pattern is downloaded into the directory +Files whose filtered value matches a **reject** pattern are never downloaded. +One whose filtered value matches an **accept** pattern is downloaded into the directory declared by the closest **directory** option above the matching **accept** option. **acceptUnmatched** is used to decide what to do when no reject or accept clauses matched. diff --git a/docs/source/fr/Explication/GuideLigneDeCommande.rst b/docs/source/fr/Explication/GuideLigneDeCommande.rst index b48f9de2b..12a4b74dd 100644 --- a/docs/source/fr/Explication/GuideLigneDeCommande.rst +++ b/docs/source/fr/Explication/GuideLigneDeCommande.rst @@ -953,7 +953,7 @@ alors : En d'autres termes, faire correspondre n'importe quoi. - cap.* signifie toute séquence de caractères commençant par cap. - .*CAP.* signifie n'importe quelle séquence de caractères avec CAP quelque part dedans. - - .*CAP signifie toute séquence de caractères qui se termine par CAP. + - .*CAP$ signifie toute séquence de caractères qui se termine par CAP. - Dans le cas où plusieurs portions de la chaîne de caractères pourraient correspondre, la plus longue est sélectionnée. - .*?CAP comme ci-dessus, mais *non-greedy*, ce qui signifie que le match le plus court est choisi. - noter que l'implantaions de regexp en C n'inclu pas le *greediness*, alors certains expressions @@ -975,9 +975,10 @@ accept, reject and accept_unmatch - **baseUrl_relPath (par défaut: False)** Les options **accept** et **reject** traitent des expressions régulières (regexp). -La regexp est appliquée à l'URL du message pour détecter une correspondance. +Elles sont interprétées dans l'ordre, et la première règle **accept** ou +**reject** qui correspond est appliquée. -Si l'URL du message d'un fichier correspond à un motif **reject**, on informe +Si la valeur filtrée d'un message correspond à un motif **reject**, on informe le courtier que le message a été consommé et on abandonne son traitement. Celui qui correspond à un motif **accept** est traité par le composant. @@ -1006,9 +1007,36 @@ sequence #2:: reject .*\.gif -Dans la séquence #1, tous les fichiers se terminant par 'gif' sont rejetés. -Dans la séquence #2, l'option accept .* (regexp qui veut dire accepte tout) est -rencontré avant la déclaration de rejet, de sorte que le rejet n'a aucun effet. +Dans la séquence #1, tous les fichiers dont la valeur filtrée correspond à ``.*\.gif`` sont rejetés. +Dans la séquence #2, la règle ``accept .*`` est rencontrée en premier et accepte tout, +de sorte que le rejet n'a aucun effet. + +Les flux Python construisent une chaîne de filtrage temporaire à partir de +``baseUrl + relPath``. Lorsqu'un en-tête ``sundew_extension`` est présent, et +que l'URL contient moins de trois deux-points, cette chaîne de filtrage +temporaire peut recevoir ``:`` à la fin pour compatibilité +ancienne. L'URL du message d'annonce elle-même n'est pas modifiée. Les +composants C n'ajoutent pas l'en-tête séparé ``sundew_extension``: ``cpost`` +filtre le nom de chemin et ``cpump`` filtre ``relPath``. + +Comme la correspondance des flux Python commence au début de la chaîne de +filtrage, les filtres qui cherchent du texte n'importe où dans cette chaîne +commencent généralement par ``.*``. Il n'y a pas de ``.*`` implicite à la fin +du modèle. Par exemple:: + + accept .*\.csv$ + # correspond seulement à une valeur filtrée se terminant par .csv + + accept .*\.csv:.* + # correspond à une chaîne de filtrage Python avec une extension Sundew après .csv + + accept .*\.csv$|.*\.csv: + # correspond soit à une fin .csv simple, soit à .csv suivi d'une limite d'extension + +Préférez filtrer sur le chemin lorsque c'est possible. Traitez +``sundew_extension`` comme une métadonnée de compatibilité ancienne et +incluez-la dans les filtres seulement lorsque le chemin seul n'est pas assez +spécifique. Il est préférable d'utiliser le filtrage côté serveur pour réduire le nombre de avis envoyées au composant à un petit sur-ensemble de ce qui est @@ -1138,10 +1166,10 @@ Combiné avec les options **accept** / **reject**, l’utilisateur peut sélecti les fichiers d’intérêt et leurs répertoires de résidence. Les options **accept** et **reject** utilisent des expressions régulières (regexp) pour trouver -une correspondance avec l’URL. +une correspondance avec la valeur filtrée. Ces options sont traitées séquentiellement. -L’URL d’un fichier qui correspond à un modèle **reject** n’est pas publiée. -Les fichiers correspondant à un modèle **accept** sont publiés. +Les fichiers dont la valeur filtrée correspond à un modèle **reject** ne sont pas publiés. +Les fichiers dont la valeur filtrée correspond à un modèle **accept** sont publiés. Le répertoire peut avoir des modèles. Ces modèles pris en charge concernent la date/l’heure. Ils sont fixes... @@ -1557,7 +1585,7 @@ L’option **répertoire** définit un autre « chemin relatif » pour le produi Si une autre séquence de **directory**/**accept** suit dans le fichier de configuration, le deuxième répertoire est marqué pour les acceptations suivantes et ainsi de suite. -Les modèles **accept/reject** s’appliquent à l’URL de notification du message comme ci-dessus. +Les modèles **accept/reject** s’appliquent à la chaîne de filtrage du message comme ci-dessus. Voici un exemple, voici quelques options de configuration ordonnées : :: @@ -1846,11 +1874,15 @@ sequence #2:: .. Note: - FIXME : est-ce que cela ne correspond qu'aux fichiers se terminant par'gif' ou devrions-nous y ajouter un $ ? - correspondra-t-il à quelque chose comme.gif2 ? y a-t-il un .* supposé à la fin ? + Les modèles sont des expressions régulières. Les flux Python utilisent les + expressions régulières Python ``re`` et appellent ``Pattern.match()`` sur la + chaîne de filtrage. Les composants C utilisent les expressions régulières + POSIX avec ``regexec()``. Il n'y a pas de ``.*`` implicite à la fin d'un + modèle; utilisez donc ``$`` lorsque la correspondance doit atteindre la fin + de la valeur filtrée. -Dans la séquence #1, tous les fichiers se terminant par 'gif' sont rejetés. Dans la séquence #2, le +Dans la séquence #1, tous les fichiers dont la valeur filtrée correspond à ``.*\.gif`` sont rejetés. Dans la séquence #2, le accept .* (qui accepte tout) est lu avant la déclaration du rejet, donc le rejet n’a aucun effet. Certaines options ont une portée globale, plutôt que d’être interprété dans l’ordre. Dans ces cas, la dernière déclaration remplace celle qu'il y avait plus tôt dans le fichier.. diff --git a/docs/source/fr/Reference/sr3_options.7.rst b/docs/source/fr/Reference/sr3_options.7.rst index 6f517d317..0e605e1f0 100644 --- a/docs/source/fr/Reference/sr3_options.7.rst +++ b/docs/source/fr/Reference/sr3_options.7.rst @@ -95,10 +95,14 @@ séquence #2:: .. note:: - FIXME: cela ne correspond-il qu'aux fichiers se terminant par 'gif' ou devrions-nous y ajouter un $ ? - cela correspondra-t-il à quelque chose comme .gif2 ? y a-t-il un .* supposé à la fin ? - -Dans la séquence #1, tous les fichiers se terminant par 'gif' sont rejetés. Dans la séquence #2, le + Les modèles sont des expressions régulières. Les flux Python utilisent les + expressions régulières Python ``re`` et appellent ``Pattern.match()`` sur la + chaîne de filtrage. Les composants C utilisent les expressions régulières + POSIX avec ``regexec()``. Il n'y a pas de ``.*`` implicite à la fin d'un + modèle; utilisez donc ``$`` lorsque la correspondance doit atteindre la fin + de la valeur filtrée. + +Dans la séquence #1, tous les fichiers dont la valeur filtrée correspond à ``.*\.gif`` sont rejetés. Dans la séquence #2, le accept .* (qui accepte tout) est lu avant la déclaration du rejet, donc le rejet n’a aucun effet. Certaines options ont une portée globale, plutôt que d’être interprété dans l’ordre. Dans ces cas, la dernière déclaration remplace celle qu'il y avait plus tôt dans le fichier.. @@ -304,9 +308,10 @@ accept, reject et acceptUnmatched - **acceptUnmatched (défaut: True)** Les options **accept** et **reject** traitent les expressions régulières (regexp). -Le regexp est appliqué à l’URL du message d'annonce pour trouver une correspondance. +Elles sont interprétées dans l'ordre, et la première règle **accept** ou +**reject** qui correspond est appliquée. -Si l’URL d’un fichier correspond à un modèle **reject**, le message d'annonce +Si la valeur filtrée d'un message d'annonce correspond à un modèle **reject**, le message d'annonce est reconnu comme consommé par le courtier et est ignoré. Celui qui correspond à un modèle **accept** est traité par le composant. @@ -332,18 +337,45 @@ séquence #2:: reject .*\.gif -Dans la séquence #1, tous les fichiers se terminant par 'gif' sont rejetés. Dans la séquence #2, -le accept .* (qui accepte tout) est lu avant la déclaration de reject, de sorte que le reject n’a aucun effet. +Dans la séquence #1, tous les fichiers dont la valeur filtrée correspond à ``.*\.gif`` sont rejetés. Dans la séquence #2, +la règle ``accept .*`` est lue en premier et accepte tout, de sorte que le reject n’a aucun effet. + +Les flux Python construisent une chaîne de filtrage temporaire à partir de +``baseUrl + relPath``. Lorsqu'un en-tête ``sundew_extension`` est présent, et +que l'URL contient moins de trois deux-points, cette chaîne de filtrage +temporaire peut recevoir ``:`` à la fin pour compatibilité +ancienne. L'URL du message d'annonce elle-même n'est pas modifiée. Les +composants C n'ajoutent pas l'en-tête séparé ``sundew_extension``: ``cpost`` +filtre le nom de chemin et ``cpump`` filtre ``relPath``. + +Comme la correspondance des flux Python commence au début de la chaîne de +filtrage, les filtres qui cherchent du texte n'importe où dans cette chaîne +commencent généralement par ``.*``. Il n'y a pas de ``.*`` implicite à la fin +du modèle. Par exemple:: + + accept .*\.csv$ + # correspond seulement à une valeur filtrée se terminant par .csv + + accept .*\.csv:.* + # correspond à une chaîne de filtrage Python avec une extension Sundew après .csv + + accept .*\.csv$|.*\.csv: + # correspond soit à une fin .csv simple, soit à .csv suivi d'une limite d'extension + +Préférez filtrer sur le chemin lorsque c'est possible. Traitez +``sundew_extension`` comme une métadonnée de compatibilité ancienne et +incluez-la dans les filtres seulement lorsque le chemin seul n'est pas assez +spécifique. Il est recommandé d’utiliser le filtrage côté serveur pour réduire le nombre d’annonces envoyées au composant, et a la place, envoyer un sur ensemble de ce qui est pertinent, et de seulement régler les mécanismes côté client, économisant du bandwidth et du traitement pour tous. Plus de détails sur les directives: Les options **accept** et **reject** utilisent des expressions régulières (regexp) pour trouver -une correspondance avec l’URL. +une correspondance avec la valeur filtrée. Ces options sont traitées séquentiellement. -L’URL d’un fichier qui correspond à un modèle **reject** n’est pas publiée. -Les fichiers correspondant à un modèle **accept** sont publiés. +Les fichiers dont la valeur filtrée correspond à un modèle **reject** ne sont pas publiés. +Les fichiers dont la valeur filtrée correspond à un modèle **accept** sont publiés. Encore une fois, un *rename* peut être ajouté à l’option *accept*... les produits qui correspondent a l'option *accept* seront renommé comme décrit... à moins que le *accept* corresponde à un fichier, l’option *rename* doit décrire un répertoire dans lequel les fichiers @@ -730,10 +762,10 @@ Combiné avec les options **accept** / **reject**, l’utilisateur peut sélecti les fichiers d’intérêt et leurs répertoires de résidence (voir le **mirror** pour plus de paramètres de répertoire). -Les options **accept** et **reject** utilisent des expressions régulières (regexp) pour trouver une correspondance avec l’URL. +Les options **accept** et **reject** utilisent des expressions régulières (regexp) pour trouver une correspondance avec la valeur filtrée. Ces options sont traitées séquentiellement. -L’URL d’un fichier qui correspond à un modèle **reject** n’est jamais téléchargée. -Celui qui correspond à un modèle **accept** est téléchargé dans le répertoire +Les fichiers dont la valeur filtrée correspond à un modèle **reject** ne sont jamais téléchargés. +Celui dont la valeur filtrée correspond à un modèle **accept** est téléchargé dans le répertoire déclaré par l’option **directory** la plus proche au-dessus de l’option **accept** correspondante. **acceptUnmatched** est utilisé pour décider quoi faire lorsque aucune clause de rejet ou d’acceptation corresponde.