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))')   # em-dash
  46
  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+)')
  52
  53     def __init__(self,
  54                  width=70,
  55                  tabwidth=8,
  56                  break_on_hyphens=False,
  57                  drop_whitespace=True):
  58         self.width = width
  59         self.tabwidth = tabwidth
  60         self.break_on_hyphens = break_on_hyphens
  61         self.drop_whitespace = drop_whitespace
  62
  63         # recompile the regexes for Unicode mode -- done in this clumsy way for
  64         # backwards compatibility because it's rather common to monkey-patch
  65         # the TextWrapper class' wordsep_re attribute.
  66         self.wordsep_re_uni = re.compile(self.wordsep_re.pattern, re.U)
  67         self.wordsep_simple_re_uni = re.compile(
  68             self.wordsep_simple_re.pattern, re.U)
  69
  70     def _split(self, text):
  71         """_split(text : string) -> [string]
  72
  73         Split the text to wrap into indivisible chunks.  Chunks are
  74         not quite the same as words; see _wrap_chunks() for full
  75         details.  As an example, the text
  76           Look, goof-ball -- use the -b option!
  77         breaks into the following chunks:
  78           'Look,', ' ', 'goof-', 'ball', ' ', '--', ' ',
  79           'use', ' ', 'the', ' ', '-b', ' ', 'option!'
  80         if break_on_hyphens is True, or in:
  81           'Look,', ' ', 'goof-ball', ' ', '--', ' ',
  82           'use', ' ', 'the', ' ', '-b', ' ', option!'
  83         otherwise.
  84         """
  85         if isinstance(text, ustr):
  86             if self.break_on_hyphens:
  87                 pat = self.wordsep_re_uni
  88             else:
  89                 pat = self.wordsep_simple_re_uni
  90         else:
  91             if self.break_on_hyphens:
  92                 pat = self.wordsep_re
  93             else:
  94                 pat = self.wordsep_simple_re
  95         chunks = pat.split(text)
  96         chunks = list(filter(None, chunks))  # remove empty chunks
  97         return chunks
  98
  99     def _wrap_chunks(self, chunks):
 100         """_wrap_chunks(chunks : [string]) -> [string]
 101
 102         Wrap a sequence of text chunks and return a list of lines of length
 103         'self.width' or less.  Some lines may be longer than this.  Chunks
 104         correspond roughly to words and the whitespace between them: each
 105         chunk is indivisible, but a line break can come between any two
 106         chunks.  Chunks should not have internal whitespace; ie. a chunk is
 107         either all whitespace or a "word".  Whitespace chunks will be removed
 108         from the beginning and end of lines, but apart from that whitespace is
 109         preserved.
 110         """
 111         lines = []
 112
 113         # Arrange in reverse order so items can be efficiently popped
 114         # from a stack of chucks.
 115         chunks = list(reversed(chunks))
 116
 117         while chunks:
 118
 119             # Start the list of chunks that will make up the current line.
 120             # cur_len is just the length of all the chunks in cur_line.
 121             cur_line = []
 122             cur_len = 0
 123
 124             # Maximum width for this line.
 125             width = self.width
 126
 127             # First chunk on line is a space -- drop it, unless this
 128             # is the very beginning of the text (ie. no lines started yet).
 129             if self.drop_whitespace and is_blank(chunks[-1]) and lines:
 130                 chunks.pop()
 131
 132             linebreak = False
 133             while chunks:
 134                 length = self.chunklen(chunks[-1])
 135
 136                 # Can at least squeeze this chunk onto the current line.
 137                 if cur_len + length <= width:
 138                     cur_line.append(chunks.pop())
 139                     cur_len += length
 140                 # Nope, this line is full.
 141                 else:
 142                     linebreak = True
 143                     break
 144
 145             # The current line is full, and the next chunk is too big to
 146             # fit on *any* line (not just this one).
 147             if chunks and self.chunklen(chunks[-1]) > width:
 148                 if not cur_line:
 149                     cur_line.append(chunks.pop())
 150
 151             # Avoid whitespace at the beginining of split lines
 152             if (linebreak and self.drop_whitespace and
 153                     cur_line and is_blank(cur_line[0])):
 154                 cur_line.pop(0)
 155
 156             # If the last chunk on this line is all a space, drop it.
 157             if self.drop_whitespace and cur_line and is_blank(cur_line[-1]):
 158                 cur_line.pop()
 159
 160             # Convert current line back to a string and store it in list
 161             # of all lines (return value).
 162             if cur_line:
 163                 lines.append(''.join(cur_line))
 164
 165         return lines
 166
 167     def chunklen(self, word):
 168         """Return length of a word taking tabs into account
 169
 170         >>> w = TextWrapper(tabwidth=8)
 171         >>> w.chunklen("\\t\\t\\t\\tX")
 172         33
 173
 174         """
 175         return len(word.replace('\t', '')) + word.count('\t') * self.tabwidth
 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, break_on_hyphens=False):
 202     """Wrap long lines to the specified limit"""
 203
 204     lines = []
 205
 206     # Acked-by:, Signed-off-by:, Helped-by:, etc.
 207     special_tag_rgx = re.compile(
 208         r'^('
 209         r'(('
 210         r'Acked-by|'
 211         r"Ack'd-by|"
 212         r'Based-on-patch-by|'
 213         r'Cheered-on-by|'
 214         r'Co-authored-by|'
 215         r'Comments-by|'
 216         r'Confirmed-by|'
 217         r'Contributions-by|'
 218         r'Debugged-by|'
 219         r'Discovered-by|'
 220         r'Explained-by|'
 221         r'Backtraced-by|'
 222         r'Helped-by|'
 223         r'Liked-by|'
 224         r'Link|'
 225         r'Improved-by|'
 226         r'Inspired-by|'
 227         r'Initial-patch-by|'
 228         r'Noticed-by|'
 229         r'Original-patch-by|'
 230         r'Originally-by|'
 231         r'Mentored-by|'
 232         r'Patch-by|'
 233         r'Proposed-by|'
 234         r'References|'
 235         r'Related-to|'
 236         r'Reported-by|'
 237         r'Requested-by|'
 238         r'Reviewed-by|'
 239         r'See-also|'
 240         r'Signed-off-by|'
 241         r'Signed-Off-by|'
 242         r'Spotted-by|'
 243         r'Suggested-by|'
 244         r'Tested-by|'
 245         r'Tested-on-([a-zA-Z-_]+)-by|'
 246         r'With-suggestions-by'
 247         r'):)'
 248         r'|([Cc]\.\s*[Ff]\.\s+)'
 249         r')')
 250
 251     w = TextWrapper(width=limit,
 252                     tabwidth=tabwidth,
 253                     break_on_hyphens=break_on_hyphens,
 254                     drop_whitespace=True)
 255
 256     for line in text.split('\n'):
 257         if special_tag_rgx.match(line):
 258             lines.append(line)
 259         else:
 260             lines.append(w.fill(line))
 261
 262     return '\n'.join(lines)
 263
 264
 265 def is_blank(string):
 266     return string and not string.strip(' ')