XMLHandler.h

Go to the documentation of this file.

// --------------------------------------------------------------------------
//                   OpenMS -- Open-Source Mass Spectrometry
// --------------------------------------------------------------------------
// Copyright The OpenMS Team -- Eberhard Karls University Tuebingen,
// ETH Zurich, and Freie Universitaet Berlin 2002-2022.
//
// This software is released under a three-clause BSD license:
//  * Redistributions of source code must retain the above copyright
//    notice, this list of conditions and the following disclaimer.
//  * Redistributions in binary form must reproduce the above copyright
//    notice, this list of conditions and the following disclaimer in the
//    documentation and/or other materials provided with the distribution.
//  * Neither the name of any author or any participating institution
//    may be used to endorse or promote products derived from this software
//    without specific prior written permission.
// For a full list of authors, refer to the file AUTHORS.
// --------------------------------------------------------------------------
// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
// ARE DISCLAIMED. IN NO EVENT SHALL ANY OF THE AUTHORS OR THE CONTRIBUTING
// INSTITUTIONS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
// EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
// PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
// OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
// WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
// OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
// ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
//
// --------------------------------------------------------------------------
// $Maintainer: Chris Bielow $
// $Authors: Marc Sturm, Chris Bielow $
// --------------------------------------------------------------------------

#pragma once

#include <OpenMS/CONCEPT/Types.h>
#include <OpenMS/CONCEPT/Macros.h>

#include <OpenMS/DATASTRUCTURES/ListUtils.h> // StringList
#include <OpenMS/DATASTRUCTURES/DateTime.h>
#include <OpenMS/DATASTRUCTURES/DataValue.h>
#include <OpenMS/DATASTRUCTURES/ListUtils.h>

#include <xercesc/util/XMLString.hpp>
#include <xercesc/sax2/DefaultHandler.hpp>
#include <xercesc/sax2/Attributes.hpp>

#include <iosfwd>
#include <string>
#include <memory>


namespace OpenMS
{
  class ProteinIdentification;
  class MetaInfoInterface;

  namespace Internal
  {

    #define CONST_XMLCH(s) reinterpret_cast<const ::XMLCh*>(u ## s)

    static_assert(sizeof(::XMLCh) == sizeof(char16_t),
                  "XMLCh is not sized correctly for UTF-16.");

    //Adapted from https://www.codeproject.com/articles/99551/redux-raii-adapter-for-xerces
    //Copyright 2010 Orjan Westin
    //Under BSD license
    //========================================================================================================
    template<typename T>
    class OPENMS_DLLAPI shared_xerces_ptr
    {
      // Function to release Xerces data type with a release member function
      template<typename U>
      static void doRelease_(U* item)
      {
        // Only release this if it has no owner
        if (nullptr == item->getOwnerDocument())
          item->release();
      }

      static void doRelease_(char* item);
      static void doRelease_(XMLCh* item);

      // The actual data we're holding
      std::shared_ptr<T> item_;
    public:
      // Default constructor
      shared_xerces_ptr() = default;
      // Assignment constructor
      shared_xerces_ptr(T* item)
          : item_(item, doRelease_ )
      {}
      // Assignment of data to guard
      shared_xerces_ptr& operator=(T* item)
      {
        assign(item);
        return *this;
      }
      // Give up hold on data
      void reset()
      {
        item_.reset();
      }
      // Release currently held data, if any, to hold another
      void assign(T* item)
      {
        item_.reset(item, doRelease_ );
      }
      // Get pointer to the currently held data, if any
      T* get()
      {
        return item_.get();
      }
      const T* get() const
      {
        return item_.get();
      }
      // Return true if no data is held
      bool is_released() const
      {
        return (nullptr == item_.get());
      }
    };

    template <typename T>
    class OPENMS_DLLAPI unique_xerces_ptr
    {
    private:

      template<typename U>
      static void doRelease_(U*& item)
      {
        // Only release this if it has no parent (otherwise
        // parent will release it)
        if (nullptr == item->getOwnerDocument())
          item->release();
      }

      static void doRelease_(char*& item);
      static void doRelease_(XMLCh*& item);

      T* item_;

    public:

      // Hide copy constructor and assignment operator
      unique_xerces_ptr(const unique_xerces_ptr<T>&) = delete;
      unique_xerces_ptr& operator=(const unique_xerces_ptr<T>&) = delete;

      unique_xerces_ptr()
          : item_(nullptr)
      {}

      explicit unique_xerces_ptr(T* i)
          : item_(i)
      {}

      ~unique_xerces_ptr()
      {
        xerces_release();
      }

      unique_xerces_ptr(unique_xerces_ptr<T>&& other) noexcept
          : item_(nullptr)
      {
        this->swap(other);
      }

      void swap(unique_xerces_ptr<T>& other) noexcept
      {
        std::swap(item_, other.item_);
      }

      // Assignment of data to guard (not chainable)
      void operator=(T* i)
      {
        reassign(i);
      }

      // Release held data (i.e. delete/free it)
      void xerces_release()
      {
        if (!is_released())
        {
          // Use type-specific release mechanism
          doRelease_(item_);
          item_ = nullptr;
        }
      }

      // Give up held data (i.e. return data without releasing)
      T* yield()
      {
        T* tempItem = item_;
        item_ = nullptr;
        return tempItem;
      }

      // Release currently held data, if any, to hold another
      void assign(T* i)
      {
        xerces_release();
        item_ = i;
      }

      // Get pointer to the currently held data, if any
      T* get() const
      {
        return item_;
      }

      // Return true if no data is held
      bool is_released() const
      {
        return (nullptr == item_);
      }
    };

    //========================================================================================================

    /*
     * @brief Helper class for XML parsing that handles the conversions of Xerces strings
     *
     * It provides the convert() function which internally calls
     * XMLString::transcode and ensures that the memory is released properly
     * through XMLString::release internally. It returns a std::string or
     * std::basic_string<XMLCh> to the caller who takes ownership of the data.
     *
    */
    class OPENMS_DLLAPI StringManager
    {

      typedef std::basic_string<XMLCh> XercesString;

      // Converts from a narrow-character string to a wide-character string.
      inline static unique_xerces_ptr<XMLCh> fromNative_(const char* str)
      {
        return unique_xerces_ptr<XMLCh>(xercesc::XMLString::transcode(str));
      }

      // Converts from a narrow-character string to a wide-character string.
      inline static unique_xerces_ptr<XMLCh> fromNative_(const String& str)
      {
        return fromNative_(str.c_str());
      }

      // Converts from a wide-character string to a narrow-character string.
      inline static String toNative_(const XMLCh* str)
      {
        return String(unique_xerces_ptr<char>(xercesc::XMLString::transcode(str)).get());
      }

      // Converts from a wide-character string to a narrow-character string.
      inline static String toNative_(const unique_xerces_ptr<XMLCh>& str)
      {
        return toNative_(str.get());
      }


public:
      StringManager();

      ~StringManager();

      inline static XercesString convert(const char * str)
      {
        return fromNative_(str).get();
      }

      inline static XercesString convert(const std::string & str)
      {
        return fromNative_(str.c_str()).get();
      }

      inline static XercesString convert(const String & str)
      {
        return fromNative_(str.c_str()).get();
      }

      inline static unique_xerces_ptr<XMLCh> convertPtr(const char * str)
      {
        return fromNative_(str);
      }

      inline static unique_xerces_ptr<XMLCh> convertPtr(const std::string & str)
      {
        return fromNative_(str.c_str());
      }

      inline static unique_xerces_ptr<XMLCh> convertPtr(const String & str)
      {
        return fromNative_(str.c_str());
      }

      inline static String convert(const XMLCh * str)
      {
        return toNative_(str);
      }

      static void appendASCII(const XMLCh * str, const XMLSize_t length, String & result);

    };

    class OPENMS_DLLAPI XMLHandler :
      public xercesc::DefaultHandler
    {
public:

      class OPENMS_DLLAPI EndParsingSoftly :
        public Exception::BaseException
      {
      public:
        EndParsingSoftly(const char * file, int line, const char * function) :
          Exception::BaseException(file, line, function)
        {
        }

      };

      enum ActionMode
      {
        LOAD,               
        STORE               
      };

      enum LOADDETAIL 
      {  
        LD_ALLDATA,       // default; load all data
        LD_RAWCOUNTS,     // only count the total number of spectra and chromatograms (usually very fast)
        LD_COUNTS_WITHOPTIONS // count the number of spectra, while respecting PeakFileOptions (msLevel and RTRange) and chromatograms (fast)
      };


      XMLHandler(const String & filename, const String & version);
      ~XMLHandler() override;

      void reset();


      void fatalError(const xercesc::SAXParseException & exception) override;
      void error(const xercesc::SAXParseException & exception) override;
      void warning(const xercesc::SAXParseException & exception) override;

      void fatalError(ActionMode mode, const String & msg, UInt line = 0, UInt column = 0) const;
      void error(ActionMode mode, const String & msg, UInt line = 0, UInt column = 0) const;
      void warning(ActionMode mode, const String & msg, UInt line = 0, UInt column = 0) const;

      void characters(const XMLCh * const chars, const XMLSize_t length) override;
      void startElement(const XMLCh * const uri, const XMLCh * const localname, const XMLCh * const qname, const xercesc::Attributes & attrs) override;
      void endElement(const XMLCh * const uri, const XMLCh * const localname, const XMLCh * const qname) override;

      virtual void writeTo(std::ostream & /*os*/);

      String errorString();

      virtual LOADDETAIL getLoadDetail() const;

      virtual void setLoadDetail(const LOADDETAIL d);

      static String writeXMLEscape(const String& to_escape)
      {
        String _copy = to_escape;
        // has() is cheap, so check before calling substitute(), since substitute() will usually happen rarely
        if (_copy.has('&')) _copy.substitute("&","&amp;");
        if (_copy.has('>')) _copy.substitute(">","&gt;");
        if (_copy.has('"')) _copy.substitute("\"","&quot;");
        if (_copy.has('<')) _copy.substitute("<","&lt;");
        if (_copy.has('\'')) _copy.substitute("'","&apos;");

        return _copy;
      }

      static DataValue fromXSDString(const String& type, const String& value)
      {
        DataValue data_value;
        // float type
        if (type == "xsd:double" || type == "xsd:float" || type == "xsd:decimal")
        {
          data_value = DataValue(value.toDouble());
        }
        // <=32 bit integer types
        else if (type == "xsd:byte" ||          // 8bit signed
                 type == "xsd:int" ||           // 32bit signed
                 type == "xsd:unsignedShort" || // 16bit unsigned
                 type == "xsd:short" ||         // 16bit signed
                 type == "xsd:unsignedByte" || type == "xsd:unsignedInt")
        {
          data_value = DataValue(value.toInt32());
        }
        // 64 bit integer types
        else if (type == "xsd:long" || type == "xsd:unsignedLong" ||       // 64bit signed or unsigned respectively
                 type == "xsd:integer" || type == "xsd:negativeInteger" || // any 'integer' has arbitrary size... but we have to cope with 64bit for now.
                 type == "xsd:nonNegativeInteger" || type == "xsd:nonPositiveInteger" || type == "xsd:positiveInteger")
        {
          data_value = DataValue(value.toInt64()); // internally a signed 64-bit integer. So if someone uses 2^64-1 as value, toInt64() will raise an exception...
        }
        // everything else is treated as a string
        else
        {
          data_value = DataValue(value);
        }
        return data_value;
      }

      void checkUniqueIdentifiers_(const std::vector<ProteinIdentification>& prot_ids) const;

protected:
      mutable String error_message_;

      String file_;

      String version_;

      StringManager sm_;

      std::vector<String> open_tags_;

      LOADDETAIL load_detail_; 


      inline bool equal_(const XMLCh * a, const XMLCh * b) const
      {
        return xercesc::XMLString::compareString(a, b) == 0;
      }



      void writeUserParam_(const String & tag_name, std::ostream & os, const MetaInfoInterface & meta, UInt indent) const;




      std::vector<std::vector<String> > cv_terms_;

      SignedSize cvStringToEnum_(const Size section, const String & term, const char * message, const SignedSize result_on_error = 0);




      inline Int asInt_(const String & in) const
      {
        Int res = 0;
        try
        {
          res = in.toInt();
        }
        catch (Exception::ConversionError&)
        {
          error(LOAD, String("Int conversion error of \"") + in + "\"");
        }
        return res;
      }

      inline Int asInt_(const XMLCh * in) const
      {
        return xercesc::XMLString::parseInt(in);
      }

      inline UInt asUInt_(const String & in) const
      {
        UInt res = 0;
        try
        {
          Int tmp = in.toInt();
          if (tmp < 0)
          {
            throw Exception::ConversionError(__FILE__, __LINE__, OPENMS_PRETTY_FUNCTION, "");
          }
          res = UInt(tmp);
        }
        catch (Exception::ConversionError& )
        {
          error(LOAD, String("UInt conversion error of \"") + in + "\"");
        }
        return res;
      }

      inline double asDouble_(const String & in) const
      {
        double res = 0.0;
        try
        {
          res = in.toDouble();
        }
        catch (Exception::ConversionError& )
        {
          error(LOAD, String("Double conversion error of \"") + in + "\"");
        }
        return res;
      }

      inline float asFloat_(const String & in) const
      {
        float res = 0.0;
        try
        {
          res = in.toFloat();
        }
        catch (Exception::ConversionError& )
        {
          error(LOAD, String("Float conversion error of \"") + in + "\"");
        }
        return res;
      }

      inline bool asBool_(const String & in) const
      {
        if (in == "true" || in == "TRUE" || in == "True" || in == "1")
        {
          return true;
        }
        else if (in == "false" || in == "FALSE" || in == "False" || in == "0")
        {
          return false;
        }
        else
        {
          error(LOAD, String("Boolean conversion error of \"") + in + "\"");
        }
        return false;
      }

      inline DateTime asDateTime_(String date_string) const
      {
        DateTime date_time;
        if (!date_string.empty())
        {
          try
          {
            //strip away milliseconds
            date_string.trim();
            date_string = date_string.substr(0, 19);
            date_time.set(date_string);
          }
          catch (Exception::ParseError& /*err*/ )
          {
            error(LOAD, String("DateTime conversion error of \"") + date_string + "\"");
          }
        }
        return date_time;
      }




      inline String attributeAsString_(const xercesc::Attributes & a, const char * name) const
      {
        const XMLCh * val = a.getValue(sm_.convertPtr(name).get());
        if (val == nullptr) fatalError(LOAD, String("Required attribute '") + name + "' not present!");
        return sm_.convert(val);
      }

      inline Int attributeAsInt_(const xercesc::Attributes & a, const char * name) const
      {
        const XMLCh * val = a.getValue(sm_.convertPtr(name).get());
        if (val == nullptr) fatalError(LOAD, String("Required attribute '") + name + "' not present!");
        return xercesc::XMLString::parseInt(val);
      }

      inline double attributeAsDouble_(const xercesc::Attributes & a, const char * name) const
      {
        const XMLCh * val = a.getValue(sm_.convertPtr(name).get());
        if (val == nullptr) fatalError(LOAD, String("Required attribute '") + name + "' not present!");
        return String(sm_.convert(val)).toDouble();
      }

      inline DoubleList attributeAsDoubleList_(const xercesc::Attributes & a, const char * name) const
      {
        String tmp(expectList_(attributeAsString_(a, name)));
        return ListUtils::create<double>(tmp.substr(1, tmp.size() - 2));
      }

      inline IntList attributeAsIntList_(const xercesc::Attributes & a, const char * name) const
      {
        String tmp(expectList_(attributeAsString_(a, name)));
        return ListUtils::create<Int>(tmp.substr(1, tmp.size() - 2));
      }

      inline StringList attributeAsStringList_(const xercesc::Attributes & a, const char * name) const
      {
        String tmp(expectList_(attributeAsString_(a, name)));         
        StringList tmp_list = ListUtils::create<String>(tmp.substr(1, tmp.size() - 2)); // between [ and ]
  
        if (tmp.hasSubstring("\\|")) // check full string for escaped comma
        {
          for (String& s : tmp_list)
          {
            s.substitute("\\|", ",");
          }          
        }
        return tmp_list;
      }

      inline bool optionalAttributeAsString_(String & value, const xercesc::Attributes & a, const char * name) const
      {
        const XMLCh * val = a.getValue(sm_.convertPtr(name).get());
        if (val != nullptr)
        {
          value = sm_.convert(val);
          return true;
        }
        return false;
      }

      inline bool optionalAttributeAsInt_(Int & value, const xercesc::Attributes & a, const char * name) const
      {
        const XMLCh * val = a.getValue(sm_.convertPtr(name).get());
        if (val != nullptr)
        {
          value = xercesc::XMLString::parseInt(val);
          return true;
        }
        return false;
      }

      inline bool optionalAttributeAsUInt_(UInt & value, const xercesc::Attributes & a, const char * name) const
      {
        const XMLCh * val = a.getValue(sm_.convertPtr(name).get());
        if (val != nullptr)
        {
          value = xercesc::XMLString::parseInt(val);
          return true;
        }
        return false;
      }

      inline bool optionalAttributeAsDouble_(double & value, const xercesc::Attributes & a, const char * name) const
      {
        const XMLCh * val = a.getValue(sm_.convertPtr(name).get());
        if (val != nullptr)
        {
          value = String(sm_.convert(val)).toDouble();
          return true;
        }
        return false;
      }

      inline bool optionalAttributeAsDoubleList_(DoubleList & value, const xercesc::Attributes & a, const char * name) const
      {
        const XMLCh * val = a.getValue(sm_.convertPtr(name).get());
        if (val != nullptr)
        {
          value = attributeAsDoubleList_(a, name);
          return true;
        }
        return false;
      }

      inline bool optionalAttributeAsStringList_(StringList & value, const xercesc::Attributes & a, const char * name) const
      {
        const XMLCh * val = a.getValue(sm_.convertPtr(name).get());
        if (val != nullptr)
        {
          value = attributeAsStringList_(a, name);
          return true;
        }
        return false;
      }

      inline bool optionalAttributeAsIntList_(IntList & value, const xercesc::Attributes & a, const char * name) const
      {
        const XMLCh * val = a.getValue(sm_.convertPtr(name).get());
        if (val != nullptr)
        {
          value = attributeAsIntList_(a, name);
          return true;
        }
        return false;
      }

      inline String attributeAsString_(const xercesc::Attributes & a, const XMLCh * name) const
      {
        const XMLCh * val = a.getValue(name);
        if (val == nullptr) fatalError(LOAD, String("Required attribute '") + sm_.convert(name) + "' not present!");
        return sm_.convert(val);
      }

      inline Int attributeAsInt_(const xercesc::Attributes & a, const XMLCh * name) const
      {
        const XMLCh * val = a.getValue(name);
        if (val == nullptr) fatalError(LOAD, String("Required attribute '") + sm_.convert(name) + "' not present!");
        return xercesc::XMLString::parseInt(val);
      }

      inline double attributeAsDouble_(const xercesc::Attributes & a, const XMLCh * name) const
      {
        const XMLCh * val = a.getValue(name);
        if (val == nullptr) fatalError(LOAD, String("Required attribute '") + sm_.convert(name) + "' not present!");
        return sm_.convert(val).toDouble();
      }

      inline DoubleList attributeAsDoubleList_(const xercesc::Attributes & a, const XMLCh * name) const
      {
        String tmp(expectList_(attributeAsString_(a, name)));
        return ListUtils::create<double>(tmp.substr(1, tmp.size() - 2));
      }

      inline IntList attributeAsIntList_(const xercesc::Attributes & a, const XMLCh * name) const
      {
        String tmp(expectList_(attributeAsString_(a, name)));
        return ListUtils::create<Int>(tmp.substr(1, tmp.size() - 2));
      }

      inline StringList attributeAsStringList_(const xercesc::Attributes & a, const XMLCh * name) const
      {
        String tmp(expectList_(attributeAsString_(a, name)));
        StringList tmp_list = ListUtils::create<String>(tmp.substr(1, tmp.size() - 2)); // between [ and ]

        if (tmp.hasSubstring("\\|")) // check full string for escaped comma
        {
          for (String& s : tmp_list)
          {
            s.substitute("\\|", ",");
          }          
        }
        return tmp_list;
      }

      inline bool optionalAttributeAsString_(String& value, const xercesc::Attributes & a, const XMLCh * name) const
      {
        const XMLCh * val = a.getValue(name);
        if (val != nullptr)
        {
          value = sm_.convert(val);
          return !value.empty();
        }
        return false;
      }

      inline bool optionalAttributeAsInt_(Int & value, const xercesc::Attributes & a, const XMLCh * name) const
      {
        const XMLCh * val = a.getValue(name);
        if (val != nullptr)
        {
          value = xercesc::XMLString::parseInt(val);
          return true;
        }
        return false;
      }

      inline bool optionalAttributeAsUInt_(UInt & value, const xercesc::Attributes & a, const XMLCh * name) const
      {
        const XMLCh * val = a.getValue(name);
        if (val != nullptr)
        {
          value = xercesc::XMLString::parseInt(val);
          return true;
        }
        return false;
      }

      inline bool optionalAttributeAsDouble_(double & value, const xercesc::Attributes & a, const XMLCh * name) const
      {
        const XMLCh * val = a.getValue(name);
        if (val != nullptr)
        {
          value = sm_.convert(val).toDouble();
          return true;
        }
        return false;
      }

      inline bool optionalAttributeAsDoubleList_(DoubleList & value, const xercesc::Attributes & a, const XMLCh * name) const
      {
        const XMLCh * val = a.getValue(name);
        if (val != nullptr)
        {
          value = attributeAsDoubleList_(a, name);
          return true;
        }
        return false;
      }

      inline bool optionalAttributeAsIntList_(IntList & value, const xercesc::Attributes & a, const XMLCh * name) const
      {
        const XMLCh * val = a.getValue(name);
        if (val != nullptr)
        {
          value = attributeAsIntList_(a, name);
          return true;
        }
        return false;
      }

      inline bool optionalAttributeAsStringList_(StringList & value, const xercesc::Attributes & a, const XMLCh * name) const
      {
        const XMLCh * val = a.getValue(name);
        if (val != nullptr)
        {
          value = attributeAsStringList_(a, name);
          return true;
        }
        return false;
      }


private:
      XMLHandler();

      inline const String& expectList_(const String& str) const
      {
        if (!(str.hasPrefix('[') && str.hasSuffix(']')))
        {
          fatalError(LOAD, String("List argument is not a string representation of a list!"));
        }
        return str;
      }

    };

  }   // namespace Internal
} // namespace OpenMS