io.hpp

/******************************************************************************
 *
 * Project:  PROJ
 * Purpose:  ISO19111:2018 implementation
 * Author:   Even Rouault <even dot rouault at spatialys dot com>
 *
 ******************************************************************************
 * Copyright (c) 2018, Even Rouault <even dot rouault at spatialys dot com>
 *
 * Permission is hereby granted, free of charge, to any person obtaining a
 * copy of this software and associated documentation files (the "Software"),
 * to deal in the Software without restriction, including without limitation
 * the rights to use, copy, modify, merge, publish, distribute, sublicense,
 * and/or sell copies of the Software, and to permit persons to whom the
 * Software is furnished to do so, subject to the following conditions:
 *
 * The above copyright notice and this permission notice shall be included
 * in all copies or substantial portions of the Software.
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
 * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
 * THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
 * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
 * DEALINGS IN THE SOFTWARE.
 ****************************************************************************/

#ifndef IO_HH_INCLUDED
#define IO_HH_INCLUDED

#include <memory>
#include <set>
#include <string>
#include <utility>
#include <vector>

#include "util.hpp"

NS_PROJ_START

namespace common {
class UnitOfMeasure;
using UnitOfMeasurePtr = std::shared_ptr<UnitOfMeasure>;
using UnitOfMeasureNNPtr = util::nn<UnitOfMeasurePtr>;
} // namespace common

namespace cs {
class CoordinateSystem;
using CoordinateSystemPtr = std::shared_ptr<CoordinateSystem>;
using CoordinateSystemNNPtr = util::nn<CoordinateSystemPtr>;
} // namespace cs

namespace metadata {
class Extent;
using ExtentPtr = std::shared_ptr<Extent>;
using ExtentNNPtr = util::nn<ExtentPtr>;
} // namespace metadata

namespace datum {
class Datum;
using DatumPtr = std::shared_ptr<Datum>;
using DatumNNPtr = util::nn<DatumPtr>;

class Ellipsoid;
using EllipsoidPtr = std::shared_ptr<Ellipsoid>;
using EllipsoidNNPtr = util::nn<EllipsoidPtr>;

class PrimeMeridian;
using PrimeMeridianPtr = std::shared_ptr<PrimeMeridian>;
using PrimeMeridianNNPtr = util::nn<PrimeMeridianPtr>;

class GeodeticReferenceFrame;
using GeodeticReferenceFramePtr = std::shared_ptr<GeodeticReferenceFrame>;
using GeodeticReferenceFrameNNPtr = util::nn<GeodeticReferenceFramePtr>;

class VerticalReferenceFrame;
using VerticalReferenceFramePtr = std::shared_ptr<VerticalReferenceFrame>;
using VerticalReferenceFrameNNPtr = util::nn<VerticalReferenceFramePtr>;
} // namespace datum

namespace crs {
class CRS;
using CRSPtr = std::shared_ptr<CRS>;
using CRSNNPtr = util::nn<CRSPtr>;

class GeodeticCRS;
using GeodeticCRSPtr = std::shared_ptr<GeodeticCRS>;
using GeodeticCRSNNPtr = util::nn<GeodeticCRSPtr>;

class GeographicCRS;
using GeographicCRSPtr = std::shared_ptr<GeographicCRS>;
using GeographicCRSNNPtr = util::nn<GeographicCRSPtr>;

class VerticalCRS;
using VerticalCRSPtr = std::shared_ptr<VerticalCRS>;
using VerticalCRSNNPtr = util::nn<VerticalCRSPtr>;

class ProjectedCRS;
using ProjectedCRSPtr = std::shared_ptr<ProjectedCRS>;
using ProjectedCRSNNPtr = util::nn<ProjectedCRSPtr>;

class CompoundCRS;
using CompoundCRSPtr = std::shared_ptr<CompoundCRS>;
using CompoundCRSNNPtr = util::nn<CompoundCRSPtr>;
} // namespace crs

namespace operation {
class Conversion;
using ConversionPtr = std::shared_ptr<Conversion>;
using ConversionNNPtr = util::nn<ConversionPtr>;

class CoordinateOperation;
using CoordinateOperationPtr = std::shared_ptr<CoordinateOperation>;
using CoordinateOperationNNPtr = util::nn<CoordinateOperationPtr>;
} // namespace operation

namespace io {

class DatabaseContext;
using DatabaseContextPtr = std::shared_ptr<DatabaseContext>;
using DatabaseContextNNPtr = util::nn<DatabaseContextPtr>;

// ---------------------------------------------------------------------------

class WKTFormatter;
using WKTFormatterPtr = std::unique_ptr<WKTFormatter>;
using WKTFormatterNNPtr = util::nn<WKTFormatterPtr>;

class WKTFormatter {
  public:

    enum class PROJ_DLL Version {
        WKT1,
        WKT2
    };

    enum class PROJ_DLL Convention {
        WKT2,
        WKT2_2015 = WKT2,

        WKT2_SIMPLIFIED,
        WKT2_2015_SIMPLIFIED = WKT2_SIMPLIFIED,

        WKT2_2018,

        WKT2_2018_SIMPLIFIED,

        WKT1_GDAL
    };

    PROJ_DLL static WKTFormatterNNPtr
    create(Convention convention = Convention::WKT2);
    PROJ_DLL static WKTFormatterNNPtr create(const WKTFormatterNNPtr &other);
    PROJ_DLL ~WKTFormatter();

    PROJ_DLL WKTFormatter &setMultiLine(bool multiLine);
    PROJ_DLL WKTFormatter &setIndendationWidth(int width);
    PROJ_DLL WKTFormatter &setStrict(bool strict);
    PROJ_DLL bool isStrict() const;

    PROJ_DLL const std::string &toString() const;

    PROJ_PRIVATE :
        PROJ_DLL WKTFormatter &
        setOutputId(bool outputIdIn);

    void enter();
    void leave();

    void startNode(const std::string &keyword, bool hasId);
    void endNode();

    PROJ_DLL WKTFormatter &simulCurNodeHasId();

    void addQuotedString(const char *str);
    void addQuotedString(const std::string &str);
    void add(const std::string &str);
    void add(int number);
    void add(size_t number) = delete;
    void add(double number, int precision = 15);

    void pushOutputUnit(bool outputUnitIn);
    void popOutputUnit();
    bool outputUnit() const;

    void pushOutputId(bool outputIdIn);
    void popOutputId();
    bool outputId() const;

    void pushAxisLinearUnit(const common::UnitOfMeasureNNPtr &unit);
    void popAxisLinearUnit();
    const common::UnitOfMeasureNNPtr &axisLinearUnit() const;

    void pushAxisAngularUnit(const common::UnitOfMeasureNNPtr &unit);
    void popAxisAngularUnit();
    const common::UnitOfMeasureNNPtr &axisAngularUnit() const;

    void setAbridgedTransformation(bool abriged);
    bool abridgedTransformation() const;

    void setUseDerivingConversion(bool useDerivingConversionIn);
    bool useDerivingConversion() const;

    void setTOWGS84Parameters(const std::vector<double> &params);
    const std::vector<double> &getTOWGS84Parameters() const;

    void setVDatumExtension(const std::string &filename);
    const std::string &getVDatumExtension() const;

    void setHDatumExtension(const std::string &filename);
    const std::string &getHDatumExtension() const;

#ifdef unused
    void startInversion();
    void stopInversion();
    bool isInverted() const;
#endif

    bool outputAxisOrder() const;
    bool primeMeridianOmittedIfGreenwich() const;
    bool ellipsoidUnitOmittedIfMetre() const;
    bool forceUNITKeyword() const;
    bool primeMeridianOrParameterUnitOmittedIfSameAsAxis() const;
    bool primeMeridianInDegree() const;
    bool outputCSUnitOnlyOnceIfSame() const;
    Version version() const;
    bool use2018Keywords() const;


  protected:
    explicit WKTFormatter(Convention convention);
    WKTFormatter(const WKTFormatter &other) = delete;

    INLINED_MAKE_UNIQUE

  private:
    PROJ_OPAQUE_PRIVATE_DATA
};

// ---------------------------------------------------------------------------

class PROJStringFormatter;
using PROJStringFormatterPtr = std::unique_ptr<PROJStringFormatter>;
using PROJStringFormatterNNPtr = util::nn<PROJStringFormatterPtr>;

class PROJStringFormatter {
  public:
    enum class PROJ_DLL Convention {
        PROJ_5,

        PROJ_4
    };

    PROJ_DLL static PROJStringFormatterNNPtr
    create(Convention conventionIn = Convention::PROJ_5,
           DatabaseContextPtr dbContext = nullptr);
    PROJ_DLL ~PROJStringFormatter();

    PROJ_DLL void setUseETMercForTMerc(bool flag);

    PROJ_DLL const std::string &toString() const;

    PROJ_PRIVATE :

        PROJ_DLL void
        startInversion();
    PROJ_DLL void stopInversion();
    bool isInverted() const;
    bool getUseETMercForTMerc() const;

    PROJ_DLL void
    ingestPROJString(const std::string &str); // throw ParsingException

    PROJ_DLL void addStep(const char *step);
    PROJ_DLL void addStep(const std::string &step);
    PROJ_DLL void setCurrentStepInverted(bool inverted);
    PROJ_DLL void addParam(const std::string &paramName);
    PROJ_DLL void addParam(const char *paramName, double val);
    PROJ_DLL void addParam(const std::string &paramName, double val);
    PROJ_DLL void addParam(const char *paramName, int val);
    PROJ_DLL void addParam(const std::string &paramName, int val);
    PROJ_DLL void addParam(const char *paramName, const char *val);
    PROJ_DLL void addParam(const char *paramName, const std::string &val);
    PROJ_DLL void addParam(const std::string &paramName, const char *val);
    PROJ_DLL void addParam(const std::string &paramName,
                           const std::string &val);
    PROJ_DLL void addParam(const char *paramName,
                           const std::vector<double> &vals);

    std::set<std::string> getUsedGridNames() const;

    void setTOWGS84Parameters(const std::vector<double> &params);
    const std::vector<double> &getTOWGS84Parameters() const;

    void setVDatumExtension(const std::string &filename);
    const std::string &getVDatumExtension() const;

    void setHDatumExtension(const std::string &filename);
    const std::string &getHDatumExtension() const;

    void setOmitProjLongLatIfPossible(bool omit);
    bool omitProjLongLatIfPossible() const;

    void setOmitZUnitConversion(bool omit);
    bool omitZUnitConversion() const;

    DatabaseContextPtr databaseContext() const;

    Convention convention() const;


  protected:
    explicit PROJStringFormatter(Convention conventionIn,
                                 const DatabaseContextPtr &dbContext);
    PROJStringFormatter(const PROJStringFormatter &other) = delete;

    INLINED_MAKE_UNIQUE

  private:
    PROJ_OPAQUE_PRIVATE_DATA
};

// ---------------------------------------------------------------------------

class FormattingException : public util::Exception {
  public:
    PROJ_DLL explicit FormattingException(const char *message);
    PROJ_DLL explicit FormattingException(const std::string &message);
    PROJ_DLL FormattingException(const FormattingException &other);
    PROJ_DLL virtual ~FormattingException() override;

    static void Throw(const char *msg) PROJ_NO_RETURN;
    static void Throw(const std::string &msg) PROJ_NO_RETURN;
};

// ---------------------------------------------------------------------------

class ParsingException : public util::Exception {
  public:
    PROJ_DLL explicit ParsingException(const char *message);
    PROJ_DLL explicit ParsingException(const std::string &message);
    PROJ_DLL ParsingException(const ParsingException &other);
    PROJ_DLL virtual ~ParsingException() override;
};

// ---------------------------------------------------------------------------

class IWKTExportable {
  public:
    PROJ_DLL virtual ~IWKTExportable();

    PROJ_DLL std::string
    exportToWKT(WKTFormatter *formatter) const; // throw(FormattingException)

    PROJ_PRIVATE :

        virtual void
        _exportToWKT(
            WKTFormatter *formatter) const = 0; // throw(FormattingException)
};

// ---------------------------------------------------------------------------

class IPROJStringExportable;
using IPROJStringExportablePtr = std::shared_ptr<IPROJStringExportable>;
using IPROJStringExportableNNPtr = util::nn<IPROJStringExportablePtr>;

class IPROJStringExportable {
  public:
    PROJ_DLL virtual ~IPROJStringExportable();

    PROJ_DLL std::string exportToPROJString(
        PROJStringFormatter *formatter) const; // throw(FormattingException)

    PROJ_PRIVATE :

        virtual void
        _exportToPROJString(PROJStringFormatter *formatter)
            const = 0; // throw(FormattingException)
};

// ---------------------------------------------------------------------------

class WKTNode;
using WKTNodePtr = std::unique_ptr<WKTNode>;
using WKTNodeNNPtr = util::nn<WKTNodePtr>;

class WKTNode {
  public:
    PROJ_DLL explicit WKTNode(const std::string &valueIn);
    PROJ_DLL ~WKTNode();

    PROJ_DLL const std::string &value() const;
    PROJ_DLL const std::vector<WKTNodeNNPtr> &children() const;

    PROJ_DLL void addChild(WKTNodeNNPtr &&child);
    PROJ_DLL const WKTNodePtr &lookForChild(const std::string &childName,
                                            int occurrence = 0) const noexcept;
    PROJ_DLL int countChildrenOfName(const std::string &childName) const
        noexcept;

    PROJ_DLL std::string toString() const;

    PROJ_DLL static WKTNodeNNPtr createFrom(const std::string &wkt,
                                            size_t indexStart = 0);

  protected:
    static WKTNodeNNPtr createFrom(const std::string &wkt, size_t indexStart,
                                   int recLevel,
                                   size_t &indexEnd); // throw(ParsingException)

  private:
    friend class WKTParser;
    PROJ_OPAQUE_PRIVATE_DATA
};

// ---------------------------------------------------------------------------

PROJ_DLL util::BaseObjectNNPtr
createFromUserInput(const std::string &text,
                    const DatabaseContextPtr &dbContext);

// ---------------------------------------------------------------------------

class WKTParser {
  public:
    PROJ_DLL WKTParser();
    PROJ_DLL ~WKTParser();

    PROJ_DLL WKTParser &setStrict(bool strict);
    PROJ_DLL std::vector<std::string> warningList() const;

    PROJ_DLL util::BaseObjectNNPtr
    createFromWKT(const std::string &wkt); // throw(ParsingException)

  private:
    PROJ_OPAQUE_PRIVATE_DATA
};

// ---------------------------------------------------------------------------

class PROJStringParser {
  public:
    PROJ_DLL PROJStringParser();
    PROJ_DLL ~PROJStringParser();

    PROJ_DLL PROJStringParser &
    attachDatabaseContext(const DatabaseContextPtr &dbContext);

    PROJ_DLL std::vector<std::string> warningList() const;

    PROJ_DLL util::BaseObjectNNPtr createFromPROJString(
        const std::string &projString); // throw(ParsingException)

  private:
    PROJ_OPAQUE_PRIVATE_DATA
};

// ---------------------------------------------------------------------------

class DatabaseContext {
  public:
    PROJ_DLL ~DatabaseContext();

    PROJ_DLL static DatabaseContextNNPtr create();

    PROJ_DLL static DatabaseContextNNPtr
    create(const std::string &databasePath);

    PROJ_DLL static DatabaseContextNNPtr
    create(const std::string &databasePath,
           const std::vector<std::string> &auxiliaryDatabasePaths);

    PROJ_DLL const std::string &getPath() const;

    PROJ_DLL std::set<std::string> getAuthorities() const;

    PROJ_DLL std::vector<std::string> getDatabaseStructure() const;

    PROJ_PRIVATE :
        PROJ_DLL void *
        getSqliteHandle() const;

    PROJ_DLL static DatabaseContextNNPtr create(void *sqlite_handle);

    void attachPJContext(void *pjCtxt);

    bool lookForGridAlternative(const std::string &officialName,
                                std::string &projFilename,
                                std::string &projFormat, bool &inverse);

    PROJ_DLL bool lookForGridInfo(const std::string &projFilename,
                                  std::string &fullFilename,
                                  std::string &packageName, std::string &url,
                                  bool &directDownload, bool &openLicense,
                                  bool &gridAvailable);

  protected:
    DatabaseContext();
    INLINED_MAKE_SHARED
    PROJ_FRIEND(AuthorityFactory);

  private:
    PROJ_OPAQUE_PRIVATE_DATA
    DatabaseContext(const DatabaseContext &) = delete;
    DatabaseContext &operator=(const DatabaseContext &other) = delete;
};

// ---------------------------------------------------------------------------

class AuthorityFactory;
using AuthorityFactoryPtr = std::shared_ptr<AuthorityFactory>;
using AuthorityFactoryNNPtr = util::nn<AuthorityFactoryPtr>;

class AuthorityFactory {
  public:
    PROJ_DLL ~AuthorityFactory();

    PROJ_DLL util::BaseObjectNNPtr createObject(const std::string &code) const;

    PROJ_DLL common::UnitOfMeasureNNPtr
    createUnitOfMeasure(const std::string &code) const;

    PROJ_DLL metadata::ExtentNNPtr createExtent(const std::string &code) const;

    PROJ_DLL datum::PrimeMeridianNNPtr
    createPrimeMeridian(const std::string &code) const;

    PROJ_DLL std::string identifyBodyFromSemiMajorAxis(double a,
                                                       double tolerance) const;

    PROJ_DLL datum::EllipsoidNNPtr
    createEllipsoid(const std::string &code) const;

    PROJ_DLL datum::DatumNNPtr createDatum(const std::string &code) const;

    PROJ_DLL datum::GeodeticReferenceFrameNNPtr
    createGeodeticDatum(const std::string &code) const;

    PROJ_DLL datum::VerticalReferenceFrameNNPtr
    createVerticalDatum(const std::string &code) const;

    PROJ_DLL cs::CoordinateSystemNNPtr
    createCoordinateSystem(const std::string &code) const;

    PROJ_DLL crs::GeodeticCRSNNPtr
    createGeodeticCRS(const std::string &code) const;

    PROJ_DLL crs::GeographicCRSNNPtr
    createGeographicCRS(const std::string &code) const;

    PROJ_DLL crs::VerticalCRSNNPtr
    createVerticalCRS(const std::string &code) const;

    PROJ_DLL operation::ConversionNNPtr
    createConversion(const std::string &code) const;

    PROJ_DLL crs::ProjectedCRSNNPtr
    createProjectedCRS(const std::string &code) const;

    PROJ_DLL crs::CompoundCRSNNPtr
    createCompoundCRS(const std::string &code) const;

    PROJ_DLL crs::CRSNNPtr
    createCoordinateReferenceSystem(const std::string &code) const;

    PROJ_DLL operation::CoordinateOperationNNPtr
    createCoordinateOperation(const std::string &code,
                              bool usePROJAlternativeGridNames) const;

    PROJ_DLL std::vector<operation::CoordinateOperationNNPtr>
    createFromCoordinateReferenceSystemCodes(
        const std::string &sourceCRSCode,
        const std::string &targetCRSCode) const;

    PROJ_DLL const std::string &getAuthority() PROJ_CONST_DECL;

    enum class ObjectType {
        PRIME_MERIDIAN,
        ELLIPSOID,
        DATUM,
        GEODETIC_REFERENCE_FRAME,
        VERTICAL_REFERENCE_FRAME,
        CRS,
        GEODETIC_CRS,
        GEOGRAPHIC_CRS,
        PROJECTED_CRS,
        VERTICAL_CRS,
        COMPOUND_CRS,
        COORDINATE_OPERATION,
        CONVERSION,
        TRANSFORMATION,
        CONCATENATED_OPERATION,
    };

    PROJ_DLL std::set<std::string>
    getAuthorityCodes(const ObjectType &type,
                      bool allowDeprecated = true) const;

    PROJ_DLL std::string getDescriptionText(const std::string &code) const;

    // non-standard
    PROJ_DLL static AuthorityFactoryNNPtr
    create(DatabaseContextNNPtr context, const std::string &authorityName);

    PROJ_DLL DatabaseContextNNPtr databaseContext() const;

    PROJ_DLL std::vector<operation::CoordinateOperationNNPtr>
    createFromCoordinateReferenceSystemCodes(
        const std::string &sourceCRSAuthName, const std::string &sourceCRSCode,
        const std::string &targetCRSAuthName, const std::string &targetCRSCode,
        bool usePROJAlternativeGridNames, bool discardIfMissingGrid) const;

    PROJ_DLL std::vector<operation::CoordinateOperationNNPtr>
    createFromCRSCodesWithIntermediates(
        const std::string &sourceCRSAuthName, const std::string &sourceCRSCode,
        const std::string &targetCRSAuthName, const std::string &targetCRSCode,
        bool usePROJAlternativeGridNames, bool discardIfMissingGrid,
        const std::vector<std::pair<std::string, std::string>>
            &intermediateCRSAuthCodes) const;

  protected:
    AuthorityFactory(const DatabaseContextNNPtr &context,
                     const std::string &authorityName);

    crs::CRSNNPtr createCoordinateReferenceSystem(const std::string &code,
                                                  bool allowCompound) const;

    crs::GeodeticCRSNNPtr createGeodeticCRS(const std::string &code,
                                            bool geographicOnly) const;

    operation::CoordinateOperationNNPtr
    createCoordinateOperation(const std::string &code, bool allowConcatenated,
                              bool usePROJAlternativeGridNames) const;

    INLINED_MAKE_SHARED

  private:
    PROJ_OPAQUE_PRIVATE_DATA
};

// ---------------------------------------------------------------------------

class FactoryException : public util::Exception {
  public:
    PROJ_DLL explicit FactoryException(const char *message);
    PROJ_DLL explicit FactoryException(const std::string &message);
    PROJ_DLL
    FactoryException(const FactoryException &other);
    PROJ_DLL ~FactoryException() override;
};

// ---------------------------------------------------------------------------

class NoSuchAuthorityCodeException : public FactoryException {
  public:
    PROJ_DLL explicit NoSuchAuthorityCodeException(const std::string &message,
                                                   const std::string &authority,
                                                   const std::string &code);
    PROJ_DLL
    NoSuchAuthorityCodeException(const NoSuchAuthorityCodeException &other);
    PROJ_DLL ~NoSuchAuthorityCodeException() override;

    PROJ_DLL const std::string &getAuthority() const;
    PROJ_DLL const std::string &getAuthorityCode() const;

  private:
    PROJ_OPAQUE_PRIVATE_DATA
};

} // namespace io

NS_PROJ_END

#endif // IO_HH_INCLUDED