# GDALAlgorithm C++ API

## Include file

gdalalgorithm.h

## GDALAlgorithm class

class GDALAlgorithm

  GDAL algorithm.

  An algorithm declares its name, description, help URL. It also defined arguments or (mutual exclusion) sub-algorithms.

  It can be used from the command line with the ParseCommandLineArguments() method, or users can iterate over the available arguments with the GetArgs() or GetArg() method and fill them programmatically with GDALAlgorithmArg::Set().

  Execution of the algorithm is done with the Run() method.

  This is an abstract class. Implementations must sub-class it and implement the RunImpl() method.

  Subclassed by GDALDatasetAlgorithm, GDALMdimAlgorithm, GDALRasterAlgorithm, GDALVSIAlgorithm, GDALVectorAlgorithm

  Public Functions

  inline const std::string &GetName() const

    Get the algorithm name.

  inline const std::string &GetDescription() const

    Get the algorithm description (a few sentences at most)

  inline const std::string &GetLongDescription() const

    Get the long algorithm description.

    May be empty.

  inline const std::string &GetHelpURL() const

    Get the algorithm help URL.

    If starting with '/', it is relative to "https://gdal.org".

  inline const std::string &GetHelpFullURL() const

    Get the algorithm full URL, resolving relative URLs.

  inline bool IsHidden() const

    Returns whether this algorithm is hidden.

  bool HasSubAlgorithms() const

    Returns whether this algorithm has sub-algorithms.

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

    Get the names of registered algorithms.

    This only returns the main name of each algorithm, not its potential alternate names.

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

    Instantiate an algorithm by its name (or its alias).

  inline const std::vector<std::unique_ptr<GDALAlgorithmArg>> &GetArgs() const

    Return the potential arguments of the algorithm.

  inline std::vector<std::unique_ptr<GDALAlgorithmArg>> &GetArgs()

    Return the potential arguments of the algorithm.

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

    Return a likely matching argument using a Damerau-Levenshtein distance.

  inline GDALAlgorithmArg *GetArg(const std::string &osName, bool suggestionAllowed = false)

    Return an argument from its long name, short name or an alias.

  inline GDALAlgorithmArg &operator[](const std::string &osName)

    Return an argument from its long name, short name or an alias.

  inline const GDALAlgorithmArg *GetArg(const std::string &osName, bool suggestionAllowed = false) const

    Return an argument from its long name, short name or an alias.

  inline const GDALAlgorithmArg &operator[](const std::string &osName) const

    Return an argument from its long name, short name or an alias.

  inline void SetCallPath(const std::vector<std::string> &path)

    Set the calling path to this algorithm.

    For example the main "gdal" CLI will set the path to the name of its binary before calling ParseCommandLineArguments().

  inline void SetParseForAutoCompletion()

    Set hint before calling ParseCommandLineArguments() that it must try to be be graceful when possible, e.g.

    accepting "gdal raster convert in.tif out.tif --co"

  inline void SetReferencePathForRelativePaths(const std::string &referencePath)

    Set the reference file paths used to interpret relative paths.

    This has only effect if called before calling ParseCommandLineArguments().

  inline const std::string &GetReferencePathForRelativePaths() const

    Return the reference file paths used to interpret relative paths.

  inline bool SupportsStreamedOutput() const

    Returns whether this algorithm supports a streamed output dataset.

  inline void SetExecutionForStreamedOutput()

    Indicates that the algorithm must be run to generate a streamed output dataset.

    In particular, this must be used as a hint by algorithms to avoid writing files on the filesystem. This is used by the GDALG driver when executing a serialized algorithm command line.

    This has only effect if called before calling Run().

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

    Parse a command line argument, which does not include the algorithm name, to set the value of corresponding arguments.

  virtual bool ValidateArguments()

    Validate that all constraints are met.

    This method may emit several errors if several constraints are not met.

    This method is automatically executed by ParseCommandLineArguments() and Run(), and thus does generally not need to be explicitly called. Derived classes overriding this method should generally call the base method.

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

    Execute the algorithm, starting with ValidateArguments() and then calling RunImpl().

  virtual bool Finalize()

    Complete any pending actions, and return the final status.

    This is typically useful for algorithm that generate an output dataset.

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

    Return the usage as a string appropriate for command-line interface --help output.

  virtual std::string GetUsageAsJSON() const

    Return the usage of the algorithm as a JSON-serialized string.

    This can be used to dynamically generate interfaces to algorithms.

  inline GDALAlgorithm &GetActualAlgorithm()

    Return the actual algorithm that is going to be invoked, when the current algorithm has sub-algorithms.

    Only valid after ParseCommandLineArguments() has been called.

  inline bool IsHelpRequested() const

    Whether the --help flag has been specified.

  inline bool IsJSONUsageRequested() const

    Whether the --json-usage flag has been specified.

  inline bool IsProgressBarRequested() const

    Whether the --progress flag has been specified.

  inline const std::vector<std::string> &GetAliases() const

    Return alias names (generally short) for the current algorithm.

  inline bool PropagateSpecialActionTo(GDALAlgorithm *target)

    Used by the "gdal info" special algorithm when it first tries to run "gdal raster info", to inherit from the potential special flags, such as --help or --json-usage, that this later algorithm has received.

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

    Return auto completion suggestions.

  inline void SetCalledFromCommandLine()

    Set whether the algorithm is called from the command line.

  inline bool IsCalledFromCommandLine() const

    Return whether the algorithm is called from the command line.

  virtual bool HasOutputString() const

    Whether the algorithm generates an output string.

  Public Static Functions

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

    Save command line in a .gdalg.json file.

    If filename is empty, outString will contain the serialized JSON content.

  struct UsageOptions

    Usage options.

    Public Members

    bool isPipelineStep

      Whether this is a pipeline step.

    size_t maxOptLen

      Maximum width of the names of the options.

    bool isPipelineMain

      Whether this is a pipeline main.

## GDALAlgorithmArg class

class GDALAlgorithmArg

  Argument of an algorithm.

  Subclassed by GDALInConstructionAlgorithmArg

  Public Functions

  template<class T>
  inline GDALAlgorithmArg(const GDALAlgorithmArgDecl &decl, T *pValue)

    Constructor.

  virtual ~GDALAlgorithmArg()

    Destructor.

  inline const GDALAlgorithmArgDecl &GetDeclaration() const

    Return the argument declaration.

  inline const std::string &GetName() const

    Alias for GDALAlgorithmArgDecl::GetName()

  inline const std::string &GetShortName() const

    Alias for GDALAlgorithmArgDecl::GetShortName()

  inline const std::vector<std::string> &GetAliases() const

    Alias for GDALAlgorithmArgDecl::GetAliases()

  inline const std::vector<char> &GetShortNameAliases() const

    Alias for GDALAlgorithmArgDecl::GetShortNameAliases()

  inline const std::string &GetDescription() const

    Alias for GDALAlgorithmArgDecl::GetDescription()

  inline const std::string &GetMetaVar() const

    Alias for GDALAlgorithmArgDecl::GetMetaVar()

  inline GDALAlgorithmArgType GetType() const

    Alias for GDALAlgorithmArgDecl::GetType()

  inline const std::string &GetCategory() const

    Alias for GDALAlgorithmArgDecl::GetCategory()

  inline bool IsRequired() const

    Alias for GDALAlgorithmArgDecl::IsRequired()

  inline int GetMinCount() const

    Alias for GDALAlgorithmArgDecl::GetMinCount()

  inline int GetMaxCount() const

    Alias for GDALAlgorithmArgDecl::GetMaxCount()

  inline bool GetDisplayHintAboutRepetition() const

    Alias for GDALAlgorithmArgDecl::GetDisplayHintAboutRepetition()

  inline bool GetPackedValuesAllowed() const

    Alias for GDALAlgorithmArgDecl::GetPackedValuesAllowed()

  inline bool GetRepeatedArgAllowed() const

    Alias for GDALAlgorithmArgDecl::GetRepeatedArgAllowed()

  inline bool IsPositional() const

    Alias for GDALAlgorithmArgDecl::IsPositional()

  inline const std::vector<std::string> &GetChoices() const

    Alias for GDALAlgorithmArgDecl::GetChoices()

  inline const std::vector<std::string> &GetHiddenChoices() const

    Alias for GDALAlgorithmArgDecl::GetHiddenChoices()

  inline std::vector<std::string> GetAutoCompleteChoices(const std::string &currentValue) const

    Return auto completion choices, if a auto completion function has been registered.

  inline std::pair<double, bool> GetMinValue() const

    Alias for GDALAlgorithmArgDecl::GetMinValue()

  inline std::pair<double, bool> GetMaxValue() const

    Alias for GDALAlgorithmArgDecl::GetMaxValue()

  inline int GetMinCharCount() const

    Alias for GDALAlgorithmArgDecl::GetMinCharCount()

  inline bool IsExplicitlySet() const

    Return whether the argument value has been explicitly set with Set()

  inline bool HasDefaultValue() const

    Alias for GDALAlgorithmArgDecl::HasDefaultValue()

  inline bool IsHidden() const

    Alias for GDALAlgorithmArgDecl::IsHidden()

  inline bool IsHiddenForCLI() const

    Alias for GDALAlgorithmArgDecl::IsHiddenForCLI()

  inline bool IsOnlyForCLI() const

    Alias for GDALAlgorithmArgDecl::IsOnlyForCLI()

  inline bool IsHiddenForAPI() const

    Alias for GDALAlgorithmArgDecl::IsHiddenForAPI()

  inline bool IsInput() const

    Alias for GDALAlgorithmArgDecl::IsInput()

  inline bool IsOutput() const

    Alias for GDALAlgorithmArgDecl::IsOutput()

  inline bool IsReadFromFileAtSyntaxAllowed() const

    Alias for GDALAlgorithmArgDecl::IsReadFromFileAtSyntaxAllowed()

  inline bool IsRemoveSQLCommentsEnabled() const

    Alias for GDALAlgorithmArgDecl::IsRemoveSQLCommentsEnabled()

  inline const std::string &GetMutualExclusionGroup() const

    Alias for GDALAlgorithmArgDecl::GetMutualExclusionGroup()

  inline const std::map<std::string, std::vector<std::string>> GetMetadata() const

    Alias for GDALAlgorithmArgDecl::GetMetadata()

  inline const std::vector<std::string> *GetMetadataItem(const std::string &name) const

    Alias for GDALAlgorithmArgDecl::GetMetadataItem()

  template<class T>
  inline const T &GetDefault() const

    Alias for GDALAlgorithmArgDecl::GetDefault()

  inline bool AutoOpenDataset() const

    Alias for GDALAlgorithmArgDecl::AutoOpenDataset()

  inline bool IsUserProvided() const

    Alias for GDALAlgorithmArgDecl::IsUserProvided()

  inline GDALArgDatasetType GetDatasetType() const

    Alias for GDALAlgorithmArgDecl::GetDatasetType()

  inline int GetDatasetInputFlags() const

    Alias for GDALAlgorithmArgDecl::GetDatasetInputFlags()

  inline int GetDatasetOutputFlags() const

    Alias for GDALAlgorithmArgDecl::GetDatasetOutputFlags()

  template<class T>
  inline T &Get()

    Return the value of the argument, which is by decreasing order of priority:

    - the value set through Set().

    - the default value set through SetDefault().

    - the initial value of the C++ variable to which this argument is bound to.

    Must be called with T consistent of the type of the algorithm:

    - bool for GAAT_BOOLEAN

    - int for GAAT_INTEGER

    - double for GAAT_REAL

    - std::string for GAAT_STRING

    - GDALArgDatasetValue for GAAT_DATASET

    - std::vector<int> for GAAT_INTEGER_LIST

    - std::vector<double for GAAT_REAL_LIST

    - std::vector<std::string> for GAAT_STRING_LIST

    - std::vector<GDALArgDatasetValue> for GAAT_DATASET_LIST

  template<class T>
  inline const T &Get() const

    Return the value of the argument, which is by decreasing order of priority:

    - the value set through Set().

    - the default value set through SetDefault().

    - the initial value of the C++ variable to which this argument is bound to.

    Must be called with T consistent of the type of the algorithm:

    - bool for GAAT_BOOLEAN

    - int for GAAT_INTEGER

    - double for GAAT_REAL

    - std::string for GAAT_STRING

    - GDALArgDatasetValue for GAAT_DATASET

    - std::vector<int> for GAAT_INTEGER_LIST

    - std::vector<double for GAAT_REAL_LIST

    - std::vector<std::string> for GAAT_STRING_LIST

    - std::vector<GDALArgDatasetValue> for GAAT_DATASET_LIST

  bool Set(bool value)

    Set the value for a GAAT_BOOLEAN argument.

    It cannot be called several times for a given argument. Validation checks and other actions are run. Return true if success.

  bool Set(const std::string &value)

    Set the value for a GAAT_STRING argument.

    It cannot be called several times for a given argument. Validation checks and other actions are run. Return true if success.

  inline bool Set(const char *value)

    Set the value for a GAAT_STRING argument.

    It cannot be called several times for a given argument. Validation checks and other actions are run. Return true if success.

  inline bool Set(GDALDataType dt)

    Set the value for a GAAT_STRING argument from a GDALDataType It cannot be called several times for a given argument.

    Validation checks and other actions are run. Return true if success.

  bool Set(const OGRSpatialReference&)

    Set the value for a GAAT_STRING argument (representing a CRS) from a OGRSpatialReference It cannot be called several times for a given argument.

    Validation checks and other actions are run. Return true if success.

  bool Set(int value)

    Set the value for a GAAT_INTEGER (or GAAT_REAL) argument.

    It cannot be called several times for a given argument. Validation checks and other actions are run. Return true if success.

  bool Set(double value)

    Set the value for a GAAT_REAL argument.

  bool Set(GDALDataset *ds)

    Set the value for a GAAT_DATASET argument, increasing ds' reference counter if ds is not null.

    It cannot be called several times for a given argument. Validation checks and other actions are run. Return true if success.

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

    Set the value for a GAAT_DATASET argument.

    It cannot be called several times for a given argument. Validation checks and other actions are run. Return true if success.

  bool SetDatasetName(const std::string &name)

    Set the value for a GAAT_DATASET argument.

    It cannot be called several times for a given argument. Validation checks and other actions are run. Return true if success.

  bool SetFrom(const GDALArgDatasetValue &other)

    Set the value for a GAAT_DATASET argument.

    It references the dataset pointed by other.m_poDS. It cannot be called several times for a given argument. Validation checks and other actions are run. Return true if success.

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

    Set the value for a GAAT_STRING_LIST argument.

    It cannot be called several times for a given argument. Validation checks and other actions are run. Return true if success.

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

    Set the value for a GAAT_INTEGER_LIST argument.

    It cannot be called several times for a given argument. Validation checks and other actions are run. Return true if success.

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

    Set the value for a GAAT_REAL_LIST argument.

    It cannot be called several times for a given argument. Validation checks and other actions are run. Return true if success.

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

    Set the value for a GAAT_DATASET_LIST argument.

    It cannot be called several times for a given argument. Validation checks and other actions are run. Return true if success.

  inline GDALAlgorithmArg &operator=(bool value)

    Set the value of the argument.

  inline GDALAlgorithmArg &operator=(int value)

    Set the value of the argument.

  inline GDALAlgorithmArg &operator=(double value)

    Set the value of the argument.

  inline GDALAlgorithmArg &operator=(const std::string &value)

    Set the value of the argument.

  inline GDALAlgorithmArg &operator=(const char *value)

    Set the value of the argument.

  inline GDALAlgorithmArg &operator=(GDALDataType value)

    Set the value of the argument.

  inline GDALAlgorithmArg &operator=(const OGRSpatialReference &value)

    Set the value of the argument.

  inline GDALAlgorithmArg &operator=(const std::vector<int> &value)

    Set the value of the argument.

  inline GDALAlgorithmArg &operator=(const std::vector<double> &value)

    Set the value of the argument.

  inline GDALAlgorithmArg &operator=(const std::vector<std::string> &value)

    Set the value of the argument.

  inline GDALAlgorithmArg &operator=(GDALDataset *value)

    Set the value of the argument.

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

    Set the value of the argument.

  bool SetFrom(const GDALAlgorithmArg &other)

    Set the value for another argument.

    For GAAT_DATASET, it will reference the dataset pointed by other.m_poDS. It cannot be called several times for a given argument. Validation checks and other actions are run. Return true if success.

  inline void SetSkipIfAlreadySet(bool skip = true)

    Advanced method used to make "gdal info" and "gdal raster|vector info" to avoid re-opening an already opened dataset.

  inline bool SkipIfAlreadySet() const

    Advanced method used to make "gdal info" and "gdal raster|vector info" to avoid re-opening an already opened dataset.

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

    Serialize this argument and its value.

    May return false if the argument is not explicitly set or if a dataset is passed by value.

  Public Static Functions

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

    Return an escaped string for argument serialization.

## GDALAlgorithmArgDecl class

class GDALAlgorithmArgDecl

  Argument declaration.

  It does not hold its value.

  Public Functions

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

    Constructor.

    Parameters:

      - longName -- Long name. Must be 2 characters at least. Must not start with dash.

      - chShortName -- 1-letter short name, or NUL character

      - description -- Description.

      - type -- Type of the argument.

  inline GDALAlgorithmArgDecl &AddAlias(const std::string &alias)

    Declare an alias.

    Must be 2 characters at least.

  inline GDALAlgorithmArgDecl &AddShortNameAlias(char shortNameAlias)

    Declare a shortname alias.

  inline GDALAlgorithmArgDecl &AddHiddenAlias(const std::string &alias)

    Declare an hidden alias (i.e.

    not exposed in usage). Must be 2 characters at least.

  inline GDALAlgorithmArgDecl &SetPositional()

    Declare that the argument is positional.

    Typically input / output files

  inline GDALAlgorithmArgDecl &SetRequired()

    Declare that the argument is required.

    Default is no

  inline GDALAlgorithmArgDecl &SetMetaVar(const std::string &metaVar)

    Declare the "meta-var" hint.

    By default, the meta-var value is the long name of the argument in upper case.

  inline GDALAlgorithmArgDecl &SetCategory(const std::string &category)

    Declare the argument category: GAAC_COMMON, GAAC_BASE, GAAC_ADVANCED, GAAC_ESOTERIC or a custom category.

  template<class T>
  inline GDALAlgorithmArgDecl &SetDefault(const T &value)

    Declare a default value for the argument.

  inline GDALAlgorithmArgDecl &SetDefault(const char *value)

    Declare a default value for the argument.

  GDALAlgorithmArgDecl &SetMinCount(int count)

    Declare the minimum number of values for the argument.

    Defaults to 0. Only applies to list type of arguments. Setting it to non-zero does not make the argument required. It just sets the minimum number of values when it is specified. To also make it required, use SetRequired().

  GDALAlgorithmArgDecl &SetMaxCount(int count)

    Declare the maximum number of values for the argument.

    Defaults to 1 for scalar types, and UNBOUNDED for list types. Only applies to list type of arguments.

  inline GDALAlgorithmArgDecl &SetDisplayHintAboutRepetition(bool displayHint)

    Declare whether in --help message one should display hints about the minimum/maximum number of values.

    Defaults to true.

  inline GDALAlgorithmArgDecl &SetPackedValuesAllowed(bool allowed)

    Declares whether, for list type of arguments, several values, comma separated, may be specified.

    That is "--foo=bar,baz". The default is true.

  inline GDALAlgorithmArgDecl &SetRepeatedArgAllowed(bool allowed)

    Declares whether, for list type of arguments, the argument may be repeated.

    That is "--foo=bar --foo=baz". The default is true.

  template<typename T, typename ...U, typename std::enable_if<!std::is_same_v<T, std::vector<std::string>&>, bool>::type = true>
  inline GDALAlgorithmArgDecl &SetChoices(T &&first, U&&... rest)

    Declares the allowed values (as strings) for the argument.

    Only honored for GAAT_STRING and GAAT_STRING_LIST types.

  inline GDALAlgorithmArgDecl &SetChoices(const std::vector<std::string> &choices)

    Declares the allowed values (as strings) for the argument.

    Only honored for GAAT_STRING and GAAT_STRING_LIST types.

  inline GDALAlgorithmArgDecl &SetMinValueIncluded(double min)

    Set the minimum (included) value allowed.

    Only taken into account on GAAT_INTEGER, GAAT_INTEGER_LIST, GAAT_REAL and GAAT_REAL_LIST arguments.

  inline GDALAlgorithmArgDecl &SetMinValueExcluded(double min)

    Set the minimum (excluded) value allowed.

    Only taken into account on GAAT_INTEGER, GAAT_INTEGER_LIST, GAAT_REAL and GAAT_REAL_LIST arguments.

  inline GDALAlgorithmArgDecl &SetMaxValueIncluded(double max)

    Set the maximum (included) value allowed.

  inline GDALAlgorithmArgDecl &SetMaxValueExcluded(double max)

    Set the maximum (excluded) value allowed.

  inline GDALAlgorithmArgDecl &SetMinCharCount(int count)

    Sets the minimum number of characters (for arguments of type GAAT_STRING and GAAT_STRING_LIST)

  template<typename T, typename ...U>
  inline GDALAlgorithmArgDecl &SetHiddenChoices(T &&first, U&&... rest)

    Declares the, hidden, allowed values (as strings) for the argument.

    Only honored for GAAT_STRING and GAAT_STRING_LIST types.

  inline GDALAlgorithmArgDecl &SetHiddenForCLI(bool hiddenForCLI = true)

    Declare that the argument must not be mentioned in CLI usage.

    For example, "output-value" for "gdal raster info", which is only meant when the algorithm is used from a non-CLI context.

  inline GDALAlgorithmArgDecl &SetHiddenForAPI(bool hiddenForAPI = true)

    Declare that the argument is hidden in the context of an API use.

    Said otherwise, if it is only for CLI usage. For example "--help"

  inline GDALAlgorithmArgDecl &SetHidden()

    Declare that the argument is hidden.

    Default is no. This is equivalent to calling SetHiddenForCLI() and SetHiddenForAPI()

  inline GDALAlgorithmArgDecl &SetIsInput(bool isInput = true)

    Indicate whether the value of the argument is read-only during the execution of the algorithm.

    Default is true.

  inline GDALAlgorithmArgDecl &SetIsOutput(bool isOutput = true)

    Indicate whether (at least part of) the value of the argument is set during the execution of the algorithm.

    For example, "output-value" for "gdal raster info" Default is false. An argument may return both IsInput() and IsOutput() as true. For example the "gdal raster convert" algorithm consumes the dataset name of its "output" argument, and sets the dataset object during its execution.

  inline GDALAlgorithmArgDecl &SetMutualExclusionGroup(const std::string &group)

    Set the name of the mutual exclusion group to which this argument belongs to.

    At most one argument in a group can be specified.

  inline GDALAlgorithmArgDecl &AddMetadataItem(const std::string &name, const std::vector<std::string> &values)

    Set user-defined metadata item.

  inline GDALAlgorithmArgDecl &SetReadFromFileAtSyntaxAllowed()

    Set that this (string) argument accepts the @filename syntax to mean that the content of the specified file should be used as the value of the argument.

  inline GDALAlgorithmArgDecl &SetRemoveSQLCommentsEnabled()

    Sets that SQL comments must be removed from a (string) argument.

  inline GDALAlgorithmArgDecl &SetAutoOpenDataset(bool autoOpen)

    Sets whether the dataset should be opened automatically by GDALAlgorithm.

    Only applies to GAAT_DATASET and GAAT_DATASET_LIST.

  inline GDALAlgorithmArgDecl &SetUserProvided()

    Declares that this argument has been created on-the-fly from user-provided argument.

  inline const std::string &GetName() const

    Return the (long) name.

  inline const std::string &GetShortName() const

    Return the short name, or empty string if there is none.

  inline const std::vector<std::string> &GetAliases() const

    Return the aliases (potentially none)

  inline const std::vector<char> &GetShortNameAliases() const

    Return the shortname aliases (potentially none)

  inline const std::string &GetDescription() const

    Return the description.

  inline const std::string &GetMetaVar() const

    Return the "meta-var" hint.

    By default, the meta-var value is the long name of the argument in upper case.

  inline const std::string &GetCategory() const

    Return the argument category: GAAC_COMMON, GAAC_BASE, GAAC_ADVANCED, GAAC_ESOTERIC or a custom category.

  inline GDALAlgorithmArgType GetType() const

    Return the type.

  inline const std::vector<std::string> &GetChoices() const

    Return the allowed values (as strings) for the argument.

    Only honored for GAAT_STRING and GAAT_STRING_LIST types.

  inline const std::vector<std::string> &GetHiddenChoices() const

    Return the allowed hidden values (as strings) for the argument.

    Only honored for GAAT_STRING and GAAT_STRING_LIST types.

  inline std::pair<double, bool> GetMinValue() const

    Return the minimum value and whether it is included.

  inline std::pair<double, bool> GetMaxValue() const

    Return the maximum value and whether it is included.

  inline int GetMinCharCount() const

    Return the minimum number of characters (for arguments of type GAAT_STRING and GAAT_STRING_LIST)

  inline bool IsRequired() const

    Return whether the argument is required.

    Defaults to false.

  inline int GetMinCount() const

    Return the minimum number of values for the argument.

    Defaults to 0. Only applies to list type of arguments.

  inline int GetMaxCount() const

    Return the maximum number of values for the argument.

    Defaults to 1 for scalar types, and UNBOUNDED for list types. Only applies to list type of arguments.

  inline bool GetDisplayHintAboutRepetition() const

    Returns whether in --help message one should display hints about the minimum/maximum number of values.

    Defaults to true.

  inline bool GetPackedValuesAllowed() const

    Return whether, for list type of arguments, several values, space separated, may be specified.

    That is "--foo=bar,baz". The default is true.

  inline bool GetRepeatedArgAllowed() const

    Return whether, for list type of arguments, the argument may be repeated.

    That is "--foo=bar --foo=baz". The default is true.

  inline bool IsPositional() const

    Return if the argument is a positional one.

  inline bool HasDefaultValue() const

    Return if the argument has a declared default value.

  inline bool IsHidden() const

    Return whether the argument is hidden.

  inline bool IsHiddenForCLI() const

    Return whether the argument must not be mentioned in CLI usage.

    For example, "output-value" for "gdal raster info", which is only meant when the algorithm is used from a non-CLI context.

  inline bool IsOnlyForCLI() const

    Return whether the argument is only for CLI usage.

    For example "--help" This is an alias for IsHiddenForAPI()

  inline bool IsHiddenForAPI() const

    Return whether the argument is hidden for API usage For example "--help".

  inline bool IsInput() const

    Indicate whether the value of the argument is read-only during the execution of the algorithm.

    Default is true.

  inline bool IsOutput() const

    Return whether (at least part of) the value of the argument is set during the execution of the algorithm.

    For example, "output-value" for "gdal raster info" Default is false. An argument may return both IsInput() and IsOutput() as true. For example the "gdal raster convert" algorithm consumes the dataset name of its "output" argument, and sets the dataset object during its execution.

  inline const std::string &GetMutualExclusionGroup() const

    Return the name of the mutual exclusion group to which this argument belongs to, or empty string if it does not belong to any exclusion group.

  inline bool IsReadFromFileAtSyntaxAllowed() const

    Return if this (string) argument accepts the @filename syntax to mean that the content of the specified file should be used as the value of the argument.

  inline bool IsRemoveSQLCommentsEnabled() const

    Returns whether SQL comments must be removed from a (string) argument.

  inline bool AutoOpenDataset() const

    Returns whether the dataset should be opened automatically by GDALAlgorithm.

    Only applies to GAAT_DATASET and GAAT_DATASET_LIST.

  inline bool IsUserProvided() const

    Returns whether the argument has been user-provided.

  inline const std::map<std::string, std::vector<std::string>> GetMetadata() const

    Get user-defined metadata.

  inline const std::vector<std::string> *GetMetadataItem(const std::string &name) const

    Get user-defined metadata by item name.

  template<class T>
  inline const T &GetDefault() const

    Return the default value of the argument.

    Must be called with T consistent of the type of the algorithm, and only if HasDefaultValue() is true. Valid T types are:

    - bool for GAAT_BOOLEAN

    - int for GAAT_INTEGER

    - double for GAAT_REAL

    - std::string for GAAT_STRING

    - GDALArgDatasetValue for GAAT_DATASET

    - std::vector<int> for GAAT_INTEGER_LIST

    - std::vector<double for GAAT_REAL_LIST

    - std::vector<std::string> for GAAT_STRING_LIST

    - std::vector<GDALArgDatasetValue> for GAAT_DATASET_LIST

  inline GDALArgDatasetType GetDatasetType() const

    Get which type of dataset is allowed / generated.

    Binary-or combination of GDAL_OF_RASTER, GDAL_OF_VECTOR and GDAL_OF_MULTIDIM_RASTER, possibly combined with GDAL_OF_UPDATE. Only applies to arguments of type GAAT_DATASET or GAAT_DATASET_LIST.

  inline void SetDatasetType(GDALArgDatasetType type)

    Set which type of dataset is allowed / generated.

    Binary-or combination of GDAL_OF_RASTER, GDAL_OF_VECTOR and GDAL_OF_MULTIDIM_RASTER. Only applies to arguments of type GAAT_DATASET or GAAT_DATASET_LIST.

  inline int GetDatasetInputFlags() const

    Indicates which components among name and dataset are accepted as input, when this argument serves as an input.

    If the GADV_NAME bit is set, it indicates a dataset name is accepted as input. If the GADV_OBJECT bit is set, it indicates a dataset object is accepted as input. If both bits are set, the algorithm can accept either a name or a dataset object. Only applies to arguments of type GAAT_DATASET or GAAT_DATASET_LIST.

  inline int GetDatasetOutputFlags() const

    Indicates which components among name and dataset are modified, when this argument serves as an output.

    If the GADV_NAME bit is set, it indicates a dataset name is generated as output (that is the algorithm will generate the name. Rarely used). If the GADV_OBJECT bit is set, it indicates a dataset object is generated as output, and available for use after the algorithm has completed. Only applies to arguments of type GAAT_DATASET or GAAT_DATASET_LIST.

  inline void SetDatasetInputFlags(int flags)

    Set which components among name and dataset are accepted as input, when this argument serves as an input.

    Only applies to arguments of type GAAT_DATASET or GAAT_DATASET_LIST.

  inline void SetDatasetOutputFlags(int flags)

    Set which components among name and dataset are modified when this argument serves as an output.

    Only applies to arguments of type GAAT_DATASET or GAAT_DATASET_LIST.

  Public Static Attributes

  static constexpr int UNBOUNDED = std::numeric_limits<int>::max()

    Special value for the SetMaxCount() / GetMaxCount() to indicate unlimited number of values.

## GDALArgDatasetValue class

class GDALArgDatasetValue

  Value for an argument that points to a GDALDataset.

  This is the value of arguments of type GAAT_DATASET or GAAT_DATASET_LIST.

  Public Functions

  GDALArgDatasetValue() = default

    Default (empty) constructor.

  inline explicit GDALArgDatasetValue(const std::string &name)

    Constructor by dataset name.

  explicit GDALArgDatasetValue(GDALDataset *poDS)

    Constructor by dataset instance, increasing its reference counter.

  GDALArgDatasetValue(GDALArgDatasetValue &&other)

    Move constructor.

  ~GDALArgDatasetValue()

    Destructor.

    Decrease m_poDS reference count, and destroy it if no longer referenced.

  bool Close()

    Dereference the dataset object and close it if no longer referenced.

    Return an error if an error occurred during dataset closing.

  GDALArgDatasetValue &operator=(GDALArgDatasetValue &&other)

    Move-assignment operator.

  GDALDataset *GetDatasetIncreaseRefCount()

    Get the GDALDataset* instance (may be null), and increase its reference count if not null.

    Once done with the dataset, the caller should call GDALDataset::Release().

  inline GDALDataset *GetDatasetRef()

    Get a GDALDataset* instance (may be null).

    This does not modify the reference counter, hence the lifetime of the returned object is not guaranteed to exceed the one of this instance.

  inline const GDALDataset *GetDatasetRef() const

    Get a GDALDataset* instance (may be null).

    This does not modify the reference counter, hence the lifetime of the returned object is not guaranteed to exceed the one of this instance.

  inline GDALDataset *BorrowDataset()

    Borrow the GDALDataset* instance (may be null), leaving its reference counter unchanged.

  inline void BorrowDatasetFrom(GDALArgDatasetValue &other)

    Borrow the GDALDataset* instance from another GDALArgDatasetValue, leaving its reference counter unchanged.

  inline const std::string &GetName() const

    Get dataset name.

  inline bool IsNameSet() const

    Return whether a dataset name has been set.

  void Set(const std::string &name)

    Set dataset name.

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

    Transfer dataset to this instance (does not affect its reference counter).

  void Set(GDALDataset *poDS)

    Set dataset object, increasing its reference counter.

  void SetFrom(const GDALArgDatasetValue &other)

    Set from other value, increasing the reference counter of the GDALDataset object.

  inline void SetDatasetOpenedByAlgorithm()

    Set that the dataset has been opened by the algorithm.

  inline bool HasDatasetBeenOpenedByAlgorithm() const

    Whether the dataset has been opened by the algorithm.

## GDALAlgorithmRegistry class

class GDALAlgorithmRegistry

  Registry of GDAL algorithms.

  Subclassed by GDALGlobalAlgorithmRegistry

  Public Functions

  template<class MyAlgorithm>
  inline bool Register()

    Register the algorithm of type MyAlgorithm.

  bool Register(const AlgInfo &info)

    Register an algorithm by its AlgInfo structure.

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

    Get the names of registered algorithms.

    This only returns the main name of each algorithm, not its potential alternate names.

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

    Instantiate an algorithm by its name or one of its alias.

    Returns:

      algorithm, or nullptr

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

    Instantiate an algorithm by its path.

    Since

      3.12

    Returns:

      algorithm, or nullptr

  template<typename ...V>
  inline std::unique_ptr<GDALAlgorithm> Instantiate(const std::string &first, V&&... rest)

    Instantiate an algorithm by its path.

    Since

      3.12

    Returns:

      algorithm, or nullptr

  inline const AlgInfo *GetInfo(const std::string &name) const

    Get an algorithm by its name.

  inline bool empty() const

    Returns true if there are no algorithms registered.

  Public Static Attributes

  static constexpr const char *HIDDEN_ALIAS_SEPARATOR = "==hide=="

    Special value to put in m_aliases to separate public alias from hidden aliases.

  class AlgInfo

    Algorithm information.

    Public Members

    std::string m_name = {}

      Algorithm (short) name.

    std::vector<std::string> m_aliases = {}

      Aliases.

    std::function m_creationFunc = {}

      Creation function.

## GDALGlobalAlgorithmRegistry class

class GDALGlobalAlgorithmRegistry : public GDALAlgorithmRegistry

  Global registry of GDAL algorithms.

  Public Types

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

    Instantiation function.

  Public Functions

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

    Declare the algorithm designed by its path (omitting leading path) and provide its instantiation method.

    For example {"driver", "pdf", "list-layers"}

    This is typically used by plugins to register extra algorithms.

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

    Return the direct declared (as per DeclareAlgorithm()) subalgorithms of the given path.

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

    Return whether a subalgorithm is declared at the given path.

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

    Instantiate a declared (as per DeclareAlgorithm()) subalgorithm.

  Public Static Functions

  static GDALGlobalAlgorithmRegistry &GetSingleton()

    Get the singleton.

  Public Static Attributes

  static constexpr const char *ROOT_ALG_NAME = "gdal"

    Name of the root "gdal" algorithm.