Implement #1289

docs/source/Explanation/SarraPluginDev.rst

@@ -894,6 +894,20 @@ reaches the number given by the  **batch**  option (default 100).
 All download (upload) operations use a buffer. The size, in bytes,
 of the buffer used is given by the **bufsize** option (default 8192).
 
+Accessing accept/reject "masks"
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+When a message is accepted or rejected, the "mask" that was used to accept/reject it will be stored in the value of the message's ``_mask`` key. The ``_mask`` is a tuple that contains the regex from the accept/reject statement, the corresponding ``directory`` path, the value of the ``mirror`` and ``filename`` options. The last item in the tuple is a list containing any additional text, split by whitespace, that was included at the end of the accept/reject line in the config file. This additional text can be used to pass additional information to plugins.
+
+For example, with an accept statement in a config file like this::
+
+    accept .*abc.*  your_text=here from_accept_abc
+
+The last item in ``msg['_mask']`` would be:
+
+.. code-block:: python
+
+    msg['_mask'][-1] # == [ 'your_text=here', 'from_accept_abc' ]
 
 Why v3 API should be used whenever possible
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

docs/source/fr/Explication/SarraPluginDev.rst

@@ -773,6 +773,21 @@ atteint le nombre donné par l’option **batch** (100 par défaut).
 Toutes les opérations de téléchargement (upload) utilisent un buffer. La taille, en octets,
 du buffer utilisé est donné par l’option **bufsize** (8192 par défaut).
 
+Accéder aux « masques » d'accept/reject
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Lorsqu'un message est accepté ou rejeté, le « masque » qui a été utilisé pour l'accept/reject sera stocké dans la valeur de la clé ``_mask`` du message. Le ``_mask`` est un tuple qui contient l'expression régulière de l'instruction d'accept/reject, le chemin du ``directory`` correspondant, la valeur des options ``mirror`` et ``filename`` . Le dernier élément de le tuple est une liste contenant tout texte supplémentaire, divisé par espaces, inclus à la fin de la ligne d'accept/reject dans le fichier de configuration. Ce texte supplémentaire peut être utilisé pour transmettre des informations supplémentaires aux plugins.
+
+Par exemple, avec une instruction accept dans un fichier de configuration comme ceci :
+
+    accept .*abc.* votre_texte=ici from_accept_abc
+
+Le dernier élément de ``msg['_mask']`` serait :
+
+.. code-block:: python
+
+    msg['_mask'][-1] # == [ 'votre_text=ici', 'from_accept_abc' ]
+
 Pourquoi l’API v3 doit être utilisée dans la mesure du possible
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 

sarracenia/config/__init__.py

@@ -1077,9 +1077,18 @@ def _build_mask(self, option, arguments):
             return None
 
         if len(arguments) > 1:
-            fn = arguments[1]
+            # First arg is a Sundew filename option
+            if arguments[1].split(':')[0].split('=')[0] in ['None', 'DESTFN', 'DESTFNSCRIPT', 'HEADFN',
+                                                            'NONE', 'NONESENDER', 'SATNET', 'SENDER', 'WHATFN']:
+                fn = arguments[1]
+                # Other arguments can be used by plugins
+                args = arguments[2:]
+            else:
+                fn = self.filename
+                args = arguments[1:]
         else:
             fn = self.filename
+            args = []
         if fn and re.compile('DESTFNSCRIPT=.*').match(fn):
             script=fn[13:]
             self.destfn_scripts.append(script)
@@ -1090,21 +1099,22 @@ def _build_mask(self, option, arguments):
            d = self.directory
         return (arguments[0], d, fn, regex,
                 option.lower() in ['accept' ], self.mirror, self.strip,
-                self.pstrip, self.flatten)
+                self.pstrip, self.flatten, args)
 
     def mask_ppstr(self, mask):
         """
            return a pretty print string version of the given mask, easier for humans to read.
         """
-        pattern, maskDir, maskFileOption, mask_regexp, accepting, mirror, strip, pstrip, flatten = mask
+        pattern, maskDir, maskFileOption, mask_regexp, accepting, mirror, strip, pstrip, flatten, args = mask
 
         s = 'accept' if accepting else 'reject'
         if pstrip : strip=pstrip
         strip = '' if strip == 0 else f' strip:{strip}'
         fn = '' if (maskFileOption == 'WHATFN') else f' filename:{maskFileOption}'
         flatten = '' if flatten == '/' else f' flatten:{flatten}'
         w = 'with ' if fn or flatten or strip else ''
-        return f'{s} {pattern} into {maskDir} {w}mirror:{mirror}{strip}{flatten}{fn}'
+        args = '' if len(args) == 0 else ' args:' + str(args)
+        return f'{s} {pattern} into {maskDir} {w}mirror:{mirror}{strip}{flatten}{fn}{args}'
 
     def _parse_set_string( self, v:str, old_value: set ) -> set:
         """

sarracenia/flow/__init__.py

@@ -1013,14 +1013,17 @@ def filter(self) -> None:
                     urlToMatch = url
                 oldname_matched = False
                 for mask in self.o.masks:
-                    pattern, maskDir, maskFileOption, mask_regexp, accepting, mirror, strip, pstrip, flatten = mask
+                    pattern, maskDir, maskFileOption, mask_regexp, accepting, mirror, strip, pstrip, flatten, args = mask
                     if (pattern == '.*'):
                         oldname_matched = accepting
+                        m['_mask'] = mask
+                        m['_deleteOnPost'].add('_mask')
                         break
                     matches = mask_regexp.match(urlToMatch)
                     if matches:
                             m[ '_matches'] = matches
-                            m['_deleteOnPost'] |= set(['_matches'])
+                            m['_mask'] = mask
+                            m['_deleteOnPost'] |= set(['_matches', '_mask'])
                             oldname_matched = accepting
                     break
 
@@ -1042,7 +1045,7 @@ def filter(self) -> None:
             # apply masks for accept/reject options.
             matched = False
             for mask in self.o.masks:
-                pattern, maskDir, maskFileOption, mask_regexp, accepting, mirror, strip, pstrip, flatten = mask
+                pattern, maskDir, maskFileOption, mask_regexp, accepting, mirror, strip, pstrip, flatten, args = mask
                 if (pattern != '.*') :
                     matches = mask_regexp.match(urlToMatch)
                     if matches:
@@ -1065,6 +1068,9 @@ def filter(self) -> None:
                                 (str(mask), strip, urlToMatch))
                         break
 
+                    m['_mask'] = mask
+                    m['_deleteOnPost'].add('_mask')
+
                     self.updateFieldsAccepted(m, url, pattern, maskDir,
                                            maskFileOption, mirror, strip,
                                            pstrip, flatten)