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 write(self, to_file):
175
"""Write stanza to a file"""
176
to_file.writelines(self.to_lines())
179
"""Return the value for a field wih given tag.
181
If there is more than one value, only the first is returned. If the
182
tag is not present, KeyError is raised.
184
for t, v in self.items:
192
def get_all(self, tag):
194
for t, v in self.items:
200
"""Return a dict containing the unique values of the stanza.
203
for tag, value in self.items:
208
_tag_re = re.compile(r'^[-a-zA-Z0-9_]+$')
210
return bool(_tag_re.match(tag))
213
def read_stanza(line_iter):
214
"""Return new Stanza read from list of lines or a file
216
Returns one Stanza that was read, or returns None at end of file. If a
217
blank line follows the stanza, it is consumed. It's not an error for
218
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.
221
Only the stanza lines and the trailing blank (if any) are consumed
224
The raw lines must be in utf-8 encoding.
230
for line in line_iter:
231
if line == None or line == '':
234
break # end of stanza
235
line = line.decode('utf-8')
236
assert line[-1] == '\n'
238
if line[0] == '\t': # continues previous value
240
raise ValueError('invalid continuation line %r' % real_l)
241
accum_value += '\n' + line[1:-1]
242
else: # new tag:value line
244
stanza.add(tag, accum_value)
246
colon_index = line.index(': ')
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)
256
else: # didn't see any content
added
removed
bzrlib/rio.py
