OpenShot Library | OpenShotAudio 0.2.2
juce_XmlDocument.h
1
2/** @weakgroup juce_core-xml
3 * @{
4 */
5/*
6 ==============================================================================
7
8 This file is part of the JUCE library.
9 Copyright (c) 2017 - ROLI Ltd.
10
11 JUCE is an open source library subject to commercial or open-source
12 licensing.
13
14 The code included in this file is provided under the terms of the ISC license
15 http://www.isc.org/downloads/software-support-policy/isc-license. Permission
16 To use, copy, modify, and/or distribute this software for any purpose with or
17 without fee is hereby granted provided that the above copyright notice and
18 this permission notice appear in all copies.
19
20 JUCE IS PROVIDED "AS IS" WITHOUT ANY WARRANTY, AND ALL WARRANTIES, WHETHER
21 EXPRESSED OR IMPLIED, INCLUDING MERCHANTABILITY AND FITNESS FOR PURPOSE, ARE
22 DISCLAIMED.
23
24 ==============================================================================
25*/
26
27namespace juce
28{
29
30//==============================================================================
31/**
32 Parses a text-based XML document and creates an XmlElement object from it.
33
34 The parser will parse DTDs to load external entities but won't
35 check the document for validity against the DTD.
36
37 e.g.
38 @code
39 XmlDocument myDocument (File ("myfile.xml"));
40
41 if (auto mainElement = myDocument.getDocumentElement())
42 {
43 ..use the element
44 }
45 else
46 {
47 String error = myDocument.getLastParseError();
48 }
49 @endcode
50
51 Or you can use the helper functions for much less verbose parsing..
52
53 @code
54 if (auto xml = parseXML (myXmlFile))
55 {
56 if (xml->hasTagName ("foobar"))
57 {
58 ...etc
59 }
60 }
61 @endcode
62
63 @see XmlElement
64
65 @tags{Core}
66*/
68{
69public:
70 //==============================================================================
71 /** Creates an XmlDocument from the xml text.
72 The text doesn't actually get parsed until the getDocumentElement() method is called.
73 */
74 XmlDocument (const String& documentText);
75
76 /** Creates an XmlDocument from a file.
77 The text doesn't actually get parsed until the getDocumentElement() method is called.
78 */
79 XmlDocument (const File& file);
80
81 /** Destructor. */
83
84 //==============================================================================
85 /** Creates an XmlElement object to represent the main document node.
86
87 This method will do the actual parsing of the text, and if there's a
88 parse error, it may returns nullptr (and you can find out the error using
89 the getLastParseError() method).
90
91 See also the parse() methods, which provide a shorthand way to quickly
92 parse a file or string.
93
94 @param onlyReadOuterDocumentElement if true, the parser will only read the
95 first section of the file, and will only
96 return the outer document element - this
97 allows quick checking of large files to
98 see if they contain the correct type of
99 tag, without having to parse the entire file
100 @returns a new XmlElement which the caller will need to delete, or null if
101 there was an error.
102 @see getLastParseError, getDocumentElementIfTagMatches
103 */
104 std::unique_ptr<XmlElement> getDocumentElement (bool onlyReadOuterDocumentElement = false);
105
106 /** Does an inexpensive check to see whether the outer element has the given tag name, and
107 then does a full parse if it matches.
108 If the tag is different, or the XML parse fails, this will return nullptr.
109 */
110 std::unique_ptr<XmlElement> getDocumentElementIfTagMatches (StringRef requiredTag);
111
112 /** Returns the parsing error that occurred the last time getDocumentElement was called.
113 @returns the error, or an empty string if there was no error.
114 */
115 const String& getLastParseError() const noexcept;
116
117 /** Sets an input source object to use for parsing documents that reference external entities.
118
119 If the document has been created from a file, this probably won't be needed, but
120 if you're parsing some text and there might be a DTD that references external
121 files, you may need to create a custom input source that can retrieve the
122 other files it needs.
123
124 The object that is passed-in will be deleted automatically when no longer needed.
125
126 @see InputSource
127 */
128 void setInputSource (InputSource* newSource) noexcept;
129
130 /** Sets a flag to change the treatment of empty text elements.
131
132 If this is true (the default state), then any text elements that contain only
133 whitespace characters will be ingored during parsing. If you need to catch
134 whitespace-only text, then you should set this to false before calling the
135 getDocumentElement() method.
136 */
137 void setEmptyTextElementsIgnored (bool shouldBeIgnored) noexcept;
138
139 //==============================================================================
140 /** A handy static method that parses a file.
141 This is a shortcut for creating an XmlDocument object and calling getDocumentElement() on it.
142 An even better shortcut is the juce::parseXML() function, which returns a std::unique_ptr<XmlElement>!
143 @returns a new XmlElement which the caller will need to delete, or null if there was an error.
144 */
145 static std::unique_ptr<XmlElement> parse (const File& file);
146
147 /** A handy static method that parses some XML data.
148 This is a shortcut for creating an XmlDocument object and calling getDocumentElement() on it.
149 An even better shortcut is the juce::parseXML() function, which returns a std::unique_ptr<XmlElement>!
150 @returns a new XmlElement which the caller will need to delete, or null if there was an error.
151 */
152 static std::unique_ptr<XmlElement> parse (const String& xmlData);
153
154
155 //==============================================================================
156private:
157 String originalText;
158 String::CharPointerType input { nullptr };
159 bool outOfData = false, errorOccurred = false;
160 String lastError, dtdText;
161 StringArray tokenisedDTD;
162 bool needToLoadDTD = false, ignoreEmptyTextElements = true;
163 std::unique_ptr<InputSource> inputSource;
164
165 std::unique_ptr<XmlElement> parseDocumentElement (String::CharPointerType, bool outer);
166 void setLastError (const String&, bool carryOn);
167 bool parseHeader();
168 bool parseDTD();
169 void skipNextWhiteSpace();
170 juce_wchar readNextChar() noexcept;
171 XmlElement* readNextElement (bool alsoParseSubElements);
172 void readChildElements (XmlElement&);
173 void readQuotedString (String&);
174 void readEntity (String&);
175
176 String getFileContents (const String&) const;
177 String expandEntity (const String&);
178 String expandExternalEntity (const String&);
179 String getParameterEntity (const String&);
180
181 JUCE_DECLARE_NON_COPYABLE_WITH_LEAK_DETECTOR (XmlDocument)
182};
183
184//==============================================================================
185/** Attempts to parse some XML text, returning a new XmlElement if it was valid.
186 If the parse fails, this will return a nullptr - if you need more information about
187 errors or more parsing options, see the XmlDocument class instead.
188 @see XmlDocument, parseXMLIfTagMatches
189*/
190std::unique_ptr<XmlElement> parseXML (const String& textToParse);
191
192/** Attempts to parse some XML text, returning a new XmlElement if it was valid.
193 If the parse fails, this will return a nullptr - if you need more information about
194 errors or more parsing options, see the XmlDocument class instead.
195 @see XmlDocument, parseXMLIfTagMatches
196*/
197std::unique_ptr<XmlElement> parseXML (const File& fileToParse);
198
199/** Does an inexpensive check to see whether the top-level element has the given tag
200 name, and if that's true, does a full parse and returns the result.
201 If the outer tag doesn't match, or the XML has errors, this will return nullptr;
202 @see parseXML
203*/
204std::unique_ptr<XmlElement> parseXMLIfTagMatches (const String& textToParse, StringRef requiredTag);
205
206/** Does an inexpensive check to see whether the top-level element has the given tag
207 name, and if that's true, does a full parse and returns the result.
208 If the outer tag doesn't match, or the XML has errors, this will return nullptr;
209 @see parseXML
210*/
211std::unique_ptr<XmlElement> parseXMLIfTagMatches (const File& fileToParse, StringRef requiredTag);
212
213
214} // namespace juce
215
216/** @}*/
Wraps a pointer to a null-terminated UTF-8 character string, and provides various methods to operate ...
Represents a local file or directory.
Definition: juce_File.h:45
A lightweight object that can create a stream to read some kind of resource.
A special array for holding a list of strings.
A simple class for holding temporary references to a string literal or String.
The JUCE String class!
Definition: juce_String.h:43
Parses a text-based XML document and creates an XmlElement object from it.
Used to build a tree of elements representing an XML document.
#define JUCE_API
This macro is added to all JUCE public class declarations.