1
# Copyright (C) 2005 by Canonical Ltd
3
# Distributed under the GNU General Public Licence v2
5
# \subsection{\emph{rio} - simple text metaformat}
7
# \emph{r} stands for `restricted', `reproducible', or `rfc822-like'.
9
# The stored data consists of a series of \emph{stanzas}, each of which contains
10
# \emph{fields} identified by an ascii name, with Unicode or string contents.
11
# The field tag is constrained to alphanumeric characters.
12
# There may be more than one field in a stanza with the same name.
14
# The format itself does not deal with character encoding issues, though
15
# the result will normally be written in Unicode.
17
# The format is intended to be simple enough that there is exactly one character
18
# stream representation of an object and vice versa, and that this relation
19
# will continue to hold for future versions of bzr.
23
from bzrlib.iterablefile import IterableFile
25
# XXX: some redundancy is allowing to write stanzas in isolation as well as
26
# through a writer object.
28
class RioWriter(object):
29
def __init__(self, to_file):
31
self._to_file = to_file
33
def write_stanza(self, stanza):
36
stanza.write(self._to_file)
40
class RioReader(object):
41
"""Read stanzas from a file as a sequence
43
to_file can be anything that can be enumerated as a sequence of
44
lines (with newlines.)
46
def __init__(self, from_file):
47
self._from_file = from_file
51
s = read_stanza(self._from_file)
58
def rio_file(stanzas, header=None):
59
"""Produce a rio IterableFile from an iterable of stanzas"""
61
if header is not None:
65
if first_stanza is not True:
67
for line in s.to_lines():
70
return IterableFile(str_iter())
73
def read_stanzas(from_file):
75
s = read_stanza(from_file)
82
"""One stanza for rio.
84
Each stanza contains a set of named fields.
86
Names must be non-empty ascii alphanumeric plus _. Names can be repeated
87
within a stanza. Names are case-sensitive. The ordering of fields is
90
Each field value must be either an int or a string.
95
def __init__(self, **kwargs):
96
"""Construct a new Stanza.
98
The keyword arguments, if any, are added in sorted order to the stanza.
102
for tag, value in sorted(kwargs.items()):
105
def add(self, tag, value):
106
"""Append a name and value to the stanza."""
107
assert valid_tag(tag), \
108
("invalid tag %r" % tag)
109
if isinstance(value, str):
110
value = unicode(value)
111
elif isinstance(value, unicode):
113
## elif isinstance(value, (int, long)):
114
## value = str(value) # XXX: python2.4 without L-suffix
116
raise TypeError("invalid type for rio value: %r of type %s"
117
% (value, type(value)))
118
self.items.append((tag, value))
120
def __contains__(self, find_tag):
121
"""True if there is any field in this stanza with the given tag."""
122
for tag, value in self.items:
128
"""Return number of pairs in the stanza."""
129
return len(self.items)
131
def __eq__(self, other):
132
if not isinstance(other, Stanza):
134
return self.items == other.items
136
def __ne__(self, other):
137
return not self.__eq__(other)
140
return "Stanza(%r)" % self.items
142
def iter_pairs(self):
143
"""Return iterator of tag, value pairs."""
144
return iter(self.items)
147
"""Generate sequence of lines for external version of this file.
149
The lines are always utf-8 encoded strings.
152
# max() complains if sequence is empty
155
for tag, value in self.items:
156
assert isinstance(tag, str), type(tag)
157
assert isinstance(value, unicode)
159
result.append(tag + ': \n')
161
# don't want splitlines behaviour on empty lines
162
val_lines = value.split('\n')
163
result.append(tag + ': ' + val_lines[0].encode('utf-8') + '\n')
164
for line in val_lines[1:]:
165
result.append('\t' + line.encode('utf-8') + '\n')
167
result.append(tag + ': ' + value.encode('utf-8') + '\n')
171
"""Return stanza as a single string"""
172
return ''.join(self.to_lines())
174
def to_unicode(self):
175
"""Return stanza as a single Unicode string.
177
This is most useful when adding a Stanza to a parent Stanza
183
for tag, value in self.items:
185
result.append(tag + ': \n')
187
# don't want splitlines behaviour on empty lines
188
val_lines = value.split('\n')
189
result.append(tag + ': ' + val_lines[0] + '\n')
190
for line in val_lines[1:]:
191
result.append('\t' + line + '\n')
193
result.append(tag + ': ' + value + '\n')
194
return u''.join(result)
196
def write(self, to_file):
197
"""Write stanza to a file"""
198
to_file.writelines(self.to_lines())
201
"""Return the value for a field wih given tag.
203
If there is more than one value, only the first is returned. If the
204
tag is not present, KeyError is raised.
206
for t, v in self.items:
214
def get_all(self, tag):
216
for t, v in self.items:
222
"""Return a dict containing the unique values of the stanza.
225
for tag, value in self.items:
230
_tag_re = re.compile(r'^[-a-zA-Z0-9_]+$')
232
return bool(_tag_re.match(tag))
235
def read_stanza(line_iter):
236
"""Return new Stanza read from list of lines or a file
238
Returns one Stanza that was read, or returns None at end of file. If a
239
blank line follows the stanza, it is consumed. It's not an error for
240
there to be no blank at end of file. If there is a blank file at the
241
start of the input this is really an empty stanza and that is returned.
243
Only the stanza lines and the trailing blank (if any) are consumed
246
The raw lines must be in utf-8 encoding.
248
unicode_iter = (line.decode('utf-8') for line in line_iter)
249
return read_stanza_unicode(unicode_iter)
252
def read_stanza_unicode(unicode_iter):
253
"""Read a Stanza from a list of lines or a file.
255
The lines should already be in unicode form. This returns a single
256
stanza that was read. If there is a blank line at the end of the Stanza,
257
it is consumed. It is not an error for there to be no blank line at
258
the end of the iterable. If there is a blank line at the beginning,
259
this is treated as an empty Stanza and None is returned.
261
Only the stanza lines and the trailing blank (if any) are consumed
262
from the unicode_iter
264
:param unicode_iter: A iterable, yeilding Unicode strings. See read_stanza
265
if you have a utf-8 encoded string.
266
:return: A Stanza object if there are any lines in the file.
273
# TODO: jam 20060922 This code should raise real errors rather than
274
# using 'assert' to process user input, or raising ValueError
275
# rather than a more specific error.
277
for line in unicode_iter:
278
if line is None or line == '':
281
break # end of stanza
282
assert line.endswith('\n')
284
if line[0] == '\t': # continues previous value
286
raise ValueError('invalid continuation line %r' % real_l)
287
accum_value += '\n' + line[1:-1]
288
else: # new tag:value line
290
stanza.add(tag, accum_value)
292
colon_index = line.index(': ')
294
raise ValueError('tag/value separator not found in line %r'
296
tag = str(line[:colon_index])
297
assert valid_tag(tag), \
298
"invalid rio tag %r" % tag
299
accum_value = line[colon_index+2:-1]
301
if tag is not None: # add last tag-value
302
stanza.add(tag, accum_value)
304
else: # didn't see any content
added
removed
bzrlib/rio.py
