GDALAlgorithm C++ API

Include file

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.