← Back to branch summary

~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

Viewing changes to bzrlib/rio.py

  • Committer: Robert Collins
  • Date: 2009-09-07 03:08:30 UTC
  • mto: This revision was merged to the branch mainline in revision 4690.
  • Revision ID: robertc@robertcollins.net-20090907030830-rf59kt28d550eauj
Milestones language tightning, internal consistency.

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.iterablefile import IterableFile
 
36
 
23
37
# XXX: some redundancy is allowing to write stanzas in isolation as well as
24
 
# through a writer object.  
 
38
# through a writer object.
25
39
 
26
40
class RioWriter(object):
27
41
    def __init__(self, to_file):
30
44
 
31
45
    def write_stanza(self, stanza):
32
46
        if self._soft_nl:
33
 
            print >>self._to_file
 
47
            self._to_file.write('\n')
34
48
        stanza.write(self._to_file)
35
49
        self._soft_nl = True
36
50
 
37
51
 
38
52
class RioReader(object):
39
53
    """Read stanzas from a file as a sequence
40
 
    
41
 
    to_file can be anything that can be enumerated as a sequence of 
 
54
 
 
55
    to_file can be anything that can be enumerated as a sequence of
42
56
    lines (with newlines.)
43
57
    """
44
58
    def __init__(self, from_file):
52
66
            else:
53
67
                yield s
54
68
 
 
69
 
 
70
def rio_file(stanzas, header=None):
 
71
    """Produce a rio IterableFile from an iterable of stanzas"""
 
72
    def str_iter():
 
73
        if header is not None:
 
74
            yield header + '\n'
 
75
        first_stanza = True
 
76
        for s in stanzas:
 
77
            if first_stanza is not True:
 
78
                yield '\n'
 
79
            for line in s.to_lines():
 
80
                yield line
 
81
            first_stanza = False
 
82
    return IterableFile(str_iter())
 
83
 
 
84
 
55
85
def read_stanzas(from_file):
56
86
    while True:
57
87
        s = read_stanza(from_file)
63
93
class Stanza(object):
64
94
    """One stanza for rio.
65
95
 
66
 
    Each stanza contains a set of named fields.  
67
 
    
 
96
    Each stanza contains a set of named fields.
 
97
 
68
98
    Names must be non-empty ascii alphanumeric plus _.  Names can be repeated
69
99
    within a stanza.  Names are case-sensitive.  The ordering of fields is
70
100
    preserved.
86
116
 
87
117
    def add(self, tag, value):
88
118
        """Append a name and value to the stanza."""
89
 
        assert valid_tag(tag), \
90
 
            ("invalid tag %r" % tag)
 
119
        if not valid_tag(tag):
 
120
            raise ValueError("invalid tag %r" % (tag,))
91
121
        if isinstance(value, str):
92
122
            value = unicode(value)
93
123
        elif isinstance(value, unicode):
98
128
            raise TypeError("invalid type for rio value: %r of type %s"
99
129
                            % (value, type(value)))
100
130
        self.items.append((tag, value))
101
 
        
 
131
 
 
132
    @classmethod
 
133
    def from_pairs(cls, pairs):
 
134
        ret = cls()
 
135
        ret.items = pairs
 
136
        return ret
 
137
 
102
138
    def __contains__(self, find_tag):
103
139
        """True if there is any field in this stanza with the given tag."""
104
140
        for tag, value in self.items:
127
163
 
128
164
    def to_lines(self):
129
165
        """Generate sequence of lines for external version of this file.
130
 
        
 
166
 
131
167
        The lines are always utf-8 encoded strings.
132
168
        """
133
169
        if not self.items:
135
171
            return []
136
172
        result = []
137
173
        for tag, value in self.items:
138
 
            assert isinstance(tag, str)
139
 
            assert isinstance(value, unicode)
140
174
            if value == '':
141
175
                result.append(tag + ': \n')
142
176
            elif '\n' in value:
153
187
        """Return stanza as a single string"""
154
188
        return ''.join(self.to_lines())
155
189
 
 
190
    def to_unicode(self):
 
191
        """Return stanza as a single Unicode string.
 
192
 
 
193
        This is most useful when adding a Stanza to a parent Stanza
 
194
        """
 
195
        if not self.items:
 
196
            return u''
 
197
 
 
198
        result = []
 
199
        for tag, value in self.items:
 
200
            if value == u'':
 
201
                result.append(tag + u': \n')
 
202
            elif u'\n' in value:
 
203
                # don't want splitlines behaviour on empty lines
 
204
                val_lines = value.split(u'\n')
 
205
                result.append(tag + u': ' + val_lines[0] + u'\n')
 
206
                for line in val_lines[1:]:
 
207
                    result.append(u'\t' + line + u'\n')
 
208
            else:
 
209
                result.append(tag + u': ' + value + u'\n')
 
210
        return u''.join(result)
 
211
 
156
212
    def write(self, to_file):
157
213
        """Write stanza to a file"""
158
214
        to_file.writelines(self.to_lines())
183
239
        """
184
240
        d = {}
185
241
        for tag, value in self.items:
186
 
            assert tag not in d
187
242
            d[tag] = value
188
243
        return d
189
 
         
190
 
_tag_re = re.compile(r'^[-a-zA-Z0-9_]+$')
 
244
 
 
245
 
191
246
def valid_tag(tag):
192
 
    return bool(_tag_re.match(tag))
 
247
    return _valid_tag(tag)
193
248
 
194
249
 
195
250
def read_stanza(line_iter):
196
251
    """Return new Stanza read from list of lines or a file
197
 
    
 
252
 
198
253
    Returns one Stanza that was read, or returns None at end of file.  If a
199
254
    blank line follows the stanza, it is consumed.  It's not an error for
200
255
    there to be no blank at end of file.  If there is a blank file at the
201
 
    start of the input this is really an empty stanza and that is returned. 
 
256
    start of the input this is really an empty stanza and that is returned.
202
257
 
203
258
    Only the stanza lines and the trailing blank (if any) are consumed
204
259
    from the line_iter.
205
260
 
206
261
    The raw lines must be in utf-8 encoding.
207
262
    """
208
 
    items = []
209
 
    stanza = Stanza()
210
 
    tag = None
211
 
    accum_value = None
 
263
    return _read_stanza_utf8(line_iter)
 
264
 
 
265
 
 
266
def read_stanza_unicode(unicode_iter):
 
267
    """Read a Stanza from a list of lines or a file.
 
268
 
 
269
    The lines should already be in unicode form. This returns a single
 
270
    stanza that was read. If there is a blank line at the end of the Stanza,
 
271
    it is consumed. It is not an error for there to be no blank line at
 
272
    the end of the iterable. If there is a blank line at the beginning,
 
273
    this is treated as an empty Stanza and None is returned.
 
274
 
 
275
    Only the stanza lines and the trailing blank (if any) are consumed
 
276
    from the unicode_iter
 
277
 
 
278
    :param unicode_iter: A iterable, yeilding Unicode strings. See read_stanza
 
279
        if you have a utf-8 encoded string.
 
280
    :return: A Stanza object if there are any lines in the file.
 
281
        None otherwise
 
282
    """
 
283
    return _read_stanza_unicode(unicode_iter)
 
284
 
 
285
 
 
286
def to_patch_lines(stanza, max_width=72):
 
287
    """Convert a stanza into RIO-Patch format lines.
 
288
 
 
289
    RIO-Patch is a RIO variant designed to be e-mailed as part of a patch.
 
290
    It resists common forms of damage such as newline conversion or the removal
 
291
    of trailing whitespace, yet is also reasonably easy to read.
 
292
 
 
293
    :param max_width: The maximum number of characters per physical line.
 
294
    :return: a list of lines
 
295
    """
 
296
    if max_width <= 6:
 
297
        raise ValueError(max_width)
 
298
    max_rio_width = max_width - 4
 
299
    lines = []
 
300
    for pline in stanza.to_lines():
 
301
        for line in pline.split('\n')[:-1]:
 
302
            line = re.sub('\\\\', '\\\\\\\\', line)
 
303
            while len(line) > 0:
 
304
                partline = line[:max_rio_width]
 
305
                line = line[max_rio_width:]
 
306
                if len(line) > 0 and line[0] != [' ']:
 
307
                    break_index = -1
 
308
                    break_index = partline.rfind(' ', -20)
 
309
                    if break_index < 3:
 
310
                        break_index = partline.rfind('-', -20)
 
311
                        break_index += 1
 
312
                    if break_index < 3:
 
313
                        break_index = partline.rfind('/', -20)
 
314
                    if break_index >= 3:
 
315
                        line = partline[break_index:] + line
 
316
                        partline = partline[:break_index]
 
317
                if len(line) > 0:
 
318
                    line = '  ' + line
 
319
                partline = re.sub('\r', '\\\\r', partline)
 
320
                blank_line = False
 
321
                if len(line) > 0:
 
322
                    partline += '\\'
 
323
                elif re.search(' $', partline):
 
324
                    partline += '\\'
 
325
                    blank_line = True
 
326
                lines.append('# ' + partline + '\n')
 
327
                if blank_line:
 
328
                    lines.append('#   \n')
 
329
    return lines
 
330
 
 
331
 
 
332
def _patch_stanza_iter(line_iter):
 
333
    map = {'\\\\': '\\',
 
334
           '\\r' : '\r',
 
335
           '\\\n': ''}
 
336
    def mapget(match):
 
337
        return map[match.group(0)]
 
338
 
 
339
    last_line = None
212
340
    for line in line_iter:
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    
 
341
        if line.startswith('# '):
 
342
            line = line[2:]
 
343
        elif line.startswith('#'):
 
344
            line = line[1:]
 
345
        else:
 
346
            raise ValueError("bad line %r" % (line,))
 
347
        if last_line is not None and len(line) > 2:
 
348
            line = line[2:]
 
349
        line = re.sub('\r', '', line)
 
350
        line = re.sub('\\\\(.|\n)', mapget, line)
 
351
        if last_line is None:
 
352
            last_line = line
 
353
        else:
 
354
            last_line += line
 
355
        if last_line[-1] == '\n':
 
356
            yield last_line
 
357
            last_line = None
 
358
    if last_line is not None:
 
359
        yield last_line
 
360
 
 
361
 
 
362
def read_patch_stanza(line_iter):
 
363
    """Convert an iterable of RIO-Patch format lines into a Stanza.
 
364
 
 
365
    RIO-Patch is a RIO variant designed to be e-mailed as part of a patch.
 
366
    It resists common forms of damage such as newline conversion or the removal
 
367
    of trailing whitespace, yet is also reasonably easy to read.
 
368
 
 
369
    :return: a Stanza
 
370
    """
 
371
    return read_stanza(_patch_stanza_iter(line_iter))
 
372
 
 
373
 
 
374
try:
 
375
    from bzrlib._rio_pyx import (
 
376
        _read_stanza_utf8,
 
377
        _read_stanza_unicode,
 
378
        _valid_tag,
 
379
        )
 
380
except ImportError:
 
381
    from bzrlib._rio_py import (
 
382
       _read_stanza_utf8,
 
383
       _read_stanza_unicode,
 
384
       _valid_tag,
 
385
       )