cola/textwrap.py

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