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
# XXX: some redundancy is allowing to write stanzas in isolation as well as
24
# through a writer object.
26
class RioWriter(object):
27
def __init__(self, to_file):
29
self._to_file = to_file
31
def write_stanza(self, stanza):
34
stanza.write(self._to_file)
38
class RioReader(object):
39
"""Read stanzas from a file as a sequence
41
to_file can be anything that can be enumerated as a sequence of
42
lines (with newlines.)
44
def __init__(self, from_file):
45
self._from_file = from_file
49
s = read_stanza(self._from_file)
55
def read_stanzas(from_file):
57
s = read_stanza(from_file)
64
"""One stanza for rio.
66
Each stanza contains a set of named fields.
68
Names must be non-empty ascii alphanumeric plus _. Names can be repeated
69
within a stanza. Names are case-sensitive. The ordering of fields is
72
Each field value must be either an int or a string.
77
def __init__(self, **kwargs):
78
"""Construct a new Stanza.
80
The keyword arguments, if any, are added in sorted order to the stanza.
84
for tag, value in sorted(kwargs.items()):
87
def add(self, tag, value):
88
"""Append a name and value to the stanza."""
89
assert valid_tag(tag), \
90
("invalid tag %r" % tag)
91
if isinstance(value, str):
92
value = unicode(value)
93
elif isinstance(value, unicode):
95
## elif isinstance(value, (int, long)):
96
## value = str(value) # XXX: python2.4 without L-suffix
98
raise TypeError("invalid type for rio value: %r of type %s"
99
% (value, type(value)))
100
self.items.append((tag, value))
102
def __contains__(self, find_tag):
103
"""True if there is any field in this stanza with the given tag."""
104
for tag, value in self.items:
110
"""Return number of pairs in the stanza."""
111
return len(self.items)
113
def __eq__(self, other):
114
if not isinstance(other, Stanza):
116
return self.items == other.items
118
def __ne__(self, other):
119
return not self.__eq__(other)
122
return "Stanza(%r)" % self.items
124
def iter_pairs(self):
125
"""Return iterator of tag, value pairs."""
126
return iter(self.items)
129
"""Generate sequence of lines for external version of this file.
131
The lines are always utf-8 encoded strings.
134
# max() complains if sequence is empty
137
for tag, value in self.items:
138
assert isinstance(tag, str)
139
assert isinstance(value, unicode)
141
result.append(tag + ': \n')
143
# don't want splitlines behaviour on empty lines
144
val_lines = value.split('\n')
145
result.append(tag + ': ' + val_lines[0].encode('utf-8') + '\n')
146
for line in val_lines[1:]:
147
result.append('\t' + line.encode('utf-8') + '\n')
149
result.append(tag + ': ' + value.encode('utf-8') + '\n')
153
"""Return stanza as a single string"""
154
return ''.join(self.to_lines())
156
def write(self, to_file):
157
"""Write stanza to a file"""
158
to_file.writelines(self.to_lines())
161
"""Return the value for a field wih given tag.
163
If there is more than one value, only the first is returned. If the
164
tag is not present, KeyError is raised.
166
for t, v in self.items:
174
def get_all(self, tag):
176
for t, v in self.items:
182
"""Return a dict containing the unique values of the stanza.
185
for tag, value in self.items:
190
_tag_re = re.compile(r'^[-a-zA-Z0-9_]+$')
192
return bool(_tag_re.match(tag))
195
def read_stanza(line_iter):
196
"""Return new Stanza read from list of lines or a file
198
Returns one Stanza that was read, or returns None at end of file. If a
199
blank line follows the stanza, it is consumed. It's not an error for
200
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.
203
Only the stanza lines and the trailing blank (if any) are consumed
206
The raw lines must be in utf-8 encoding.
212
for line in line_iter:
213
if line == None or line == '':
216
break # end of stanza
217
line = line.decode('utf-8')
218
assert line[-1] == '\n'
220
if line[0] == '\t': # continues previous value
222
raise ValueError('invalid continuation line %r' % real_l)
223
accum_value += '\n' + line[1:-1]
224
else: # new tag:value line
226
stanza.add(tag, accum_value)
228
colon_index = line.index(': ')
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)
238
else: # didn't see any content
added
removed
bzrlib/rio.py
