OpenShot Library | OpenShotAudio  0.2.1
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 
27 namespace 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 {
69 public:
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. */
82  ~XmlDocument();
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  //==============================================================================
156 private:
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 */
190 std::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 */
197 std::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 */
204 std::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 */
211 std::unique_ptr<XmlElement> parseXMLIfTagMatches (const File& fileToParse, StringRef requiredTag);
212 
213 
214 } // namespace juce
215 
216 /** @}*/
Parses a text-based XML document and creates an XmlElement object from it.
#define JUCE_API
This macro is added to all JUCE public class declarations.
A simple class for holding temporary references to a string literal or String.
Used to build a tree of elements representing an XML document.
A special array for holding a list of strings.
The JUCE String class!
Definition: juce_String.h:42
Represents a local file or directory.
Definition: juce_File.h:44
A lightweight object that can create a stream to read some kind of resource.
Wraps a pointer to a null-terminated UTF-8 character string, and provides various methods to operate ...