1 """Text wrapping and filling.
3 from __future__
import division
, absolute_import
, unicode_literals
6 from .compat
import ustr
8 # Copyright (C) 1999-2001 Gregory P. Ward.
9 # Copyright (C) 2002, 2003 Python Software Foundation.
10 # Copyright (C) 2013, David Aguilar
11 # Written by Greg Ward <gward@python.net>
12 # Simplified for git-cola by David Aguilar <davvid@gmail.com>
15 class TextWrapper(object):
17 Object for wrapping/filling text. The public interface consists of
18 the wrap() and fill() methods; the other methods are just there for
19 subclasses to override in order to tweak the default behaviour.
20 If you want to completely replace the main wrapping algorithm,
21 you'll probably have to override _wrap_chunks().
23 Several instance attributes control various aspects of wrapping:
25 The preferred width of wrapped lines.
27 The width of a tab used when calculating line length.
28 break_on_hyphens (default: false)
29 Allow breaking hyphenated words. If true, wrapping will occur
30 preferably on whitespaces and right after hyphens part of
32 drop_whitespace (default: true)
33 Drop leading and trailing whitespace from lines.
36 # This funky little regex is just the trick for splitting
37 # text up into word-wrappable chunks. E.g.
38 # "Hello there -- you goof-ball, use the -b option!"
40 # Hello/ /there/ /--/ /you/ /goof-/ball,/ /use/ /the/ /-b/ /option!
41 # (after stripping out empty strings).
42 wordsep_re
= re
.compile(
43 r
'(\s+|' # any whitespace
44 r
'[^\s\w]*\w+[^0-9\W]-(?=\w+[^0-9\W])|' # hyphenated words
45 r
'(?<=[\w\!\"\'\
&\
.\
,\?])-{2,}(?
=\w
))'
48 # This less funky little regex just split on recognized spaces. E.g.
49 # "Hello there -- you goof-ball, use the -b option!"
51 # Hello/ /there/ /--/ /you/ /goof-ball,/ /use/ /the/ /-b/ /option!/
52 wordsep_simple_re = re.compile(r'(\s
+)')
55 self, width=70, tabwidth=8, break_on_hyphens=False, drop_whitespace=True
58 self.tabwidth = tabwidth
59 self.break_on_hyphens = break_on_hyphens
60 self.drop_whitespace = drop_whitespace
62 # recompile the regexes for Unicode mode -- done in this clumsy way for
63 # backwards compatibility because it's rather common to monkey
-patch
64 # the TextWrapper class' wordsep_re attribute.
65 self
.wordsep_re_uni
= re
.compile(self
.wordsep_re
.pattern
, re
.U
)
66 self
.wordsep_simple_re_uni
= re
.compile(self
.wordsep_simple_re
.pattern
, re
.U
)
68 def _split(self
, text
):
69 """_split(text : string) -> [string]
71 Split the text to wrap into indivisible chunks. Chunks are
72 not quite the same as words; see _wrap_chunks() for full
73 details. As an example, the text
74 Look, goof-ball -- use the -b option!
75 breaks into the following chunks:
76 'Look,', ' ', 'goof-', 'ball', ' ', '--', ' ',
77 'use', ' ', 'the', ' ', '-b', ' ', 'option!'
78 if break_on_hyphens is True, or in:
79 'Look,', ' ', 'goof-ball', ' ', '--', ' ',
80 'use', ' ', 'the', ' ', '-b', ' ', option!'
83 if isinstance(text
, ustr
):
84 if self
.break_on_hyphens
:
85 pat
= self
.wordsep_re_uni
87 pat
= self
.wordsep_simple_re_uni
89 if self
.break_on_hyphens
:
92 pat
= self
.wordsep_simple_re
93 chunks
= pat
.split(text
)
94 chunks
= list(filter(None, chunks
)) # remove empty chunks
97 def _wrap_chunks(self
, chunks
):
98 """_wrap_chunks(chunks : [string]) -> [string]
100 Wrap a sequence of text chunks and return a list of lines of length
101 'self.width' or less. Some lines may be longer than this. Chunks
102 correspond roughly to words and the whitespace between them: each
103 chunk is indivisible, but a line break can come between any two
104 chunks. Chunks should not have internal whitespace; ie. a chunk is
105 either all whitespace or a "word". Whitespace chunks will be removed
106 from the beginning and end of lines, but apart from that whitespace is
111 # Arrange in reverse order so items can be efficiently popped
112 # from a stack of chucks.
113 chunks
= list(reversed(chunks
))
117 # Start the list of chunks that will make up the current line.
118 # cur_len is just the length of all the chunks in cur_line.
122 # Maximum width for this line.
125 # First chunk on line is a space -- drop it, unless this
126 # is the very beginning of the text (ie. no lines started yet).
127 if self
.drop_whitespace
and is_blank(chunks
[-1]) and lines
:
132 length
= self
.chunklen(chunks
[-1])
134 # Can at least squeeze this chunk onto the current line.
135 if cur_len
+ length
<= width
:
136 cur_line
.append(chunks
.pop())
138 # Nope, this line is full.
143 # The current line is full, and the next chunk is too big to
144 # fit on *any* line (not just this one).
145 if chunks
and self
.chunklen(chunks
[-1]) > width
:
147 cur_line
.append(chunks
.pop())
149 # Avoid whitespace at the beginining of split lines
152 and self
.drop_whitespace
154 and is_blank(cur_line
[0])
158 # If the last chunk on this line is all a space, drop it.
159 if self
.drop_whitespace
and cur_line
and is_blank(cur_line
[-1]):
162 # Convert current line back to a string and store it in list
163 # of all lines (return value).
165 lines
.append(''.join(cur_line
))
169 def chunklen(self
, word
):
170 """Return length of a word taking tabs into account
172 >>> w = TextWrapper(tabwidth=8)
173 >>> w.chunklen("\\t\\t\\t\\tX")
177 return len(word
.replace('\t', '')) + word
.count('\t') * self
.tabwidth
179 # -- Public interface ----------------------------------------------
181 def wrap(self
, text
):
182 """wrap(text : string) -> [string]
184 Reformat the single paragraph in 'text' so it fits in lines of
185 no more than 'self.width' columns, and return a list of wrapped
186 lines. Tabs in 'text' are expanded with string.expandtabs(),
187 and all other whitespace characters (including newline) are
190 chunks
= self
._split
(text
)
191 return self
._wrap
_chunks
(chunks
)
193 def fill(self
, text
):
194 """fill(text : string) -> string
196 Reformat the single paragraph in 'text' to fit in lines of no
197 more than 'self.width' columns, and return a new string
198 containing the entire wrapped paragraph.
200 return "\n".join(self
.wrap(text
))
203 def word_wrap(text
, tabwidth
, limit
, break_on_hyphens
=False):
204 """Wrap long lines to the specified limit"""
208 # Acked-by:, Signed-off-by:, Helped-by:, etc.
209 special_tag_rgx
= re
.compile(
214 r
'Based-on-patch-by|'
231 r
'Original-patch-by|'
247 r
'Tested-on-([a-zA-Z-_]+)-by|'
248 r
'With-suggestions-by'
250 r
'|([Cc]\.\s*[Ff]\.\s+)'
257 break_on_hyphens
=break_on_hyphens
,
258 drop_whitespace
=True,
261 for line
in text
.split('\n'):
262 if special_tag_rgx
.match(line
):
265 lines
.append(w
.fill(line
))
267 return '\n'.join(lines
)
270 def is_blank(string
):
271 return string
and not string
.strip(' ')