gdalalgorithm_cpp.h

/******************************************************************************
 *
 * Project:  GDAL
 * Purpose:  GDALAlgorithm C++ API
 * Author:   Even Rouault <even dot rouault at spatialys.com>
 *
 ******************************************************************************
 * Copyright (c) 2025, Even Rouault <even dot rouault at spatialys.com>
 *
 * SPDX-License-Identifier: MIT
 ****************************************************************************/
 
#ifndef GDAL_ALGORITHM_CPP_INCLUDED
#define GDAL_ALGORITHM_CPP_INCLUDED
 
#include "gdalalgorithm_c.h"
 
/************************************************************************/
/************************************************************************/
/*                      GDAL Algorithm C++ API                          */
/************************************************************************/
/************************************************************************/
 
// This header requires C++17
// _MSC_VER >= 1920 : Visual Studio >= 2019
#if defined(__cplusplus) && !defined(CPL_SUPRESS_CPLUSPLUS) &&                 \
    (defined(DOXYGEN_SKIP) || __cplusplus >= 201703L || _MSC_VER >= 1920)
 
#include "cpl_error.h"
 
#include <limits>
#include <functional>
#include <map>
#include <memory>
#include <string>
#include <string_view>
#include <type_traits>
#include <utility>
#include <variant>
#include <vector>
 
class GDALDataset;
class OGRSpatialReference;

constexpr const char *GAAC_COMMON = "Common";

constexpr const char *GAAC_BASE = "Base";

constexpr const char *GAAC_ADVANCED = "Advanced";

constexpr const char *GAAC_ESOTERIC = "Esoteric";

constexpr const char *GAAMDI_REQUIRED_CAPABILITIES = "required_capabilities";

constexpr const char *GAAMDI_VRT_COMPATIBLE = "vrt_compatible";

constexpr const char *GAAMDI_ALLOWED_FORMATS = "allowed_formats";

constexpr const char *GAAMDI_EXCLUDED_FORMATS = "excluded_formats";

constexpr const char *GDAL_ARG_NAME_INPUT = "input";

constexpr const char *GDAL_ARG_NAME_INPUT_FORMAT = "input-format";

constexpr const char *GDAL_ARG_NAME_INPUT_LAYER = "input-layer";

constexpr const char *GDAL_ARG_NAME_OPEN_OPTION = "open-option";

constexpr const char *GDAL_ARG_NAME_OUTPUT = "output";

constexpr const char *GDAL_ARG_NAME_OUTPUT_STRING = "output-string";

constexpr const char *GDAL_ARG_NAME_STDOUT = "stdout";

constexpr const char *GDAL_ARG_NAME_OUTPUT_FORMAT = "output-format";

constexpr const char *GDAL_ARG_NAME_OUTPUT_LAYER = "output-layer";

constexpr const char *GDAL_ARG_NAME_CREATION_OPTION = "creation-option";

constexpr const char *GDAL_ARG_NAME_LAYER_CREATION_OPTION =
    "layer-creation-option";

constexpr const char *GDAL_ARG_NAME_UPDATE = "update";

constexpr const char *GDAL_ARG_NAME_OVERWRITE = "overwrite";

constexpr const char *GDAL_ARG_NAME_OVERWRITE_LAYER = "overwrite-layer";

constexpr const char *GDAL_ARG_NAME_APPEND = "append";

constexpr const char *GDAL_ARG_NAME_READ_ONLY = "read-only";

constexpr const char *GDAL_ARG_NAME_NUM_THREADS = "num-threads";

constexpr const char *GDAL_ARG_NAME_NUM_THREADS_INT_HIDDEN =
    "num-threads-int-hidden";

constexpr const char *GDAL_ARG_NAME_QUIET = "quiet";

constexpr const char *GDAL_ALG_DCAP_RASTER_OR_MULTIDIM_RASTER =
    "raster-or-multidim-raster";
 
/************************************************************************/
/*                           GDALArgDatasetValue                        */
/************************************************************************/

std::string CPL_DLL GDALAlgorithmArgDatasetTypeName(GDALArgDatasetType);
 
class GDALAlgorithmArg;

class CPL_DLL GDALArgDatasetValue final
{
  public:
    GDALArgDatasetValue() = default;

    explicit GDALArgDatasetValue(const std::string &name)
        : m_name(name), m_nameSet(true)
    {
    }

    explicit GDALArgDatasetValue(GDALDataset *poDS);

    GDALArgDatasetValue(GDALArgDatasetValue &&other);

    ~GDALArgDatasetValue();

    bool Close();

    GDALArgDatasetValue &operator=(GDALArgDatasetValue &&other);

    GDALDataset *GetDatasetIncreaseRefCount();

    GDALDataset *GetDatasetRef()
    {
        return m_poDS;
    }

    const GDALDataset *GetDatasetRef() const
    {
        return m_poDS;
    }

    GDALDataset *BorrowDataset()
    {
        GDALDataset *ret = m_poDS;
        m_poDS = nullptr;
        return ret;
    }

    void BorrowDatasetFrom(GDALArgDatasetValue &other)
    {
        Close();
        m_poDS = other.BorrowDataset();
        m_name = other.m_name;
    }

    const std::string &GetName() const
    {
        return m_name;
    }

    bool IsNameSet() const
    {
        return m_nameSet;
    }

    void Set(const std::string &name);

    void Set(std::unique_ptr<GDALDataset> poDS);

    void Set(GDALDataset *poDS);

    void SetFrom(const GDALArgDatasetValue &other);

    void SetDatasetOpenedByAlgorithm()
    {
        m_openedByAlgorithm = true;
    }

    bool HasDatasetBeenOpenedByAlgorithm() const
    {
        return m_openedByAlgorithm;
    }
 
  protected:
    friend class GDALAlgorithm;

    void SetOwnerArgument(GDALAlgorithmArg *arg)
    {
        CPLAssert(!m_ownerArg);
        m_ownerArg = arg;
    }
 
  private:
    GDALAlgorithmArg *m_ownerArg = nullptr;

    GDALDataset *m_poDS = nullptr;

    std::string m_name{};

    bool m_nameSet = false;

    bool m_openedByAlgorithm = false;
 
    GDALArgDatasetValue(const GDALArgDatasetValue &) = delete;
    GDALArgDatasetValue &operator=(const GDALArgDatasetValue &) = delete;
};
 
/************************************************************************/
/*                           GDALAlgorithmArgDecl                       */
/************************************************************************/

class CPL_DLL GDALAlgorithmArgDecl final
{
  public:
    static constexpr int UNBOUNDED = std::numeric_limits<int>::max();

    GDALAlgorithmArgDecl(const std::string &longName, char chShortName,
                         const std::string &description,
                         GDALAlgorithmArgType type);

    GDALAlgorithmArgDecl &AddAlias(const std::string &alias)
    {
        m_aliases.push_back(alias);
        return *this;
    }

    GDALAlgorithmArgDecl &AddShortNameAlias(char shortNameAlias)
    {
        m_shortNameAliases.push_back(shortNameAlias);
        return *this;
    }

    GDALAlgorithmArgDecl &AddHiddenAlias(const std::string &alias)
    {
        m_hiddenAliases.push_back(alias);
        return *this;
    }

    GDALAlgorithmArgDecl &SetPositional()
    {
        m_positional = true;
        return *this;
    }

    GDALAlgorithmArgDecl &SetRequired()
    {
        m_required = true;
        return *this;
    }

    GDALAlgorithmArgDecl &SetMetaVar(const std::string &metaVar)
    {
        m_metaVar = metaVar;
        return *this;
    }

    GDALAlgorithmArgDecl &SetCategory(const std::string &category)
    {
        m_category = category;
        return *this;
    }

    template <class T> GDALAlgorithmArgDecl &SetDefault(const T &value)
    {
        m_hasDefaultValue = true;
        try
        {
            switch (m_type)
            {
                case GAAT_BOOLEAN:
                {
                    if constexpr (std::is_same_v<T, bool>)
                    {
                        m_defaultValue = value;
                        return *this;
                    }
                    break;
                }
 
                case GAAT_STRING:
                {
                    if constexpr (std::is_same_v<T, std::string>)
                    {
                        m_defaultValue = value;
                        return *this;
                    }
                    break;
                }
 
                case GAAT_INTEGER:
                {
                    if constexpr (std::is_same_v<T, int>)
                    {
                        m_defaultValue = value;
                        return *this;
                    }
                    break;
                }
 
                case GAAT_REAL:
                {
                    if constexpr (std::is_assignable_v<double &, T>)
                    {
                        m_defaultValue = static_cast<double>(value);
                        return *this;
                    }
                    break;
                }
 
                case GAAT_STRING_LIST:
                {
                    if constexpr (std::is_same_v<T, std::string>)
                    {
                        m_defaultValue = std::vector<std::string>{value};
                        return *this;
                    }
                    else if constexpr (std::is_same_v<T,
                                                      std::vector<std::string>>)
                    {
                        m_defaultValue = value;
                        return *this;
                    }
                    break;
                }
 
                case GAAT_INTEGER_LIST:
                {
                    if constexpr (std::is_same_v<T, int>)
                    {
                        m_defaultValue = std::vector<int>{value};
                        return *this;
                    }
                    else if constexpr (std::is_same_v<T, std::vector<int>>)
                    {
                        m_defaultValue = value;
                        return *this;
                    }
                    break;
                }
 
                case GAAT_REAL_LIST:
                {
                    if constexpr (std::is_assignable_v<double &, T>)
                    {
                        m_defaultValue =
                            std::vector<double>{static_cast<double>(value)};
                        return *this;
                    }
                    else if constexpr (std::is_same_v<T, std::vector<double>>)
                    {
                        m_defaultValue = value;
                        return *this;
                    }
                    break;
                }
 
                case GAAT_DATASET:
                case GAAT_DATASET_LIST:
                    break;
            }
        }
        catch (const std::bad_variant_access &)
        {
            // should not happen
            // fallthrough
        }
        CPLError(CE_Failure, CPLE_AppDefined,
                 "Argument %s: SetDefault(): unexpected type for value",
                 GetName().c_str());
        return *this;
    }

    GDALAlgorithmArgDecl &SetDefault(const char *value)
    {
        return SetDefault(std::string(value));
    }

    GDALAlgorithmArgDecl &SetMinCount(int count);

    GDALAlgorithmArgDecl &SetMaxCount(int count);

    GDALAlgorithmArgDecl &SetDisplayHintAboutRepetition(bool displayHint)
    {
        m_displayHintAboutRepetition = displayHint;
        return *this;
    }

    GDALAlgorithmArgDecl &SetPackedValuesAllowed(bool allowed)
    {
        m_packedValuesAllowed = allowed;
        return *this;
    }

    GDALAlgorithmArgDecl &SetRepeatedArgAllowed(bool allowed)
    {
        m_repeatedArgAllowed = allowed;
        return *this;
    }

    GDALAlgorithmArgDecl &SetChoices()
    {
        return *this;
    }


    template <
        typename T, typename... U,
        typename std::enable_if<!std::is_same_v<T, std::vector<std::string> &>,
                                bool>::type = true>
    GDALAlgorithmArgDecl &SetChoices(T &&first, U &&...rest)
    {
        m_choices.push_back(std::forward<T>(first));
        SetChoices(std::forward<U>(rest)...);
        return *this;
    }

    GDALAlgorithmArgDecl &SetChoices(const std::vector<std::string> &choices)
    {
        m_choices = choices;
        return *this;
    }

    GDALAlgorithmArgDecl &SetMinValueIncluded(double min)
    {
        m_minVal = min;
        m_minValIsIncluded = true;
        return *this;
    }

    GDALAlgorithmArgDecl &SetMinValueExcluded(double min)
    {
        m_minVal = min;
        m_minValIsIncluded = false;
        return *this;
    }

    GDALAlgorithmArgDecl &SetMaxValueIncluded(double max)
    {
        m_maxVal = max;
        m_maxValIsIncluded = true;
        return *this;
    }

    GDALAlgorithmArgDecl &SetMaxValueExcluded(double max)
    {
        m_maxVal = max;
        m_maxValIsIncluded = false;
        return *this;
    }

    GDALAlgorithmArgDecl &SetMinCharCount(int count)
    {
        m_minCharCount = count;
        return *this;
    }

    GDALAlgorithmArgDecl &SetHiddenChoices()
    {
        return *this;
    }


    template <typename T, typename... U>
    GDALAlgorithmArgDecl &SetHiddenChoices(T &&first, U &&...rest)
    {
        m_hiddenChoices.push_back(std::forward<T>(first));
        SetHiddenChoices(std::forward<U>(rest)...);
        return *this;
    }

    GDALAlgorithmArgDecl &SetHiddenForCLI(bool hiddenForCLI = true)
    {
        m_hiddenForCLI = hiddenForCLI;
        return *this;
    }

    GDALAlgorithmArgDecl &SetHiddenForAPI(bool hiddenForAPI = true)
    {
        m_hiddenForAPI = hiddenForAPI;
        return *this;
    }

    GDALAlgorithmArgDecl &SetHidden()
    {
        m_hiddenForCLI = true;
        m_hiddenForAPI = true;
        return *this;
    }

    GDALAlgorithmArgDecl &SetIsInput(bool isInput = true)
    {
        m_isInput = isInput;
        return *this;
    }

    GDALAlgorithmArgDecl &SetIsOutput(bool isOutput = true)
    {
        m_isOutput = isOutput;
        return *this;
    }

    GDALAlgorithmArgDecl &SetMutualExclusionGroup(const std::string &group)
    {
        m_mutualExclusionGroup = group;
        return *this;
    }

    GDALAlgorithmArgDecl &
    AddMetadataItem(const std::string &name,
                    const std::vector<std::string> &values)
    {
        m_metadata[name] = values;
        return *this;
    }

    GDALAlgorithmArgDecl &SetReadFromFileAtSyntaxAllowed()
    {
        m_readFromFileAtSyntaxAllowed = true;
        return *this;
    }

    GDALAlgorithmArgDecl &SetRemoveSQLCommentsEnabled()
    {
        m_removeSQLComments = true;
        return *this;
    }

    GDALAlgorithmArgDecl &SetAutoOpenDataset(bool autoOpen)
    {
        m_autoOpenDataset = autoOpen;
        return *this;
    }

    GDALAlgorithmArgDecl &SetUserProvided()
    {
        m_userProvided = true;
        return *this;
    }

    inline const std::string &GetName() const
    {
        return m_longName;
    }

    inline const std::string &GetShortName() const
    {
        return m_shortName;
    }

    inline const std::vector<std::string> &GetAliases() const
    {
        return m_aliases;
    }

    inline const std::vector<char> &GetShortNameAliases() const
    {
        return m_shortNameAliases;
    }

    inline const std::string &GetDescription() const
    {
        return m_description;
    }

    inline const std::string &GetMetaVar() const
    {
        return m_metaVar;
    }

    inline const std::string &GetCategory() const
    {
        return m_category;
    }

    inline GDALAlgorithmArgType GetType() const
    {
        return m_type;
    }

    inline const std::vector<std::string> &GetChoices() const
    {
        return m_choices;
    }

    inline const std::vector<std::string> &GetHiddenChoices() const
    {
        return m_hiddenChoices;
    }

    inline std::pair<double, bool> GetMinValue() const
    {
        return {m_minVal, m_minValIsIncluded};
    }

    inline std::pair<double, bool> GetMaxValue() const
    {
        return {m_maxVal, m_maxValIsIncluded};
    }

    inline int GetMinCharCount() const
    {
        return m_minCharCount;
    }

    inline bool IsRequired() const
    {
        return m_required;
    }

    inline int GetMinCount() const
    {
        return m_minCount;
    }

    inline int GetMaxCount() const
    {
        return m_maxCount;
    }

    inline bool GetDisplayHintAboutRepetition() const
    {
        return m_displayHintAboutRepetition;
    }

    inline bool GetPackedValuesAllowed() const
    {
        return m_packedValuesAllowed;
    }

    inline bool GetRepeatedArgAllowed() const
    {
        return m_repeatedArgAllowed;
    }

    inline bool IsPositional() const
    {
        return m_positional;
    }

    inline bool HasDefaultValue() const
    {
        return m_hasDefaultValue;
    }

    inline bool IsHidden() const
    {
        return m_hiddenForCLI && m_hiddenForAPI;
    }

    inline bool IsHiddenForCLI() const
    {
        return m_hiddenForCLI;
    }

    inline bool IsOnlyForCLI() const
        CPL_WARN_DEPRECATED("Use IsHiddenForAPI() instead")
    {
        return m_hiddenForAPI;
    }

    inline bool IsHiddenForAPI() const
    {
        return m_hiddenForAPI;
    }

    inline bool IsInput() const
    {
        return m_isInput;
    }

    inline bool IsOutput() const
    {
        return m_isOutput;
    }

    inline const std::string &GetMutualExclusionGroup() const
    {
        return m_mutualExclusionGroup;
    }

    inline bool IsReadFromFileAtSyntaxAllowed() const
    {
        return m_readFromFileAtSyntaxAllowed;
    }

    bool IsRemoveSQLCommentsEnabled() const
    {
        return m_removeSQLComments;
    }

    bool AutoOpenDataset() const
    {
        return m_autoOpenDataset;
    }

    bool IsUserProvided() const
    {
        return m_userProvided;
    }

    inline const std::map<std::string, std::vector<std::string>>
    GetMetadata() const
    {
        return m_metadata;
    }

    inline const std::vector<std::string> *
    GetMetadataItem(const std::string &name) const
    {
        const auto iter = m_metadata.find(name);
        return iter == m_metadata.end() ? nullptr : &(iter->second);
    }

    template <class T> inline const T &GetDefault() const
    {
        return std::get<T>(m_defaultValue);
    }

    GDALArgDatasetType GetDatasetType() const
    {
        return m_datasetType;
    }

    void SetDatasetType(GDALArgDatasetType type)
    {
        m_datasetType = type;
    }

    int GetDatasetInputFlags() const
    {
        return m_datasetInputFlags;
    }

    int GetDatasetOutputFlags() const
    {
        return m_datasetOutputFlags;
    }

    void SetDatasetInputFlags(int flags)
    {
        m_datasetInputFlags = flags;
    }

    void SetDatasetOutputFlags(int flags)
    {
        m_datasetOutputFlags = flags;
    }
 
  private:
    const std::string m_longName;
    const std::string m_shortName;
    const std::string m_description;
    const GDALAlgorithmArgType m_type;
    std::string m_category = GAAC_BASE;
    std::string m_metaVar{};
    std::string m_mutualExclusionGroup{};
    int m_minCount = 0;
    int m_maxCount = 0;
    bool m_required = false;
    bool m_positional = false;
    bool m_hasDefaultValue = false;
    bool m_hiddenForCLI = false;
    bool m_hiddenForAPI = false;
    bool m_isInput = true;
    bool m_isOutput = false;
    bool m_packedValuesAllowed = true;
    bool m_repeatedArgAllowed = true;
    bool m_displayHintAboutRepetition = true;
    bool m_readFromFileAtSyntaxAllowed = false;
    bool m_removeSQLComments = false;
    bool m_autoOpenDataset = true;
    bool m_userProvided = false;
    std::map<std::string, std::vector<std::string>> m_metadata{};
    std::vector<std::string> m_aliases{};
    std::vector<std::string> m_hiddenAliases{};
    std::vector<char> m_shortNameAliases{};
    std::vector<std::string> m_choices{};
    std::vector<std::string> m_hiddenChoices{};
    std::variant<bool, std::string, int, double, std::vector<std::string>,
                 std::vector<int>, std::vector<double>>
        m_defaultValue{};
    double m_minVal = std::numeric_limits<double>::quiet_NaN();
    double m_maxVal = std::numeric_limits<double>::quiet_NaN();
    bool m_minValIsIncluded = false;
    bool m_maxValIsIncluded = false;
    int m_minCharCount = 0;
    GDALArgDatasetType m_datasetType =
        GDAL_OF_RASTER | GDAL_OF_VECTOR | GDAL_OF_MULTIDIM_RASTER;

    int m_datasetInputFlags = GADV_NAME | GADV_OBJECT;

    int m_datasetOutputFlags = GADV_OBJECT;
};
 
/************************************************************************/
/*                           GDALAlgorithmArg                           */
/************************************************************************/
 
class GDALAlgorithm;

class CPL_DLL GDALAlgorithmArg /* non-final */
{
  public:
    template <class T>
    GDALAlgorithmArg(const GDALAlgorithmArgDecl &decl, T *pValue)
        : m_decl(decl), m_value(pValue)
    {
        if constexpr (!std::is_same_v<T, GDALArgDatasetValue> &&
                      !std::is_same_v<T, std::vector<GDALArgDatasetValue>>)
        {
            if (decl.HasDefaultValue())
            {
                try
                {
                    *std::get<T *>(m_value) = decl.GetDefault<T>();
                }
                catch (const std::bad_variant_access &e)
                {
                    // I don't think that can happen, but Coverity Scan thinks
                    // so
                    CPLError(CE_Failure, CPLE_AppDefined,
                             "*std::get<T *>(m_value) = decl.GetDefault<T>() "
                             "failed: %s",
                             e.what());
                }
            }
        }
    }

    virtual ~GDALAlgorithmArg();

    const GDALAlgorithmArgDecl &GetDeclaration() const
    {
        return m_decl;
    }

    inline const std::string &GetName() const
    {
        return m_decl.GetName();
    }

    inline const std::string &GetShortName() const
    {
        return m_decl.GetShortName();
    }

    inline const std::vector<std::string> &GetAliases() const
    {
        return m_decl.GetAliases();
    }

    inline const std::vector<char> &GetShortNameAliases() const
    {
        return m_decl.GetShortNameAliases();
    }

    inline const std::string &GetDescription() const
    {
        return m_decl.GetDescription();
    }

    inline const std::string &GetMetaVar() const
    {
        return m_decl.GetMetaVar();
    }

    inline GDALAlgorithmArgType GetType() const
    {
        return m_decl.GetType();
    }

    inline const std::string &GetCategory() const
    {
        return m_decl.GetCategory();
    }

    inline bool IsRequired() const
    {
        return m_decl.IsRequired();
    }

    inline int GetMinCount() const
    {
        return m_decl.GetMinCount();
    }

    inline int GetMaxCount() const
    {
        return m_decl.GetMaxCount();
    }

    inline bool GetDisplayHintAboutRepetition() const
    {
        return m_decl.GetDisplayHintAboutRepetition();
    }

    inline bool GetPackedValuesAllowed() const
    {
        return m_decl.GetPackedValuesAllowed();
    }

    inline bool GetRepeatedArgAllowed() const
    {
        return m_decl.GetRepeatedArgAllowed();
    }

    inline bool IsPositional() const
    {
        return m_decl.IsPositional();
    }

    inline const std::vector<std::string> &GetChoices() const
    {
        return m_decl.GetChoices();
    }

    inline const std::vector<std::string> &GetHiddenChoices() const
    {
        return m_decl.GetHiddenChoices();
    }

    inline std::vector<std::string>
    GetAutoCompleteChoices(const std::string &currentValue) const
    {
        if (m_autoCompleteFunction)
            return m_autoCompleteFunction(currentValue);
        return {};
    }

    inline std::pair<double, bool> GetMinValue() const
    {
        return m_decl.GetMinValue();
    }

    inline std::pair<double, bool> GetMaxValue() const
    {
        return m_decl.GetMaxValue();
    }

    inline int GetMinCharCount() const
    {
        return m_decl.GetMinCharCount();
    }

    inline bool IsExplicitlySet() const
    {
        return m_explicitlySet;
    }

    inline bool HasDefaultValue() const
    {
        return m_decl.HasDefaultValue();
    }

    inline bool IsHidden() const
    {
        return m_decl.IsHidden();
    }

    inline bool IsHiddenForCLI() const
    {
        return m_decl.IsHiddenForCLI();
    }

    inline bool IsOnlyForCLI() const
        CPL_WARN_DEPRECATED("Use IsHiddenForAPI() instead")
    {
        return m_decl.IsHiddenForAPI();
    }

    inline bool IsHiddenForAPI() const
    {
        return m_decl.IsHiddenForAPI();
    }

    inline bool IsInput() const
    {
        return m_decl.IsInput();
    }

    inline bool IsOutput() const
    {
        return m_decl.IsOutput();
    }

    inline bool IsReadFromFileAtSyntaxAllowed() const
    {
        return m_decl.IsReadFromFileAtSyntaxAllowed();
    }

    inline bool IsRemoveSQLCommentsEnabled() const
    {
        return m_decl.IsRemoveSQLCommentsEnabled();
    }

    inline const std::string &GetMutualExclusionGroup() const
    {
        return m_decl.GetMutualExclusionGroup();
    }

    inline const std::map<std::string, std::vector<std::string>>
    GetMetadata() const
    {
        return m_decl.GetMetadata();
    }

    inline const std::vector<std::string> *
    GetMetadataItem(const std::string &name) const
    {
        return m_decl.GetMetadataItem(name);
    }

    template <class T> inline const T &GetDefault() const
    {
        return m_decl.GetDefault<T>();
    }

    inline bool AutoOpenDataset() const
    {
        return m_decl.AutoOpenDataset();
    }

    inline bool IsUserProvided() const
    {
        return m_decl.IsUserProvided();
    }

    inline GDALArgDatasetType GetDatasetType() const
    {
        return m_decl.GetDatasetType();
    }

    inline int GetDatasetInputFlags() const
    {
        return m_decl.GetDatasetInputFlags();
    }

    inline int GetDatasetOutputFlags() const
    {
        return m_decl.GetDatasetOutputFlags();
    }

    template <class T> inline T &Get()
    {
        return *(std::get<T *>(m_value));
    }

    template <class T> inline const T &Get() const
    {
        return *(std::get<T *>(m_value));
    }

    bool Set(bool value);

    bool Set(const std::string &value);

    bool Set(const char *value)
    {
        return Set(std::string(value ? value : ""));
    }

    bool Set(GDALDataType dt)
    {
        return Set(GDALGetDataTypeName(dt));
    }

    bool Set(const OGRSpatialReference &);

    bool Set(int value);

    bool Set(double value);

    bool Set(GDALDataset *ds);

    bool Set(std::unique_ptr<GDALDataset> ds);

    bool SetDatasetName(const std::string &name);

    bool SetFrom(const GDALArgDatasetValue &other);

    bool Set(const std::vector<std::string> &value);

    bool Set(const std::vector<int> &value);

    bool Set(const std::vector<double> &value);

    bool Set(std::vector<GDALArgDatasetValue> &&value);

    inline GDALAlgorithmArg &operator=(bool value)
    {
        Set(value);
        return *this;
    }

    inline GDALAlgorithmArg &operator=(int value)
    {
        Set(value);
        return *this;
    }

    inline GDALAlgorithmArg &operator=(double value)
    {
        Set(value);
        return *this;
    }

    inline GDALAlgorithmArg &operator=(const std::string &value)
    {
        Set(value);
        return *this;
    }

    inline GDALAlgorithmArg &operator=(const char *value)
    {
        Set(value);
        return *this;
    }

    inline GDALAlgorithmArg &operator=(GDALDataType value)
    {
        Set(value);
        return *this;
    }

    inline GDALAlgorithmArg &operator=(const OGRSpatialReference &value)
    {
        Set(value);
        return *this;
    }

    inline GDALAlgorithmArg &operator=(const std::vector<int> &value)
    {
        Set(value);
        return *this;
    }

    inline GDALAlgorithmArg &operator=(const std::vector<double> &value)
    {
        Set(value);
        return *this;
    }

    inline GDALAlgorithmArg &operator=(const std::vector<std::string> &value)
    {
        Set(value);
        return *this;
    }

    inline GDALAlgorithmArg &operator=(GDALDataset *value)
    {
        Set(value);
        return *this;
    }

    GDALAlgorithmArg &operator=(std::unique_ptr<GDALDataset> value);

    bool SetFrom(const GDALAlgorithmArg &other);

    void SetSkipIfAlreadySet(bool skip = true)
    {
        m_skipIfAlreadySet = skip;
    }

    bool SkipIfAlreadySet() const
    {
        return m_skipIfAlreadySet;
    }

    bool Serialize(std::string &serializedArg, bool absolutePath = false) const;

    static std::string GetEscapedString(const std::string &s);

    void NotifyValueSet()
    {
        m_explicitlySet = true;
    }

 
  protected:
    friend class GDALAlgorithm;
    GDALAlgorithmArgDecl m_decl;
    std::variant<bool *, std::string *, int *, double *, GDALArgDatasetValue *,
                 std::vector<std::string> *, std::vector<int> *,
                 std::vector<double> *, std::vector<GDALArgDatasetValue> *>
        m_value{};
    std::vector<std::function<void()>> m_actions{};
    std::vector<std::function<bool()>> m_validationActions{};
    std::function<std::vector<std::string>(const std::string &)>
        m_autoCompleteFunction{};
    GDALAlgorithm *m_owner = nullptr;
 
  private:
    bool m_skipIfAlreadySet = false;
    bool m_explicitlySet = false;
 
    template <class T> bool SetInternal(const T &value)
    {
        m_explicitlySet = true;
        *std::get<T *>(m_value) = value;
        return RunAllActions();
    }
 
    bool ProcessString(std::string &value) const;
 
    bool RunAllActions();
    void RunActions();
    bool RunValidationActions();
    std::string ValidateChoice(const std::string &value) const;
    bool ValidateIntRange(int val) const;
    bool ValidateRealRange(double val) const;
 
    void ReportError(CPLErr eErrClass, CPLErrorNum err_no, const char *fmt,
                     ...) const CPL_PRINT_FUNC_FORMAT(4, 5);
 
    CPL_DISALLOW_COPY_ASSIGN(GDALAlgorithmArg)
};
 
/************************************************************************/
/*                     GDALInConstructionAlgorithmArg                   */
/************************************************************************/

namespace test_gdal_algorithm
{
struct test_gdal_algorithm;
}


class CPL_DLL GDALInConstructionAlgorithmArg final : public GDALAlgorithmArg
{
    friend struct test_gdal_algorithm::test_gdal_algorithm;
 
  public:
    template <class T>
    GDALInConstructionAlgorithmArg(GDALAlgorithm *owner,
                                   const GDALAlgorithmArgDecl &decl, T *pValue)
        : GDALAlgorithmArg(decl, pValue)
    {
        m_owner = owner;
    }

    ~GDALInConstructionAlgorithmArg() override;

    GDALInConstructionAlgorithmArg &AddAlias(const std::string &alias);

    GDALInConstructionAlgorithmArg &AddHiddenAlias(const std::string &alias);

    GDALInConstructionAlgorithmArg &AddShortNameAlias(char shortNameAlias);

    GDALInConstructionAlgorithmArg &SetPositional();

    GDALInConstructionAlgorithmArg &SetRequired()
    {
        m_decl.SetRequired();
        return *this;
    }

    GDALInConstructionAlgorithmArg &SetMetaVar(const std::string &metaVar)
    {
        m_decl.SetMetaVar(metaVar);
        return *this;
    }

    GDALInConstructionAlgorithmArg &SetCategory(const std::string &category)
    {
        m_decl.SetCategory(category);
        return *this;
    }

    template <class T>
    GDALInConstructionAlgorithmArg &SetDefault(const T &value)
    {
        m_decl.SetDefault(value);
 
        if constexpr (!std::is_same_v<T, GDALArgDatasetValue> &&
                      !std::is_same_v<T, std::vector<GDALArgDatasetValue>>)
        {
            try
            {
                switch (m_decl.GetType())
                {
                    case GAAT_BOOLEAN:
                        *std::get<bool *>(m_value) = m_decl.GetDefault<bool>();
                        break;
                    case GAAT_STRING:
                        *std::get<std::string *>(m_value) =
                            m_decl.GetDefault<std::string>();
                        break;
                    case GAAT_INTEGER:
                        *std::get<int *>(m_value) = m_decl.GetDefault<int>();
                        break;
                    case GAAT_REAL:
                        *std::get<double *>(m_value) =
                            m_decl.GetDefault<double>();
                        break;
                    case GAAT_STRING_LIST:
                        *std::get<std::vector<std::string> *>(m_value) =
                            m_decl.GetDefault<std::vector<std::string>>();
                        break;
                    case GAAT_INTEGER_LIST:
                        *std::get<std::vector<int> *>(m_value) =
                            m_decl.GetDefault<std::vector<int>>();
                        break;
                    case GAAT_REAL_LIST:
                        *std::get<std::vector<double> *>(m_value) =
                            m_decl.GetDefault<std::vector<double>>();
                        break;
                    case GAAT_DATASET:
                    case GAAT_DATASET_LIST:
                        break;
                }
            }
            catch (const std::bad_variant_access &)
            {
                // I don't think that can happen, but Coverity Scan thinks so
                CPLError(CE_Failure, CPLE_AppDefined,
                         "Argument %s: SetDefault(): unexpected type for value",
                         GetName().c_str());
            }
        }
        return *this;
    }

    GDALInConstructionAlgorithmArg &SetDefault(const char *value)
    {
        return SetDefault(std::string(value));
    }

    GDALInConstructionAlgorithmArg &SetMinCount(int count)
    {
        m_decl.SetMinCount(count);
        return *this;
    }

    GDALInConstructionAlgorithmArg &SetMaxCount(int count)
    {
        m_decl.SetMaxCount(count);
        return *this;
    }

    GDALInConstructionAlgorithmArg &
    SetDisplayHintAboutRepetition(bool displayHint)
    {
        m_decl.SetDisplayHintAboutRepetition(displayHint);
        return *this;
    }

    GDALInConstructionAlgorithmArg &SetPackedValuesAllowed(bool allowed)
    {
        m_decl.SetPackedValuesAllowed(allowed);
        return *this;
    }

    GDALInConstructionAlgorithmArg &SetRepeatedArgAllowed(bool allowed)
    {
        m_decl.SetRepeatedArgAllowed(allowed);
        return *this;
    }

    template <
        typename T, typename... U,
        typename std::enable_if<!std::is_same_v<T, std::vector<std::string> &>,
                                bool>::type = true>
    GDALInConstructionAlgorithmArg &SetChoices(T &&first, U &&...rest)
    {
        m_decl.SetChoices(std::forward<T>(first), std::forward<U>(rest)...);
        return *this;
    }

    GDALInConstructionAlgorithmArg &
    SetChoices(const std::vector<std::string> &choices)
    {
        m_decl.SetChoices(choices);
        return *this;
    }

    template <typename T, typename... U>
    GDALInConstructionAlgorithmArg &SetHiddenChoices(T &&first, U &&...rest)
    {
        m_decl.SetHiddenChoices(std::forward<T>(first),
                                std::forward<U>(rest)...);
        return *this;
    }

    GDALInConstructionAlgorithmArg &SetMinValueIncluded(double min)
    {
        m_decl.SetMinValueIncluded(min);
        return *this;
    }

    GDALInConstructionAlgorithmArg &SetMinValueExcluded(double min)
    {
        m_decl.SetMinValueExcluded(min);
        return *this;
    }

    GDALInConstructionAlgorithmArg &SetMaxValueIncluded(double max)
    {
        m_decl.SetMaxValueIncluded(max);
        return *this;
    }

    GDALInConstructionAlgorithmArg &SetMaxValueExcluded(double max)
    {
        m_decl.SetMaxValueExcluded(max);
        return *this;
    }

    GDALInConstructionAlgorithmArg &SetMinCharCount(int count)
    {
        m_decl.SetMinCharCount(count);
        return *this;
    }

    GDALInConstructionAlgorithmArg &SetHidden()
    {
        m_decl.SetHidden();
        return *this;
    }

    GDALInConstructionAlgorithmArg &SetHiddenForCLI(bool hiddenForCLI = true)
    {
        m_decl.SetHiddenForCLI(hiddenForCLI);
        return *this;
    }

    GDALInConstructionAlgorithmArg &SetHiddenForAPI(bool hiddenForAPI = true)
    {
        m_decl.SetHiddenForAPI(hiddenForAPI);
        return *this;
    }

    GDALInConstructionAlgorithmArg &SetIsInput(bool isInput = true)
    {
        m_decl.SetIsInput(isInput);
        return *this;
    }

    GDALInConstructionAlgorithmArg &SetIsOutput(bool isOutput = true)
    {
        m_decl.SetIsOutput(isOutput);
        return *this;
    }

    GDALInConstructionAlgorithmArg &SetReadFromFileAtSyntaxAllowed()
    {
        m_decl.SetReadFromFileAtSyntaxAllowed();
        return *this;
    }

    GDALInConstructionAlgorithmArg &SetRemoveSQLCommentsEnabled()
    {
        m_decl.SetRemoveSQLCommentsEnabled();
        return *this;
    }

    GDALInConstructionAlgorithmArg &SetAutoOpenDataset(bool autoOpen)
    {
        m_decl.SetAutoOpenDataset(autoOpen);
        return *this;
    }

    GDALInConstructionAlgorithmArg &
    SetMutualExclusionGroup(const std::string &group)
    {
        m_decl.SetMutualExclusionGroup(group);
        return *this;
    }

    GDALInConstructionAlgorithmArg &
    AddMetadataItem(const std::string &name,
                    const std::vector<std::string> &values)
    {
        m_decl.AddMetadataItem(name, values);
        return *this;
    }

    GDALInConstructionAlgorithmArg &
    SetDatasetType(GDALArgDatasetType datasetType)
    {
        m_decl.SetDatasetType(datasetType);
        return *this;
    }

    GDALInConstructionAlgorithmArg &SetDatasetInputFlags(int flags)
    {
        m_decl.SetDatasetInputFlags(flags);
        return *this;
    }

    GDALInConstructionAlgorithmArg &SetDatasetOutputFlags(int flags)
    {
        m_decl.SetDatasetOutputFlags(flags);
        return *this;
    }

    GDALInConstructionAlgorithmArg &AddAction(std::function<void()> f)
    {
        m_actions.push_back(f);
        return *this;
    }

    GDALInConstructionAlgorithmArg &AddValidationAction(std::function<bool()> f)
    {
        m_validationActions.push_back(f);
        return *this;
    }

    GDALInConstructionAlgorithmArg &SetAutoCompleteFunction(
        std::function<std::vector<std::string>(const std::string &)> f)
    {
        m_autoCompleteFunction = std::move(f);
        return *this;
    }

    GDALInConstructionAlgorithmArg &
    SetIsCRSArg(bool noneAllowed = false,
                const std::vector<std::string> &specialValues =
                    std::vector<std::string>());

    GDALInConstructionAlgorithmArg &SetUserProvided()
    {
        m_decl.SetUserProvided();
        return *this;
    }
};
 
/************************************************************************/
/*                      GDALAlgorithmRegistry                           */
/************************************************************************/

class CPL_DLL GDALAlgorithmRegistry
{
  public:
    static constexpr const char *HIDDEN_ALIAS_SEPARATOR = "==hide==";
 
    virtual ~GDALAlgorithmRegistry();

    class AlgInfo
    {
      public:
        std::string m_name{};
        std::vector<std::string> m_aliases{};
#ifdef DOXYGEN_SKIP
        std::function m_creationFunc{};
#else
        std::function<std::unique_ptr<GDALAlgorithm>(void)> m_creationFunc{};
#endif
    };

    template <class MyAlgorithm> bool Register()
    {
        AlgInfo info;
        info.m_name = MyAlgorithm::NAME;
        info.m_aliases = MyAlgorithm::GetAliasesStatic();
        info.m_creationFunc = []() -> std::unique_ptr<GDALAlgorithm>
        { return std::make_unique<MyAlgorithm>(); };
        return Register(info);
    }

    bool Register(const AlgInfo &info);

    std::vector<std::string> GetNames() const;

    std::unique_ptr<GDALAlgorithm> Instantiate(const std::string &name) const;

    std::unique_ptr<GDALAlgorithm>
    Instantiate(const std::vector<std::string> &path) const;

    template <typename... V>
    inline std::unique_ptr<GDALAlgorithm> Instantiate(const std::string &first,
                                                      V &&...rest)
    {
        std::vector<std::string> path;
        return InstantiateInternal(path, first, std::forward<V>(rest)...);
    }

    const AlgInfo *GetInfo(const std::string &name) const
    {
        auto iter = m_mapNameToInfo.find(name);
        return iter != m_mapNameToInfo.end() ? &(iter->second) : nullptr;
    }

    bool empty() const
    {
        return m_mapNameToInfo.empty();
    }
 
  protected:
    virtual std::unique_ptr<GDALAlgorithm>
    InstantiateTopLevel(const std::string &name) const;
 
  private:
    std::map<std::string, AlgInfo> m_mapNameToInfo{};
    std::map<std::string, AlgInfo> m_mapAliasToInfo{};
    std::map<std::string, AlgInfo> m_mapHiddenAliasToInfo{};
 
    std::unique_ptr<GDALAlgorithm>
    InstantiateInternal(std::vector<std::string> &path);
 
    template <typename... V>
    std::unique_ptr<GDALAlgorithm>
    InstantiateInternal(std::vector<std::string> &path,
                        const std::string &first, V &&...rest)
    {
        path.push_back(first);
        return InstantiateInternal(path, std::forward<V>(rest)...);
    }
};
 
/************************************************************************/
/*                            GDALAlgorithm                             */
/************************************************************************/

 
/* abstract */ class CPL_DLL GDALAlgorithm
{
    friend struct test_gdal_algorithm::test_gdal_algorithm;
 
  public:
    virtual ~GDALAlgorithm();

    const std::string &GetName() const
    {
        return m_name;
    }

    const std::string &GetDescription() const
    {
        return m_description;
    }

    const std::string &GetLongDescription() const
    {
        return m_longDescription;
    }

    const std::string &GetHelpURL() const
    {
        return m_helpURL;
    }

    const std::string &GetHelpFullURL() const
    {
        return m_helpFullURL;
    }

    bool IsHidden() const
    {
        return m_hidden;
    }

    bool HasSubAlgorithms() const;

    std::vector<std::string> GetSubAlgorithmNames() const;

    std::unique_ptr<GDALAlgorithm>
    InstantiateSubAlgorithm(const std::string &name,
                            bool suggestionAllowed = true) const;

    const std::vector<std::unique_ptr<GDALAlgorithmArg>> &GetArgs() const
    {
        return m_args;
    }

    std::vector<std::unique_ptr<GDALAlgorithmArg>> &GetArgs()
    {
        return m_args;
    }

    std::string GetSuggestionForArgumentName(const std::string &osName) const;

    GDALAlgorithmArg *GetArg(const std::string &osName,
                             bool suggestionAllowed = false)
    {
        return GetArg(osName, suggestionAllowed, /* isConst = */ false);
    }

    GDALAlgorithmArg &operator[](const std::string &osName)
    {
        auto alg = GetArg(osName, false);
        if (!alg)
        {
            ReportError(CE_Failure, CPLE_AppDefined,
                        "Argument '%s' does not exist", osName.c_str());
            return m_dummyArg;
        }
        return *alg;
    }

    const GDALAlgorithmArg *GetArg(const std::string &osName,
                                   bool suggestionAllowed = false) const
    {
        return const_cast<GDALAlgorithm *>(this)->GetArg(
            osName, suggestionAllowed, /* isConst = */ true);
    }

    const GDALAlgorithmArg &operator[](const std::string &osName) const
    {
        const auto alg = GetArg(osName, false);
        if (!alg)
        {
            ReportError(CE_Failure, CPLE_AppDefined,
                        "Argument '%s' does not exist", osName.c_str());
            return m_dummyArg;
        }
        return *alg;
    }

    void SetCallPath(const std::vector<std::string> &path)
    {
        m_callPath = path;
    }

    void SetParseForAutoCompletion()
    {
        m_parseForAutoCompletion = true;
    }

    void SetReferencePathForRelativePaths(const std::string &referencePath)
    {
        m_referencePath = referencePath;
    }

    const std::string &GetReferencePathForRelativePaths() const
    {
        return m_referencePath;
    }

    bool SupportsStreamedOutput() const
    {
        return m_supportsStreamedOutput;
    }

    void SetExecutionForStreamedOutput()
    {
        m_executionForStreamOutput = true;
    }

    virtual bool
    ParseCommandLineArguments(const std::vector<std::string> &args);

    virtual bool ValidateArguments();

    bool Run(GDALProgressFunc pfnProgress = nullptr,
             void *pProgressData = nullptr);

    virtual bool Finalize();

    struct UsageOptions
    {
        bool isPipelineStep;
        size_t maxOptLen;
        bool isPipelineMain;
 
        UsageOptions()
            : isPipelineStep(false), maxOptLen(0), isPipelineMain(false)
        {
        }
    };

    virtual std::string
    GetUsageForCLI(bool shortUsage,
                   const UsageOptions &usageOptions = UsageOptions()) const;

    virtual std::string GetUsageAsJSON() const;

    GDALAlgorithm &GetActualAlgorithm()
    {
        if (m_selectedSubAlg)
            return m_selectedSubAlg->GetActualAlgorithm();
        return *this;
    }

    bool IsHelpRequested() const
    {
        return m_helpRequested;
    }

    bool IsJSONUsageRequested() const
    {
        return m_JSONUsageRequested;
    }

    bool IsProgressBarRequested() const
    {
        if (m_selectedSubAlg)
            return m_selectedSubAlg->IsProgressBarRequested();
        return m_progressBarRequested;
    }

    const std::vector<std::string> &GetAliases() const
    {
        return m_aliases;
    }


    static std::vector<std::string> GetAliasesStatic()
    {
        return {};
    }


    bool PropagateSpecialActionTo(GDALAlgorithm *target)
    {
        target->m_calledFromCommandLine = m_calledFromCommandLine;
        target->m_progressBarRequested = m_progressBarRequested;
        target->m_quiet = m_quiet;
        if (m_specialActionRequested)
        {
            target->m_specialActionRequested = m_specialActionRequested;
            target->m_helpRequested = m_helpRequested;
            target->m_helpDocRequested = m_helpDocRequested;
            target->m_JSONUsageRequested = m_JSONUsageRequested;
            return true;
        }
        return false;
    }

    virtual std::vector<std::string>
    GetAutoComplete(std::vector<std::string> &args, bool lastWordIsComplete,
                    bool showAllOptions);

    void SetCalledFromCommandLine()
    {
        m_calledFromCommandLine = true;
    }

    bool IsCalledFromCommandLine() const
    {
        return m_calledFromCommandLine;
    }

    virtual bool HasOutputString() const;

    static bool SaveGDALG(const std::string &filename, std::string &outString,
                          const std::string &commandLine);

    void ReportError(CPLErr eErrClass, CPLErrorNum err_no, const char *fmt,
                     ...) const CPL_PRINT_FUNC_FORMAT(4, 5);
 
  protected:
    friend class GDALInConstructionAlgorithmArg;
    friend class GDALRasterReprojectUtils;

    GDALAlgorithm *m_selectedSubAlg = nullptr;

    std::vector<std::string> m_callPath{};

    std::string m_longDescription{};

    bool m_progressBarRequested = true;

    bool m_quiet = false;

    bool m_skipValidationInParseCommandLine = false;
 
    friend class GDALAlgorithmRegistry;  // to set m_aliases
    std::vector<std::string> m_aliases{};

    bool m_supportsStreamedOutput = false;

    bool m_executionForStreamOutput = false;

    bool m_hidden = false;

    std::map<std::string, GDALDataset *> m_oMapDatasetNameToDataset{};

    GDALAlgorithm(const std::string &name, const std::string &description,
                  const std::string &helpURL);

    bool ProcessDatasetArg(GDALAlgorithmArg *arg, GDALAlgorithm *algForOutput);

    template <class MyAlgorithm> bool RegisterSubAlgorithm()
    {
        return m_subAlgRegistry.Register<MyAlgorithm>();
    }

    bool RegisterSubAlgorithm(const GDALAlgorithmRegistry::AlgInfo &info)
    {
        return m_subAlgRegistry.Register(info);
    }

    void AllowArbitraryLongNameArgs()
    {
        m_arbitraryLongNameArgsAllowed = true;
    }

    GDALInConstructionAlgorithmArg &AddArg(const std::string &longName,
                                           char chShortName,
                                           const std::string &helpMessage,
                                           bool *pValue);

    GDALInConstructionAlgorithmArg &AddArg(const std::string &longName,
                                           char chShortName,
                                           const std::string &helpMessage,
                                           std::string *pValue);

    GDALInConstructionAlgorithmArg &AddArg(const std::string &longName,
                                           char chShortName,
                                           const std::string &helpMessage,
                                           int *pValue);

    GDALInConstructionAlgorithmArg &AddArg(const std::string &longName,
                                           char chShortName,
                                           const std::string &helpMessage,
                                           double *pValue);

    static void
    SetAutoCompleteFunctionForFilename(GDALInConstructionAlgorithmArg &arg,
                                       GDALArgDatasetType type);

    GDALInConstructionAlgorithmArg &
    AddArg(const std::string &longName, char chShortName,
           const std::string &helpMessage, GDALArgDatasetValue *pValue,
           GDALArgDatasetType type = GDAL_OF_RASTER | GDAL_OF_VECTOR |
                                     GDAL_OF_MULTIDIM_RASTER);

    GDALInConstructionAlgorithmArg &AddArg(const std::string &longName,
                                           char chShortName,
                                           const std::string &helpMessage,
                                           std::vector<std::string> *pValue);

    GDALInConstructionAlgorithmArg &AddArg(const std::string &longName,
                                           char chShortName,
                                           const std::string &helpMessage,
                                           std::vector<int> *pValue);

    GDALInConstructionAlgorithmArg &AddArg(const std::string &longName,
                                           char chShortName,
                                           const std::string &helpMessage,
                                           std::vector<double> *pValue);

    GDALInConstructionAlgorithmArg &
    AddArg(const std::string &longName, char chShortName,
           const std::string &helpMessage,
           std::vector<GDALArgDatasetValue> *pValue,
           GDALArgDatasetType type = GDAL_OF_RASTER | GDAL_OF_VECTOR |
                                     GDAL_OF_MULTIDIM_RASTER);

    GDALInConstructionAlgorithmArg &AddInputDatasetArg(
        GDALArgDatasetValue *pValue,
        GDALArgDatasetType type = GDAL_OF_RASTER | GDAL_OF_VECTOR |
                                  GDAL_OF_MULTIDIM_RASTER,
        bool positionalAndRequired = true, const char *helpMessage = nullptr);

    GDALInConstructionAlgorithmArg &AddInputDatasetArg(
        std::vector<GDALArgDatasetValue> *pValue,
        GDALArgDatasetType type = GDAL_OF_RASTER | GDAL_OF_VECTOR |
                                  GDAL_OF_MULTIDIM_RASTER,
        bool positionalAndRequired = true, const char *helpMessage = nullptr);

    GDALInConstructionAlgorithmArg &
    AddOpenOptionsArg(std::vector<std::string> *pValue,
                      const char *helpMessage = nullptr);

    GDALInConstructionAlgorithmArg &
    AddOutputOpenOptionsArg(std::vector<std::string> *pValue,
                            const char *helpMessage = nullptr);

    GDALInConstructionAlgorithmArg &
    AddInputFormatsArg(std::vector<std::string> *pValue,
                       const char *helpMessage = nullptr);

    GDALInConstructionAlgorithmArg &AddOutputDatasetArg(
        GDALArgDatasetValue *pValue,
        GDALArgDatasetType type = GDAL_OF_RASTER | GDAL_OF_VECTOR |
                                  GDAL_OF_MULTIDIM_RASTER,
        bool positionalAndRequired = true, const char *helpMessage = nullptr);

    GDALInConstructionAlgorithmArg &
    AddOverwriteArg(bool *pValue, const char *helpMessage = nullptr);

    GDALInConstructionAlgorithmArg &
    AddOverwriteLayerArg(bool *pValue, const char *helpMessage = nullptr);

    GDALInConstructionAlgorithmArg &
    AddUpdateArg(bool *pValue, const char *helpMessage = nullptr);

    GDALInConstructionAlgorithmArg &
    AddAppendLayerArg(bool *pValue, const char *helpMessage = nullptr);

    GDALInConstructionAlgorithmArg &
    AddOutputStringArg(std::string *pValue, const char *helpMessage = nullptr);

    GDALInConstructionAlgorithmArg &
    AddStdoutArg(bool *pValue, const char *helpMessage = nullptr);

    GDALInConstructionAlgorithmArg &
    AddOutputFormatArg(std::string *pValue, bool bStreamAllowed = false,
                       bool bGDALGAllowed = false,
                       const char *helpMessage = nullptr);

    GDALInConstructionAlgorithmArg &
    AddOutputDataTypeArg(std::string *pValue,
                         const char *helpMessage = nullptr);

    GDALInConstructionAlgorithmArg &
    AddNodataArg(std::string *pValue, bool noneAllowed,
                 const std::string &optionName = "nodata",
                 const char *helpMessage = nullptr);

    GDALInConstructionAlgorithmArg &
    AddCreationOptionsArg(std::vector<std::string> *pValue,
                          const char *helpMessage = nullptr);

    GDALInConstructionAlgorithmArg &
    AddLayerCreationOptionsArg(std::vector<std::string> *pValue,
                               const char *helpMessage = nullptr);

    GDALInConstructionAlgorithmArg &
    AddLayerNameArg(std::string *pValue, const char *helpMessage = nullptr);

    GDALInConstructionAlgorithmArg &
    AddOutputLayerNameArg(std::string *pValue,
                          const char *helpMessage = nullptr);

    GDALInConstructionAlgorithmArg &
    AddLayerNameArg(std::vector<std::string> *pValue,
                    const char *helpMessage = nullptr);

    GDALInConstructionAlgorithmArg &
    AddArrayNameArg(std::string *pValue, const char *helpMessage = nullptr);

    GDALInConstructionAlgorithmArg &
    AddArrayNameArg(std::vector<std::string> *pValue,
                    const char *helpMessage = nullptr);

    GDALInConstructionAlgorithmArg &
    AddMemorySizeArg(size_t *pValue, std::string *pStrValue,
                     const std::string &optionName, const char *helpMessage);

    GDALInConstructionAlgorithmArg &
    AddGeometryTypeArg(std::string *pValue, const char *helpMessage = nullptr);

    static void SetAutoCompleteFunctionForLayerName(
        GDALInConstructionAlgorithmArg &layerArg,
        GDALInConstructionAlgorithmArg &datasetArg);

    static void SetAutoCompleteFunctionForFieldName(
        GDALInConstructionAlgorithmArg &fieldArg,
        GDALInConstructionAlgorithmArg &layerNameArg,
        std::vector<GDALArgDatasetValue> &datasetArg);

    GDALInConstructionAlgorithmArg &
    AddFieldNameArg(std::string *pValue, const char *helpMessage = nullptr);

    GDALInConstructionAlgorithmArg &AddFieldTypeSubtypeArg(
        OGRFieldType *pTypeValue, OGRFieldSubType *pSubtypeValue,
        std::string *pStrValue, const std::string &argName = std::string(),
        const char *helpMessage = nullptr);

    GDALInConstructionAlgorithmArg &
    AddBandArg(int *pValue, const char *helpMessage = nullptr);

    GDALInConstructionAlgorithmArg &
    AddBandArg(std::vector<int> *pValue, const char *helpMessage = nullptr);

    GDALInConstructionAlgorithmArg &
    AddBBOXArg(std::vector<double> *pValue, const char *helpMessage = nullptr);

    GDALInConstructionAlgorithmArg &
    AddActiveLayerArg(std::string *pValue, const char *helpMessage = nullptr);

    GDALInConstructionAlgorithmArg &
    AddNumThreadsArg(int *pValue, std::string *pStrValue,
                     const char *helpMessage = nullptr);

    GDALInConstructionAlgorithmArg &
    AddAbsolutePathArg(bool *pValue, const char *helpMessage = nullptr);

    GDALInConstructionAlgorithmArg &
    AddPixelFunctionNameArg(std::string *pValue,
                            const char *helpMessage = nullptr);

    GDALInConstructionAlgorithmArg &
    AddPixelFunctionArgsArg(std::vector<std::string> *pValue,
                            const char *helpMessage = nullptr);

    void AddProgressArg();

    void AddValidationAction(std::function<bool()> f)
    {
        m_validationActions.push_back(f);
    }

    static bool AddOptionsSuggestions(const char *pszXML, int datasetType,
                                      const std::string &currentValue,
                                      std::vector<std::string> &oRet);

    bool ParseAndValidateKeyValue(GDALAlgorithmArg &arg);

    bool RunPreStepPipelineValidations() const;

    bool IsGDALGOutput() const;

    enum class ProcessGDALGOutputRet
    {
        GDALG_OK,
        GDALG_ERROR,
        NOT_GDALG,
    };

    virtual ProcessGDALGOutputRet ProcessGDALGOutput();

    virtual bool CheckSafeForStreamOutput();

    bool ValidateFormat(const GDALAlgorithmArg &arg, bool bStreamAllowed,
                        bool bGDALGAllowed) const;

    static std::vector<std::string>
    FormatAutoCompleteFunction(const GDALAlgorithmArg &arg, bool bStreamAllowed,
                               bool bGDALGAllowed);

    void AddAliasFor(GDALInConstructionAlgorithmArg *arg,
                     const std::string &alias);
 
    void AddShortNameAliasFor(GDALInConstructionAlgorithmArg *arg,
                              char shortNameAlias);
 
    void SetPositional(GDALInConstructionAlgorithmArg *arg);
 
    std::vector<std::string>
    OpenOptionCompleteFunction(const std::string &currentValue) const;


    static bool IsKnownOutputRelatedBooleanArgName(std::string_view osName);

    void SetDisplayInJSONUsage(bool b)
    {
        m_displayInJSONUsage = b;
    }

    virtual void WarnIfDeprecated()
    {
    }

    std::pair<std::vector<std::pair<GDALAlgorithmArg *, std::string>>, size_t>
    GetArgNamesForCLI() const;

    std::string GetUsageForCLIEnd() const;
 
  private:
    const std::string m_name{};
    const std::string m_description{};
    const std::string m_helpURL{};
    const std::string m_helpFullURL{};
    bool m_parsedSubStringAlreadyCalled = false;
    bool m_displayInJSONUsage = true;
    bool m_specialActionRequested = false;
    bool m_helpRequested = false;
    bool m_calledFromCommandLine = false;
 
    // Used by program-output directives in .rst files
    bool m_helpDocRequested = false;
 
    bool m_JSONUsageRequested = false;
    bool m_parseForAutoCompletion = false;
    std::string m_referencePath{};
    std::vector<std::string> m_dummyConfigOptions{};
    std::vector<std::unique_ptr<GDALAlgorithmArg>> m_args{};
    std::map<std::string, GDALAlgorithmArg *> m_mapLongNameToArg{};
    std::map<std::string, GDALAlgorithmArg *> m_mapShortNameToArg{};
    std::vector<GDALAlgorithmArg *> m_positionalArgs{};
    GDALAlgorithmRegistry m_subAlgRegistry{};
    std::unique_ptr<GDALAlgorithm> m_selectedSubAlgHolder{};
    std::function<std::vector<std::string>(const std::vector<std::string> &)>
        m_autoCompleteFunction{};
    std::vector<std::function<bool()>> m_validationActions{};
 
    std::string m_dummyVal{};
    GDALAlgorithmArg m_dummyArg{
        GDALAlgorithmArgDecl("dummy", 0, "", GAAT_STRING), &m_dummyVal};

    bool m_arbitraryLongNameArgsAllowed = false;
 
    std::vector<std::unique_ptr<std::string>>
        m_arbitraryLongNameArgsValuesStr{};
    std::vector<std::unique_ptr<bool>> m_arbitraryLongNameArgsValuesBool{};
 
    friend GDALAlgorithmArgH GDALAlgorithmGetArg(GDALAlgorithmH hAlg,
                                                 const char *pszArgName);
    friend GDALAlgorithmArgH
    GDALAlgorithmGetArgNonConst(GDALAlgorithmH hAlg, const char *pszArgName);
    GDALAlgorithmArg *GetArg(const std::string &osName, bool suggestionAllowed,
                             bool isConst);
 
    GDALInConstructionAlgorithmArg &
    AddArg(std::unique_ptr<GDALInConstructionAlgorithmArg> arg);
    bool ParseArgument(
        GDALAlgorithmArg *arg, const std::string &name,
        const std::string &value,
        std::map<
            GDALAlgorithmArg *,
            std::variant<std::vector<std::string>, std::vector<int>,
                         std::vector<double>, std::vector<GDALArgDatasetValue>>>
            &inConstructionValues);
 
    bool ValidateBandArg() const;
 
    virtual bool RunImpl(GDALProgressFunc pfnProgress, void *pProgressData) = 0;

    void ExtractLastOptionAndValue(std::vector<std::string> &args,
                                   std::string &option,
                                   std::string &value) const;
 
    std::vector<std::string> AutoCompleteArrayName() const;
 
    GDALAlgorithm(const GDALAlgorithm &) = delete;
    GDALAlgorithm &operator=(const GDALAlgorithm &) = delete;
};

struct GDALAlgorithmHS
{
  private:
    std::unique_ptr<GDALAlgorithm> uniquePtr{};
 
    GDALAlgorithmHS(const GDALAlgorithmHS &) = delete;
    GDALAlgorithmHS &operator=(const GDALAlgorithmHS &) = delete;
 
  public:
    GDALAlgorithm *ptr = nullptr;
 
    GDALAlgorithmHS() = default;
 
    explicit GDALAlgorithmHS(std::unique_ptr<GDALAlgorithm> alg)
        : uniquePtr(std::move(alg)), ptr(uniquePtr.get())
    {
    }
 
    static std::unique_ptr<GDALAlgorithmHS> FromRef(GDALAlgorithm &alg)
    {
        auto ret = std::make_unique<GDALAlgorithmHS>();
        ret->ptr = &alg;
        return ret;
    }
};
 
/************************************************************************/
/*                       GDALContainerAlgorithm                         */
/************************************************************************/
 
class CPL_DLL GDALContainerAlgorithm : public GDALAlgorithm
{
  public:
    explicit GDALContainerAlgorithm(
        const std::string &name, const std::string &description = std::string(),
        const std::string &helpURL = std::string())
        : GDALAlgorithm(name, description, helpURL)
    {
    }
 
  protected:
    bool RunImpl(GDALProgressFunc, void *) override;
};

 
/************************************************************************/
/*                   GDALGlobalAlgorithmRegistry                        */
/************************************************************************/

class CPL_DLL GDALGlobalAlgorithmRegistry final : public GDALAlgorithmRegistry
{
  public:
    static constexpr const char *ROOT_ALG_NAME = "gdal";

    static GDALGlobalAlgorithmRegistry &GetSingleton();

    using InstantiateFunc = std::function<std::unique_ptr<GDALAlgorithm>()>;

    void DeclareAlgorithm(const std::vector<std::string> &path,
                          InstantiateFunc instantiateFunc);

    std::vector<std::string>
    GetDeclaredSubAlgorithmNames(const std::vector<std::string> &path) const;

    bool HasDeclaredSubAlgorithm(const std::vector<std::string> &path) const;

    std::unique_ptr<GDALAlgorithm>
    InstantiateDeclaredSubAlgorithm(const std::vector<std::string> &path) const;
 
  protected:
    std::unique_ptr<GDALAlgorithm>
    InstantiateTopLevel(const std::string &name) const override;
 
  private:
    struct Node
    {
        InstantiateFunc instantiateFunc{};
        std::map<std::string, Node> children{};
    };
 
    Node m_root{};
 
    GDALGlobalAlgorithmRegistry();
    ~GDALGlobalAlgorithmRegistry() override;
 
    const Node *GetNodeFromPath(const std::vector<std::string> &path) const;
};
 
#endif  // #if defined(__cplusplus) && !defined(CPL_SUPRESS_CPLUSPLUS) && (defined(DOXYGEN_SKIP) || __cplusplus >= 201703L || _MSC_VER >= 1920)
 
#endif  // GDAL_ALGORITHM_CPP_INCLUDED