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 def c_repr(text: str) -> str:
43 return '"' + text + '"'
44
45
46 def wrapped_c_string_literal(
47 text: str,
48 *,
49 width: int = 72,
50 suffix: str = "",
51 initial_indent: int = 0,
52 subsequent_indent: int = 4
53 ) -> str:
54 wrapped = textwrap.wrap(
55 text,
56 width=width,
57 replace_whitespace=False,
58 drop_whitespace=False,
59 break_on_hyphens=False,
60 )
61 separator = c_repr(suffix + "\n" + subsequent_indent * " ")
62 return initial_indent * " " + c_repr(separator.join(wrapped))
63
64
65 def _add_prefix_and_suffix(text: str, *, prefix: str = "", suffix: str = "") -> str:
66 """Return 'text' with 'prefix' prepended and 'suffix' appended to all lines.
67
68 If the last line is empty, it remains unchanged.
69 If text is blank, return text unchanged.
70
71 (textwrap.indent only adds to non-blank lines.)
72 """
73 *split, last = text.split("\n")
74 lines = [prefix + line + suffix + "\n" for line in split]
75 if last:
76 lines.append(prefix + last + suffix)
77 return "".join(lines)
78
79
80 def indent_all_lines(text: str, prefix: str) -> str:
81 return _add_prefix_and_suffix(text, prefix=prefix)
82
83
84 def suffix_all_lines(text: str, suffix: str) -> str:
85 return _add_prefix_and_suffix(text, suffix=suffix)
86
87
88 def pprint_words(items: list[str]) -> str:
89 if len(items) <= 2:
90 return " and ".join(items)
91 return ", ".join(items[:-1]) + " and " + items[-1]
92
93
94 def _strip_leading_and_trailing_blank_lines(text: str) -> str:
95 lines = text.rstrip().split("\n")
96 while lines:
97 line = lines[0]
98 if line.strip():
99 break
100 del lines[0]
101 return "\n".join(lines)
102
103
104 @functools.lru_cache()
105 def normalize_snippet(text: str, *, indent: int = 0) -> str:
106 """
107 Reformats 'text':
108 * removes leading and trailing blank lines
109 * ensures that it does not end with a newline
110 * dedents so the first nonwhite character on any line is at column "indent"
111 """
112 text = _strip_leading_and_trailing_blank_lines(text)
113 text = textwrap.dedent(text)
114 if indent:
115 text = textwrap.indent(text, " " * indent)
116 return text
117
118
119 def format_escape(text: str) -> str:
120 # double up curly-braces, this string will be used
121 # as part of a format_map() template later
122 text = text.replace("{", "{{")
123 text = text.replace("}", "}}")
124 return text
125
126
127 def wrap_declarations(text: str, length: int = 78) -> str:
128 """
129 A simple-minded text wrapper for C function declarations.
130
131 It views a declaration line as looking like this:
132 xxxxxxxx(xxxxxxxxx,xxxxxxxxx)
133 If called with length=30, it would wrap that line into
134 xxxxxxxx(xxxxxxxxx,
135 xxxxxxxxx)
136 (If the declaration has zero or one parameters, this
137 function won't wrap it.)
138
139 If this doesn't work properly, it's probably better to
140 start from scratch with a more sophisticated algorithm,
141 rather than try and improve/debug this dumb little function.
142 """
143 lines = []
144 for line in text.split("\n"):
145 prefix, _, after_l_paren = line.partition("(")
146 if not after_l_paren:
147 lines.append(line)
148 continue
149 in_paren, _, after_r_paren = after_l_paren.partition(")")
150 if not _:
151 lines.append(line)
152 continue
153 if "," not in in_paren:
154 lines.append(line)
155 continue
156 parameters = [x.strip() + ", " for x in in_paren.split(",")]
157 prefix += "("
158 if len(prefix) < length:
159 spaces = " " * len(prefix)
160 else:
161 spaces = " " * 4
162
163 while parameters:
164 line = prefix
165 first = True
166 while parameters:
167 if not first and (len(line) + len(parameters[0]) > length):
168 break
169 line += parameters.pop(0)
170 first = False
171 if not parameters:
172 line = line.rstrip(", ") + ")" + after_r_paren
173 lines.append(line.rstrip())
174 prefix = spaces
175 return "\n".join(lines)
176
177
178 def linear_format(text: str, **kwargs: str) -> str:
179 """
180 Perform str.format-like substitution, except:
181 * The strings substituted must be on lines by
182 themselves. (This line is the "source line".)
183 * If the substitution text is empty, the source line
184 is removed in the output.
185 * If the field is not recognized, the original line
186 is passed unmodified through to the output.
187 * If the substitution text is not empty:
188 * Each line of the substituted text is indented
189 by the indent of the source line.
190 * A newline will be added to the end.
191 """
192 lines = []
193 for line in text.split("\n"):
194 indent, curly, trailing = line.partition("{")
195 if not curly:
196 lines.extend([line, "\n"])
197 continue
198
199 name, curly, trailing = trailing.partition("}")
200 if not curly or name not in kwargs:
201 lines.extend([line, "\n"])
202 continue
203
204 if trailing:
205 raise ClinicError(
206 f"Text found after '{{{name}}}' block marker! "
207 "It must be on a line by itself."
208 )
209 if indent.strip():
210 raise ClinicError(
211 f"Non-whitespace characters found before '{{{name}}}' block marker! "
212 "It must be on a line by itself."
213 )
214
215 value = kwargs[name]
216 if not value:
217 continue
218
219 stripped = [line.rstrip() for line in value.split("\n")]
220 value = textwrap.indent("\n".join(stripped), indent)
221 lines.extend([value, "\n"])
222
223 return "".join(lines[:-1])