Debian Codegraph @

Tools/clinic/libclinic/formatting.py

raw
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])