1/*
2 * Copyright (c) 1999-2000, Eric Moon.
3 * All rights reserved.
4 *
5 * Redistribution and use in source and binary forms, with or without
6 * modification, are permitted provided that the following conditions
7 * are met:
8 *
9 * 1. Redistributions of source code must retain the above copyright
10 *    notice, this list of conditions, and the following disclaimer.
11 *
12 * 2. Redistributions in binary form must reproduce the above copyright
13 *    notice, this list of conditions, and the following disclaimer in the
14 *    documentation and/or other materials provided with the distribution.
15 *
16 * 3. The name of the author may not be used to endorse or promote products
17 *    derived from this software without specific prior written permission.
18 *
19 * THIS SOFTWARE IS PROVIDED BY THE AUTHOR "AS IS" AND ANY EXPRESS OR
20 * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
21 * OF TITLE, NON-INFRINGEMENT, MERCHANTABILITY AND FITNESS FOR A PARTICULAR
22 * PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY
23 * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
24 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
25 * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
26 * AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR
27 * TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
28 * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
29 */
30
31
32// Importer.h
33//
34// * PURPOSE
35//   Given a stream of XML parser events, produce the object[s]
36//   represented by the markup.
37//
38// * HISTORY
39//   e.moon		30jun99   Moved actual object-building responsibility
40//                      to IPersistent; this class is now internal
41//                      to Cortex::XML.
42//   e.moon		28jun99		Begun.  [was 'Importer']
43
44#ifndef __Importer_H__
45#define __Importer_H__
46
47#include <list>
48#include <String.h>
49
50#include "ImportContext.h"
51#include "XML.h"
52#include "expat.h"
53
54#include "cortex_defs.h"
55__BEGIN_CORTEX_NAMESPACE
56
57class Importer {
58
59public:													// *** ctor/dtor
60	virtual ~Importer();
61
62	// constructs a format-guessing Importer (uses the
63	// DocumentType registry)
64	Importer(
65		std::list<BString>&						errors);
66
67	// the Importer takes ownership of the given context!
68	Importer(
69		ImportContext*							context);
70
71	// constructs a manual Importer; the given root
72	// object is populated
73	Importer(
74		std::list<BString>&						errors,
75		IPersistent*								rootObject,
76		XML::DocumentType*					docType);
77
78	// the Importer takes ownership of the given context!
79	Importer(
80		ImportContext*							context,
81		IPersistent*								rootObject,
82		XML::DocumentType*					docType);
83
84public:													// *** accessors
85
86	// the import context
87	const ImportContext& context() const;
88
89	// matched document type
90	XML::DocumentType* docType() const;
91
92	// completed object (available if
93	// context().state() == ImportContext::COMPLETE, or
94	// if a root object was provided to the ctor)
95	IPersistent* target() const;
96
97public:													// *** operations
98
99	// put the importer into 'identify mode'
100	// (disengaged once the first element is encountered)
101	void setIdentifyMode();
102
103	// prepare to read the document after an identify cycle
104	void reset();
105
106	// handle a buffer; return false if an error occurs
107	bool parseBuffer(
108		const char*									buffer,
109		uint32											length,
110		bool												last);
111
112public:													// *** internal operations
113
114	// create & initialize parser
115	void initParser();
116
117	// clean up the parser
118	void freeParser();
119
120public:													// *** XML parser event hooks
121
122	virtual void xmlElementStart(
123		const char*									name,
124		const char**								attributes);
125
126	virtual void xmlElementEnd(
127		const char*									name);
128
129	virtual void xmlProcessingInstruction(
130		const char*									target,
131		const char*									data);
132
133	// not 0-terminated
134	virtual void xmlCharacterData(
135		const char*									data,
136		int32												length);
137
138	// not 0-terminated
139	virtual void xmlDefaultData(
140		const char*									data,
141		int32												length);
142
143private:												// *** implementation
144
145	XML_Parser										m_parser;
146	XML::DocumentType*						m_docType;
147
148	// if true, the importer is being used to identify the
149	// document type -- it should halt as soon as the first
150	// element is encountered.
151	bool													m_identify;
152
153	ImportContext* const					m_context;
154
155	// the constructed object: if no rootObject was provided
156	// in the ctor, this is only filled in once the document
157	// end tag has been encountered.
158	IPersistent*									m_rootObject;
159};
160
161__END_CORTEX_NAMESPACE
162#endif /*__Importer_H__*/
163