← Back to branch summary

~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

Viewing changes to bzrlib/rio.py

  • Committer: Patch Queue Manager
  • Date: 2011-09-22 14:12:18 UTC
  • mfrom: (6155.3.1 jam)
  • Revision ID: pqm@pqm.ubuntu.com-20110922141218-86s4uu6nqvourw4f
(jameinel) Cleanup comments bzrlib/smart/__init__.py (John A Meinel)

Show diffs side-by-side

added added

removed removed

Lines of Context:
bzrlib/rio.py
1
 
# Copyright (C) 2005 by Canonical Ltd
2
 
#
3
 
# Distributed under the GNU General Public Licence v2
 
1
# Copyright (C) 2005 Canonical Ltd
 
2
#
 
3
# This program is free software; you can redistribute it and/or modify
 
4
# it under the terms of the GNU General Public License as published by
 
5
# the Free Software Foundation; either version 2 of the License, or
 
6
# (at your option) any later version.
 
7
#
 
8
# This program is distributed in the hope that it will be useful,
 
9
# but WITHOUT ANY WARRANTY; without even the implied warranty of
 
10
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 
11
# GNU General Public License for more details.
 
12
#
 
13
# You should have received a copy of the GNU General Public License
 
14
# along with this program; if not, write to the Free Software
 
15
# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
4
16
 
5
17
# \subsection{\emph{rio} - simple text metaformat}
6
 
# 
 
18
#
7
19
# \emph{r} stands for `restricted', `reproducible', or `rfc822-like'.
8
 
# 
 
20
#
9
21
# The stored data consists of a series of \emph{stanzas}, each of which contains
10
22
# \emph{fields} identified by an ascii name, with Unicode or string contents.
11
 
# The field tag is constrained to alphanumeric characters.  
 
23
# The field tag is constrained to alphanumeric characters.
12
24
# There may be more than one field in a stanza with the same name.
13
 
# 
 
25
#
14
26
# The format itself does not deal with character encoding issues, though
15
27
# the result will normally be written in Unicode.
16
 
# 
 
28
#
17
29
# The format is intended to be simple enough that there is exactly one character
18
30
# stream representation of an object and vice versa, and that this relation
19
31
# will continue to hold for future versions of bzr.
20
32
 
21
33
import re
22
34
 
 
35
from bzrlib import osutils
23
36
from bzrlib.iterablefile import IterableFile
24
37
 
25
38
# XXX: some redundancy is allowing to write stanzas in isolation as well as
26
 
# through a writer object.  
 
39
# through a writer object.
27
40
 
28
41
class RioWriter(object):
29
42
    def __init__(self, to_file):
32
45
 
33
46
    def write_stanza(self, stanza):
34
47
        if self._soft_nl:
35
 
            print >>self._to_file
 
48
            self._to_file.write('\n')
36
49
        stanza.write(self._to_file)
37
50
        self._soft_nl = True
38
51
 
39
52
 
40
53
class RioReader(object):
41
54
    """Read stanzas from a file as a sequence
42
 
    
43
 
    to_file can be anything that can be enumerated as a sequence of 
 
55
 
 
56
    to_file can be anything that can be enumerated as a sequence of
44
57
    lines (with newlines.)
45
58
    """
46
59
    def __init__(self, from_file):
81
94
class Stanza(object):
82
95
    """One stanza for rio.
83
96
 
84
 
    Each stanza contains a set of named fields.  
85
 
    
 
97
    Each stanza contains a set of named fields.
 
98
 
86
99
    Names must be non-empty ascii alphanumeric plus _.  Names can be repeated
87
100
    within a stanza.  Names are case-sensitive.  The ordering of fields is
88
101
    preserved.
104
117
 
105
118
    def add(self, tag, value):
106
119
        """Append a name and value to the stanza."""
107
 
        assert valid_tag(tag), \
108
 
            ("invalid tag %r" % tag)
 
120
        if not valid_tag(tag):
 
121
            raise ValueError("invalid tag %r" % (tag,))
109
122
        if isinstance(value, str):
110
123
            value = unicode(value)
111
124
        elif isinstance(value, unicode):
116
129
            raise TypeError("invalid type for rio value: %r of type %s"
117
130
                            % (value, type(value)))
118
131
        self.items.append((tag, value))
119
 
        
 
132
 
 
133
    @classmethod
 
134
    def from_pairs(cls, pairs):
 
135
        ret = cls()
 
136
        ret.items = pairs
 
137
        return ret
 
138
 
120
139
    def __contains__(self, find_tag):
121
140
        """True if there is any field in this stanza with the given tag."""
122
141
        for tag, value in self.items:
145
164
 
146
165
    def to_lines(self):
147
166
        """Generate sequence of lines for external version of this file.
148
 
        
 
167
 
149
168
        The lines are always utf-8 encoded strings.
150
169
        """
151
170
        if not self.items:
153
172
            return []
154
173
        result = []
155
174
        for tag, value in self.items:
156
 
            assert isinstance(tag, str), type(tag)
157
 
            assert isinstance(value, unicode)
158
175
            if value == '':
159
176
                result.append(tag + ': \n')
160
177
            elif '\n' in value:
171
188
        """Return stanza as a single string"""
172
189
        return ''.join(self.to_lines())
173
190
 
 
191
    def to_unicode(self):
 
192
        """Return stanza as a single Unicode string.
 
193
 
 
194
        This is most useful when adding a Stanza to a parent Stanza
 
195
        """
 
196
        if not self.items:
 
197
            return u''
 
198
 
 
199
        result = []
 
200
        for tag, value in self.items:
 
201
            if value == u'':
 
202
                result.append(tag + u': \n')
 
203
            elif u'\n' in value:
 
204
                # don't want splitlines behaviour on empty lines
 
205
                val_lines = value.split(u'\n')
 
206
                result.append(tag + u': ' + val_lines[0] + u'\n')
 
207
                for line in val_lines[1:]:
 
208
                    result.append(u'\t' + line + u'\n')
 
209
            else:
 
210
                result.append(tag + u': ' + value + u'\n')
 
211
        return u''.join(result)
 
212
 
174
213
    def write(self, to_file):
175
214
        """Write stanza to a file"""
176
215
        to_file.writelines(self.to_lines())
201
240
        """
202
241
        d = {}
203
242
        for tag, value in self.items:
204
 
            assert tag not in d
205
243
            d[tag] = value
206
244
        return d
207
 
         
208
 
_tag_re = re.compile(r'^[-a-zA-Z0-9_]+$')
 
245
 
 
246
 
209
247
def valid_tag(tag):
210
 
    return bool(_tag_re.match(tag))
 
248
    return _valid_tag(tag)
211
249
 
212
250
 
213
251
def read_stanza(line_iter):
214
252
    """Return new Stanza read from list of lines or a file
215
 
    
 
253
 
216
254
    Returns one Stanza that was read, or returns None at end of file.  If a
217
255
    blank line follows the stanza, it is consumed.  It's not an error for
218
256
    there to be no blank at end of file.  If there is a blank file at the
219
 
    start of the input this is really an empty stanza and that is returned. 
 
257
    start of the input this is really an empty stanza and that is returned.
220
258
 
221
259
    Only the stanza lines and the trailing blank (if any) are consumed
222
260
    from the line_iter.
223
261
 
224
262
    The raw lines must be in utf-8 encoding.
225
263
    """
226
 
    items = []
227
 
    stanza = Stanza()
228
 
    tag = None
229
 
    accum_value = None
 
264
    return _read_stanza_utf8(line_iter)
 
265
 
 
266
 
 
267
def read_stanza_unicode(unicode_iter):
 
268
    """Read a Stanza from a list of lines or a file.
 
269
 
 
270
    The lines should already be in unicode form. This returns a single
 
271
    stanza that was read. If there is a blank line at the end of the Stanza,
 
272
    it is consumed. It is not an error for there to be no blank line at
 
273
    the end of the iterable. If there is a blank line at the beginning,
 
274
    this is treated as an empty Stanza and None is returned.
 
275
 
 
276
    Only the stanza lines and the trailing blank (if any) are consumed
 
277
    from the unicode_iter
 
278
 
 
279
    :param unicode_iter: A iterable, yeilding Unicode strings. See read_stanza
 
280
        if you have a utf-8 encoded string.
 
281
    :return: A Stanza object if there are any lines in the file.
 
282
        None otherwise
 
283
    """
 
284
    return _read_stanza_unicode(unicode_iter)
 
285
 
 
286
 
 
287
def to_patch_lines(stanza, max_width=72):
 
288
    """Convert a stanza into RIO-Patch format lines.
 
289
 
 
290
    RIO-Patch is a RIO variant designed to be e-mailed as part of a patch.
 
291
    It resists common forms of damage such as newline conversion or the removal
 
292
    of trailing whitespace, yet is also reasonably easy to read.
 
293
 
 
294
    :param max_width: The maximum number of characters per physical line.
 
295
    :return: a list of lines
 
296
    """
 
297
    if max_width <= 6:
 
298
        raise ValueError(max_width)
 
299
    max_rio_width = max_width - 4
 
300
    lines = []
 
301
    for pline in stanza.to_lines():
 
302
        for line in pline.split('\n')[:-1]:
 
303
            line = re.sub('\\\\', '\\\\\\\\', line)
 
304
            while len(line) > 0:
 
305
                partline = line[:max_rio_width]
 
306
                line = line[max_rio_width:]
 
307
                if len(line) > 0 and line[0] != [' ']:
 
308
                    break_index = -1
 
309
                    break_index = partline.rfind(' ', -20)
 
310
                    if break_index < 3:
 
311
                        break_index = partline.rfind('-', -20)
 
312
                        break_index += 1
 
313
                    if break_index < 3:
 
314
                        break_index = partline.rfind('/', -20)
 
315
                    if break_index >= 3:
 
316
                        line = partline[break_index:] + line
 
317
                        partline = partline[:break_index]
 
318
                if len(line) > 0:
 
319
                    line = '  ' + line
 
320
                partline = re.sub('\r', '\\\\r', partline)
 
321
                blank_line = False
 
322
                if len(line) > 0:
 
323
                    partline += '\\'
 
324
                elif re.search(' $', partline):
 
325
                    partline += '\\'
 
326
                    blank_line = True
 
327
                lines.append('# ' + partline + '\n')
 
328
                if blank_line:
 
329
                    lines.append('#   \n')
 
330
    return lines
 
331
 
 
332
 
 
333
def _patch_stanza_iter(line_iter):
 
334
    map = {'\\\\': '\\',
 
335
           '\\r' : '\r',
 
336
           '\\\n': ''}
 
337
    def mapget(match):
 
338
        return map[match.group(0)]
 
339
 
 
340
    last_line = None
230
341
    for line in line_iter:
231
 
        if line == None or line == '':
232
 
            break       # end of file
233
 
        if line == '\n':
234
 
            break       # end of stanza
235
 
        line = line.decode('utf-8')
236
 
        assert line[-1] == '\n'
237
 
        real_l = line
238
 
        if line[0] == '\t': # continues previous value
239
 
            if tag is None:
240
 
                raise ValueError('invalid continuation line %r' % real_l)
241
 
            accum_value += '\n' + line[1:-1]
242
 
        else: # new tag:value line
243
 
            if tag is not None:
244
 
                stanza.add(tag, accum_value)
245
 
            try:
246
 
                colon_index = line.index(': ')
247
 
            except ValueError:
248
 
                raise ValueError('tag/value separator not found in line %r' % real_l)
249
 
            tag = str(line[:colon_index])
250
 
            assert valid_tag(tag), \
251
 
                    "invalid rio tag %r" % tag
252
 
            accum_value = line[colon_index+2:-1]
253
 
    if tag is not None: # add last tag-value
254
 
        stanza.add(tag, accum_value)
255
 
        return stanza
256
 
    else:     # didn't see any content
257
 
        return None    
 
342
        if line.startswith('# '):
 
343
            line = line[2:]
 
344
        elif line.startswith('#'):
 
345
            line = line[1:]
 
346
        else:
 
347
            raise ValueError("bad line %r" % (line,))
 
348
        if last_line is not None and len(line) > 2:
 
349
            line = line[2:]
 
350
        line = re.sub('\r', '', line)
 
351
        line = re.sub('\\\\(.|\n)', mapget, line)
 
352
        if last_line is None:
 
353
            last_line = line
 
354
        else:
 
355
            last_line += line
 
356
        if last_line[-1] == '\n':
 
357
            yield last_line
 
358
            last_line = None
 
359
    if last_line is not None:
 
360
        yield last_line
 
361
 
 
362
 
 
363
def read_patch_stanza(line_iter):
 
364
    """Convert an iterable of RIO-Patch format lines into a Stanza.
 
365
 
 
366
    RIO-Patch is a RIO variant designed to be e-mailed as part of a patch.
 
367
    It resists common forms of damage such as newline conversion or the removal
 
368
    of trailing whitespace, yet is also reasonably easy to read.
 
369
 
 
370
    :return: a Stanza
 
371
    """
 
372
    return read_stanza(_patch_stanza_iter(line_iter))
 
373
 
 
374
 
 
375
try:
 
376
    from bzrlib._rio_pyx import (
 
377
        _read_stanza_utf8,
 
378
        _read_stanza_unicode,
 
379
        _valid_tag,
 
380
        )
 
381
except ImportError, e:
 
382
    osutils.failed_to_load_extension(e)
 
383
    from bzrlib._rio_py import (
 
384
       _read_stanza_utf8,
 
385
       _read_stanza_unicode,
 
386
       _valid_tag,
 
387
       )