GDAL
GDALAlgorithm Class Referenceabstract

GDAL algorithm. More...

#include <gdalalgorithm_cpp.h>

Classes

struct  UsageOptions
 Usage options. More...

Public Member Functions

const std::string & GetName () const
 Get the algorithm name.
const std::string & GetDescription () const
 Get the algorithm description (a few sentences at most).
const std::string & GetLongDescription () const
 Get the long algorithm description.
const std::string & GetHelpURL () const
 Get the algorithm help URL.
const std::string & GetHelpFullURL () const
 Get the algorithm full URL, resolving relative URLs.
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.
std::unique_ptr< GDALAlgorithmInstantiateSubAlgorithm (const std::string &name, bool suggestionAllowed=true) const
 Instantiate an algorithm by its name (or its alias).
const std::vector< std::unique_ptr< GDALAlgorithmArg > > & GetArgs () const
 Return the potential arguments of the algorithm.
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.
GDALAlgorithmArgGetArg (const std::string &osName, bool suggestionAllowed=false)
 Return an argument from its long name, short name or an alias.
GDALAlgorithmArgoperator[] (const std::string &osName)
 Return an argument from its long name, short name or an alias.
const GDALAlgorithmArgGetArg (const std::string &osName, bool suggestionAllowed=false) const
 Return an argument from its long name, short name or an alias.
const GDALAlgorithmArgoperator[] (const std::string &osName) const
 Return an argument from its long name, short name or an alias.
void SetCallPath (const std::vector< std::string > &path)
 Set the calling path to this algorithm.
void SetParseForAutoCompletion ()
 Set hint before calling ParseCommandLineArguments() that it must try to be be graceful when possible, e.g.
void SetReferencePathForRelativePaths (const std::string &referencePath)
 Set the reference file paths used to interpret relative paths.
const std::string & GetReferencePathForRelativePaths () const
 Return the reference file paths used to interpret relative paths.
bool SupportsStreamedOutput () const
 Returns whether this algorithm supports a streamed output dataset.
void SetExecutionForStreamedOutput ()
 Indicates that the algorithm must be run to generate a streamed output dataset.
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.
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.
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.
GDALAlgorithmGetActualAlgorithm ()
 Return the actual algorithm that is going to be invoked, when the current algorithm has sub-algorithms.
bool IsHelpRequested () const
 Whether the --help flag has been specified.
bool IsJSONUsageRequested () const
 Whether the --json-usage flag has been specified.
bool IsProgressBarRequested () const
 Whether the --progress flag has been specified.
const std::vector< std::string > & GetAliases () const
 Return alias names (generally short) for the current algorithm.
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.
void SetCalledFromCommandLine ()
 Set whether the algorithm is called from the command line.
bool IsCalledFromCommandLine () const
 Return whether the algorithm is called from the command line.
virtual bool HasOutputString () const
 Whether the algorithm generates an output string.

Static Public Member Functions

static bool SaveGDALG (const std::string &filename, std::string &outString, const std::string &commandLine)
 Save command line in a .gdalg.json file.

Protected Types

enum class  ProcessGDALGOutputRet { GDALG_OK , GDALG_ERROR , NOT_GDALG }
 Return value for ProcessGDALGOutput. More...

Protected Member Functions

 GDALAlgorithm (const std::string &name, const std::string &description, const std::string &helpURL)
 Constructor.
bool ProcessDatasetArg (GDALAlgorithmArg *arg, GDALAlgorithm *algForOutput)
 Special processing for an argument of type GAAT_DATASET.
template<class MyAlgorithm>
bool RegisterSubAlgorithm ()
 Register the sub-algorithm of type MyAlgorithm.
bool RegisterSubAlgorithm (const GDALAlgorithmRegistry::AlgInfo &info)
 Register a sub-algoritm by its AlgInfo structure.
void AllowArbitraryLongNameArgs ()
 Allow arbitrary user arguments using long name syntax (–something).
GDALInConstructionAlgorithmArgAddArg (const std::string &longName, char chShortName, const std::string &helpMessage, bool *pValue)
 Add boolean argument.
GDALInConstructionAlgorithmArgAddArg (const std::string &longName, char chShortName, const std::string &helpMessage, std::string *pValue)
 Add string argument.
GDALInConstructionAlgorithmArgAddArg (const std::string &longName, char chShortName, const std::string &helpMessage, int *pValue)
 Add integer argument.
GDALInConstructionAlgorithmArgAddArg (const std::string &longName, char chShortName, const std::string &helpMessage, double *pValue)
 Add real argument.
GDALInConstructionAlgorithmArgAddArg (const std::string &longName, char chShortName, const std::string &helpMessage, GDALArgDatasetValue *pValue, GDALArgDatasetType type=GDAL_OF_RASTER|GDAL_OF_VECTOR|GDAL_OF_MULTIDIM_RASTER)
 Add dataset argument.
GDALInConstructionAlgorithmArgAddArg (const std::string &longName, char chShortName, const std::string &helpMessage, std::vector< std::string > *pValue)
 Add list of string argument.
GDALInConstructionAlgorithmArgAddArg (const std::string &longName, char chShortName, const std::string &helpMessage, std::vector< int > *pValue)
 Add list of integer argument.
GDALInConstructionAlgorithmArgAddArg (const std::string &longName, char chShortName, const std::string &helpMessage, std::vector< double > *pValue)
 Add list of real argument.
GDALInConstructionAlgorithmArgAddArg (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)
 Add list of dataset argument.
GDALInConstructionAlgorithmArgAddInputDatasetArg (GDALArgDatasetValue *pValue, GDALArgDatasetType type=GDAL_OF_RASTER|GDAL_OF_VECTOR|GDAL_OF_MULTIDIM_RASTER, bool positionalAndRequired=true, const char *helpMessage=nullptr)
 Add input dataset argument.
GDALInConstructionAlgorithmArgAddInputDatasetArg (std::vector< GDALArgDatasetValue > *pValue, GDALArgDatasetType type=GDAL_OF_RASTER|GDAL_OF_VECTOR|GDAL_OF_MULTIDIM_RASTER, bool positionalAndRequired=true, const char *helpMessage=nullptr)
 Add input dataset argument.
GDALInConstructionAlgorithmArgAddOpenOptionsArg (std::vector< std::string > *pValue, const char *helpMessage=nullptr)
 Add (input) open option(s) argument.
GDALInConstructionAlgorithmArgAddOutputOpenOptionsArg (std::vector< std::string > *pValue, const char *helpMessage=nullptr)
 Add output open option(s) argument.
GDALInConstructionAlgorithmArgAddInputFormatsArg (std::vector< std::string > *pValue, const char *helpMessage=nullptr)
 Add input format(s) argument.
GDALInConstructionAlgorithmArgAddOutputDatasetArg (GDALArgDatasetValue *pValue, GDALArgDatasetType type=GDAL_OF_RASTER|GDAL_OF_VECTOR|GDAL_OF_MULTIDIM_RASTER, bool positionalAndRequired=true, const char *helpMessage=nullptr)
 Add output dataset argument.
GDALInConstructionAlgorithmArgAddOverwriteArg (bool *pValue, const char *helpMessage=nullptr)
 Add --overwrite argument.
GDALInConstructionAlgorithmArgAddOverwriteLayerArg (bool *pValue, const char *helpMessage=nullptr)
 Add --overwrite-layer argument.
GDALInConstructionAlgorithmArgAddUpdateArg (bool *pValue, const char *helpMessage=nullptr)
 Add --update argument.
GDALInConstructionAlgorithmArgAddAppendLayerArg (bool *pValue, const char *helpMessage=nullptr)
 Add --append argument for a vector layer.
GDALInConstructionAlgorithmArgAddOutputStringArg (std::string *pValue, const char *helpMessage=nullptr)
 Add (non-CLI) output-string argument.
GDALInConstructionAlgorithmArgAddStdoutArg (bool *pValue, const char *helpMessage=nullptr)
 Add (hidden) stdout argument.
GDALInConstructionAlgorithmArgAddOutputFormatArg (std::string *pValue, bool bStreamAllowed=false, bool bGDALGAllowed=false, const char *helpMessage=nullptr)
 Add output format argument.
GDALInConstructionAlgorithmArgAddOutputDataTypeArg (std::string *pValue, const char *helpMessage=nullptr)
 Add output data type argument.
GDALInConstructionAlgorithmArgAddNodataArg (std::string *pValue, bool noneAllowed, const std::string &optionName="nodata", const char *helpMessage=nullptr)
 Add nodata argument.
GDALInConstructionAlgorithmArgAddCreationOptionsArg (std::vector< std::string > *pValue, const char *helpMessage=nullptr)
 Add creation option(s) argument.
GDALInConstructionAlgorithmArgAddLayerCreationOptionsArg (std::vector< std::string > *pValue, const char *helpMessage=nullptr)
 Add layer creation option(s) argument.
GDALInConstructionAlgorithmArgAddLayerNameArg (std::string *pValue, const char *helpMessage=nullptr)
 Add (single) layer name argument.
GDALInConstructionAlgorithmArgAddOutputLayerNameArg (std::string *pValue, const char *helpMessage=nullptr)
 Add (single) output layer name argument.
GDALInConstructionAlgorithmArgAddLayerNameArg (std::vector< std::string > *pValue, const char *helpMessage=nullptr)
 Add (potentially multiple) layer name(s) argument.
GDALInConstructionAlgorithmArgAddArrayNameArg (std::string *pValue, const char *helpMessage=nullptr)
 Add (single) (multidimensional) array name argument.
GDALInConstructionAlgorithmArgAddArrayNameArg (std::vector< std::string > *pValue, const char *helpMessage=nullptr)
 Add (multiple) (multidimensional) array name argument.
GDALInConstructionAlgorithmArgAddMemorySizeArg (size_t *pValue, std::string *pStrValue, const std::string &optionName, const char *helpMessage)
 Add a memory size argument(s), The final value is stored in *pValue.
GDALInConstructionAlgorithmArgAddGeometryTypeArg (std::string *pValue, const char *helpMessage=nullptr)
 Add geometry type argument.
GDALInConstructionAlgorithmArgAddFieldNameArg (std::string *pValue, const char *helpMessage=nullptr)
 Add a field name argument.
GDALInConstructionAlgorithmArgAddFieldTypeSubtypeArg (OGRFieldType *pTypeValue, OGRFieldSubType *pSubtypeValue, std::string *pStrValue, const std::string &argName=std::string(), const char *helpMessage=nullptr)
 Add a field type (or subtype) argument.
GDALInConstructionAlgorithmArgAddBandArg (int *pValue, const char *helpMessage=nullptr)
 Add (single) band argument.
GDALInConstructionAlgorithmArgAddBandArg (std::vector< int > *pValue, const char *helpMessage=nullptr)
 Add (potentially multiple) band argument.
GDALInConstructionAlgorithmArgAddBBOXArg (std::vector< double > *pValue, const char *helpMessage=nullptr)
 Add bbox=xmin,ymin,xmax,ymax argument.
GDALInConstructionAlgorithmArgAddActiveLayerArg (std::string *pValue, const char *helpMessage=nullptr)
 Add active layer argument.
GDALInConstructionAlgorithmArgAddNumThreadsArg (int *pValue, std::string *pStrValue, const char *helpMessage=nullptr)
 A number of thread argument.
GDALInConstructionAlgorithmArgAddAbsolutePathArg (bool *pValue, const char *helpMessage=nullptr)
 Add an argument to ask writing absolute paths.
GDALInConstructionAlgorithmArgAddPixelFunctionNameArg (std::string *pValue, const char *helpMessage=nullptr)
 Add an argument for pixel function name.
GDALInConstructionAlgorithmArgAddPixelFunctionArgsArg (std::vector< std::string > *pValue, const char *helpMessage=nullptr)
 Add an argument for pixel function arguments.
void AddProgressArg ()
 Add --quiet (and hidden --progress) argument.
void AddValidationAction (std::function< bool()> f)
 Register an action that is executed by the ValidateArguments() method.
bool ParseAndValidateKeyValue (GDALAlgorithmArg &arg)
 Validation function to use for key=value type of arguments.
bool RunPreStepPipelineValidations () const
 Method used by GDALRaster|VectorPipelineAlgorithm.
bool IsGDALGOutput () const
 Return whether output-format or output arguments express GDALG output.
virtual ProcessGDALGOutputRet ProcessGDALGOutput ()
 Process output to a .gdalg file.
virtual bool CheckSafeForStreamOutput ()
 Method executed by Run() when m_executionForStreamOutput is set to ensure the command is safe to execute in a streamed dataset context.
bool ValidateFormat (const GDALAlgorithmArg &arg, bool bStreamAllowed, bool bGDALGAllowed) const
 Validate a format argument.
void SetDisplayInJSONUsage (bool b)
 Set whether this algorithm should be reported in JSON usage.
virtual void WarnIfDeprecated ()
 Method that an algorithm can implement to issue a warning message about its deprecation.
std::pair< std::vector< std::pair< GDALAlgorithmArg *, std::string > >, size_t > GetArgNamesForCLI () const
 Return the list of arguments for CLI usage.

Static Protected Member Functions

static void SetAutoCompleteFunctionForFilename (GDALInConstructionAlgorithmArg &arg, GDALArgDatasetType type)
 Register an auto complete function for a filename argument.
static void SetAutoCompleteFunctionForLayerName (GDALInConstructionAlgorithmArg &layerArg, GDALInConstructionAlgorithmArg &datasetArg)
 Register an auto complete function for a layer name argument.
static void SetAutoCompleteFunctionForFieldName (GDALInConstructionAlgorithmArg &fieldArg, GDALInConstructionAlgorithmArg &layerNameArg, std::vector< GDALArgDatasetValue > &datasetArg)
 Register an auto complete function for a field name argument.
static bool AddOptionsSuggestions (const char *pszXML, int datasetType, const std::string &currentValue, std::vector< std::string > &oRet)
 Add KEY=VALUE suggestion from open, creation options.
static std::vector< std::string > FormatAutoCompleteFunction (const GDALAlgorithmArg &arg, bool bStreamAllowed, bool bGDALGAllowed)
 Completion function for a format argument.
static bool IsKnownOutputRelatedBooleanArgName (std::string_view osName)
 Whether this argument name is the one of a well-known boolean argument.

Protected Attributes

GDALAlgorithmm_selectedSubAlg = nullptr
 Selected sub-algorithm.
std::vector< std::string > m_callPath {}
 Call path to the current algorithm.
std::string m_longDescription {}
 Long description of the algorithm.
bool m_progressBarRequested = true
 Whether a progress bar is requested (value of --progress argument).
bool m_quiet = false
 Whether a progress bar is disabled (value of --quiet argument).
bool m_skipValidationInParseCommandLine = false
 Whether ValidateArguments() should be skipped during ParseCommandLineArguments().
std::vector< std::string > m_aliases {}
 Algorithm alias names.
bool m_supportsStreamedOutput = false
 Whether this algorithm supports a streamed output dataset.
bool m_executionForStreamOutput = false
 Whether this algorithm is run to generated a streamed output dataset.
bool m_hidden = false
 Whether this algorithm should be hidden (but can be instantiate if name known).
std::map< std::string, GDALDataset * > m_oMapDatasetNameToDataset {}
 Map a dataset name to its object (used for nested pipelines).

Friends

struct test_gdal_algorithm::test_gdal_algorithm
class GDALInConstructionAlgorithmArg
class GDALRasterReprojectUtils
class GDALAlgorithmRegistry
GDALAlgorithmArgH GDALAlgorithmGetArg (GDALAlgorithmH hAlg, const char *pszArgName)
 Return an argument from its name.
GDALAlgorithmArgH GDALAlgorithmGetArgNonConst (GDALAlgorithmH hAlg, const char *pszArgName)
 Return an argument from its name, possibly allowing creation of user-provided argument if the algorithm allow it.

Detailed Description

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.

Member Enumeration Documentation

◆ ProcessGDALGOutputRet

enum class GDALAlgorithm::ProcessGDALGOutputRet
strongprotected

Return value for ProcessGDALGOutput.

Enumerator
GDALG_OK 

GDALG output requested and successful.

GDALG_ERROR 

GDALG output requested but an error has occurred.

NOT_GDALG 

GDALG output not requeste.

RunImpl() must be run.

Member Function Documentation

◆ AddMemorySizeArg()

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

Add a memory size argument(s), The final value is stored in *pValue.

pStrValue must be provided as temporary storage, and its initial value (if not empty) is used as the SetDefault() value.

◆ AddNumThreadsArg()

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

A number of thread argument.

The final value is stored in *pValue. pStrValue must be provided as temporary storage, and its initial value (if not empty) is used as the SetDefault() value.

◆ AddValidationAction()

void GDALAlgorithm::AddValidationAction ( std::function< bool()> f)
inlineprotected

Register an action that is executed by the ValidateArguments() method.

If the provided function returns false, validation fails. Such validation function should typically be used to ensure cross-argument validation. For validation of individual arguments, GDALAlgorithmArg::AddValidationAction should rather be called.

◆ Finalize()

bool GDALAlgorithm::Finalize ( )
virtual

Complete any pending actions, and return the final status.

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

◆ GetActualAlgorithm()

GDALAlgorithm & GDALAlgorithm::GetActualAlgorithm ( )
inline

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

Only valid after ParseCommandLineArguments() has been called.

◆ GetHelpURL()

const std::string & GDALAlgorithm::GetHelpURL ( ) const
inline

Get the algorithm help URL.

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

◆ GetLongDescription()

const std::string & GDALAlgorithm::GetLongDescription ( ) const
inline

Get the long algorithm description.

May be empty.

◆ GetSubAlgorithmNames()

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

Get the names of registered algorithms.

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

◆ GetUsageAsJSON()

std::string GDALAlgorithm::GetUsageAsJSON ( ) const
virtual

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

This can be used to dynamically generate interfaces to algorithms.

◆ SaveGDALG()

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

Save command line in a .gdalg.json file.

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

◆ SetCallPath()

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

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().

◆ SetExecutionForStreamedOutput()

void GDALAlgorithm::SetExecutionForStreamedOutput ( )
inline

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().

◆ SetParseForAutoCompletion()

void GDALAlgorithm::SetParseForAutoCompletion ( )
inline

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"

◆ SetReferencePathForRelativePaths()

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

Set the reference file paths used to interpret relative paths.

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

◆ ValidateArguments()

bool GDALAlgorithm::ValidateArguments ( )
virtual

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.

◆ WarnIfDeprecated()

virtual void GDALAlgorithm::WarnIfDeprecated ( )
inlineprotectedvirtual

Method that an algorithm can implement to issue a warning message about its deprecation.

This is called at the beginning of the Run() method.

◆ GDALAlgorithmGetArg

GDALAlgorithmArgH GDALAlgorithmGetArg ( GDALAlgorithmH hAlg,
const char * pszArgName )
friend

Return an argument from its name.

The lifetime of the returned object does not exceed the one of hAlg.

Parameters
hAlgHandle to an algorithm. Must NOT be null.
pszArgNameArgument name. Must NOT be null.
Returns
an argument that must be released with GDALAlgorithmArgRelease(), or nullptr in case of error
Since
3.11

◆ GDALAlgorithmGetArgNonConst

GDALAlgorithmArgH GDALAlgorithmGetArgNonConst ( GDALAlgorithmH hAlg,
const char * pszArgName )
friend

Return an argument from its name, possibly allowing creation of user-provided argument if the algorithm allow it.

The lifetime of the returned object does not exceed the one of hAlg.

Parameters
hAlgHandle to an algorithm. Must NOT be null.
pszArgNameArgument name. Must NOT be null.
Returns
an argument that must be released with GDALAlgorithmArgRelease(), or nullptr in case of error
Since
3.12

Member Data Documentation

◆ m_callPath

std::vector<std::string> GDALAlgorithm::m_callPath {}
protected

Call path to the current algorithm.

For example, for "gdal convert raster", it is ["gdal", "convert"]

◆ m_selectedSubAlg

GDALAlgorithm* GDALAlgorithm::m_selectedSubAlg = nullptr
protected

Selected sub-algorithm.

Set by ParseCommandLineArguments() when handling over on a sub-algorithm.


The documentation for this class was generated from the following files: