| 1 |
"""A collection of string formatting helpers.""" |
| 2 |
|
| 3 |
import functools |
| 4 |
import textwrap |
| 5 |
from typing import Final |
| 6 |
|
| 7 |
from libclinic import ClinicError |
| 8 |
|
| 9 |
|
| 10 |
SIG_END_MARKER: Final = "--" |
| 11 |
|
| 12 |
|
| 13 |
def docstring_for_c_string(docstring: str) -> str: |
| 14 |
lines = [] |
| 15 |
# Turn docstring into a properly quoted C string. |
| 16 |
for line in docstring.split("\n"): |
| 17 |
lines.append('"') |
| 18 |
lines.append(_quoted_for_c_string(line)) |
| 19 |
lines.append('\\n"\n') |
| 20 |
|
| 21 |
if lines[-2] == SIG_END_MARKER: |
| 22 |
# If we only have a signature, add the blank line that the |
| 23 |
# __text_signature__ getter expects to be there. |
| 24 |
lines.append('"\\n"') |
| 25 |
else: |
| 26 |
lines.pop() |
| 27 |
lines.append('"') |
| 28 |
return "".join(lines) |
| 29 |
|
| 30 |
|
| 31 |
def _quoted_for_c_string(text: str) -> str: |
| 32 |
"""Helper for docstring_for_c_string().""" |
| 33 |
for old, new in ( |
| 34 |
("\\", "\\\\"), # must be first! |
| 35 |
('"', '\\"'), |
| 36 |
("'", "\\'"), |
| 37 |
): |
| 38 |
text = text.replace(old, new) |
| 39 |
return text |
| 40 |
|
| 41 |
|
| 42 |
# Use octals, because \x... in C has arbitrary number of hexadecimal digits. |
| 43 |
_c_repr = [chr(i) if 32 <= i < 127 else fr'\{i:03o}' for i in range(256)] |
| 44 |
_c_repr[ord('"')] = r'\"' |
| 45 |
_c_repr[ord('\\')] = r'\\' |
| 46 |
_c_repr[ord('\a')] = r'\a' |
| 47 |
_c_repr[ord('\b')] = r'\b' |
| 48 |
_c_repr[ord('\f')] = r'\f' |
| 49 |
_c_repr[ord('\n')] = r'\n' |
| 50 |
_c_repr[ord('\r')] = r'\r' |
| 51 |
_c_repr[ord('\t')] = r'\t' |
| 52 |
_c_repr[ord('\v')] = r'\v' |
| 53 |
|
| 54 |
def _break_trigraphs(s: str) -> str: |
| 55 |
# Prevent trigraphs from being interpreted inside string literals. |
| 56 |
if '??' in s: |
| 57 |
s = s.replace('??', r'?\?') |
| 58 |
s = s.replace(r'\??', r'\?\?') |
| 59 |
# Also Argument Clinic does not like comment-like sequences |
| 60 |
# in string literals. |
| 61 |
s = s.replace(r'/*', r'/\*') |
| 62 |
s = s.replace(r'*/', r'*\/') |
| 63 |
return s |
| 64 |
|
| 65 |
def c_bytes_repr(data: bytes) -> str: |
| 66 |
r = ''.join(_c_repr[i] for i in data) |
| 67 |
r = _break_trigraphs(r) |
| 68 |
return '"' + r + '"' |
| 69 |
|
| 70 |
def c_str_repr(text: str) -> str: |
| 71 |
r = ''.join(_c_repr[i] if i < 0x80 |
| 72 |
else fr'\u{i:04x}' if i < 0x10000 |
| 73 |
else fr'\U{i:08x}' |
| 74 |
for i in map(ord, text)) |
| 75 |
r = _break_trigraphs(r) |
| 76 |
return '"' + r + '"' |
| 77 |
|
| 78 |
def c_unichar_repr(char: str) -> str: |
| 79 |
if char == "'": |
| 80 |
return r"'\''" |
| 81 |
if char == '"': |
| 82 |
return """'"'""" |
| 83 |
if char == '\0': |
| 84 |
return '0' |
| 85 |
i = ord(char) |
| 86 |
if i < 0x80: |
| 87 |
r = _c_repr[i] |
| 88 |
if not r.startswith((r'\0', r'\1')): |
| 89 |
return "'" + r + "'" |
| 90 |
return f'0x{i:02x}' |
| 91 |
|
| 92 |
|
| 93 |
def wrapped_c_string_literal( |
| 94 |
text: str, |
| 95 |
*, |
| 96 |
width: int = 72, |
| 97 |
suffix: str = "", |
| 98 |
initial_indent: int = 0, |
| 99 |
subsequent_indent: int = 4 |
| 100 |
) -> str: |
| 101 |
wrapped = textwrap.wrap( |
| 102 |
text, |
| 103 |
width=width, |
| 104 |
replace_whitespace=False, |
| 105 |
drop_whitespace=False, |
| 106 |
break_on_hyphens=False, |
| 107 |
) |
| 108 |
separator = '"' + suffix + "\n" + subsequent_indent * " " + '"' |
| 109 |
return initial_indent * " " + '"' + separator.join(wrapped) + '"' |
| 110 |
|
| 111 |
|
| 112 |
def _add_prefix_and_suffix(text: str, *, prefix: str = "", suffix: str = "") -> str: |
| 113 |
"""Return 'text' with 'prefix' prepended and 'suffix' appended to all lines. |
| 114 |
|
| 115 |
If the last line is empty, it remains unchanged. |
| 116 |
If text is blank, return text unchanged. |
| 117 |
|
| 118 |
(textwrap.indent only adds to non-blank lines.) |
| 119 |
""" |
| 120 |
*split, last = text.split("\n") |
| 121 |
lines = [prefix + line + suffix + "\n" for line in split] |
| 122 |
if last: |
| 123 |
lines.append(prefix + last + suffix) |
| 124 |
return "".join(lines) |
| 125 |
|
| 126 |
|
| 127 |
def indent_all_lines(text: str, prefix: str) -> str: |
| 128 |
return _add_prefix_and_suffix(text, prefix=prefix) |
| 129 |
|
| 130 |
|
| 131 |
def suffix_all_lines(text: str, suffix: str) -> str: |
| 132 |
return _add_prefix_and_suffix(text, suffix=suffix) |
| 133 |
|
| 134 |
|
| 135 |
def pprint_words(items: list[str]) -> str: |
| 136 |
if len(items) <= 2: |
| 137 |
return " and ".join(items) |
| 138 |
return ", ".join(items[:-1]) + " and " + items[-1] |
| 139 |
|
| 140 |
|
| 141 |
def _strip_leading_and_trailing_blank_lines(text: str) -> str: |
| 142 |
lines = text.rstrip().split("\n") |
| 143 |
while lines: |
| 144 |
line = lines[0] |
| 145 |
if line.strip(): |
| 146 |
break |
| 147 |
del lines[0] |
| 148 |
return "\n".join(lines) |
| 149 |
|
| 150 |
|
| 151 |
@functools.lru_cache() |
| 152 |
def normalize_snippet(text: str, *, indent: int = 0) -> str: |
| 153 |
""" |
| 154 |
Reformats 'text': |
| 155 |
* removes leading and trailing blank lines |
| 156 |
* ensures that it does not end with a newline |
| 157 |
* dedents so the first nonwhite character on any line is at column "indent" |
| 158 |
""" |
| 159 |
text = _strip_leading_and_trailing_blank_lines(text) |
| 160 |
text = textwrap.dedent(text) |
| 161 |
if indent: |
| 162 |
text = textwrap.indent(text, " " * indent) |
| 163 |
return text |
| 164 |
|
| 165 |
|
| 166 |
def format_escape(text: str) -> str: |
| 167 |
# double up curly-braces, this string will be used |
| 168 |
# as part of a format_map() template later |
| 169 |
text = text.replace("{", "{{") |
| 170 |
text = text.replace("}", "}}") |
| 171 |
return text |
| 172 |
|
| 173 |
|
| 174 |
def wrap_declarations(text: str, length: int = 78) -> str: |
| 175 |
""" |
| 176 |
A simple-minded text wrapper for C function declarations. |
| 177 |
|
| 178 |
It views a declaration line as looking like this: |
| 179 |
xxxxxxxx(xxxxxxxxx,xxxxxxxxx) |
| 180 |
If called with length=30, it would wrap that line into |
| 181 |
xxxxxxxx(xxxxxxxxx, |
| 182 |
xxxxxxxxx) |
| 183 |
(If the declaration has zero or one parameters, this |
| 184 |
function won't wrap it.) |
| 185 |
|
| 186 |
If this doesn't work properly, it's probably better to |
| 187 |
start from scratch with a more sophisticated algorithm, |
| 188 |
rather than try and improve/debug this dumb little function. |
| 189 |
""" |
| 190 |
lines = [] |
| 191 |
for line in text.split("\n"): |
| 192 |
prefix, _, after_l_paren = line.partition("(") |
| 193 |
if not after_l_paren: |
| 194 |
lines.append(line) |
| 195 |
continue |
| 196 |
in_paren, _, after_r_paren = after_l_paren.partition(")") |
| 197 |
if not _: |
| 198 |
lines.append(line) |
| 199 |
continue |
| 200 |
if "," not in in_paren: |
| 201 |
lines.append(line) |
| 202 |
continue |
| 203 |
parameters = [x.strip() + ", " for x in in_paren.split(",")] |
| 204 |
prefix += "(" |
| 205 |
if len(prefix) < length: |
| 206 |
spaces = " " * len(prefix) |
| 207 |
else: |
| 208 |
spaces = " " * 4 |
| 209 |
|
| 210 |
while parameters: |
| 211 |
line = prefix |
| 212 |
first = True |
| 213 |
while parameters: |
| 214 |
if not first and (len(line) + len(parameters[0]) > length): |
| 215 |
break |
| 216 |
line += parameters.pop(0) |
| 217 |
first = False |
| 218 |
if not parameters: |
| 219 |
line = line.rstrip(", ") + ")" + after_r_paren |
| 220 |
lines.append(line.rstrip()) |
| 221 |
prefix = spaces |
| 222 |
return "\n".join(lines) |
| 223 |
|
| 224 |
|
| 225 |
def linear_format(text: str, **kwargs: str) -> str: |
| 226 |
""" |
| 227 |
Perform str.format-like substitution, except: |
| 228 |
* The strings substituted must be on lines by |
| 229 |
themselves. (This line is the "source line".) |
| 230 |
* If the substitution text is empty, the source line |
| 231 |
is removed in the output. |
| 232 |
* If the field is not recognized, the original line |
| 233 |
is passed unmodified through to the output. |
| 234 |
* If the substitution text is not empty: |
| 235 |
* Each line of the substituted text is indented |
| 236 |
by the indent of the source line. |
| 237 |
* A newline will be added to the end. |
| 238 |
""" |
| 239 |
lines = [] |
| 240 |
for line in text.split("\n"): |
| 241 |
indent, curly, trailing = line.partition("{") |
| 242 |
if not curly: |
| 243 |
lines.extend([line, "\n"]) |
| 244 |
continue |
| 245 |
|
| 246 |
name, curly, trailing = trailing.partition("}") |
| 247 |
if not curly or name not in kwargs: |
| 248 |
lines.extend([line, "\n"]) |
| 249 |
continue |
| 250 |
|
| 251 |
if trailing: |
| 252 |
raise ClinicError( |
| 253 |
f"Text found after '{{{name}}}' block marker! " |
| 254 |
"It must be on a line by itself." |
| 255 |
) |
| 256 |
if indent.strip(): |
| 257 |
raise ClinicError( |
| 258 |
f"Non-whitespace characters found before '{{{name}}}' block marker! " |
| 259 |
"It must be on a line by itself." |
| 260 |
) |
| 261 |
|
| 262 |
value = kwargs[name] |
| 263 |
if not value: |
| 264 |
continue |
| 265 |
|
| 266 |
stripped = [line.rstrip() for line in value.split("\n")] |
| 267 |
value = textwrap.indent("\n".join(stripped), indent) |
| 268 |
lines.extend([value, "\n"]) |
| 269 |
|
| 270 |
return "".join(lines[:-1]) |