OpenShot Audio Library | OpenShotAudio  0.3.0
juce_XmlElement.h
1 /*
2  ==============================================================================
3 
4  This file is part of the JUCE library.
5  Copyright (c) 2017 - ROLI Ltd.
6 
7  JUCE is an open source library subject to commercial or open-source
8  licensing.
9 
10  The code included in this file is provided under the terms of the ISC license
11  http://www.isc.org/downloads/software-support-policy/isc-license. Permission
12  To use, copy, modify, and/or distribute this software for any purpose with or
13  without fee is hereby granted provided that the above copyright notice and
14  this permission notice appear in all copies.
15 
16  JUCE IS PROVIDED "AS IS" WITHOUT ANY WARRANTY, AND ALL WARRANTIES, WHETHER
17  EXPRESSED OR IMPLIED, INCLUDING MERCHANTABILITY AND FITNESS FOR PURPOSE, ARE
18  DISCLAIMED.
19 
20  ==============================================================================
21 */
22 
23 namespace juce
24 {
25 
26 //==============================================================================
45 #define forEachXmlChildElement(parentXmlElement, childElementVariableName) \
46 \
47  for (auto* childElementVariableName = (parentXmlElement).getFirstChildElement(); \
48  childElementVariableName != nullptr; \
49  childElementVariableName = childElementVariableName->getNextElement())
50 
74 #define forEachXmlChildElementWithTagName(parentXmlElement, childElementVariableName, requiredTagName) \
75 \
76  for (auto* childElementVariableName = (parentXmlElement).getChildByName (requiredTagName); \
77  childElementVariableName != nullptr; \
78  childElementVariableName = childElementVariableName->getNextElementWithTagName (requiredTagName))
79 
80 
81 //==============================================================================
137 class JUCE_API XmlElement
138 {
139 public:
140  //==============================================================================
142  explicit XmlElement (const String& tagName);
143 
145  explicit XmlElement (const char* tagName);
146 
148  explicit XmlElement (const Identifier& tagName);
149 
151  explicit XmlElement (StringRef tagName);
152 
154  XmlElement (String::CharPointerType tagNameBegin, String::CharPointerType tagNameEnd);
155 
157  XmlElement (const XmlElement&);
158 
160  XmlElement& operator= (const XmlElement&);
161 
163  XmlElement& operator= (XmlElement&&) noexcept;
164 
166  XmlElement (XmlElement&&) noexcept;
167 
169  ~XmlElement() noexcept;
170 
171  //==============================================================================
183  bool isEquivalentTo (const XmlElement* other,
184  bool ignoreOrderOfAttributes) const noexcept;
185 
186  //==============================================================================
190  struct TextFormat
191  {
193  TextFormat();
194 
198  bool addDefaultHeader = true;
199  int lineWrapLength = 60;
200  const char* newLineChars = "\r\n";
202  TextFormat singleLine() const;
203  TextFormat withoutHeader() const;
204  };
205 
211  String toString (const TextFormat& format = {}) const;
212 
216  void writeTo (OutputStream& output, const TextFormat& format = {}) const;
217 
221  bool writeTo (const File& destinationFile, const TextFormat& format = {}) const;
222 
223  //==============================================================================
228  const String& getTagName() const noexcept { return tagName; }
229 
231  String getNamespace() const;
232 
234  String getTagNameWithoutNamespace() const;
235 
240  bool hasTagName (StringRef possibleTagName) const noexcept;
241 
246  bool hasTagNameIgnoringNamespace (StringRef possibleTagName) const;
247 
251  void setTagName (StringRef newTagName);
252 
253  //==============================================================================
259  int getNumAttributes() const noexcept;
260 
268  const String& getAttributeName (int attributeIndex) const noexcept;
269 
277  const String& getAttributeValue (int attributeIndex) const noexcept;
278 
279  //==============================================================================
280  // Attribute-handling methods..
281 
283  bool hasAttribute (StringRef attributeName) const noexcept;
284 
288  const String& getStringAttribute (StringRef attributeName) const noexcept;
289 
295  String getStringAttribute (StringRef attributeName, const String& defaultReturnValue) const;
296 
305  bool compareAttribute (StringRef attributeName,
306  StringRef stringToCompareAgainst,
307  bool ignoreCase = false) const noexcept;
308 
319  int getIntAttribute (StringRef attributeName, int defaultReturnValue = 0) const;
320 
331  double getDoubleAttribute (StringRef attributeName, double defaultReturnValue = 0.0) const;
332 
343  bool getBoolAttribute (StringRef attributeName, bool defaultReturnValue = false) const;
344 
358  void setAttribute (const Identifier& attributeName, const String& newValue);
359 
372  void setAttribute (const Identifier& attributeName, int newValue);
373 
386  void setAttribute (const Identifier& attributeName, double newValue);
387 
393  void removeAttribute (const Identifier& attributeName) noexcept;
394 
396  void removeAllAttributes() noexcept;
397 
398  //==============================================================================
399  // Child element methods..
400 
405  XmlElement* getFirstChildElement() const noexcept { return firstChildElement; }
406 
433  inline XmlElement* getNextElement() const noexcept { return nextListItem; }
434 
443  XmlElement* getNextElementWithTagName (StringRef requiredTagName) const;
444 
448  int getNumChildElements() const noexcept;
449 
458  XmlElement* getChildElement (int index) const noexcept;
459 
466  XmlElement* getChildByName (StringRef tagNameToLookFor) const noexcept;
467 
475  XmlElement* getChildByAttribute (StringRef attributeName,
476  StringRef attributeValue) const noexcept;
477 
478  //==============================================================================
492  void addChildElement (XmlElement* newChildElement) noexcept;
493 
505  void insertChildElement (XmlElement* newChildElement,
506  int indexToInsertAt) noexcept;
507 
520  void prependChildElement (XmlElement* newChildElement) noexcept;
521 
536  XmlElement* createNewChildElement (StringRef tagName);
537 
545  bool replaceChildElement (XmlElement* currentChildElement,
546  XmlElement* newChildNode) noexcept;
547 
554  void removeChildElement (XmlElement* childToRemove,
555  bool shouldDeleteTheChild) noexcept;
556 
560  void deleteAllChildElements() noexcept;
561 
565  void deleteAllChildElementsWithTagName (StringRef tagName) noexcept;
566 
568  bool containsChildElement (const XmlElement* possibleChild) const noexcept;
569 
580  XmlElement* findParentElementOf (const XmlElement* childToSearchFor) noexcept;
581 
582  //==============================================================================
605  template <class ElementComparator>
606  void sortChildElements (ElementComparator& comparator,
607  bool retainOrderOfEquivalentItems = false)
608  {
609  auto num = getNumChildElements();
610 
611  if (num > 1)
612  {
613  HeapBlock<XmlElement*> elems (num);
614  getChildElementsAsArray (elems);
615  sortArray (comparator, (XmlElement**) elems, 0, num - 1, retainOrderOfEquivalentItems);
616  reorderChildElements (elems, num);
617  }
618  }
619 
620  //==============================================================================
628  bool isTextElement() const noexcept;
629 
646  const String& getText() const noexcept;
647 
654  void setText (const String& newText);
655 
669  String getAllSubText() const;
670 
679  String getChildElementAllSubText (StringRef childTagName,
680  const String& defaultReturnValue) const;
681 
685  void addTextElement (const String& text);
686 
690  void deleteAllTextElements() noexcept;
691 
693  static XmlElement* createTextElement (const String& text);
694 
696  static bool isValidXmlName (StringRef possibleName) noexcept;
697 
698  //==============================================================================
700  JUCE_DEPRECATED (String createDocument (StringRef dtdToUse,
701  bool allOnOneLine = false,
702  bool includeXmlHeader = true,
703  StringRef encodingType = "UTF-8",
704  int lineWrapLength = 60) const);
705 
707  JUCE_DEPRECATED (void writeToStream (OutputStream& output,
708  StringRef dtdToUse,
709  bool allOnOneLine = false,
710  bool includeXmlHeader = true,
711  StringRef encodingType = "UTF-8",
712  int lineWrapLength = 60) const);
713 
715  JUCE_DEPRECATED (bool writeToFile (const File& destinationFile,
716  StringRef dtdToUse,
717  StringRef encodingType = "UTF-8",
718  int lineWrapLength = 60) const);
719 
720  //==============================================================================
721 private:
722  struct XmlAttributeNode
723  {
724  XmlAttributeNode (const XmlAttributeNode&) noexcept;
725  XmlAttributeNode (const Identifier&, const String&) noexcept;
726  XmlAttributeNode (String::CharPointerType, String::CharPointerType);
727 
729  Identifier name;
730  String value;
731 
732  private:
733  XmlAttributeNode& operator= (const XmlAttributeNode&) = delete;
734  };
735 
736  friend class XmlDocument;
737  friend class LinkedListPointer<XmlAttributeNode>;
738  friend class LinkedListPointer<XmlElement>;
739  friend class LinkedListPointer<XmlElement>::Appender;
740  friend class NamedValueSet;
741 
742  LinkedListPointer<XmlElement> nextListItem, firstChildElement;
743  LinkedListPointer<XmlAttributeNode> attributes;
744  String tagName;
745 
746  XmlElement (int) noexcept;
747  void copyChildrenAndAttributesFrom (const XmlElement&);
748  void writeElementAsText (OutputStream&, int, int, const char*) const;
749  void getChildElementsAsArray (XmlElement**) const noexcept;
750  void reorderChildElements (XmlElement**, int) noexcept;
751  XmlAttributeNode* getAttribute (StringRef) const noexcept;
752 
753  // Sigh.. L"" or _T("") string literals are problematic in general, and really inappropriate
754  // for XML tags. Use a UTF-8 encoded literal instead, or if you're really determined to use
755  // UTF-16, cast it to a String and use the other constructor.
756  XmlElement (const wchar_t*) = delete;
757 
758  JUCE_LEAK_DETECTOR (XmlElement)
759 };
760 
761 } // namespace juce
XmlElement * getNextElement() const noexcept
const String & getTagName() const noexcept