← Back to branch summary

~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

Viewing changes to bzrlib/rio.py

Latest bzr.dev

Show diffs side-by-side

added added

removed removed

Lines of Context:
bzrlib/rio.py
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
 
1
# Copyright (C) 2005 by Canonical Ltd
 
2
#
 
3
# Distributed under the GNU General Public Licence v2
16
4
 
17
5
# \subsection{\emph{rio} - simple text metaformat}
18
 
#
 
6
# 
19
7
# \emph{r} stands for `restricted', `reproducible', or `rfc822-like'.
20
 
#
 
8
# 
21
9
# The stored data consists of a series of \emph{stanzas}, each of which contains
22
10
# \emph{fields} identified by an ascii name, with Unicode or string contents.
23
 
# The field tag is constrained to alphanumeric characters.
 
11
# The field tag is constrained to alphanumeric characters.  
24
12
# There may be more than one field in a stanza with the same name.
25
 
#
 
13
# 
26
14
# The format itself does not deal with character encoding issues, though
27
15
# the result will normally be written in Unicode.
28
 
#
 
16
# 
29
17
# The format is intended to be simple enough that there is exactly one character
30
18
# stream representation of an object and vice versa, and that this relation
31
19
# will continue to hold for future versions of bzr.
32
20
 
33
21
import re
34
22
 
35
 
from bzrlib import osutils
36
 
from bzrlib.iterablefile import IterableFile
37
 
 
38
23
# XXX: some redundancy is allowing to write stanzas in isolation as well as
39
 
# through a writer object.
 
24
# through a writer object.  
40
25
 
41
26
class RioWriter(object):
42
27
    def __init__(self, to_file):
45
30
 
46
31
    def write_stanza(self, stanza):
47
32
        if self._soft_nl:
48
 
            self._to_file.write('\n')
 
33
            print >>self._to_file
49
34
        stanza.write(self._to_file)
50
35
        self._soft_nl = True
51
36
 
52
37
 
53
38
class RioReader(object):
54
39
    """Read stanzas from a file as a sequence
55
 
 
56
 
    to_file can be anything that can be enumerated as a sequence of
 
40
    
 
41
    to_file can be anything that can be enumerated as a sequence of 
57
42
    lines (with newlines.)
58
43
    """
59
44
    def __init__(self, from_file):
67
52
            else:
68
53
                yield s
69
54
 
70
 
 
71
 
def rio_file(stanzas, header=None):
72
 
    """Produce a rio IterableFile from an iterable of stanzas"""
73
 
    def str_iter():
74
 
        if header is not None:
75
 
            yield header + '\n'
76
 
        first_stanza = True
77
 
        for s in stanzas:
78
 
            if first_stanza is not True:
79
 
                yield '\n'
80
 
            for line in s.to_lines():
81
 
                yield line
82
 
            first_stanza = False
83
 
    return IterableFile(str_iter())
84
 
 
85
 
 
86
55
def read_stanzas(from_file):
87
56
    while True:
88
57
        s = read_stanza(from_file)
94
63
class Stanza(object):
95
64
    """One stanza for rio.
96
65
 
97
 
    Each stanza contains a set of named fields.
98
 
 
 
66
    Each stanza contains a set of named fields.  
 
67
    
99
68
    Names must be non-empty ascii alphanumeric plus _.  Names can be repeated
100
69
    within a stanza.  Names are case-sensitive.  The ordering of fields is
101
70
    preserved.
117
86
 
118
87
    def add(self, tag, value):
119
88
        """Append a name and value to the stanza."""
120
 
        if not valid_tag(tag):
121
 
            raise ValueError("invalid tag %r" % (tag,))
 
89
        assert valid_tag(tag), \
 
90
            ("invalid tag %r" % tag)
122
91
        if isinstance(value, str):
123
92
            value = unicode(value)
124
93
        elif isinstance(value, unicode):
129
98
            raise TypeError("invalid type for rio value: %r of type %s"
130
99
                            % (value, type(value)))
131
100
        self.items.append((tag, value))
132
 
 
133
 
    @classmethod
134
 
    def from_pairs(cls, pairs):
135
 
        ret = cls()
136
 
        ret.items = pairs
137
 
        return ret
138
 
 
 
101
        
139
102
    def __contains__(self, find_tag):
140
103
        """True if there is any field in this stanza with the given tag."""
141
104
        for tag, value in self.items:
164
127
 
165
128
    def to_lines(self):
166
129
        """Generate sequence of lines for external version of this file.
167
 
 
 
130
        
168
131
        The lines are always utf-8 encoded strings.
169
132
        """
170
133
        if not self.items:
172
135
            return []
173
136
        result = []
174
137
        for tag, value in self.items:
 
138
            assert isinstance(tag, str)
 
139
            assert isinstance(value, unicode)
175
140
            if value == '':
176
141
                result.append(tag + ': \n')
177
142
            elif '\n' in value:
188
153
        """Return stanza as a single string"""
189
154
        return ''.join(self.to_lines())
190
155
 
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
 
 
213
156
    def write(self, to_file):
214
157
        """Write stanza to a file"""
215
158
        to_file.writelines(self.to_lines())
240
183
        """
241
184
        d = {}
242
185
        for tag, value in self.items:
 
186
            assert tag not in d
243
187
            d[tag] = value
244
188
        return d
245
 
 
246
 
 
 
189
         
 
190
_tag_re = re.compile(r'^[-a-zA-Z0-9_]+$')
247
191
def valid_tag(tag):
248
 
    return _valid_tag(tag)
 
192
    return bool(_tag_re.match(tag))
249
193
 
250
194
 
251
195
def read_stanza(line_iter):
252
196
    """Return new Stanza read from list of lines or a file
253
 
 
 
197
    
254
198
    Returns one Stanza that was read, or returns None at end of file.  If a
255
199
    blank line follows the stanza, it is consumed.  It's not an error for
256
200
    there to be no blank at end of file.  If there is a blank file at the
257
 
    start of the input this is really an empty stanza and that is returned.
 
201
    start of the input this is really an empty stanza and that is returned. 
258
202
 
259
203
    Only the stanza lines and the trailing blank (if any) are consumed
260
204
    from the line_iter.
261
205
 
262
206
    The raw lines must be in utf-8 encoding.
263
207
    """
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
 
208
    items = []
 
209
    stanza = Stanza()
 
210
    tag = None
 
211
    accum_value = None
341
212
    for line in line_iter:
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
 
       )
 
213
        if line == None or line == '':
 
214
            break       # end of file
 
215
        if line == '\n':
 
216
            break       # end of stanza
 
217
        line = line.decode('utf-8')
 
218
        assert line[-1] == '\n'
 
219
        real_l = line
 
220
        if line[0] == '\t': # continues previous value
 
221
            if tag is None:
 
222
                raise ValueError('invalid continuation line %r' % real_l)
 
223
            accum_value += '\n' + line[1:-1]
 
224
        else: # new tag:value line
 
225
            if tag is not None:
 
226
                stanza.add(tag, accum_value)
 
227
            try:
 
228
                colon_index = line.index(': ')
 
229
            except ValueError:
 
230
                raise ValueError('tag/value separator not found in line %r' % real_l)
 
231
            tag = line[:colon_index]
 
232
            assert valid_tag(tag), \
 
233
                    "invalid rio tag %r" % tag
 
234
            accum_value = line[colon_index+2:-1]
 
235
    if tag is not None: # add last tag-value
 
236
        stanza.add(tag, accum_value)
 
237
        return stanza
 
238
    else:     # didn't see any content
 
239
        return None