Files
claude-config/bin/markdown_section/main.py
T

74 lines
2.9 KiB
Python

"""Print one section of a markdown file, picked by a fragment of its heading.
usage: markdown-section <file> <fragment>
The section runs from the first heading whose text holds the fragment, whatever its case, to the
line before the next heading of the same or a higher level, so it holds its sub-sections. The
heading's text is what follows its `#`s. A line inside a fenced code block is never a heading.
Print a record kept outside the checkout through the file `project-record open <record>` prints.
Where no heading holds the fragment, it fails saying so. Where another heading outside that section
holds it too, it fails listing each such heading with its line number, and prints no section: pass
more of the heading you want.
Exit 2 on bad arguments, and 1, saying why, on any other failure.
"""
import pathlib
import re
import sys
from failure import Failure
HEADING = re.compile(r"^ {0,3}(#{1,6})[ \t]+(.*?)[ \t]*$")
FENCE = re.compile(r"^ {0,3}(```|~~~)")
def main(argv: list[str]) -> int:
if argv[:1] in (["-h"], ["--help"]):
print(__doc__.strip())
return 0
if len(argv) != 2:
print("usage: markdown-section <file> <fragment>", file=sys.stderr)
return 2
try:
text = pathlib.Path(argv[0]).read_text()
except (OSError, UnicodeDecodeError) as error:
print(f"markdown-section: {error}", file=sys.stderr)
return 1
found = section(text, argv[1])
if isinstance(found, Failure):
print(f"markdown-section: {found.reason}", file=sys.stderr)
return 1
print(found, end="")
return 0
def headings(lines: list[str]) -> list[tuple[int, int, str]]:
"""Each heading outside a fenced code block, as its index in lines, its level and its text."""
found = []
fence = ""
for index, line in enumerate(lines):
opened = FENCE.match(line)
if opened and fence in ("", opened.group(1)):
fence = "" if fence else opened.group(1)
elif not fence and (heading := HEADING.match(line)):
found.append((index, len(heading.group(1)), heading.group(2)))
return found
def section(text: str, fragment: str) -> str | Failure:
"""The section of text under the first heading that holds fragment, or a Failure where none does or several do."""
lines = text.splitlines(keepends=True)
found = headings(lines)
matching = [at for at, (_, _, title) in enumerate(found) if fragment.lower() in title.lower()]
if not matching:
return Failure(f"no heading holds '{fragment}'")
start, level, _ = found[matching[0]]
end = next((index for index, deeper, _ in found[matching[0] + 1:] if deeper <= level), len(lines))
# A matching heading inside the first one's section is part of what is printed, not a rival.
rivals = [at for at in matching if found[at][0] >= end]
if rivals:
listed = "\n".join(f"{found[at][0] + 1}: {lines[found[at][0]].rstrip()}" for at in [matching[0], *rivals])
return Failure(f"{len(rivals) + 1} headings hold '{fragment}', so use more of one:\n{listed}")
return "".join(lines[start:end]).rstrip("\n") + "\n"