Merge pull request #10 from hendrikp/new-config-options-match-skip

New config options / features

Close #10

Author: flywire

README.md

@@ -145,11 +145,31 @@ Currently supported options are listed below:
     is inserted between the content of `caption_prefix` and the actual figure
     number.
 
+* `caption_match_re`
+
+    The regexp used to match captions from the markdown text. It can be used
+    to match captions from multiple languages at once.
+    The `group(number)` can match a optional `number`, see `numbering_preserve`.
+    The `group(title)` needs to match the `title`.
+
+* `caption_skip_empty`
+
+    Whether empty captions should be skipped. This can be used for example to
+    skip images that are used as icons (captions which have an empty `title`).
+
 * `numbering`:
 
     Adds a caption number like "Figure 1:" in front of the caption. It's
 	wrapped in a `<span />` for easier styling.
 
+* `numbering_preserve`
+
+    This preserves a number captured to the `group(number)` using the
+    `caption_match_re` option. If no number is present it falls back to
+    the number generated from `numbering` option behaviour. It is not
+    recommended to use `preserved` manual and automatic numbering at
+    the same time in the markdown text, because of the conflict potential.
+
 * `content_class`:
 
     The CSS class to add to the generated `<content />` element.
@@ -171,7 +191,10 @@ The default values for each type of content is synthesised in the following tabl
 | Config                 | Image   | Table   | Other     |
 |------------------------|---------|---------|-----------|
 | `caption_prefix`       | "Image" | "Table" | "Listing" |
+| `caption_match_re`     | - (not supported) | `^Table\s*?(?P<number>\d*)\:\s*(?P<title>.*)` | `^Listing\s*?(?P<number>\d*)\:\s*(?P<title>.*)` |
+| `caption_skip_empty`   | False   | False   | False     |
 | `numbering`            | False   | False   | False     |
+| `numbering_preserve`   | False   | False   | False     |
 | `content_class`        | -       | -       | listing   |
 | `caption_class`        | -       | -       | -         |
 | `caption_prefix_class` | -       | -       | -         |

caption/__init__.py

@@ -2,6 +2,7 @@
 #
 # Copyright (c) 2020-2023 flywire
 # Copyright (c) 2023 sanzoghenzo
+# Copyright (c) 2023 Hendrik Polczynski
 #
 # SPDX-License-Identifier: GPL-3.0-or-later
 

caption/caption.py

@@ -6,6 +6,7 @@
 https://github.com/flywire/caption
 Copyright (c) 2020-2023 flywire
 Copyright (c) 2023 sanzoghenzo
+Copyright (c) 2023 Hendrik Polczynski
 forked from yafg - https://git.sr.ht/~ferruck/yafg
 Copyright (c) 2019-2020 Philipp Trommler
 
@@ -15,6 +16,7 @@
 from markdown.treeprocessors import Treeprocessor
 from markdown.extensions import Extension
 from xml.etree import ElementTree
+import re
 
 
 class CaptionTreeprocessor(Treeprocessor):
@@ -28,22 +30,32 @@ def __init__(
         self,
         md=None,
         caption_prefix="",
+        caption_match_re="",
+        caption_skip_empty=False,
         numbering=True,
+        numbering_preserve=False,
         caption_prefix_class=None,
         caption_class=None,
         content_class=None,
         link_process=None,
         caption_top=True,
     ):
         self.caption_prefix = caption_prefix
+        self.caption_match_re = caption_match_re
+        self._match_re = re.compile(self.caption_match_re)
+        self.caption_skip_empty = caption_skip_empty
         self.numbering = numbering
+        self.numbering_preserve = numbering_preserve
         self.number = 0
         self.caption_prefix_class = caption_prefix_class
         self.caption_class = caption_class
         self.content_class = content_class
         self.link_process = link_process
         self.caption_top = caption_top
 
+        self._match_title = ""
+        self._match_number = None
+
     def build_content_element(self, par, caption, replace=True):
         """Format the content element containing the caption"""
         attrib = par.attrib
@@ -59,7 +71,7 @@ def build_content_element(self, par, caption, replace=True):
             else:
                 par.set("class", self.content_class)
         if "id" not in attrib:
-            par.set("id", "_{}-{}".format(self.name, self.number))
+            par.set("id", "_{}-{}".format(self.name, self.get_number()))
 
         if replace:
             par.text = "\n"
@@ -84,12 +96,12 @@ def build_caption_element(self, title):
         caption_prefix_span = ElementTree.SubElement(caption, "span")
         if title:
             caption_prefix_span.text = "{} {}:".format(
-                self.caption_prefix, self.number
+                self.caption_prefix, self.get_number()
             )
             caption_prefix_span.tail = " {}".format(title)
         else:
             caption_prefix_span.text = "{} {}".format(
-                self.caption_prefix, self.number
+                self.caption_prefix, self.get_number()
             )
             caption_prefix_span.tail = ""
         if self.caption_prefix_class:
@@ -99,22 +111,62 @@ def build_caption_element(self, title):
     def matches(self, par):
         """
         Whether the element tree part matches the object to be captioned.
-
-        This will be overriden by the subclasses.
+        This can be overriden by the subclasses.
+        """
+        self.reset_match()
+        if par.text:
+            match_caption = self._match_re.match(par.text)
+            if match_caption is not None:
+                return self.match_valid(match_caption.group("title"),
+                                        match_caption.group("number"))
+        return False
+
+    def reset_match(self):
+        """Resets the last found caption match data."""
+        self._match_title = ""
+        self._match_number = None
+
+    def match_valid(self, title="", number=None):
         """
-        raise NotImplementedError
+        Remember the determined number, title.
+        Determines if the current match should not be skipped.
+        """
+        valid = True
+        if title is None:
+            valid = False
+        else:
+            title = title.strip()
+            valid &= len(title) > 0
+        valid |= not self.caption_skip_empty
+        if valid:
+            self._match_title = title or ""
+            try:
+                self._match_number = int(number)
+            except TypeError:
+                pass
+            except ValueError:
+                pass
+        else:
+            self.reset_match()
+        return valid
 
-    def get_title(self, par):
-        """Title of the element. This will be overriden by the subclasses."""
-        raise NotImplementedError
+    def get_title(self):
+        """Title of the matched figure. This can be overriden by the subclasses."""
+        return self._match_title
+
+    def get_number(self):
+        """Number of the matched figure. This can be overriden by the subclasses."""
+        if self.numbering_preserve and self._match_number is not None:
+            return self._match_number
+        return self.number
 
     def run(self, root):
         """Find and format all captions."""
         for par in root.findall("./p"):
             if not self.matches(par):
                 continue
             self.number += 1
-            title = self.get_title(par)
+            title = self.get_title()
             caption = self.build_caption_element(title)
             self.build_content_element(par, caption)
             self.add_caption_to_content(par, caption)
@@ -124,11 +176,8 @@ class ListingCaptionTreeProcessor(CaptionTreeprocessor):
     name = "listing"
     content_tag = "div"
 
-    def matches(self, par):
-        return par.text and par.text.startswith("Listing: ")
-
-    def get_title(self, par):
-        return par.text[9:]
+    def __init__(self, *args, **kwargs):
+        super(ListingCaptionTreeProcessor, self).__init__(*args, **kwargs)
 
 
 class CaptionExtension(Extension):
@@ -141,7 +190,21 @@ def __init__(self, **kwargs):
                 "Listing",
                 "The text to show in front of the listing caption.",
             ],
+            "caption_match_re": [
+                r"^Listing\s*?(?P<number>\d*)\:\s*(?P<title>.*)",
+                "The regexp used to match captions."
+                "The group(number) can match a optional number."
+                "The group(title) needs to match the title.",
+            ],
+            "caption_skip_empty": [
+                False,
+                "Dont create captions for empty titles."
+            ],
             "numbering": [True, "Add the caption number to the prefix."],
+            "numbering_preserve": [
+                False,
+                "Preserve matched numbers from caption match."
+            ],
             "caption_prefix_class": [
                 "",
                 "CSS class to add to the caption prefix <span /> element.",

caption/image_caption.py

@@ -6,6 +6,7 @@
 https://github.com/flywire/caption
 Copyright (c) 2020-2023 flywire
 Copyright (c) 2023 sanzoghenzo
+Copyright (c) 2023 Hendrik Polczynski
 forked from yafg - https://git.sr.ht/~ferruck/yafg
 Copyright (c) 2019-2020 Philipp Trommler
 
@@ -20,40 +21,26 @@ class ImageCaptionTreeProcessor(CaptionTreeprocessor):
     name = "figure"
     content_tag = "figure"
 
-    def __init__(
-        self,
-        md=None,
-        caption_prefix="",
-        numbering=True,
-        caption_prefix_class=None,
-        caption_class=None,
-        content_class=None,
-        strip_title=True,
-        caption_top=False,
-    ):
-        super(ImageCaptionTreeProcessor, self).__init__(
-            md=md,
-            caption_prefix=caption_prefix,
-            numbering=numbering,
-            caption_prefix_class=caption_prefix_class,
-            caption_class=caption_class,
-            content_class=content_class,
-            caption_top=caption_top,
-        )
-        self.strip_title = strip_title
+    def __init__(self, *args, **kwargs):
+        self.strip_title = kwargs.pop("strip_title", True)
+        super(ImageCaptionTreeProcessor, self).__init__(*args, **kwargs)
 
-    def matches(self, par):
+    def reset_match(self):
+        super(ImageCaptionTreeProcessor, self).reset_match()
         self._a = None
+        self._img = None
+
+    def matches(self, par):
+        self.reset_match()
         self._img = par.find("./img")
         if self._img is None:
             self._a = par.find("./a")
-            if self._a is None:
-                return False
-            self._img = self._a.find("./img")
-        return self._img is not None
+            if self._a is not None:
+                self._img = self._a.find("./img")
 
-    def get_title(self, par):
-        return self._img.get("title")
+        if self._img is not None:
+            return self.match_valid(self._img.get("title"))
+        return False
 
     def build_content_element(self, par, caption, replace=True):
         super(ImageCaptionTreeProcessor, self).build_content_element(par, caption, replace=replace)
@@ -81,6 +68,10 @@ def __init__(self, **kwargs):
                 "Figure",
                 "The text to show in front of the image caption.",
             ],
+            "caption_skip_empty": [
+                False,
+                "Dont create captions for empty titles."
+            ],
             "numbering": [True, "Add the caption number to the prefix."],
             "caption_prefix_class": [
                 "",

caption/table_caption.py

@@ -2,6 +2,7 @@
 #
 # Copyright (c) 2020-2023 flywire
 # Copyright (c) 2023 sanzoghenzo
+# Copyright (c) 2023 Hendrik Polczynski
 # forked from yafg - https://git.sr.ht/~ferruck/yafg
 # Copyright (c) 2019 Philipp Trommler
 #
@@ -17,11 +18,8 @@ class TableCaptionTreeProcessor(CaptionTreeprocessor):
     content_tag = "table"
     caption_tag = "caption"
 
-    def matches(self, par):
-        return par.text and par.text.startswith("Table: ")
-
-    def get_title(self, par):
-        return par.text[7:]
+    def __init__(self, *args, **kwargs):
+        super(TableCaptionTreeProcessor, self).__init__(*args, **kwargs)
 
     def add_caption_to_content(self, content, caption):
         if not self.caption_top:
@@ -38,7 +36,7 @@ def run(self, root):
             if next_item.tag != self.content_tag:
                 continue
             self.number += 1
-            title = self.get_title(child)
+            title = self.get_title()
             root.remove(child)
             caption = self.build_caption_element(title)
 
@@ -66,7 +64,21 @@ def __init__(self, **kwargs):
                 "Table",
                 "The text to show in front of the table caption.",
             ],
+            "caption_match_re": [
+                r"^Table\s*?(?P<number>\d*)\:\s*(?P<title>.*)",
+                "The regexp used to match captions."
+                "The group(number) can match a optional number."
+                "The group(title) needs to match the title.",
+            ],
+            "caption_skip_empty": [
+                False,
+                "Dont create captions for empty titles."
+            ],
             "numbering": [True, "Add the caption number to the prefix."],
+            "numbering_preserve": [
+                False,
+                "Preserve matched numbers from caption match."
+            ],
             "caption_prefix_class": [
                 "",
                 "CSS class to add to the caption prefix <span /> element.",

setup.py

@@ -2,6 +2,7 @@
 #
 # Copyright (c) 2020-2023 flywire
 # Copyright (c) 2023 sanzoghenzo
+# Copyright (c) 2023 Hendrik Polczynski
 # forked from yafg - https://git.sr.ht/~ferruck/yafg
 # Copyright (c) 2019 Philipp Trommler
 #

test/__init__.py

@@ -2,5 +2,6 @@
 #
 # Copyright (c) 2020-2023 flywire
 # Copyright (c) 2023 sanzoghenzo
+# Copyright (c) 2023 Hendrik Polczynski
 #
 # SPDX-License-Identifier: GPL-3.0-or-later