74 lines
2.9 KiB
Python
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"
|