cola/textwrap.py

   1 """Text wrapping and filling"""
   2 from __future__ import absolute_import, division, print_function, unicode_literals
   3 import re
   4
   5 from .compat import ustr
   6
   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>
  12
  13
  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().
  21
  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     """
  34
  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
  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__(
  54         self, width=70, tabwidth=8, break_on_hyphens=False, drop_whitespace=True
  55     ):
  56         self.width = width
  57         self.tabwidth = tabwidth
  58         self.break_on_hyphens = break_on_hyphens
  59         self.drop_whitespace = drop_whitespace
  60
  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)
  66
  67     def _split(self, text):
  68         """_split(text : string) -> [string]
  69
  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
  95
  96     def _wrap_chunks(self, chunks):
  97         """_wrap_chunks(chunks : [string]) -> [string]
  98
  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.
 107         """
 108         lines = []
 109
 110         # Arrange in reverse order so items can be efficiently popped
 111         # from a stack of chucks.
 112         chunks = list(reversed(chunks))
 113
 114         while chunks:
 115
 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
 120
 121             # Maximum width for this line.
 122             width = self.width
 123
 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()
 128
 129             linebreak = False
 130             while chunks:
 131                 length = self.chunklen(chunks[-1])
 132
 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
 141
 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())
 147
 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])
 154             ):
 155                 cur_line.pop(0)
 156
 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()
 160
 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))
 165
 166         return lines
 167
 168     def chunklen(self, word):
 169         """Return length of a word taking tabs into account
 170
 171         >>> w = TextWrapper(tabwidth=8)
 172         >>> w.chunklen("\\t\\t\\t\\tX")
 173         33
 174
 175         """
 176         return len(word.replace('\t', '')) + word.count('\t') * self.tabwidth
 177
 178     # -- Public interface ----------------------------------------------
 179
 180     def wrap(self, text):
 181         """wrap(text : string) -> [string]
 182
 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.
 188         """
 189         chunks = self._split(text)
 190         return self._wrap_chunks(chunks)
 191
 192     def fill(self, text):
 193         """fill(text : string) -> string
 194
 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.
 198         """
 199         return "\n".join(self.wrap(text))
 200
 201
 202 def word_wrap(text, tabwidth, limit, break_on_hyphens=False):
 203     """Wrap long lines to the specified limit"""
 204
 205     lines = []
 206
 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')'
 251     )
 252
 253     w = TextWrapper(
 254         width=limit,
 255         tabwidth=tabwidth,
 256         break_on_hyphens=break_on_hyphens,
 257         drop_whitespace=True,
 258     )
 259
 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))
 265
 266     return '\n'.join(lines)
 267
 268
 269 def is_blank(string):
 270     return string and not string.strip(' ')