CHANGES: mention the documentation improvements and typofixes
[git-cola.git] / cola / textwrap.py
blob1d547815d088b6887ebf40e7b2d7852217fc8d4f
1 """Text wrapping and filling"""
2 from __future__ import absolute_import, division, print_function, unicode_literals
3 import re
5 from .compat import ustr
7 # Copyright (C) 1999-2001 Gregory P. Ward.
8 # Copyright (C) 2002, 2003 Python Software Foundation.
9 # Copyright (C) 2013, David Aguilar
10 # Written by Greg Ward <gward@python.net>
11 # Simplified for git-cola by David Aguilar <davvid@gmail.com>
14 class TextWrapper(object):
15 """
16 Object for wrapping/filling text. The public interface consists of
17 the wrap() and fill() methods; the other methods are just there for
18 subclasses to override in order to tweak the default behaviour.
19 If you want to completely replace the main wrapping algorithm,
20 you'll probably have to override _wrap_chunks().
22 Several instance attributes control various aspects of wrapping:
23 width (default: 70)
24 The preferred width of wrapped lines.
25 tabwidth (default: 8)
26 The width of a tab used when calculating line length.
27 break_on_hyphens (default: false)
28 Allow breaking hyphenated words. If true, wrapping will occur
29 preferably on whitespaces and right after hyphens part of
30 compound words.
31 drop_whitespace (default: true)
32 Drop leading and trailing whitespace from lines.
33 """
35 # This funky little regex is just the trick for splitting
36 # text up into word-wrappable chunks. E.g.
37 # "Hello there -- you goof-ball, use the -b option!"
38 # splits into
39 # Hello/ /there/ /--/ /you/ /goof-/ball,/ /use/ /the/ /-b/ /option!
40 # (after stripping out empty strings).
41 wordsep_re = re.compile(
42 r'(\s+|' # any whitespace
43 r'[^\s\w]*\w+[^0-9\W]-(?=\w+[^0-9\W])|' # hyphenated words
44 r'(?<=[\w\!\"\'\&\.\,\?])-{2,}(?=\w))'
45 ) # em-dash
47 # This less funky little regex just split on recognized spaces. E.g.
48 # "Hello there -- you goof-ball, use the -b option!"
49 # splits into
50 # Hello/ /there/ /--/ /you/ /goof-ball,/ /use/ /the/ /-b/ /option!/
51 wordsep_simple_re = re.compile(r'(\s+)')
53 def __init__(
54 self, width=70, tabwidth=8, break_on_hyphens=False, drop_whitespace=True
56 self.width = width
57 self.tabwidth = tabwidth
58 self.break_on_hyphens = break_on_hyphens
59 self.drop_whitespace = drop_whitespace
61 # recompile the regexes for Unicode mode -- done in this clumsy way for
62 # backwards compatibility because it's rather common to monkey-patch
63 # the TextWrapper class' wordsep_re attribute.
64 self.wordsep_re_uni = re.compile(self.wordsep_re.pattern, re.U)
65 self.wordsep_simple_re_uni = re.compile(self.wordsep_simple_re.pattern, re.U)
67 def _split(self, text):
68 """_split(text : string) -> [string]
70 Split the text to wrap into indivisible chunks. Chunks are
71 not quite the same as words; see _wrap_chunks() for full
72 details. As an example, the text
73 Look, goof-ball -- use the -b option!
74 breaks into the following chunks:
75 'Look,', ' ', 'goof-', 'ball', ' ', '--', ' ',
76 'use', ' ', 'the', ' ', '-b', ' ', 'option!'
77 if break_on_hyphens is True, or in:
78 'Look,', ' ', 'goof-ball', ' ', '--', ' ',
79 'use', ' ', 'the', ' ', '-b', ' ', option!'
80 otherwise.
81 """
82 if isinstance(text, ustr):
83 if self.break_on_hyphens:
84 pat = self.wordsep_re_uni
85 else:
86 pat = self.wordsep_simple_re_uni
87 else:
88 if self.break_on_hyphens:
89 pat = self.wordsep_re
90 else:
91 pat = self.wordsep_simple_re
92 chunks = pat.split(text)
93 chunks = list(filter(None, chunks)) # remove empty chunks
94 return chunks
96 def _wrap_chunks(self, chunks):
97 """_wrap_chunks(chunks : [string]) -> [string]
99 Wrap a sequence of text chunks and return a list of lines of length
100 'self.width' or less. Some lines may be longer than this. Chunks
101 correspond roughly to words and the whitespace between them: each
102 chunk is indivisible, but a line break can come between any two
103 chunks. Chunks should not have internal whitespace; ie. a chunk is
104 either all whitespace or a "word". Whitespace chunks will be removed
105 from the beginning and end of lines, but apart from that whitespace is
106 preserved.
108 lines = []
110 # Arrange in reverse order so items can be efficiently popped
111 # from a stack of chucks.
112 chunks = list(reversed(chunks))
114 while chunks:
116 # Start the list of chunks that will make up the current line.
117 # cur_len is just the length of all the chunks in cur_line.
118 cur_line = []
119 cur_len = 0
121 # Maximum width for this line.
122 width = self.width
124 # First chunk on line is a space -- drop it, unless this
125 # is the very beginning of the text (ie. no lines started yet).
126 if self.drop_whitespace and is_blank(chunks[-1]) and lines:
127 chunks.pop()
129 linebreak = False
130 while chunks:
131 length = self.chunklen(chunks[-1])
133 # Can at least squeeze this chunk onto the current line.
134 if cur_len + length <= width:
135 cur_line.append(chunks.pop())
136 cur_len += length
137 # Nope, this line is full.
138 else:
139 linebreak = True
140 break
142 # The current line is full, and the next chunk is too big to
143 # fit on *any* line (not just this one).
144 if chunks and self.chunklen(chunks[-1]) > width:
145 if not cur_line:
146 cur_line.append(chunks.pop())
148 # Avoid whitespace at the beginining of split lines
149 if (
150 linebreak
151 and self.drop_whitespace
152 and cur_line
153 and is_blank(cur_line[0])
155 cur_line.pop(0)
157 # If the last chunk on this line is all a space, drop it.
158 if self.drop_whitespace and cur_line and is_blank(cur_line[-1]):
159 cur_line.pop()
161 # Convert current line back to a string and store it in list
162 # of all lines (return value).
163 if cur_line:
164 lines.append(''.join(cur_line))
166 return lines
168 def chunklen(self, word):
169 """Return length of a word taking tabs into account
171 >>> w = TextWrapper(tabwidth=8)
172 >>> w.chunklen("\\t\\t\\t\\tX")
176 return len(word.replace('\t', '')) + word.count('\t') * self.tabwidth
178 # -- Public interface ----------------------------------------------
180 def wrap(self, text):
181 """wrap(text : string) -> [string]
183 Reformat the single paragraph in 'text' so it fits in lines of
184 no more than 'self.width' columns, and return a list of wrapped
185 lines. Tabs in 'text' are expanded with string.expandtabs(),
186 and all other whitespace characters (including newline) are
187 converted to space.
189 chunks = self._split(text)
190 return self._wrap_chunks(chunks)
192 def fill(self, text):
193 """fill(text : string) -> string
195 Reformat the single paragraph in 'text' to fit in lines of no
196 more than 'self.width' columns, and return a new string
197 containing the entire wrapped paragraph.
199 return "\n".join(self.wrap(text))
202 def word_wrap(text, tabwidth, limit, break_on_hyphens=False):
203 """Wrap long lines to the specified limit"""
205 lines = []
207 # Acked-by:, Signed-off-by:, Helped-by:, etc.
208 special_tag_rgx = re.compile(
209 r'^('
210 r'(('
211 r'Acked-by|'
212 r"Ack'd-by|"
213 r'Based-on-patch-by|'
214 r'Cheered-on-by|'
215 r'Co-authored-by|'
216 r'Comments-by|'
217 r'Confirmed-by|'
218 r'Contributions-by|'
219 r'Debugged-by|'
220 r'Discovered-by|'
221 r'Explained-by|'
222 r'Backtraced-by|'
223 r'Helped-by|'
224 r'Liked-by|'
225 r'Link|'
226 r'Improved-by|'
227 r'Inspired-by|'
228 r'Initial-patch-by|'
229 r'Noticed-by|'
230 r'Original-patch-by|'
231 r'Originally-by|'
232 r'Mentored-by|'
233 r'Patch-by|'
234 r'Proposed-by|'
235 r'References|'
236 r'Related-to|'
237 r'Reported-by|'
238 r'Requested-by|'
239 r'Reviewed-by|'
240 r'See-also|'
241 r'Signed-off-by|'
242 r'Signed-Off-by|'
243 r'Spotted-by|'
244 r'Suggested-by|'
245 r'Tested-by|'
246 r'Tested-on-([a-zA-Z-_]+)-by|'
247 r'With-suggestions-by'
248 r'):)'
249 r'|([Cc]\.\s*[Ff]\.\s+)'
250 r')'
253 w = TextWrapper(
254 width=limit,
255 tabwidth=tabwidth,
256 break_on_hyphens=break_on_hyphens,
257 drop_whitespace=True,
260 for line in text.split('\n'):
261 if special_tag_rgx.match(line):
262 lines.append(line)
263 else:
264 lines.append(w.fill(line))
266 return '\n'.join(lines)
269 def is_blank(string):
270 return string and not string.strip(' ')