1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
|
/**************************************************************************
* *
* Regina - A Normal Surface Theory Calculator *
* Computational Engine *
* *
* Copyright (c) 1999-2011, Ben Burton *
* For further details contact Ben Burton (bab@debian.org). *
* *
* This program is free software; you can redistribute it and/or *
* modify it under the terms of the GNU General Public License as *
* published by the Free Software Foundation; either version 2 of the *
* License, or (at your option) any later version. *
* *
* This program is distributed in the hope that it will be useful, but *
* WITHOUT ANY WARRANTY; without even the implied warranty of *
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU *
* General Public License for more details. *
* *
* You should have received a copy of the GNU General Public *
* License along with this program; if not, write to the Free *
* Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, *
* MA 02110-1301, USA. *
* *
**************************************************************************/
/* end stub */
/*! \file packet/nxmlpacketreader.h
* \brief Deals with parsing XML data for individual packets.
*/
#ifndef __NXMLPACKETREADER_H
#ifndef __DOXYGEN
#define __NXMLPACKETREADER_H
#endif
#include "regina-core.h"
#include "file/nxmlelementreader.h"
namespace regina {
class NPacket;
/**
* \weakgroup packet
* @{
*/
/**
* An XML element reader that reads the data for an individual packet.
*
* Generally a subclass of NXMLPacketReader will be used to receive and
* store packets that you care about. However, if you simply wish to
* ignore a particular packet (and all of its descendants), you can use
* class NXMLPacketReader itself for the packet(s) you wish to ignore.
*
* Routine getPacket() is used to return the packet that was read; see
* its documentation for further notes on how the packet should be
* constructed.
*
* Routines startSubElement() and endSubElement() should \e not be
* overridden by derived classes. They determine whether the subelement
* is another packet element or a packet tag; if so then they deal with
* the subelement themselves (packet elements will be read using a new
* NXMLPacketReader of the correct type), and if not then they call
* startContentSubElement() and endContentSubElement() which \e should
* be overridden for processing of non-packet XML subelements.
*
* If routine abort() is overridden, it \e must at some point call
* NXMLPacketReader::abort() which will destroy whatever new packets
* have already been created.
*
* \ifacespython Not present.
*/
class REGINA_API NXMLPacketReader : public NXMLElementReader {
private:
std::string childLabel;
/**< The packet label to give the child packet currently
being read. */
public:
/**
* Creates a new packet element reader.
*/
NXMLPacketReader();
/**
* Returns the newly allocated packet that has been read by
* this element reader.
*
* Deallocation of this new packet is not the responsibility of
* this class. Once this routine gives a non-zero return value,
* it should continue to give the same non-zero return value
* from this point onwards.
*
* If this routine is ever to give a non-zero return value, it
* \e must be giving that non-zero return value by the time the
* first child packet or packet tag is encountered; otherwise
* child packets will not be inserted into the packet tree and/or
* packet tags will not be added.
*
* The newly allocated packet should not be given a packet
* label. This will be done by NXMLPacketReader::endSubElement().
*
* The newly allocated packet may or may not be inserted in the
* packet tree structure; this does not matter (although if it
* is inserted it must be inserted in the correct place).
*
* The newly allocated packet should not be given any associated
* packet tags. This will be done by
* NXMLPacketReader::startSubElement().
*
* The default implementation returns 0.
*
* @return the packet that has been read, or 0 if packet reading
* is incomplete, the packet should be ignored or an error
* occurred.
*/
virtual NPacket* getPacket();
/**
* Used instead of startSubElement() for XML subelements that
* are not child packets or packet tags.
*
* The default implementation returns a new NXMLElementReader
* which can be used to ignore the subelement completely.
*
* @param subTagName the name of the subelement opening tag.
* @param subTagProps the properties associated with the
* subelement opening tag.
* @return a newly created element reader that will be used to
* parse the subelement. This class should \e not take care of
* the new reader's destruction; that will be done by the parser.
*/
virtual NXMLElementReader* startContentSubElement(
const std::string& subTagName,
const regina::xml::XMLPropertyDict& subTagProps);
/**
* Used instead of endSubElement() for XML subelements that are
* not child packets or packet tags.
*
* The default implementation does nothing.
*
* @param subTagName the name of the subelement closing tag.
* @param subReader the child reader that was used to parse the
* subelement (this is the reader that was returned by the
* corresponding startContentSubElement() call). It is guaranteed
* that endElement() has already been called upon this child reader
* and that the child reader has not yet been destroyed.
*/
virtual void endContentSubElement(const std::string& subTagName,
NXMLElementReader* subReader);
virtual NXMLElementReader* startSubElement(
const std::string& subTagName,
const regina::xml::XMLPropertyDict& subTagProps);
virtual void endSubElement(const std::string& subTagName,
NXMLElementReader* subReader);
virtual void abort(NXMLElementReader *subReader);
};
/*@}*/
// Inline functions for NXMLPacketReader
inline NXMLPacketReader::NXMLPacketReader() {
}
inline NPacket* NXMLPacketReader::getPacket() {
return 0;
}
inline NXMLElementReader* NXMLPacketReader::startContentSubElement(
const std::string&, const regina::xml::XMLPropertyDict&) {
return new NXMLElementReader();
}
inline void NXMLPacketReader::endContentSubElement(const std::string&,
NXMLElementReader*) {
}
} // namespace regina
#endif
|
