XMLHandler.h

Go to the documentation of this file.

// Copyright (c) 2002-present, OpenMS Inc. -- EKU Tuebingen, ETH Zurich, and FU Berlin
// SPDX-License-Identifier: BSD-3-Clause
//
// --------------------------------------------------------------------------
// $Maintainer: Chris Bielow $
// $Authors: Marc Sturm, Chris Bielow $
// --------------------------------------------------------------------------
 
#pragma once
 
#include <OpenMS/CONCEPT/Types.h>
#include <OpenMS/CONCEPT/Macros.h>
 
 
#include <OpenMS/DATASTRUCTURES/DateTime.h>
#include <OpenMS/DATASTRUCTURES/DataValue.h>
#include <OpenMS/FORMAT/HANDLERS/StringManager.h>
#include <OpenMS/FORMAT/HANDLERS/XMLAttributes.h>
 
#include <iosfwd>
#include <string>
#include <string_view>
 
 
namespace OpenMS
{
  class ControlledVocabulary;
  class CVTerm;
  class MetaInfoInterface;
  class ProteinIdentification;
 
  namespace Internal
  {
 
    // UTF-16 string handling lives in StringManager.
 
    class OPENMS_DLLAPI XMLHandler
    {
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 std::string & filename, const std::string & version);
      virtual ~XMLHandler();
 
      void reset();
 
      void fatalError(ActionMode mode, const std::string & msg, UInt line = 0, UInt column = 0) const;
      void error(ActionMode mode, const std::string & msg, UInt line = 0, UInt column = 0) const;
      void warning(ActionMode mode, const std::string & msg, UInt line = 0, UInt column = 0) const;
 
      virtual void onStartElement(const char16_t * qname, const XMLAttributes & attributes);
      virtual void onEndElement(const char16_t * qname);
      virtual void onCharacters(const char16_t * chars, Size length);
      virtual bool tryOnCharactersUTF8(const char* chars, Size length);
      virtual bool tryOnStartElementUTF8(std::string_view qname, const XMLAttributes& attributes);
      virtual bool tryOnEndElementUTF8(std::string_view qname);
 
 
      virtual void writeTo(std::ostream & /*os*/);
 
      virtual LOADDETAIL getLoadDetail() const;
 
      virtual void setLoadDetail(const LOADDETAIL d);
 
      static std::string writeXMLEscape(const std::string& to_escape)
      {
        std::string _copy = to_escape;
        // has() is cheap, so check before calling substitute(), since substitute() will usually happen rarely
        if (StringUtils::has(_copy, '&')) StringUtils::substitute(_copy, "&","&amp;");
        if (StringUtils::has(_copy, '>')) StringUtils::substitute(_copy, ">","&gt;");
        if (StringUtils::has(_copy, '"')) StringUtils::substitute(_copy, "\"","&quot;");
        if (StringUtils::has(_copy, '<')) StringUtils::substitute(_copy, "<","&lt;");
        if (StringUtils::has(_copy, '\'')) StringUtils::substitute(_copy, "'","&apos;");
 
        return _copy;
      }
 
      static DataValue fromXSDString(const std::string& type, const std::string& value)
      {
        DataValue data_value;
        // float type
        if (type == "xsd:double" || type == "xsd:float" || type == "xsd:decimal")
        {
          data_value = DataValue(StringUtils::toDouble(value));
        }
        // <=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(StringUtils::toInt32(value));
        }
        // 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(StringUtils::toInt64(value)); // 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;
      }
 
 
      DataValue cvParamToValue(const ControlledVocabulary& cv, const std::string& parent_tag, 
                               const std::string& accession, const std::string& name, const std::string& value,
                               const std::string& unit_accession) const;
 
      DataValue cvParamToValue(const ControlledVocabulary& cv, const CVTerm& raw_term) const;
 
      void checkUniqueIdentifiers_(const std::vector<ProteinIdentification>& prot_ids) const;
 
protected:
      std::string file_;
 
      std::string version_;
 
      StringManager sm_;
 
      std::vector<std::string> open_tags_;
 
      LOADDETAIL load_detail_; 
 
 
      inline bool equal_(const char16_t * a, const char16_t * b) const
      {
        // Guard null pointers before constructing views: u16string_view(nullptr)
        // is UB, whereas the previous XMLString::compareString tolerated nulls
        // (both null => equal, one null => unequal), which this reproduces.
        if (a == nullptr || b == nullptr) return a == b;
        return std::u16string_view(a) == std::u16string_view(b);
      }
 
 
 
      void writeUserParam_(const std::string & tag_name, std::ostream & os, const MetaInfoInterface & meta, UInt indent) const;
 
      static void writeUserParamValue_(std::ostream & os, const std::string & tag_start, const std::string & name, const DataValue & value);
 
 
 
 
      std::vector<std::vector<std::string> > cv_terms_;
 
      SignedSize cvStringToEnum_(const Size section, const std::string & term, const char * message, const SignedSize result_on_error = 0);
 
 
 
 
      inline Int asInt_(const std::string & in) const
      {
        Int res = 0;
        try
        {
          res = StringUtils::toInt32(in);
        }
        catch (Exception::ConversionError&)
        {
          error(LOAD,std::string("Int conversion error of \"") + in + "\"");
        }
        return res;
      }
 
      inline Int asInt_(const char16_t * in) const
      {
        return sm_.parseInt(in);
      }
 
      inline UInt asUInt_(const std::string & in) const
      {
        UInt res = 0;
        try
        {
          Int tmp = StringUtils::toInt32(in);
          if (tmp < 0)
          {
            throw Exception::ConversionError(__FILE__, __LINE__, OPENMS_PRETTY_FUNCTION, "");
          }
          res = UInt(tmp);
        }
        catch (Exception::ConversionError& )
        {
          error(LOAD,std::string("UInt conversion error of \"") + in + "\"");
        }
        return res;
      }
 
      inline double asDouble_(const std::string & in) const
      {
        double res = 0.0;
        try
        {
          res = StringUtils::toDouble(in);
        }
        catch (Exception::ConversionError& )
        {
          error(LOAD,std::string("Double conversion error of \"") + in + "\"");
        }
        return res;
      }
 
      inline float asFloat_(const std::string & in) const
      {
        float res = 0.0;
        try
        {
          res = StringUtils::toFloat(in);
        }
        catch (Exception::ConversionError& )
        {
          error(LOAD,std::string("Float conversion error of \"") + in + "\"");
        }
        return res;
      }
 
      inline bool asBool_(const std::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,std::string("Boolean conversion error of \"") + in + "\"");
        }
        return false;
      }
 
      inline DateTime asDateTime_(std::string date_string) const
      {
        DateTime date_time;
        if (!date_string.empty())
        {
          try
          {
            //strip away milliseconds
            StringUtils::trim(date_string);
            date_string = StringUtils::substr(date_string, 0, 19);
            date_time.set(date_string);
          }
          catch (Exception::ParseError& /*err*/ )
          {
            error(LOAD,std::string("DateTime conversion error of \"") + date_string + "\"");
          }
        }
        return date_time;
      }
 
 
 
 
      inline std::string attributeAsString_(const XMLAttributes & a, const char * name) const
      {
        std::string val;
        if (!a.valueUTF8(name, val)) fatalError(LOAD,std::string("Required attribute '") + name + "' not present!");
        return val;
      }
 
      inline Int attributeAsInt_(const XMLAttributes & a, const char * name) const
      {
        std::string val;
        if (!a.valueUTF8(name, val)) fatalError(LOAD,std::string("Required attribute '") + name + "' not present!");
        return StringUtils::toInt32(val);
      }
 
      inline double attributeAsDouble_(const XMLAttributes & a, const char * name) const
      {
        std::string val;
        if (!a.valueUTF8(name, val)) fatalError(LOAD,std::string("Required attribute '") + name + "' not present!");
        return StringUtils::toDouble(val);
      }
 
      DoubleList attributeAsDoubleList_(const XMLAttributes & a, const char * name) const;
 
      IntList attributeAsIntList_(const XMLAttributes & a, const char * name) const;
 
      StringList attributeAsStringList_(const XMLAttributes & a, const char * name) const;
 
      inline bool optionalAttributeAsString_(std::string & value, const XMLAttributes & a, const char * name) const
      {
        return a.valueUTF8(name, value);
      }
 
      inline bool optionalAttributeAsInt_(Int & value, const XMLAttributes & a, const char * name) const
      {
        std::string val;
        if (a.valueUTF8(name, val))
        {
          value = StringUtils::toInt32(val);
          return true;
        }
        return false;
      }
 
      inline bool optionalAttributeAsUInt_(UInt & value, const XMLAttributes & a, const char * name) const
      {
        std::string val;
        if (a.valueUTF8(name, val))
        {
          value = StringUtils::toInt32(val);
          return true;
        }
        return false;
      }
 
      inline bool optionalAttributeAsDouble_(double & value, const XMLAttributes & a, const char * name) const
      {
        std::string val;
        if (a.valueUTF8(name, val))
        {
          value = StringUtils::toDouble(val);
          return true;
        }
        return false;
      }
 
      inline bool optionalAttributeAsDoubleList_(DoubleList & value, const XMLAttributes & a, const char * name) const
      {
        const char16_t * val = a.value(name);
        if (val != nullptr)
        {
          value = attributeAsDoubleList_(a, name);
          return true;
        }
        return false;
      }
 
      inline bool optionalAttributeAsStringList_(StringList & value, const XMLAttributes & a, const char * name) const
      {
        const char16_t * val = a.value(name);
        if (val != nullptr)
        {
          value = attributeAsStringList_(a, name);
          return true;
        }
        return false;
      }
 
      inline bool optionalAttributeAsIntList_(IntList & value, const XMLAttributes & a, const char * name) const
      {
        const char16_t * val = a.value(name);
        if (val != nullptr)
        {
          value = attributeAsIntList_(a, name);
          return true;
        }
        return false;
      }
 
      inline std::string attributeAsString_(const XMLAttributes & a, const char16_t * name) const
      {
        std::string val;
        if (!a.valueUTF8(name, val)) fatalError(LOAD,std::string("Required attribute '") + sm_.convert(name) + "' not present!");
        return val;
      }
 
      inline Int attributeAsInt_(const XMLAttributes & a, const char16_t * name) const
      {
        std::string val;
        if (!a.valueUTF8(name, val)) fatalError(LOAD,std::string("Required attribute '") + sm_.convert(name) + "' not present!");
        return StringUtils::toInt32(val);
      }
 
      inline double attributeAsDouble_(const XMLAttributes & a, const char16_t * name) const
      {
        std::string val;
        if (!a.valueUTF8(name, val)) fatalError(LOAD,std::string("Required attribute '") + sm_.convert(name) + "' not present!");
        return StringUtils::toDouble(val);
      }
 
      DoubleList attributeAsDoubleList_(const XMLAttributes & a, const char16_t * name) const;
 
      IntList attributeAsIntList_(const XMLAttributes & a, const char16_t * name) const;
 
      StringList attributeAsStringList_(const XMLAttributes & a, const char16_t * name) const;
 
      inline bool optionalAttributeAsString_(std::string& value, const XMLAttributes & a, const char16_t * name) const
      {
        return a.valueUTF8(name, value) && !value.empty();
      }
 
      inline bool optionalAttributeAsInt_(Int & value, const XMLAttributes & a, const char16_t * name) const
      {
        std::string val;
        if (a.valueUTF8(name, val))
        {
          value = StringUtils::toInt32(val);
          return true;
        }
        return false;
      }
 
      inline bool optionalAttributeAsUInt_(UInt & value, const XMLAttributes & a, const char16_t * name) const
      {
        std::string val;
        if (a.valueUTF8(name, val))
        {
          value = StringUtils::toInt32(val);
          return true;
        }
        return false;
      }
 
      inline bool optionalAttributeAsDouble_(double & value, const XMLAttributes & a, const char16_t * name) const
      {
        std::string val;
        if (a.valueUTF8(name, val))
        {
          value = StringUtils::toDouble(val);
          return true;
        }
        return false;
      }
 
      inline bool optionalAttributeAsDoubleList_(DoubleList & value, const XMLAttributes & a, const char16_t * name) const
      {
        const char16_t * val = a.value(name);
        if (val != nullptr)
        {
          value = attributeAsDoubleList_(a, name);
          return true;
        }
        return false;
      }
 
      inline bool optionalAttributeAsIntList_(IntList & value, const XMLAttributes & a, const char16_t * name) const
      {
        const char16_t * val = a.value(name);
        if (val != nullptr)
        {
          value = attributeAsIntList_(a, name);
          return true;
        }
        return false;
      }
 
      inline bool optionalAttributeAsStringList_(StringList & value, const XMLAttributes & a, const char16_t * name) const
      {
        const char16_t * val = a.value(name);
        if (val != nullptr)
        {
          value = attributeAsStringList_(a, name);
          return true;
        }
        return false;
      }
 
 
private:
      XMLHandler();
 
      inline const std::string& expectList_(const std::string& str) const
      {
        if (!(StringUtils::hasPrefix(str, '[') && StringUtils::hasSuffix(str, ']')))
        {
          fatalError(LOAD,std::string("List argument is not a string representation of a list!"));
        }
        return str;
      }
 
    };
 
  }   // namespace Internal
} // namespace OpenMS