OpenShot Library | libopenshot-audio 0.2.0
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
40 XmlDocument myDocument (File ("myfile.xml"));
41 std::unique_ptr<XmlElement> mainElement (myDocument.getDocumentElement());
42
43 if (mainElement == nullptr)
44 {
45 String error = myDocument.getLastParseError();
46 }
47 else
48 {
49 ..use the element
50 }
51
52 @endcode
53
54 Or you can use the helper functions for much less verbose parsing..
55
56 @code
57 if (auto xml = parseXML (myXmlFile))
58 {
59 if (xml->hasTagName ("foobar"))
60 {
61 ...etc
62 }
63 }
64 @endcode
65
66 @see XmlElement
67
68 @tags{Core}
69*/
71{
72public:
73 //==============================================================================
74 /** Creates an XmlDocument from the xml text.
75 The text doesn't actually get parsed until the getDocumentElement() method is called.
76 */
77 XmlDocument (const String& documentText);
78
79 /** Creates an XmlDocument from a file.
80 The text doesn't actually get parsed until the getDocumentElement() method is called.
81 */
82 XmlDocument (const File& file);
83
84 /** Destructor. */
86
87 //==============================================================================
88 /** Creates an XmlElement object to represent the main document node.
89
90 This method will do the actual parsing of the text, and if there's a
91 parse error, it may returns nullptr (and you can find out the error using
92 the getLastParseError() method).
93
94 See also the parse() methods, which provide a shorthand way to quickly
95 parse a file or string.
96
97 @param onlyReadOuterDocumentElement if true, the parser will only read the
98 first section of the file, and will only
99 return the outer document element - this
100 allows quick checking of large files to
101 see if they contain the correct type of
102 tag, without having to parse the entire file
103 @returns a new XmlElement which the caller will need to delete, or null if
104 there was an error.
105 @see getLastParseError
106 */
107 XmlElement* getDocumentElement (bool onlyReadOuterDocumentElement = false);
108
109 /** Returns the parsing error that occurred the last time getDocumentElement was called.
110
111 @returns the error, or an empty string if there was no error.
112 */
113 const String& getLastParseError() const noexcept;
114
115 /** Sets an input source object to use for parsing documents that reference external entities.
116
117 If the document has been created from a file, this probably won't be needed, but
118 if you're parsing some text and there might be a DTD that references external
119 files, you may need to create a custom input source that can retrieve the
120 other files it needs.
121
122 The object that is passed-in will be deleted automatically when no longer needed.
123
124 @see InputSource
125 */
126 void setInputSource (InputSource* newSource) noexcept;
127
128 /** Sets a flag to change the treatment of empty text elements.
129
130 If this is true (the default state), then any text elements that contain only
131 whitespace characters will be ingored during parsing. If you need to catch
132 whitespace-only text, then you should set this to false before calling the
133 getDocumentElement() method.
134 */
135 void setEmptyTextElementsIgnored (bool shouldBeIgnored) noexcept;
136
137 //==============================================================================
138 /** A handy static method that parses a file.
139 This is a shortcut for creating an XmlDocument object and calling getDocumentElement() on it.
140 An even better shortcut is the juce::parseXML() function, which returns a std::unique_ptr<XmlElement>!
141 @returns a new XmlElement which the caller will need to delete, or null if there was an error.
142 */
143 static XmlElement* parse (const File& file);
144
145 /** A handy static method that parses some XML data.
146 This is a shortcut for creating an XmlDocument object and calling getDocumentElement() on it.
147 An even better shortcut is the juce::parseXML() function, which returns a std::unique_ptr<XmlElement>!
148 @returns a new XmlElement which the caller will need to delete, or null if there was an error.
149 */
150 static XmlElement* parse (const String& xmlData);
151
152
153 //==============================================================================
154private:
155 String originalText;
156 String::CharPointerType input { nullptr };
157 bool outOfData = false, errorOccurred = false;
158 String lastError, dtdText;
159 StringArray tokenisedDTD;
160 bool needToLoadDTD = false, ignoreEmptyTextElements = true;
161 std::unique_ptr<InputSource> inputSource;
162
163 XmlElement* parseDocumentElement (String::CharPointerType, bool outer);
164 void setLastError (const String&, bool carryOn);
165 bool parseHeader();
166 bool parseDTD();
167 void skipNextWhiteSpace();
168 juce_wchar readNextChar() noexcept;
169 XmlElement* readNextElement (bool alsoParseSubElements);
170 void readChildElements (XmlElement&);
171 void readQuotedString (String&);
172 void readEntity (String&);
173
174 String getFileContents (const String&) const;
175 String expandEntity (const String&);
176 String expandExternalEntity (const String&);
177 String getParameterEntity (const String&);
178
179 JUCE_DECLARE_NON_COPYABLE_WITH_LEAK_DETECTOR (XmlDocument)
180};
181
182//==============================================================================
183/** Attempts to parse some XML text, returning a new XmlElement if it was valid.
184 If the parse fails, this will return a nullptr - if you need more information about
185 errors or more parsing options, see the XmlDocument instead.
186 @see XmlDocument
187*/
188std::unique_ptr<XmlElement> parseXML (const String& textToParse);
189
190/** Attempts to parse some XML text, returning a new XmlElement if it was valid.
191 If the parse fails, this will return a nullptr - if you need more information about
192 errors or more parsing options, see the XmlDocument instead.
193 @see XmlDocument
194*/
195std::unique_ptr<XmlElement> parseXML (const File& fileToParse);
196
197
198
199} // namespace juce
200
201/** @}*/
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.
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.