source/modules/water/xml/XmlDocument.h

   1 /*
   2   ==============================================================================
   3
   4    This file is part of the Water library.
   5    Copyright (c) 2016 ROLI Ltd.
   6    Copyright (C) 2017-2022 Filipe Coelho <falktx@falktx.com>
   7
   8    Permission is granted to use this software under the terms of the ISC license
   9    http://www.isc.org/downloads/software-support-policy/isc-license/
  10
  11    Permission to use, copy, modify, and/or distribute this software for any
  12    purpose with or without fee is hereby granted, provided that the above
  13    copyright notice and this permission notice appear in all copies.
  14
  15    THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH REGARD
  16    TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
  17    FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT,
  18    OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF
  19    USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
  20    TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE
  21    OF THIS SOFTWARE.
  22
  23   ==============================================================================
  24 */
  25
  26 #ifndef WATER_XMLDOCUMENT_H_INCLUDED
  27 #define WATER_XMLDOCUMENT_H_INCLUDED
  28
  29 #include "../text/StringArray.h"
  30
  31 #include "CarlaScopeUtils.hpp"
  32
  33 namespace water {
  34
  35 //==============================================================================
  36 /**
  37     Parses a text-based XML document and creates an XmlElement object from it.
  38
  39     The parser will parse DTDs to load external entities but won't
  40     check the document for validity against the DTD.
  41
  42     e.g.
  43     @code
  44
  45     XmlDocument myDocument (File ("myfile.xml"));
  46     ScopedPointer<XmlElement> mainElement (myDocument.getDocumentElement());
  47
  48     if (mainElement == nullptr)
  49     {
  50         String error = myDocument.getLastParseError();
  51     }
  52     else
  53     {
  54         ..use the element
  55     }
  56
  57     @endcode
  58
  59     Or you can use the static helper methods for quick parsing..
  60
  61     @code
  62     ScopedPointer<XmlElement> xml (XmlDocument::parse (myXmlFile));
  63
  64     if (xml != nullptr && xml->hasTagName ("foobar"))
  65     {
  66         ...etc
  67     @endcode
  68
  69     @see XmlElement
  70 */
  71 class XmlDocument
  72 {
  73 public:
  74     //==============================================================================
  75     /** Creates an XmlDocument from the xml text.
  76         The text doesn't actually get parsed until the getDocumentElement() method is called.
  77     */
  78     XmlDocument (const String& documentText);
  79
  80     /** Creates an XmlDocument from a file.
  81         The text doesn't actually get parsed until the getDocumentElement() method is called.
  82     */
  83     XmlDocument (const File& file);
  84
  85     /** Destructor. */
  86     ~XmlDocument();
  87
  88     //==============================================================================
  89     /** Creates an XmlElement object to represent the main document node.
  90
  91         This method will do the actual parsing of the text, and if there's a
  92         parse error, it may returns nullptr (and you can find out the error using
  93         the getLastParseError() method).
  94
  95         See also the parse() methods, which provide a shorthand way to quickly
  96         parse a file or string.
  97
  98         @param onlyReadOuterDocumentElement     if true, the parser will only read the
  99                                                 first section of the file, and will only
 100                                                 return the outer document element - this
 101                                                 allows quick checking of large files to
 102                                                 see if they contain the correct type of
 103                                                 tag, without having to parse the entire file
 104         @returns    a new XmlElement which the caller will need to delete, or null if
 105                     there was an error.
 106         @see getLastParseError
 107     */
 108     XmlElement* getDocumentElement (bool onlyReadOuterDocumentElement = false);
 109
 110     /** Returns the parsing error that occurred the last time getDocumentElement was called.
 111
 112         @returns the error, or an empty string if there was no error.
 113     */
 114     const String& getLastParseError() const noexcept;
 115
 116     /** Sets an input source object to use for parsing documents that reference external entities.
 117
 118         If the document has been created from a file, this probably won't be needed, but
 119         if you're parsing some text and there might be a DTD that references external
 120         files, you may need to create a custom input source that can retrieve the
 121         other files it needs.
 122
 123         The object that is passed-in will be deleted automatically when no longer needed.
 124
 125         @see FileInputSource
 126     */
 127     void setInputSource (FileInputSource* newSource) noexcept;
 128
 129     /** Sets a flag to change the treatment of empty text elements.
 130
 131         If this is true (the default state), then any text elements that contain only
 132         whitespace characters will be ingored during parsing. If you need to catch
 133         whitespace-only text, then you should set this to false before calling the
 134         getDocumentElement() method.
 135     */
 136     void setEmptyTextElementsIgnored (bool shouldBeIgnored) noexcept;
 137
 138     //==============================================================================
 139     /** A handy static method that parses a file.
 140         This is a shortcut for creating an XmlDocument object and calling getDocumentElement() on it.
 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         @returns    a new XmlElement which the caller will need to delete, or null if there was an error.
 148     */
 149     static XmlElement* parse (const String& xmlData);
 150
 151
 152     //==============================================================================
 153 private:
 154     String originalText;
 155     CharPointer_UTF8 input;
 156     bool outOfData, errorOccurred;
 157
 158     String lastError, dtdText;
 159     StringArray tokenisedDTD;
 160     bool needToLoadDTD, ignoreEmptyTextElements;
 161     CarlaScopedPointer<FileInputSource> inputSource;
 162
 163     XmlElement* parseDocumentElement (CharPointer_UTF8, bool outer);
 164     void setLastError (const String&, bool carryOn);
 165     bool parseHeader();
 166     bool parseDTD();
 167     void skipNextWhiteSpace();
 168     water_uchar 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     CARLA_DECLARE_NON_COPYABLE (XmlDocument)
 180 };
 181
 182 }
 183
 184 #endif // WATER_XMLDOCUMENT_H_INCLUDED