1
# Copyright (C) 2005 Canonical Ltd
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.
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.
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
17
# \subsection{\emph{rio} - simple text metaformat}
19
# \emph{r} stands for `restricted', `reproducible', or `rfc822-like'.
21
# The stored data consists of a series of \emph{stanzas}, each of which contains
22
# \emph{fields} identified by an ascii name, with Unicode or string contents.
23
# The field tag is constrained to alphanumeric characters.
24
# There may be more than one field in a stanza with the same name.
26
# The format itself does not deal with character encoding issues, though
27
# the result will normally be written in Unicode.
29
# The format is intended to be simple enough that there is exactly one character
30
# stream representation of an object and vice versa, and that this relation
31
# will continue to hold for future versions of bzr.
35
from bzrlib import osutils
36
from bzrlib.iterablefile import IterableFile
38
# XXX: some redundancy is allowing to write stanzas in isolation as well as
39
# through a writer object.
41
class RioWriter(object):
42
def __init__(self, to_file):
44
self._to_file = to_file
46
def write_stanza(self, stanza):
48
self._to_file.write('\n')
49
stanza.write(self._to_file)
53
class RioReader(object):
54
"""Read stanzas from a file as a sequence
56
to_file can be anything that can be enumerated as a sequence of
57
lines (with newlines.)
59
def __init__(self, from_file):
60
self._from_file = from_file
64
s = read_stanza(self._from_file)
71
def rio_file(stanzas, header=None):
72
"""Produce a rio IterableFile from an iterable of stanzas"""
74
if header is not None:
78
if first_stanza is not True:
80
for line in s.to_lines():
83
return IterableFile(str_iter())
86
def read_stanzas(from_file):
88
s = read_stanza(from_file)
95
"""One stanza for rio.
97
Each stanza contains a set of named fields.
99
Names must be non-empty ascii alphanumeric plus _. Names can be repeated
100
within a stanza. Names are case-sensitive. The ordering of fields is
103
Each field value must be either an int or a string.
106
__slots__ = ['items']
108
def __init__(self, **kwargs):
109
"""Construct a new Stanza.
111
The keyword arguments, if any, are added in sorted order to the stanza.
115
for tag, value in sorted(kwargs.items()):
118
def add(self, tag, value):
119
"""Append a name and value to the stanza."""
120
if not valid_tag(tag):
121
raise ValueError("invalid tag %r" % (tag,))
122
if isinstance(value, str):
123
value = unicode(value)
124
elif isinstance(value, unicode):
126
## elif isinstance(value, (int, long)):
127
## value = str(value) # XXX: python2.4 without L-suffix
129
raise TypeError("invalid type for rio value: %r of type %s"
130
% (value, type(value)))
131
self.items.append((tag, value))
134
def from_pairs(cls, pairs):
139
def __contains__(self, find_tag):
140
"""True if there is any field in this stanza with the given tag."""
141
for tag, value in self.items:
147
"""Return number of pairs in the stanza."""
148
return len(self.items)
150
def __eq__(self, other):
151
if not isinstance(other, Stanza):
153
return self.items == other.items
155
def __ne__(self, other):
156
return not self.__eq__(other)
159
return "Stanza(%r)" % self.items
161
def iter_pairs(self):
162
"""Return iterator of tag, value pairs."""
163
return iter(self.items)
166
"""Generate sequence of lines for external version of this file.
168
The lines are always utf-8 encoded strings.
171
# max() complains if sequence is empty
174
for tag, value in self.items:
176
result.append(tag + ': \n')
178
# don't want splitlines behaviour on empty lines
179
val_lines = value.split('\n')
180
result.append(tag + ': ' + val_lines[0].encode('utf-8') + '\n')
181
for line in val_lines[1:]:
182
result.append('\t' + line.encode('utf-8') + '\n')
184
result.append(tag + ': ' + value.encode('utf-8') + '\n')
188
"""Return stanza as a single string"""
189
return ''.join(self.to_lines())
191
def to_unicode(self):
192
"""Return stanza as a single Unicode string.
194
This is most useful when adding a Stanza to a parent Stanza
200
for tag, value in self.items:
202
result.append(tag + u': \n')
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')
210
result.append(tag + u': ' + value + u'\n')
211
return u''.join(result)
213
def write(self, to_file):
214
"""Write stanza to a file"""
215
to_file.writelines(self.to_lines())
218
"""Return the value for a field wih given tag.
220
If there is more than one value, only the first is returned. If the
221
tag is not present, KeyError is raised.
223
for t, v in self.items:
231
def get_all(self, tag):
233
for t, v in self.items:
239
"""Return a dict containing the unique values of the stanza.
242
for tag, value in self.items:
248
return _valid_tag(tag)
251
def read_stanza(line_iter):
252
"""Return new Stanza read from list of lines or a file
254
Returns one Stanza that was read, or returns None at end of file. If a
255
blank line follows the stanza, it is consumed. It's not an error for
256
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.
259
Only the stanza lines and the trailing blank (if any) are consumed
262
The raw lines must be in utf-8 encoding.
264
return _read_stanza_utf8(line_iter)
267
def read_stanza_unicode(unicode_iter):
268
"""Read a Stanza from a list of lines or a file.
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.
276
Only the stanza lines and the trailing blank (if any) are consumed
277
from the unicode_iter
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.
284
return _read_stanza_unicode(unicode_iter)
287
def to_patch_lines(stanza, max_width=72):
288
"""Convert a stanza into RIO-Patch format lines.
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.
294
:param max_width: The maximum number of characters per physical line.
295
:return: a list of lines
298
raise ValueError(max_width)
299
max_rio_width = max_width - 4
301
for pline in stanza.to_lines():
302
for line in pline.split('\n')[:-1]:
303
line = re.sub('\\\\', '\\\\\\\\', line)
305
partline = line[:max_rio_width]
306
line = line[max_rio_width:]
307
if len(line) > 0 and line[0] != [' ']:
309
break_index = partline.rfind(' ', -20)
311
break_index = partline.rfind('-', -20)
314
break_index = partline.rfind('/', -20)
316
line = partline[break_index:] + line
317
partline = partline[:break_index]
320
partline = re.sub('\r', '\\\\r', partline)
324
elif re.search(' $', partline):
327
lines.append('# ' + partline + '\n')
333
def _patch_stanza_iter(line_iter):
338
return map[match.group(0)]
341
for line in line_iter:
342
if line.startswith('# '):
344
elif line.startswith('#'):
347
raise ValueError("bad line %r" % (line,))
348
if last_line is not None and len(line) > 2:
350
line = re.sub('\r', '', line)
351
line = re.sub('\\\\(.|\n)', mapget, line)
352
if last_line is None:
356
if last_line[-1] == '\n':
359
if last_line is not None:
363
def read_patch_stanza(line_iter):
364
"""Convert an iterable of RIO-Patch format lines into a Stanza.
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.
372
return read_stanza(_patch_stanza_iter(line_iter))
376
from bzrlib._rio_pyx import (
378
_read_stanza_unicode,
381
except ImportError, e:
382
osutils.failed_to_load_extension(e)
383
from bzrlib._rio_py import (
385
_read_stanza_unicode,
added
removed
bzrlib/rio.py
