← Back to branch summary

~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

Viewing changes to bzrlib/utextwrap.py

  • Committer: Vincent Ladeuil
  • Date: 2013-08-09 15:09:23 UTC
  • mto: This revision was merged to the branch mainline in revision 6587.
  • Revision ID: v.ladeuil+lp@free.fr-20130809150923-y71dusyorep0hbkt
Fix various typos in docstrings. Rename 'buffer' to 'buf' since it's now a python builtin function.

Show diffs side-by-side

added added

removed removed

Lines of Context:
bzrlib/utextwrap.py
 
1
# Copyright (C) 2011 Canonical Ltd
 
2
#
 
3
# UTextWrapper._handle_long_word, UTextWrapper._wrap_chunks,
 
4
# UTextWrapper._fix_sentence_endings, wrap and fill is copied from Python's
 
5
# textwrap module (under PSF license) and modified for support CJK.
 
6
# Original Copyright for these functions:
 
7
#
 
8
# Copyright (C) 1999-2001 Gregory P. Ward.
 
9
# Copyright (C) 2002, 2003 Python Software Foundation.
 
10
#
 
11
# Written by Greg Ward <gward@python.net>
 
12
# This program is free software; you can redistribute it and/or modify
 
13
# it under the terms of the GNU General Public License as published by
 
14
# the Free Software Foundation; either version 2 of the License, or
 
15
# (at your option) any later version.
 
16
#
 
17
# This program is distributed in the hope that it will be useful,
 
18
# but WITHOUT ANY WARRANTY; without even the implied warranty of
 
19
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 
20
# GNU General Public License for more details.
 
21
#
 
22
# You should have received a copy of the GNU General Public License
 
23
# along with this program; if not, write to the Free Software
 
24
# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
 
25
 
 
26
from __future__ import absolute_import
 
27
 
 
28
import sys
 
29
import textwrap
 
30
from unicodedata import east_asian_width as _eawidth
 
31
 
 
32
from bzrlib import osutils
 
33
 
 
34
__all__ = ["UTextWrapper", "fill", "wrap"]
 
35
 
 
36
class UTextWrapper(textwrap.TextWrapper):
 
37
    """
 
38
    Extend TextWrapper for Unicode.
 
39
 
 
40
    This textwrapper handles east asian double width and split word
 
41
    even if !break_long_words when word contains double width
 
42
    characters.
 
43
 
 
44
    :param ambiguous_width: (keyword argument) width for character when
 
45
                            unicodedata.east_asian_width(c) == 'A'
 
46
                            (default: 1)
 
47
 
 
48
    Limitations:
 
49
    * expand_tabs doesn't fixed. It uses len() for calculating width
 
50
      of string on left of TAB.
 
51
    * Handles one codeunit as a single character having 1 or 2 width.
 
52
      This is not correct when there are surrogate pairs, combined
 
53
      characters or zero-width characters.
 
54
    * Treats all asian character are line breakable. But it is not
 
55
      true because line breaking is prohibited around some characters.
 
56
      (For example, breaking before punctation mark is prohibited.)
 
57
      See UAX # 14 "UNICODE LINE BREAKING ALGORITHM"
 
58
    """
 
59
 
 
60
    def __init__(self, width=None, **kwargs):
 
61
        if width is None:
 
62
            width = (osutils.terminal_width() or
 
63
                        osutils.default_terminal_width) - 1
 
64
 
 
65
        ambi_width = kwargs.pop('ambiguous_width', 1)
 
66
        if ambi_width == 1:
 
67
            self._east_asian_doublewidth = 'FW'
 
68
        elif ambi_width == 2:
 
69
            self._east_asian_doublewidth = 'FWA'
 
70
        else:
 
71
            raise ValueError("ambiguous_width should be 1 or 2")
 
72
 
 
73
        # No drop_whitespace param before Python 2.6 it was always dropped
 
74
        if sys.version_info < (2, 6):
 
75
            self.drop_whitespace = kwargs.pop("drop_whitespace", True)
 
76
            if not self.drop_whitespace:
 
77
                raise ValueError("TextWrapper version must drop whitespace")
 
78
        textwrap.TextWrapper.__init__(self, width, **kwargs)
 
79
 
 
80
    def _unicode_char_width(self, uc):
 
81
        """Return width of character `uc`.
 
82
 
 
83
        :param:     uc      Single unicode character.
 
84
        """
 
85
        # 'A' means width of the character is not be able to determine.
 
86
        # We assume that it's width is 2 because longer wrap may over
 
87
        # terminal width but shorter wrap may be acceptable.
 
88
        return (_eawidth(uc) in self._east_asian_doublewidth and 2) or 1
 
89
 
 
90
    def _width(self, s):
 
91
        """Returns width for s.
 
92
 
 
93
        When s is unicode, take care of east asian width.
 
94
        When s is bytes, treat all byte is single width character.
 
95
        """
 
96
        charwidth = self._unicode_char_width
 
97
        return sum(charwidth(c) for c in s)
 
98
 
 
99
    def _cut(self, s, width):
 
100
        """Returns head and rest of s. (head+rest == s)
 
101
 
 
102
        Head is large as long as _width(head) <= width.
 
103
        """
 
104
        w = 0
 
105
        charwidth = self._unicode_char_width
 
106
        for pos, c in enumerate(s):
 
107
            w += charwidth(c)
 
108
            if w > width:
 
109
                return s[:pos], s[pos:]
 
110
        return s, u''
 
111
 
 
112
    def _fix_sentence_endings(self, chunks):
 
113
        """_fix_sentence_endings(chunks : [string])
 
114
 
 
115
        Correct for sentence endings buried in 'chunks'.  Eg. when the
 
116
        original text contains "... foo.\nBar ...", munge_whitespace()
 
117
        and split() will convert that to [..., "foo.", " ", "Bar", ...]
 
118
        which has one too few spaces; this method simply changes the one
 
119
        space to two.
 
120
 
 
121
        Note: This function is copied from textwrap.TextWrap and modified
 
122
        to use unicode always.
 
123
        """
 
124
        i = 0
 
125
        L = len(chunks)-1
 
126
        patsearch = self.sentence_end_re.search
 
127
        while i < L:
 
128
            if chunks[i+1] == u" " and patsearch(chunks[i]):
 
129
                chunks[i+1] = u"  "
 
130
                i += 2
 
131
            else:
 
132
                i += 1
 
133
 
 
134
    def _handle_long_word(self, chunks, cur_line, cur_len, width):
 
135
        # Figure out when indent is larger than the specified width, and make
 
136
        # sure at least one character is stripped off on every pass
 
137
        if width < 2:
 
138
            space_left = chunks[-1] and self._width(chunks[-1][0]) or 1
 
139
        else:
 
140
            space_left = width - cur_len
 
141
 
 
142
        # If we're allowed to break long words, then do so: put as much
 
143
        # of the next chunk onto the current line as will fit.
 
144
        if self.break_long_words:
 
145
            head, rest = self._cut(chunks[-1], space_left)
 
146
            cur_line.append(head)
 
147
            if rest:
 
148
                chunks[-1] = rest
 
149
            else:
 
150
                del chunks[-1]
 
151
 
 
152
        # Otherwise, we have to preserve the long word intact.  Only add
 
153
        # it to the current line if there's nothing already there --
 
154
        # that minimizes how much we violate the width constraint.
 
155
        elif not cur_line:
 
156
            cur_line.append(chunks.pop())
 
157
 
 
158
        # If we're not allowed to break long words, and there's already
 
159
        # text on the current line, do nothing.  Next time through the
 
160
        # main loop of _wrap_chunks(), we'll wind up here again, but
 
161
        # cur_len will be zero, so the next line will be entirely
 
162
        # devoted to the long word that we can't handle right now.
 
163
 
 
164
    def _wrap_chunks(self, chunks):
 
165
        lines = []
 
166
        if self.width <= 0:
 
167
            raise ValueError("invalid width %r (must be > 0)" % self.width)
 
168
 
 
169
        # Arrange in reverse order so items can be efficiently popped
 
170
        # from a stack of chucks.
 
171
        chunks.reverse()
 
172
 
 
173
        while chunks:
 
174
 
 
175
            # Start the list of chunks that will make up the current line.
 
176
            # cur_len is just the length of all the chunks in cur_line.
 
177
            cur_line = []
 
178
            cur_len = 0
 
179
 
 
180
            # Figure out which static string will prefix this line.
 
181
            if lines:
 
182
                indent = self.subsequent_indent
 
183
            else:
 
184
                indent = self.initial_indent
 
185
 
 
186
            # Maximum width for this line.
 
187
            width = self.width - len(indent)
 
188
 
 
189
            # First chunk on line is whitespace -- drop it, unless this
 
190
            # is the very beginning of the text (ie. no lines started yet).
 
191
            if self.drop_whitespace and chunks[-1].strip() == '' and lines:
 
192
                del chunks[-1]
 
193
 
 
194
            while chunks:
 
195
                # Use _width instead of len for east asian width
 
196
                l = self._width(chunks[-1])
 
197
 
 
198
                # Can at least squeeze this chunk onto the current line.
 
199
                if cur_len + l <= width:
 
200
                    cur_line.append(chunks.pop())
 
201
                    cur_len += l
 
202
 
 
203
                # Nope, this line is full.
 
204
                else:
 
205
                    break
 
206
 
 
207
            # The current line is full, and the next chunk is too big to
 
208
            # fit on *any* line (not just this one).
 
209
            if chunks and self._width(chunks[-1]) > width:
 
210
                self._handle_long_word(chunks, cur_line, cur_len, width)
 
211
 
 
212
            # If the last chunk on this line is all whitespace, drop it.
 
213
            if self.drop_whitespace and cur_line and not cur_line[-1].strip():
 
214
                del cur_line[-1]
 
215
 
 
216
            # Convert current line back to a string and store it in list
 
217
            # of all lines (return value).
 
218
            if cur_line:
 
219
                lines.append(indent + u''.join(cur_line))
 
220
 
 
221
        return lines
 
222
 
 
223
    def _split(self, text):
 
224
        chunks = textwrap.TextWrapper._split(self, unicode(text))
 
225
        cjk_split_chunks = []
 
226
        for chunk in chunks:
 
227
            prev_pos = 0
 
228
            for pos, char in enumerate(chunk):
 
229
                if self._unicode_char_width(char) == 2:
 
230
                    if prev_pos < pos:
 
231
                        cjk_split_chunks.append(chunk[prev_pos:pos])
 
232
                    cjk_split_chunks.append(char)
 
233
                    prev_pos = pos+1
 
234
            if prev_pos < len(chunk):
 
235
                cjk_split_chunks.append(chunk[prev_pos:])
 
236
        return cjk_split_chunks
 
237
 
 
238
    def wrap(self, text):
 
239
        # ensure text is unicode
 
240
        return textwrap.TextWrapper.wrap(self, unicode(text))
 
241
 
 
242
# -- Convenience interface ---------------------------------------------
 
243
 
 
244
def wrap(text, width=None, **kwargs):
 
245
    """Wrap a single paragraph of text, returning a list of wrapped lines.
 
246
 
 
247
    Reformat the single paragraph in 'text' so it fits in lines of no
 
248
    more than 'width' columns, and return a list of wrapped lines.  By
 
249
    default, tabs in 'text' are expanded with string.expandtabs(), and
 
250
    all other whitespace characters (including newline) are converted to
 
251
    space.  See TextWrapper class for available keyword args to customize
 
252
    wrapping behaviour.
 
253
    """
 
254
    return UTextWrapper(width=width, **kwargs).wrap(text)
 
255
 
 
256
def fill(text, width=None, **kwargs):
 
257
    """Fill a single paragraph of text, returning a new string.
 
258
 
 
259
    Reformat the single paragraph in 'text' to fit in lines of no more
 
260
    than 'width' columns, and return a new string containing the entire
 
261
    wrapped paragraph.  As with wrap(), tabs are expanded and other
 
262
    whitespace characters converted to space.  See TextWrapper class for
 
263
    available keyword args to customize wrapping behaviour.
 
264
    """
 
265
    return UTextWrapper(width=width, **kwargs).fill(text)
 
266