← Back to branch summary

~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

Viewing changes to bzrlib/rio.py

merge with bzr.dev revno.1860

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
 
4
 
 
5
# \subsection{\emph{rio} - simple text metaformat}
 
6
# 
 
7
# \emph{r} stands for `restricted', `reproducible', or `rfc822-like'.
 
8
# 
 
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.
 
13
# 
 
14
# The format itself does not deal with character encoding issues, though
 
15
# the result will normally be written in Unicode.
 
16
# 
 
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.
 
20
 
 
21
import re
 
22
 
 
23
from bzrlib.iterablefile import IterableFile
 
24
 
 
25
# XXX: some redundancy is allowing to write stanzas in isolation as well as
 
26
# through a writer object.  
 
27
 
 
28
class RioWriter(object):
 
29
    def __init__(self, to_file):
 
30
        self._soft_nl = False
 
31
        self._to_file = to_file
 
32
 
 
33
    def write_stanza(self, stanza):
 
34
        if self._soft_nl:
 
35
            print >>self._to_file
 
36
        stanza.write(self._to_file)
 
37
        self._soft_nl = True
 
38
 
 
39
 
 
40
class RioReader(object):
 
41
    """Read stanzas from a file as a sequence
 
42
    
 
43
    to_file can be anything that can be enumerated as a sequence of 
 
44
    lines (with newlines.)
 
45
    """
 
46
    def __init__(self, from_file):
 
47
        self._from_file = from_file
 
48
 
 
49
    def __iter__(self):
 
50
        while True:
 
51
            s = read_stanza(self._from_file)
 
52
            if s is None:
 
53
                break
 
54
            else:
 
55
                yield s
 
56
 
 
57
 
 
58
def rio_file(stanzas, header=None):
 
59
    """Produce a rio IterableFile from an iterable of stanzas"""
 
60
    def str_iter():
 
61
        if header is not None:
 
62
            yield header + '\n'
 
63
        first_stanza = True
 
64
        for s in stanzas:
 
65
            if first_stanza is not True:
 
66
                yield '\n'
 
67
            for line in s.to_lines():
 
68
                yield line
 
69
            first_stanza = False
 
70
    return IterableFile(str_iter())
 
71
 
 
72
 
 
73
def read_stanzas(from_file):
 
74
    while True:
 
75
        s = read_stanza(from_file)
 
76
        if s is None:
 
77
            break
 
78
        else:
 
79
            yield s
 
80
 
 
81
class Stanza(object):
 
82
    """One stanza for rio.
 
83
 
 
84
    Each stanza contains a set of named fields.  
 
85
    
 
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
 
88
    preserved.
 
89
 
 
90
    Each field value must be either an int or a string.
 
91
    """
 
92
 
 
93
    __slots__ = ['items']
 
94
 
 
95
    def __init__(self, **kwargs):
 
96
        """Construct a new Stanza.
 
97
 
 
98
        The keyword arguments, if any, are added in sorted order to the stanza.
 
99
        """
 
100
        self.items = []
 
101
        if kwargs:
 
102
            for tag, value in sorted(kwargs.items()):
 
103
                self.add(tag, value)
 
104
 
 
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):
 
112
            pass
 
113
        ## elif isinstance(value, (int, long)):
 
114
        ##    value = str(value)           # XXX: python2.4 without L-suffix
 
115
        else:
 
116
            raise TypeError("invalid type for rio value: %r of type %s"
 
117
                            % (value, type(value)))
 
118
        self.items.append((tag, value))
 
119
        
 
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:
 
123
            if tag == find_tag:
 
124
                return True
 
125
        return False
 
126
 
 
127
    def __len__(self):
 
128
        """Return number of pairs in the stanza."""
 
129
        return len(self.items)
 
130
 
 
131
    def __eq__(self, other):
 
132
        if not isinstance(other, Stanza):
 
133
            return False
 
134
        return self.items == other.items
 
135
 
 
136
    def __ne__(self, other):
 
137
        return not self.__eq__(other)
 
138
 
 
139
    def __repr__(self):
 
140
        return "Stanza(%r)" % self.items
 
141
 
 
142
    def iter_pairs(self):
 
143
        """Return iterator of tag, value pairs."""
 
144
        return iter(self.items)
 
145
 
 
146
    def to_lines(self):
 
147
        """Generate sequence of lines for external version of this file.
 
148
        
 
149
        The lines are always utf-8 encoded strings.
 
150
        """
 
151
        if not self.items:
 
152
            # max() complains if sequence is empty
 
153
            return []
 
154
        result = []
 
155
        for tag, value in self.items:
 
156
            assert isinstance(tag, str), type(tag)
 
157
            assert isinstance(value, unicode)
 
158
            if value == '':
 
159
                result.append(tag + ': \n')
 
160
            elif '\n' in value:
 
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')
 
166
            else:
 
167
                result.append(tag + ': ' + value.encode('utf-8') + '\n')
 
168
        return result
 
169
 
 
170
    def to_string(self):
 
171
        """Return stanza as a single string"""
 
172
        return ''.join(self.to_lines())
 
173
 
 
174
    def write(self, to_file):
 
175
        """Write stanza to a file"""
 
176
        to_file.writelines(self.to_lines())
 
177
 
 
178
    def get(self, tag):
 
179
        """Return the value for a field wih given tag.
 
180
 
 
181
        If there is more than one value, only the first is returned.  If the
 
182
        tag is not present, KeyError is raised.
 
183
        """
 
184
        for t, v in self.items:
 
185
            if t == tag:
 
186
                return v
 
187
        else:
 
188
            raise KeyError(tag)
 
189
 
 
190
    __getitem__ = get
 
191
 
 
192
    def get_all(self, tag):
 
193
        r = []
 
194
        for t, v in self.items:
 
195
            if t == tag:
 
196
                r.append(v)
 
197
        return r
 
198
 
 
199
    def as_dict(self):
 
200
        """Return a dict containing the unique values of the stanza.
 
201
        """
 
202
        d = {}
 
203
        for tag, value in self.items:
 
204
            assert tag not in d
 
205
            d[tag] = value
 
206
        return d
 
207
         
 
208
_tag_re = re.compile(r'^[-a-zA-Z0-9_]+$')
 
209
def valid_tag(tag):
 
210
    return bool(_tag_re.match(tag))
 
211
 
 
212
 
 
213
def read_stanza(line_iter):
 
214
    """Return new Stanza read from list of lines or a file
 
215
    
 
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. 
 
220
 
 
221
    Only the stanza lines and the trailing blank (if any) are consumed
 
222
    from the line_iter.
 
223
 
 
224
    The raw lines must be in utf-8 encoding.
 
225
    """
 
226
    items = []
 
227
    stanza = Stanza()
 
228
    tag = None
 
229
    accum_value = None
 
230
    for line in line_iter:
 
231
        if line == None or line == '':
 
232
            break       # end of file
 
233
        if line == '\n':
 
234
            break       # end of stanza
 
235
        line = line.decode('utf-8')
 
236
        assert line[-1] == '\n'
 
237
        real_l = line
 
238
        if line[0] == '\t': # continues previous value
 
239
            if tag is None:
 
240
                raise ValueError('invalid continuation line %r' % real_l)
 
241
            accum_value += '\n' + line[1:-1]
 
242
        else: # new tag:value line
 
243
            if tag is not None:
 
244
                stanza.add(tag, accum_value)
 
245
            try:
 
246
                colon_index = line.index(': ')
 
247
            except ValueError:
 
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)
 
255
        return stanza
 
256
    else:     # didn't see any content
 
257
        return None