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 
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 
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 {
72 public:
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. */
85  ~XmlDocument();
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  //==============================================================================
154 private:
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 */
188 std::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 */
195 std::unique_ptr<XmlElement> parseXML (const File& fileToParse);
196 
197 
198 
199 } // namespace juce
200 
201 /** @}*/
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.
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 ...