cola/textwrap.py

   1 """Text wrapping and filling.
   2 """
   3 from __future__ import division, absolute_import, unicode_literals
   4 import re
   5
   6 from .compat import ustr
   7
   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>
  13
  14
  15 class TextWrapper(object):
  16     """
  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().
  22
  23     Several instance attributes control various aspects of wrapping:
  24       width (default: 70)
  25         The preferred width of wrapped lines.
  26       tabwidth (default: 8)
  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
  31         compound words.
  32       drop_whitespace (default: true)
  33         Drop leading and trailing whitespace from lines.
  34     """
  35
  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!"
  39     # splits into
  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))'
  46     )  # em-dash
  47
  48     # This less funky little regex just split on recognized spaces. E.g.
  49     #   "Hello there -- you goof-ball, use the -b option!"
  50     # splits into
  51     #   Hello/ /there/ /--/ /you/ /goof-ball,/ /use/ /the/ /-b/ /option!/
  52     wordsep_simple_re = re.compile(r'(\s+)')
  53
  54     def __init__(
  55         self, width=70, tabwidth=8, break_on_hyphens=False, drop_whitespace=True
  56     ):
  57         self.width = width
  58         self.tabwidth = tabwidth
  59         self.break_on_hyphens = break_on_hyphens
  60         self.drop_whitespace = drop_whitespace
  61
  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)
  67
  68     def _split(self, text):
  69         """_split(text : string) -> [string]
  70
  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!'
  81         otherwise.
  82         """
  83         if isinstance(text, ustr):
  84             if self.break_on_hyphens:
  85                 pat = self.wordsep_re_uni
  86             else:
  87                 pat = self.wordsep_simple_re_uni
  88         else:
  89             if self.break_on_hyphens:
  90                 pat = self.wordsep_re
  91             else:
  92                 pat = self.wordsep_simple_re
  93         chunks = pat.split(text)
  94         chunks = list(filter(None, chunks))  # remove empty chunks
  95         return chunks
  96
  97     def _wrap_chunks(self, chunks):
  98         """_wrap_chunks(chunks : [string]) -> [string]
  99
 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
 107         preserved.
 108         """
 109         lines = []
 110
 111         # Arrange in reverse order so items can be efficiently popped
 112         # from a stack of chucks.
 113         chunks = list(reversed(chunks))
 114
 115         while chunks:
 116
 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.
 119             cur_line = []
 120             cur_len = 0
 121
 122             # Maximum width for this line.
 123             width = self.width
 124
 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:
 128                 chunks.pop()
 129
 130             linebreak = False
 131             while chunks:
 132                 length = self.chunklen(chunks[-1])
 133
 134                 # Can at least squeeze this chunk onto the current line.
 135                 if cur_len + length <= width:
 136                     cur_line.append(chunks.pop())
 137                     cur_len += length
 138                 # Nope, this line is full.
 139                 else:
 140                     linebreak = True
 141                     break
 142
 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:
 146                 if not cur_line:
 147                     cur_line.append(chunks.pop())
 148
 149             # Avoid whitespace at the beginining of split lines
 150             if (
 151                 linebreak
 152                 and self.drop_whitespace
 153                 and cur_line
 154                 and is_blank(cur_line[0])
 155             ):
 156                 cur_line.pop(0)
 157
 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]):
 160                 cur_line.pop()
 161
 162             # Convert current line back to a string and store it in list
 163             # of all lines (return value).
 164             if cur_line:
 165                 lines.append(''.join(cur_line))
 166
 167         return lines
 168
 169     def chunklen(self, word):
 170         """Return length of a word taking tabs into account
 171
 172         >>> w = TextWrapper(tabwidth=8)
 173         >>> w.chunklen("\\t\\t\\t\\tX")
 174         33
 175
 176         """
 177         return len(word.replace('\t', '')) + word.count('\t') * self.tabwidth
 178
 179     # -- Public interface ----------------------------------------------
 180
 181     def wrap(self, text):
 182         """wrap(text : string) -> [string]
 183
 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
 188         converted to space.
 189         """
 190         chunks = self._split(text)
 191         return self._wrap_chunks(chunks)
 192
 193     def fill(self, text):
 194         """fill(text : string) -> string
 195
 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.
 199         """
 200         return "\n".join(self.wrap(text))
 201
 202
 203 def word_wrap(text, tabwidth, limit, break_on_hyphens=False):
 204     """Wrap long lines to the specified limit"""
 205
 206     lines = []
 207
 208     # Acked-by:, Signed-off-by:, Helped-by:, etc.
 209     special_tag_rgx = re.compile(
 210         r'^('
 211         r'(('
 212         r'Acked-by|'
 213         r"Ack'd-by|"
 214         r'Based-on-patch-by|'
 215         r'Cheered-on-by|'
 216         r'Co-authored-by|'
 217         r'Comments-by|'
 218         r'Confirmed-by|'
 219         r'Contributions-by|'
 220         r'Debugged-by|'
 221         r'Discovered-by|'
 222         r'Explained-by|'
 223         r'Backtraced-by|'
 224         r'Helped-by|'
 225         r'Liked-by|'
 226         r'Link|'
 227         r'Improved-by|'
 228         r'Inspired-by|'
 229         r'Initial-patch-by|'
 230         r'Noticed-by|'
 231         r'Original-patch-by|'
 232         r'Originally-by|'
 233         r'Mentored-by|'
 234         r'Patch-by|'
 235         r'Proposed-by|'
 236         r'References|'
 237         r'Related-to|'
 238         r'Reported-by|'
 239         r'Requested-by|'
 240         r'Reviewed-by|'
 241         r'See-also|'
 242         r'Signed-off-by|'
 243         r'Signed-Off-by|'
 244         r'Spotted-by|'
 245         r'Suggested-by|'
 246         r'Tested-by|'
 247         r'Tested-on-([a-zA-Z-_]+)-by|'
 248         r'With-suggestions-by'
 249         r'):)'
 250         r'|([Cc]\.\s*[Ff]\.\s+)'
 251         r')'
 252     )
 253
 254     w = TextWrapper(
 255         width=limit,
 256         tabwidth=tabwidth,
 257         break_on_hyphens=break_on_hyphens,
 258         drop_whitespace=True,
 259     )
 260
 261     for line in text.split('\n'):
 262         if special_tag_rgx.match(line):
 263             lines.append(line)
 264         else:
 265             lines.append(w.fill(line))
 266
 267     return '\n'.join(lines)
 268
 269
 270 def is_blank(string):
 271     return string and not string.strip(' ')