Add --ellipses support.

Author: jlevy

README.md

@@ -151,6 +151,14 @@ quote marks around regular text.
 
 This feature is enabled with the `--smartquotes` flag or the `--auto` convenience flag.
 
+## Ellipsis Support
+
+There is a similar feature for converting `...` to an ellipsis character `…` when it
+appears to be appropriate (i.e., not in code blocks and when adjacent to words or
+punctuation).
+
+This feature is enabled with the `--ellipses` flag or the `--auto` convenience flag.
+
 ## Frontmatter Support
 
 Because **YAML frontmatter** is common on Markdown files, any YAML frontmatter (content

src/flowmark/cli.py

@@ -55,6 +55,7 @@ class Options:
     semantic: bool
     cleanups: bool
     smartquotes: bool
+    ellipses: bool
     inplace: bool
     nobackup: bool
     version: bool
@@ -119,6 +120,13 @@ def _parse_args(args: list[str] | None = None) -> Options:
         help="Convert straight quotes to typographic (curly) quotes and apostrophes "
         "(only applies to Markdown mode)",
     )
+    parser.add_argument(
+        "--ellipses",
+        action="store_true",
+        default=False,
+        help="Convert three dots (...) to ellipsis character (…) with normalized spacing "
+        "(only applies to Markdown mode)",
+    )
     parser.add_argument(
         "-i", "--inplace", action="store_true", help="Edit the file in place (ignores --output)"
     )
@@ -130,7 +138,7 @@ def _parse_args(args: list[str] | None = None) -> Options:
     parser.add_argument(
         "--auto",
         action="store_true",
-        help="Same as `--inplace --nobackup --semantic --cleanups --smartquotes`, as a convenience for "
+        help="Same as `--inplace --nobackup --semantic --cleanups --smartquotes --ellipses`, as a convenience for "
         "fully auto-formatting files",
     )
     parser.add_argument(
@@ -146,6 +154,7 @@ def _parse_args(args: list[str] | None = None) -> Options:
         opts.semantic = True
         opts.cleanups = True
         opts.smartquotes = True
+        opts.ellipses = True
 
     return Options(
         file=opts.file,
@@ -155,6 +164,7 @@ def _parse_args(args: list[str] | None = None) -> Options:
         semantic=opts.semantic,
         cleanups=opts.cleanups,
         smartquotes=opts.smartquotes,
+        ellipses=opts.ellipses,
         inplace=opts.inplace,
         nobackup=opts.nobackup,
         version=opts.version,
@@ -193,6 +203,7 @@ def main(args: list[str] | None = None) -> int:
             semantic=options.semantic,
             cleanups=options.cleanups,
             smartquotes=options.smartquotes,
+            ellipses=options.ellipses,
             make_parents=True,
         )
     except ValueError as e:

src/flowmark/ellipses.py

@@ -0,0 +1,58 @@
+import re
+from re import Pattern
+
+ELLIPSIS_PATTERN: Pattern[str] = re.compile(
+    r"(^|[\w\"\'“‘])(\s*)(\.\.\.)([.,:;?!)\-—\"\'”’]?)(\s*)",
+    re.MULTILINE,
+)
+
+
+def ellipses(text: str) -> str:
+    r"""
+    Replace three consecutive dots with a proper ellipsis character (…).
+
+    Rules:
+    - `...` must be preceded by start of line OR a word character (with optional space)
+    - `...` must be followed by word character (with optional space) OR punctuation OR end of line
+    - If immediately before the `...` is a word character (no whitespace), a space is inserted before it.
+    - If immediately after the `...` is a word character (no whitespace), a space is inserted after it.
+    - If the punctuation [\"\'“‘] immediately precedes the ellipsis, there is no space between the
+      punctuation and the ellipsis.
+    - If punctuation [.,:;?!)\-—] follows the ellipsis, there is no space between the ellipsis and
+      the punctuation.
+    """
+
+    def replace_match(match: re.Match[str]) -> str:
+        prefix = match.group(1)
+        spaces_before = match.group(2)
+        punct = match.group(4)
+        spaces_after = match.group(5)
+
+        # Get what follows the match
+        end_pos = match.end()
+        remaining = text[end_pos:] if end_pos < len(text) else ""
+        next_char = remaining[0] if remaining else ""
+
+        # Check boundary - must be followed by word or end of line
+        if remaining and not re.match(r"\w|$", next_char):
+            return match.group(0)
+
+        result = prefix
+
+        # Add space before ellipsis if word char with no existing space
+        if prefix and re.match(r"\w", prefix) and not spaces_before:
+            result += " "
+        else:
+            result += spaces_before
+
+        result += "…" + punct
+
+        # Add space after ellipsis if word char follows with no space and no punct
+        if next_char and re.match(r"\w", next_char) and not spaces_after and not punct:
+            result += " "
+        else:
+            result += spaces_after
+
+        return result
+
+    return ELLIPSIS_PATTERN.sub(replace_match, text)

src/flowmark/markdown_filling.py

@@ -18,6 +18,7 @@
 from flowmark.custom_marko import custom_marko
 from flowmark.doc_cleanups import doc_cleanups
 from flowmark.doc_transforms import rewrite_text_content
+from flowmark.ellipses import ellipses as apply_ellipses
 from flowmark.frontmatter import split_frontmatter
 from flowmark.line_wrappers import LineWrapper, line_wrap_by_sentence, line_wrap_to_width
 from flowmark.sentence_split_regex import split_sentences_regex
@@ -82,6 +83,7 @@ def fill_markdown(
     semantic: bool = False,
     cleanups: bool = False,
     smartquotes: bool = False,
+    ellipses: bool = False,
     line_wrapper: LineWrapper | None = None,
 ) -> str:
     """
@@ -130,6 +132,8 @@ def fill_markdown(
         doc_cleanups(document)
     if smartquotes:
         rewrite_text_content(document, smart_quotes, coalesce_lines=True)
+    if ellipses:
+        rewrite_text_content(document, apply_ellipses, coalesce_lines=True)
     result = marko.render(document)
 
     # Reattach frontmatter if it was present

src/flowmark/reformat_api.py

@@ -15,6 +15,7 @@ def reformat_text(
     semantic: bool = True,
     cleanups: bool = True,
     smartquotes: bool = False,
+    ellipses: bool = False,
 ) -> str:
     """
     Reformat text or markdown and wrap lines. Simply a convenient wrapper
@@ -31,7 +32,12 @@ def reformat_text(
     else:
         # Markdown mode
         result = fill_markdown(
-            text, width=width, semantic=semantic, cleanups=cleanups, smartquotes=smartquotes
+            text,
+            width=width,
+            semantic=semantic,
+            cleanups=cleanups,
+            smartquotes=smartquotes,
+            ellipses=ellipses,
         )
 
     return result
@@ -47,6 +53,7 @@ def reformat_file(
     semantic: bool = False,
     cleanups: bool = True,
     smartquotes: bool = False,
+    ellipses: bool = False,
     make_parents: bool = True,
 ) -> None:
     """
@@ -66,6 +73,8 @@ def reformat_file(
             headers (only applies to Markdown mode).
         smartquotes: Convert straight quotes to typographic (curly) quotes and apostrophes
             (only applies to Markdown mode).
+        ellipses: Convert three dots (...) to ellipsis character (…) with normalized spacing
+            (only applies to Markdown mode).
         make_parents: Whether to make parent directories if they don't exist.
     """
     read_stdin = path == "-"
@@ -79,7 +88,7 @@ def reformat_file(
     else:
         text = Path(path).read_text()
 
-    result = reformat_text(text, width, plaintext, semantic, cleanups, smartquotes)
+    result = reformat_text(text, width, plaintext, semantic, cleanups, smartquotes, ellipses)
 
     if inplace:
         backup_suffix = ".orig" if not nobackup else ""

tests/test_ellipses.py

@@ -0,0 +1,97 @@
+from flowmark.ellipses import ellipses
+
+
+def test_ellipses():
+    # Basic conversions, adding space only if needed next to a word character
+    assert ellipses("word...") == "word …"
+    assert ellipses("word ...") == "word …"
+    assert ellipses("word  ...") == "word  …"
+    assert ellipses("word ... ") == "word … "
+    assert ellipses("word  ...  ") == "word  …  "
+
+    assert ellipses("word...word") == "word … word"
+    assert ellipses("word ... word") == "word … word"
+    assert ellipses("word  ...  word") == "word  …  word"
+    assert ellipses("Hello...World") == "Hello … World"
+
+    assert ellipses("...word") == "… word"
+    assert ellipses("... word") == "… word"
+    assert ellipses(" ... word") == " … word"
+    assert ellipses("word...") == "word …"
+    assert ellipses("...") == "…"
+
+    assert ellipses("I think... well... maybe...") == "I think … well … maybe …"
+    assert ellipses("First...second...third") == "First … second … third"
+    assert ellipses("Wait... what... really?") == "Wait … what … really?"
+    assert (
+        ellipses("I was thinking... maybe we should go.") == "I was thinking … maybe we should go."
+    )
+    assert (
+        ellipses("The options are... well... complicated.")
+        == "The options are … well … complicated."
+    )
+
+    # Punctuation cases.
+    assert ellipses("word....") == "word …."
+    assert ellipses("word.... ") == "word …. "
+    assert ellipses("word....  text") == "word ….  text"
+    assert ellipses("word....word") == "word ….word"
+    assert ellipses("He said...") == "He said …"
+    assert ellipses("Really...?") == "Really …?"
+    assert ellipses("Wait...!") == "Wait …!"
+    assert ellipses("Well...,") == "Well …,"
+    assert ellipses("word .... Another") == "word …. Another"
+
+    assert ellipses("word.....") == "word....."
+    assert ellipses("word......") == "word......"
+
+    # Does not apply.
+    assert ellipses("..") == ".."  # Only two dots
+    assert ellipses(".") == "."  # Single dot
+    assert ellipses(". . .") == ". . ."  # Spaced dots
+    assert ellipses("$...") == "$..."  # Not preceded by word char or start
+    assert ellipses("@...") == "@..."  # Not preceded by word char or start
+    assert ellipses("#...") == "#..."  # Not preceded by word char or start
+    assert ellipses("...@") == "...@"  # Not followed by word char or end
+    assert ellipses("...$") == "...$"  # Not followed by word char or end ($ in pattern)
+    assert ellipses("...#") == "...#"  # Not followed by word char or end
+
+    # Multiline cases.
+    assert (
+        ellipses("First line...\nSecond line... continues\n...starts here")
+        == "First line …\nSecond line … continues\n… starts here"
+    )
+    assert ellipses("Hello....\n") == "Hello ….\n"
+
+    # Edge cases.
+    assert ellipses("") == ""
+    assert ellipses("No ellipses here") == "No ellipses here"
+    assert ellipses("   ") == "   "
+    assert ellipses("....") == "…."
+    assert ellipses(" ....") == " …."
+
+    # Code-like cases
+    assert ellipses("if (x...) {") == "if (x...) {"
+    assert ellipses("[...]") == "[...]"
+    assert ellipses("{...}") == "{...}"
+    assert ellipses("path/to/...") == "path/to/..."
+
+    # Four dots followed by word gets space
+    assert ellipses("word....word") == "word ….word"
+    assert ellipses("word....123") == "word ….123"
+
+    # Quote cases
+    assert ellipses("'...word") == "'… word"
+    assert ellipses("'... word") == "'… word"
+    assert ellipses('"...word') == '"… word'
+    assert ellipses('"... word') == '"… word'
+    assert ellipses("'...word'") == "'… word'"
+    assert ellipses('"...word"') == '"… word"'
+    assert ellipses("'...'") == "'…'"
+    assert ellipses('"..."') == '"…"'
+    assert ellipses("word...'") == "word …'"
+    assert ellipses('word..."') == 'word …"'
+    assert ellipses("word...'next") == "word …'next"
+    assert ellipses('word..."next') == 'word …"next'
+    assert ellipses("He said '...'") == "He said '…'"
+    assert ellipses('She said "..."') == 'She said "…"'

tests/test_ref_docs.py

@@ -26,6 +26,7 @@ class TestCase:
         semantic: bool
         cleanups: bool
         smartquotes: bool
+        ellipses: bool = False
 
     test_cases: list[TestCase] = [
         TestCase(
@@ -55,6 +56,7 @@ class TestCase:
             semantic=True,
             cleanups=True,
             smartquotes=True,
+            ellipses=True,
         ),
     ]
 
@@ -69,6 +71,7 @@ class TestCase:
             semantic=case.semantic,
             cleanups=case.cleanups,
             smartquotes=case.smartquotes,
+            ellipses=case.ellipses,
         )
         if actual != expected:
             actual_path = testdoc_dir / f"testdoc.actual.{case.name}.md"

tests/testdocs/testdoc.expected.auto.md

@@ -61,7 +61,7 @@ high-stakes decisions for those who give and *receive it*. Blah blah blah and bl
 
 ## Some apostrophes and quotes--and dashes, too
 
-“Hello,” he said! “What’s... your specialty?”
+“Hello,” he said! “What’s … your specialty?”
 he enquired (in an idle tone).
 
 He read the multiline quote: “This is line one and this is line two and finally line
@@ -614,7 +614,7 @@ Linux offers a rich set of POSIX\-compliant and Linux\-specific mechanisms.
        tempfile.NamedTemporaryFile(mode='w', dir=dest\_dir, delete=False) (use
        appropriate mode, e.g., wb for binary).
 
-     + Use a try...finally block to ensure cleanup:\
+     + Use a try … finally block to ensure cleanup:\
        Python\
        temp\_file = None\
        try:\
@@ -881,7 +881,7 @@ or em*phases* or **bold**face or *em*phases or bold**face** or em*phases* or
 **bold**face or *em*phases or bold**face** or em*phases* or **bold**face or *em*phases
 or bold**face** or em*phases* or **bold**face or *em*phases or bold**face** or
 em*phases* or **bold**face or *em*phases or bold**face** or em*phases* can flow on and
-on...
+on …
 
 *blah blah* *blah blah* *blah blah* *blah blah* *blah blah* *blah blah* *blah blah*
 *blah blah* *blah blah* *blah blah* *blah blah* *blah blah* *blah blah* *blah blah*
@@ -1062,7 +1062,7 @@ And let’s try some links with angle brackets.
     the value proposition of a company and ensuring the alignment of interests between
     the two parties.
 
-[^multiparagraph]: This is an even longer footnote...
+[^multiparagraph]: This is an even longer footnote …
 
     Paragraph 1.