cola/textwrap.py

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