Line data Source code
1 : /******************************************************************************
2 : *
3 : * Project: GDAL
4 : * Purpose: GDALAlgorithm class
5 : * Author: Even Rouault <even dot rouault at spatialys.com>
6 : *
7 : ******************************************************************************
8 : * Copyright (c) 2024, Even Rouault <even dot rouault at spatialys.com>
9 : *
10 : * SPDX-License-Identifier: MIT
11 : ****************************************************************************/
12 :
13 : #ifndef GDAL_ALGORITHM_INCLUDED
14 : #define GDAL_ALGORITHM_INCLUDED
15 :
16 : #include "cpl_port.h"
17 : #include "cpl_progress.h"
18 :
19 : #include "gdal.h"
20 :
21 : /************************************************************************/
22 : /************************************************************************/
23 : /* GDAL Algorithm C API */
24 : /************************************************************************/
25 : /************************************************************************/
26 :
27 : CPL_C_START
28 :
29 : /** Type of an argument */
30 : typedef enum GDALAlgorithmArgType
31 : {
32 : /** Boolean type. Value is a bool. */
33 : GAAT_BOOLEAN,
34 : /** Single-value string type. Value is a std::string */
35 : GAAT_STRING,
36 : /** Single-value integer type. Value is a int */
37 : GAAT_INTEGER,
38 : /** Single-value real type. Value is a double */
39 : GAAT_REAL,
40 : /** Dataset type. Value is a GDALArgDatasetValue */
41 : GAAT_DATASET,
42 : /** Multi-value string type. Value is a std::vector<std::string> */
43 : GAAT_STRING_LIST,
44 : /** Multi-value integer type. Value is a std::vector<int> */
45 : GAAT_INTEGER_LIST,
46 : /** Multi-value real type. Value is a std::vector<double> */
47 : GAAT_REAL_LIST,
48 : /** Multi-value dataset type. Value is a std::vector<GDALArgDatasetValue> */
49 : GAAT_DATASET_LIST,
50 : } GDALAlgorithmArgType;
51 :
52 : /** Return whether the argument type is a list / multi-valued one. */
53 : bool CPL_DLL GDALAlgorithmArgTypeIsList(GDALAlgorithmArgType type);
54 :
55 : /** Return the string representation of the argument type */
56 : const char CPL_DLL *GDALAlgorithmArgTypeName(GDALAlgorithmArgType type);
57 :
58 : /** Opaque C type for GDALArgDatasetValue */
59 : typedef struct GDALArgDatasetValueHS *GDALArgDatasetValueH;
60 :
61 : /** Opaque C type for GDALAlgorithmArg */
62 : typedef struct GDALAlgorithmArgHS *GDALAlgorithmArgH;
63 :
64 : /** Opaque C type for GDALAlgorithm */
65 : typedef struct GDALAlgorithmHS *GDALAlgorithmH;
66 :
67 : /** Opaque C type for GDALAlgorithmRegistry */
68 : typedef struct GDALAlgorithmRegistryHS *GDALAlgorithmRegistryH;
69 :
70 : /************************************************************************/
71 : /* GDALAlgorithmRegistryH API */
72 : /************************************************************************/
73 :
74 : GDALAlgorithmRegistryH CPL_DLL GDALGetGlobalAlgorithmRegistry(void);
75 :
76 : void CPL_DLL GDALAlgorithmRegistryRelease(GDALAlgorithmRegistryH);
77 :
78 : char CPL_DLL **GDALAlgorithmRegistryGetAlgNames(GDALAlgorithmRegistryH);
79 :
80 : GDALAlgorithmH CPL_DLL GDALAlgorithmRegistryInstantiateAlg(
81 : GDALAlgorithmRegistryH, const char *pszAlgName);
82 :
83 : /************************************************************************/
84 : /* GDALAlgorithmH API */
85 : /************************************************************************/
86 :
87 : void CPL_DLL GDALAlgorithmRelease(GDALAlgorithmH);
88 :
89 : const char CPL_DLL *GDALAlgorithmGetName(GDALAlgorithmH);
90 :
91 : const char CPL_DLL *GDALAlgorithmGetDescription(GDALAlgorithmH);
92 :
93 : const char CPL_DLL *GDALAlgorithmGetLongDescription(GDALAlgorithmH);
94 :
95 : const char CPL_DLL *GDALAlgorithmGetHelpFullURL(GDALAlgorithmH);
96 :
97 : bool CPL_DLL GDALAlgorithmHasSubAlgorithms(GDALAlgorithmH);
98 :
99 : char CPL_DLL **GDALAlgorithmGetSubAlgorithmNames(GDALAlgorithmH);
100 :
101 : GDALAlgorithmH CPL_DLL
102 : GDALAlgorithmInstantiateSubAlgorithm(GDALAlgorithmH, const char *pszSubAlgName);
103 :
104 : bool CPL_DLL GDALAlgorithmParseCommandLineArguments(GDALAlgorithmH,
105 : CSLConstList papszArgs);
106 :
107 : GDALAlgorithmH CPL_DLL GDALAlgorithmGetActualAlgorithm(GDALAlgorithmH);
108 :
109 : bool CPL_DLL GDALAlgorithmRun(GDALAlgorithmH, GDALProgressFunc pfnProgress,
110 : void *pProgressData);
111 :
112 : bool CPL_DLL GDALAlgorithmFinalize(GDALAlgorithmH);
113 :
114 : char CPL_DLL *GDALAlgorithmGetUsageAsJSON(GDALAlgorithmH);
115 :
116 : char CPL_DLL **GDALAlgorithmGetArgNames(GDALAlgorithmH);
117 :
118 : GDALAlgorithmArgH CPL_DLL GDALAlgorithmGetArg(GDALAlgorithmH,
119 : const char *pszArgName);
120 :
121 : /************************************************************************/
122 : /* GDALAlgorithmArgH API */
123 : /************************************************************************/
124 :
125 : void CPL_DLL GDALAlgorithmArgRelease(GDALAlgorithmArgH);
126 :
127 : const char CPL_DLL *GDALAlgorithmArgGetName(GDALAlgorithmArgH);
128 :
129 : GDALAlgorithmArgType CPL_DLL GDALAlgorithmArgGetType(GDALAlgorithmArgH);
130 :
131 : const char CPL_DLL *GDALAlgorithmArgGetDescription(GDALAlgorithmArgH);
132 :
133 : const char CPL_DLL *GDALAlgorithmArgGetShortName(GDALAlgorithmArgH);
134 :
135 : char CPL_DLL **GDALAlgorithmArgGetAliases(GDALAlgorithmArgH);
136 :
137 : const char CPL_DLL *GDALAlgorithmArgGetMetaVar(GDALAlgorithmArgH);
138 :
139 : const char CPL_DLL *GDALAlgorithmArgGetCategory(GDALAlgorithmArgH);
140 :
141 : bool CPL_DLL GDALAlgorithmArgIsPositional(GDALAlgorithmArgH);
142 :
143 : bool CPL_DLL GDALAlgorithmArgIsRequired(GDALAlgorithmArgH);
144 :
145 : int CPL_DLL GDALAlgorithmArgGetMinCount(GDALAlgorithmArgH);
146 :
147 : int CPL_DLL GDALAlgorithmArgGetMaxCount(GDALAlgorithmArgH);
148 :
149 : bool CPL_DLL GDALAlgorithmArgGetPackedValuesAllowed(GDALAlgorithmArgH);
150 :
151 : bool CPL_DLL GDALAlgorithmArgGetRepeatedArgAllowed(GDALAlgorithmArgH);
152 :
153 : char CPL_DLL **GDALAlgorithmArgGetChoices(GDALAlgorithmArgH);
154 :
155 : bool CPL_DLL GDALAlgorithmArgIsExplicitlySet(GDALAlgorithmArgH);
156 :
157 : bool CPL_DLL GDALAlgorithmArgHasDefaultValue(GDALAlgorithmArgH);
158 :
159 : bool CPL_DLL GDALAlgorithmArgIsHiddenForCLI(GDALAlgorithmArgH);
160 :
161 : bool CPL_DLL GDALAlgorithmArgIsOnlyForCLI(GDALAlgorithmArgH);
162 :
163 : bool CPL_DLL GDALAlgorithmArgIsInput(GDALAlgorithmArgH);
164 :
165 : bool CPL_DLL GDALAlgorithmArgIsOutput(GDALAlgorithmArgH);
166 :
167 : const char CPL_DLL *GDALAlgorithmArgGetMutualExclusionGroup(GDALAlgorithmArgH);
168 :
169 : bool CPL_DLL GDALAlgorithmArgGetAsBoolean(GDALAlgorithmArgH);
170 :
171 : const char CPL_DLL *GDALAlgorithmArgGetAsString(GDALAlgorithmArgH);
172 :
173 : GDALArgDatasetValueH
174 : CPL_DLL GDALAlgorithmArgGetAsDatasetValue(GDALAlgorithmArgH);
175 :
176 : int CPL_DLL GDALAlgorithmArgGetAsInteger(GDALAlgorithmArgH);
177 :
178 : double CPL_DLL GDALAlgorithmArgGetAsDouble(GDALAlgorithmArgH);
179 :
180 : char CPL_DLL **GDALAlgorithmArgGetAsStringList(GDALAlgorithmArgH);
181 :
182 : const int CPL_DLL *GDALAlgorithmArgGetAsIntegerList(GDALAlgorithmArgH,
183 : size_t *pnCount);
184 :
185 : const double CPL_DLL *GDALAlgorithmArgGetAsDoubleList(GDALAlgorithmArgH,
186 : size_t *pnCount);
187 :
188 : bool CPL_DLL GDALAlgorithmArgSetAsBoolean(GDALAlgorithmArgH, bool);
189 :
190 : bool CPL_DLL GDALAlgorithmArgSetAsString(GDALAlgorithmArgH, const char *);
191 :
192 : bool CPL_DLL GDALAlgorithmArgSetAsDatasetValue(GDALAlgorithmArgH hArg,
193 : GDALArgDatasetValueH value);
194 :
195 : bool CPL_DLL GDALAlgorithmArgSetDataset(GDALAlgorithmArgH hArg, GDALDatasetH);
196 :
197 : bool CPL_DLL GDALAlgorithmArgSetDatasets(GDALAlgorithmArgH hArg, size_t nCount,
198 : GDALDatasetH *);
199 :
200 : bool CPL_DLL GDALAlgorithmArgSetDatasetNames(GDALAlgorithmArgH hArg,
201 : CSLConstList);
202 :
203 : bool CPL_DLL GDALAlgorithmArgSetAsInteger(GDALAlgorithmArgH, int);
204 :
205 : bool CPL_DLL GDALAlgorithmArgSetAsDouble(GDALAlgorithmArgH, double);
206 :
207 : bool CPL_DLL GDALAlgorithmArgSetAsStringList(GDALAlgorithmArgH, CSLConstList);
208 :
209 : bool CPL_DLL GDALAlgorithmArgSetAsIntegerList(GDALAlgorithmArgH, size_t nCount,
210 : const int *pnValues);
211 :
212 : bool CPL_DLL GDALAlgorithmArgSetAsDoubleList(GDALAlgorithmArgH, size_t nCount,
213 : const double *pnValues);
214 :
215 : /************************************************************************/
216 : /* GDALArgDatasetValueH API */
217 : /************************************************************************/
218 :
219 : GDALArgDatasetValueH CPL_DLL GDALArgDatasetValueCreate(void);
220 :
221 : void CPL_DLL GDALArgDatasetValueRelease(GDALArgDatasetValueH);
222 :
223 : const char CPL_DLL *GDALArgDatasetValueGetName(GDALArgDatasetValueH);
224 :
225 : GDALDatasetH CPL_DLL GDALArgDatasetValueGetDatasetRef(GDALArgDatasetValueH);
226 :
227 : GDALDatasetH
228 : CPL_DLL GDALArgDatasetValueGetDatasetIncreaseRefCount(GDALArgDatasetValueH);
229 :
230 : /** Bit indicating that the name component of GDALArgDatasetValue is accepted. */
231 : #define GADV_NAME (1 << 0)
232 : /** Bit indicating that the dataset component of GDALArgDatasetValue is accepted. */
233 : #define GADV_OBJECT (1 << 1)
234 :
235 : /** Binary-or combination of GDAL_OF_RASTER, GDAL_OF_VECTOR and
236 : * GDAL_OF_MULTIDIM_RASTER.
237 : */
238 : typedef int GDALArgDatasetValueType;
239 :
240 : GDALArgDatasetValueType
241 : CPL_DLL GDALArgDatasetValueGetType(GDALArgDatasetValueH);
242 :
243 : int CPL_DLL GDALArgDatasetValueGetInputFlags(GDALArgDatasetValueH);
244 :
245 : int CPL_DLL GDALArgDatasetValueGetOutputFlags(GDALArgDatasetValueH);
246 :
247 : void CPL_DLL GDALArgDatasetValueSetName(GDALArgDatasetValueH, const char *);
248 :
249 : void CPL_DLL GDALArgDatasetValueSetDataset(GDALArgDatasetValueH, GDALDatasetH);
250 :
251 : CPL_C_END
252 :
253 : /************************************************************************/
254 : /************************************************************************/
255 : /* GDAL Algorithm C++ API */
256 : /************************************************************************/
257 : /************************************************************************/
258 :
259 : // The rest of this header requires C++17
260 : // _MSC_VER >= 1920 : Visual Studio >= 2019
261 : #if defined(__cplusplus) && !defined(CPL_SUPRESS_CPLUSPLUS) && \
262 : (defined(DOXYGEN_SKIP) || __cplusplus >= 201703L || _MSC_VER >= 1920)
263 :
264 : #include "cpl_error.h"
265 :
266 : #include <limits>
267 : #include <functional>
268 : #include <map>
269 : #include <memory>
270 : #include <string>
271 : #include <type_traits>
272 : #include <utility>
273 : #include <variant>
274 : #include <vector>
275 :
276 : class GDALDataset;
277 :
278 : /** Common argument category */
279 : constexpr const char *GAAC_COMMON = "Common";
280 :
281 : /** Base argument category */
282 : constexpr const char *GAAC_BASE = "Base";
283 :
284 : /** Advanced argument category */
285 : constexpr const char *GAAC_ADVANCED = "Advanced";
286 :
287 : /** Esoteric argument category */
288 : constexpr const char *GAAC_ESOTERIC = "Esoteric";
289 :
290 : /** Argument metadata item that applies to the "input-format" and
291 : * "output-format" argument */
292 : constexpr const char *GAAMDI_REQUIRED_CAPABILITIES = "required_capabilities";
293 :
294 : /** Name of the argument for an input dataset. */
295 : constexpr const char *GDAL_ARG_NAME_INPUT = "input";
296 :
297 : /** Name of the argument for an output dataset. */
298 : constexpr const char *GDAL_ARG_NAME_OUTPUT = "output";
299 :
300 : /** Name of the argument for update. */
301 : constexpr const char *GDAL_ARG_NAME_UPDATE = "update";
302 :
303 : /** Name of the argument for read-only. */
304 : constexpr const char *GDAL_ARG_NAME_READ_ONLY = "read-only";
305 :
306 : /************************************************************************/
307 : /* GDALArgDatasetValue */
308 : /************************************************************************/
309 :
310 : /** Return the string representation of GDALArgDatasetValueType */
311 : std::string CPL_DLL GDALArgDatasetValueTypeName(GDALArgDatasetValueType);
312 :
313 : class GDALAlgorithmArg;
314 :
315 : /** Value for an argument that points to a GDALDataset.
316 : *
317 : * This is the value of arguments of type GAAT_DATASET or GAAT_DATASET_LIST.
318 : */
319 : class CPL_DLL GDALArgDatasetValue final
320 : {
321 : public:
322 : /** Default (empty) constructor */
323 1775 : GDALArgDatasetValue() = default;
324 :
325 : /** Constructor by dataset name. */
326 22 : explicit GDALArgDatasetValue(const std::string &name) : m_name(name)
327 : {
328 22 : }
329 :
330 : /** Constructor by dataset instance, increasing its reference counter */
331 : explicit GDALArgDatasetValue(GDALDataset *poDS);
332 :
333 : /** Move constructor */
334 : GDALArgDatasetValue(GDALArgDatasetValue &&other);
335 :
336 : /** Destructor. Decrease m_poDS reference count, and destroy it if no
337 : * longer referenced. */
338 : ~GDALArgDatasetValue();
339 :
340 : /** Dereference the dataset object and close it if no longer referenced.
341 : * Return an error if an error occurred during dataset closing. */
342 : bool Close();
343 :
344 : /** Move-assignment operator */
345 : GDALArgDatasetValue &operator=(GDALArgDatasetValue &&other);
346 :
347 : /** Get the GDALDataset* instance (may be null), and increase its reference
348 : * count if not null. Once done with the dataset, the caller should call
349 : * GDALDataset::Release().
350 : */
351 : GDALDataset *GetDatasetIncreaseRefCount();
352 :
353 : /** Get a GDALDataset* instance (may be null). This does not modify the
354 : * reference counter, hence the lifetime of the returned object is not
355 : * guaranteed to exceed the one of this instance.
356 : */
357 3446 : GDALDataset *GetDatasetRef()
358 : {
359 3446 : return m_poDS;
360 : }
361 :
362 : /** Borrow the GDALDataset* instance (may be null), leaving its reference
363 : * counter unchanged.
364 : */
365 1 : GDALDataset *BorrowDataset()
366 : {
367 1 : GDALDataset *ret = m_poDS;
368 1 : m_poDS = nullptr;
369 1 : return ret;
370 : }
371 :
372 : /** Borrow the GDALDataset* instance from another GDALArgDatasetValue,
373 : * leaving its reference counter unchange.
374 : */
375 : void BorrowDatasetFrom(GDALArgDatasetValue &other)
376 : {
377 : Close();
378 : m_poDS = other.BorrowDataset();
379 : m_name = other.m_name;
380 : }
381 :
382 : /** Get dataset name */
383 765 : const std::string &GetName() const
384 : {
385 765 : return m_name;
386 : }
387 :
388 : /** Return whether a dataset name has been set */
389 538 : bool IsNameSet() const
390 : {
391 538 : return m_nameSet;
392 : }
393 :
394 : /** Indicates which components among name and dataset are accepted as
395 : * input, when this argument serves as an input.
396 : *
397 : * If the GADV_NAME bit is set, it indicates a dataset name is accepted as
398 : * input.
399 : * If the GADV_OBJECT bit is set, it indicates a dataset object is
400 : * accepted as input.
401 : * If both bits are set, the algorithm can accept either a name or a dataset
402 : * object.
403 : */
404 111 : int GetInputFlags() const
405 : {
406 111 : return m_inputFlags;
407 : }
408 :
409 : /** Indicates which components among name and dataset are modified,
410 : * when this argument serves as an output.
411 : *
412 : * If the GADV_NAME bit is set, it indicates a dataset name is generated as
413 : * output (that is the algorithm will generate the name. Rarely used).
414 : * If the GADV_OBJECT bit is set, it indicates a dataset object is
415 : * generated as output, and available for use after the algorithm has
416 : * completed.
417 : */
418 37 : int GetOutputFlags() const
419 : {
420 37 : return m_outputFlags;
421 : }
422 :
423 : /** Set dataset name */
424 : void Set(const std::string &name);
425 :
426 : /** Transfer dataset to this instance (does not affect its reference
427 : * counter). */
428 : void Set(std::unique_ptr<GDALDataset> poDS);
429 :
430 : /** Set dataset object, increasing its reference counter. */
431 : void Set(GDALDataset *poDS);
432 :
433 : /** Set from other value, increasing the reference counter of the
434 : * GDALDataset object.
435 : */
436 : void SetFrom(const GDALArgDatasetValue &other);
437 :
438 : /** Set which components among name and dataset are accepted as
439 : * input, when this argument serves as an input.
440 : * Should only be used by GDALAlgorithm sub-classes.
441 : */
442 834 : void SetInputFlags(int flags)
443 : {
444 834 : m_inputFlags = flags;
445 834 : }
446 :
447 : /** Set which components among name and dataset are modified when this
448 : * argument serves as an output.
449 : * Should only be used by GDALAlgorithm sub-classes.
450 : */
451 473 : void SetOutputFlags(int flags)
452 : {
453 473 : m_outputFlags = flags;
454 473 : }
455 :
456 : /** Get which type of dataset is allowed / generated.
457 : * Binary-or combination of GDAL_OF_RASTER, GDAL_OF_VECTOR and
458 : * GDAL_OF_MULTIDIM_RASTER, possibly combined with GDAL_OF_UPDATE.
459 : */
460 429 : GDALArgDatasetValueType GetType() const
461 : {
462 429 : return m_type;
463 : }
464 :
465 : /** Set which type of dataset is allowed / generated.
466 : * Binary-or combination of GDAL_OF_RASTER, GDAL_OF_VECTOR and
467 : * GDAL_OF_MULTIDIM_RASTER.
468 : */
469 1080 : void SetType(GDALArgDatasetValueType type)
470 : {
471 1080 : m_type = type;
472 1080 : }
473 :
474 : protected:
475 : friend class GDALAlgorithm;
476 :
477 : /** Set the argument that owns us. */
478 1080 : void SetOwnerArgument(GDALAlgorithmArg *arg)
479 : {
480 1080 : CPLAssert(!m_ownerArg);
481 1080 : m_ownerArg = arg;
482 1080 : }
483 :
484 : private:
485 : /** The owner argument (may be nullptr for freestanding objects) */
486 : GDALAlgorithmArg *m_ownerArg = nullptr;
487 :
488 : /** Dataset object. */
489 : GDALDataset *m_poDS = nullptr;
490 :
491 : /** Dataset name */
492 : std::string m_name{};
493 :
494 : /** Whether a dataset name (possibly empty for a MEM dataset...) has been set */
495 : bool m_nameSet = false;
496 :
497 : /** Dataset type */
498 : GDALArgDatasetValueType m_type =
499 : GDAL_OF_RASTER | GDAL_OF_VECTOR | GDAL_OF_MULTIDIM_RASTER;
500 :
501 : /** Which components among name and dataset are accepted as
502 : * input, when this argument serves as an input.
503 : */
504 : int m_inputFlags = GADV_NAME | GADV_OBJECT;
505 :
506 : /** Which components among name and dataset are generated as
507 : * output, when this argument serves as an output.
508 : */
509 : int m_outputFlags = GADV_OBJECT;
510 :
511 : GDALArgDatasetValue(const GDALArgDatasetValue &) = delete;
512 : GDALArgDatasetValue &operator=(const GDALArgDatasetValue &) = delete;
513 : };
514 :
515 : /************************************************************************/
516 : /* GDALAlgorithmArgDecl */
517 : /************************************************************************/
518 :
519 : /** Argument declaration.
520 : *
521 : * It does not hold its value.
522 : */
523 : class CPL_DLL GDALAlgorithmArgDecl final
524 : {
525 : public:
526 : /** Special value for the SetMaxCount() / GetMaxCount() to indicate
527 : * unlimited number of values. */
528 : static constexpr int UNBOUNDED = std::numeric_limits<int>::max();
529 :
530 : /** Constructor.
531 : *
532 : * @param longName Long name. Must be 2 characters at least. Must not start
533 : * with dash.
534 : * @param chShortName 1-letter short name, or NUL character
535 : * @param description Description.
536 : * @param type Type of the argument.
537 : */
538 : GDALAlgorithmArgDecl(const std::string &longName, char chShortName,
539 : const std::string &description,
540 : GDALAlgorithmArgType type);
541 :
542 : /** Declare an alias. Must be 2 characters at least. */
543 3128 : GDALAlgorithmArgDecl &AddAlias(const std::string &alias)
544 : {
545 3128 : m_aliases.push_back(alias);
546 3128 : return *this;
547 : }
548 :
549 : /** Declare an hidden alias (i.e. not exposed in usage).
550 : * Must be 2 characters at least. */
551 537 : GDALAlgorithmArgDecl &AddHiddenAlias(const std::string &alias)
552 : {
553 537 : m_hiddenAliases.push_back(alias);
554 537 : return *this;
555 : }
556 :
557 : /** Declare that the argument is positional. Typically input / output files
558 : */
559 1025 : GDALAlgorithmArgDecl &SetPositional()
560 : {
561 1025 : m_positional = true;
562 1025 : return *this;
563 : }
564 :
565 : /** Declare that the argument is required. Default is no
566 : */
567 848 : GDALAlgorithmArgDecl &SetRequired()
568 : {
569 848 : m_required = true;
570 848 : return *this;
571 : }
572 :
573 : /** Declare the "meta-var" hint.
574 : * By default, the meta-var value is the long name of the argument in
575 : * upper case.
576 : */
577 3049 : GDALAlgorithmArgDecl &SetMetaVar(const std::string &metaVar)
578 : {
579 3049 : m_metaVar = metaVar;
580 3049 : return *this;
581 : }
582 :
583 : /** Declare the argument category: GAAC_COMMON, GAAC_BASE, GAAC_ADVANCED,
584 : * GAAC_ESOTERIC or a custom category.
585 : */
586 8824 : GDALAlgorithmArgDecl &SetCategory(const std::string &category)
587 : {
588 8824 : m_category = category;
589 8824 : return *this;
590 : }
591 :
592 : /** Declare a default value for the argument.
593 : */
594 1367 : template <class T> GDALAlgorithmArgDecl &SetDefault(const T &value)
595 : {
596 1367 : m_hasDefaultValue = true;
597 : if constexpr (std::is_same_v<T, int>)
598 : {
599 2 : if (m_type == GAAT_REAL)
600 : {
601 1 : m_defaultValue = static_cast<double>(value);
602 1 : return *this;
603 : }
604 : }
605 1366 : m_defaultValue = value;
606 1366 : return *this;
607 : }
608 :
609 : /** Declare the minimum number of values for the argument. Defaults to 0.
610 : * Only applies to list type of arguments.
611 : * Setting it to non-zero does *not* make the argument required. It just
612 : * sets the minimum number of values when it is specified. To also make
613 : * it required, use SetRequired().
614 : */
615 : GDALAlgorithmArgDecl &SetMinCount(int count);
616 :
617 : /** Declare the maximum number of values for the argument.
618 : * Defaults to 1 for scalar types, and UNBOUNDED for list types.
619 : * Only applies to list type of arguments.
620 : */
621 : GDALAlgorithmArgDecl &SetMaxCount(int count);
622 :
623 : /** Declare whether in --help message one should display hints about the
624 : * minimum/maximum number of values. Defaults to true.
625 : */
626 178 : GDALAlgorithmArgDecl &SetDisplayHintAboutRepetition(bool displayHint)
627 : {
628 178 : m_displayHintAboutRepetition = displayHint;
629 178 : return *this;
630 : }
631 :
632 : /** Declares whether, for list type of arguments, several values, space
633 : * separated, may be specified. That is "--foo=bar,baz".
634 : * The default is true.
635 : */
636 17 : GDALAlgorithmArgDecl &SetPackedValuesAllowed(bool allowed)
637 : {
638 17 : m_packedValuesAllowed = allowed;
639 17 : return *this;
640 : }
641 :
642 : /** Declares whether, for list type of arguments, the argument may be
643 : * repeated. That is "--foo=bar --foo=baz".
644 : * The default is true.
645 : */
646 236 : GDALAlgorithmArgDecl &SetRepeatedArgAllowed(bool allowed)
647 : {
648 236 : m_repeatedArgAllowed = allowed;
649 236 : return *this;
650 : }
651 :
652 : //! @cond Doxygen_Suppress
653 154 : GDALAlgorithmArgDecl &SetChoices()
654 : {
655 154 : return *this;
656 : }
657 :
658 : //! @endcond
659 :
660 : /** Declares the allowed values (as strings) for the argument.
661 : * Only honored for GAAT_STRING and GAAT_STRING_LIST types.
662 : */
663 : template <typename T, typename... U>
664 706 : GDALAlgorithmArgDecl &SetChoices(T &&first, U &&...rest)
665 : {
666 706 : m_choices.push_back(std::forward<T>(first));
667 706 : SetChoices(std::forward<U>(rest)...);
668 706 : return *this;
669 : }
670 :
671 : //! @cond Doxygen_Suppress
672 40 : GDALAlgorithmArgDecl &SetHiddenChoices()
673 : {
674 40 : return *this;
675 : }
676 :
677 : //! @endcond
678 :
679 : /** Declares the, hidden, allowed values (as strings) for the argument.
680 : * Only honored for GAAT_STRING and GAAT_STRING_LIST types.
681 : */
682 : template <typename T, typename... U>
683 40 : GDALAlgorithmArgDecl &SetHiddenChoices(T &&first, U &&...rest)
684 : {
685 40 : m_hiddenChoices.push_back(std::forward<T>(first));
686 40 : SetHiddenChoices(std::forward<U>(rest)...);
687 40 : return *this;
688 : }
689 :
690 : /** Declare that the argument must not be mentioned in CLI usage.
691 : * For example, "output-value" for "gdal raster info", which is only
692 : * meant when the algorithm is used from a non-CLI context.
693 : */
694 3950 : GDALAlgorithmArgDecl &SetHiddenForCLI(bool hiddenForCLI = true)
695 : {
696 3950 : m_hiddenForCLI = hiddenForCLI;
697 3950 : return *this;
698 : }
699 :
700 : /** Declare that the argument is only for CLI usage.
701 : * For example "--help" */
702 7388 : GDALAlgorithmArgDecl &SetOnlyForCLI(bool onlyForCLI = true)
703 : {
704 7388 : m_onlyForCLI = onlyForCLI;
705 7388 : return *this;
706 : }
707 :
708 : /** Indicate whether the value of the argument is read-only during the
709 : * execution of the algorithm. Default is true.
710 : */
711 551 : GDALAlgorithmArgDecl &SetIsInput(bool isInput = true)
712 : {
713 551 : m_isInput = isInput;
714 551 : return *this;
715 : }
716 :
717 : /** Indicate whether (at least part of) the value of the argument is set
718 : * during the execution of the algorithm.
719 : * For example, "output-value" for "gdal raster info"
720 : * Default is false.
721 : * An argument may return both IsInput() and IsOutput() as true.
722 : * For example the "gdal raster convert" algorithm consumes the dataset
723 : * name of its "output" argument, and sets the dataset object during its
724 : * execution.
725 : */
726 551 : GDALAlgorithmArgDecl &SetIsOutput(bool isOutput = true)
727 : {
728 551 : m_isOutput = isOutput;
729 551 : return *this;
730 : }
731 :
732 : /** Set the name of the mutual exclusion group to which this argument
733 : * belongs to. At most one argument in a group can be specified.
734 : */
735 496 : GDALAlgorithmArgDecl &SetMutualExclusionGroup(const std::string &group)
736 : {
737 496 : m_mutualExclusionGroup = group;
738 496 : return *this;
739 : }
740 :
741 : /** Set user-defined metadata item.
742 : */
743 : GDALAlgorithmArgDecl &
744 884 : AddMetadataItem(const std::string &name,
745 : const std::vector<std::string> &values)
746 : {
747 884 : m_metadata[name] = values;
748 884 : return *this;
749 : }
750 :
751 : /** Set that this (string) argument accepts the \@filename syntax to
752 : * mean that the content of the specified file should be used as the
753 : * value of the argument.
754 : */
755 103 : GDALAlgorithmArgDecl &SetReadFromFileAtSyntaxAllowed()
756 : {
757 103 : m_readFromFileAtSyntaxAllowed = true;
758 103 : return *this;
759 : }
760 :
761 : /** Sets that SQL comments must be removed from a (string) argument.
762 : */
763 102 : GDALAlgorithmArgDecl &SetRemoveSQLCommentsEnabled()
764 : {
765 102 : m_removeSQLComments = true;
766 102 : return *this;
767 : }
768 :
769 : /** Sets whether the dataset should be opened automatically by
770 : * GDALAlgorithm. Only applies to GAAT_DATASET and GAAT_DATASET_LIST.
771 : */
772 63 : GDALAlgorithmArgDecl &SetAutoOpenDataset(bool autoOpen)
773 : {
774 63 : m_autoOpenDataset = autoOpen;
775 63 : return *this;
776 : }
777 :
778 : /** Return the (long) name */
779 19253 : inline const std::string &GetName() const
780 : {
781 19253 : return m_longName;
782 : }
783 :
784 : /** Return the short name, or empty string if there is none */
785 15538 : inline const std::string &GetShortName() const
786 : {
787 15538 : return m_shortName;
788 : }
789 :
790 : /** Return the aliases (potentially none) */
791 560 : inline const std::vector<std::string> &GetAliases() const
792 : {
793 560 : return m_aliases;
794 : }
795 :
796 : /** Return the description */
797 911 : inline const std::string &GetDescription() const
798 : {
799 911 : return m_description;
800 : }
801 :
802 : /** Return the "meta-var" hint.
803 : * By default, the meta-var value is the long name of the argument in
804 : * upper case.
805 : */
806 571 : inline const std::string &GetMetaVar() const
807 : {
808 571 : return m_metaVar;
809 : }
810 :
811 : /** Return the argument category: GAAC_COMMON, GAAC_BASE, GAAC_ADVANCED,
812 : * GAAC_ESOTERIC or a custom category.
813 : */
814 1515 : inline const std::string &GetCategory() const
815 : {
816 1515 : return m_category;
817 : }
818 :
819 : /** Return the type */
820 20555 : inline GDALAlgorithmArgType GetType() const
821 : {
822 20555 : return m_type;
823 : }
824 :
825 : /** Return the allowed values (as strings) for the argument.
826 : * Only honored for GAAT_STRING and GAAT_STRING_LIST types.
827 : */
828 1300 : inline const std::vector<std::string> &GetChoices() const
829 : {
830 1300 : return m_choices;
831 : }
832 :
833 : /** Return the allowed hidden values (as strings) for the argument.
834 : * Only honored for GAAT_STRING and GAAT_STRING_LIST types.
835 : */
836 252 : inline const std::vector<std::string> &GetHiddenChoices() const
837 : {
838 252 : return m_hiddenChoices;
839 : }
840 :
841 : /** Return whether the argument is required. Defaults to false.
842 : */
843 12822 : inline bool IsRequired() const
844 : {
845 12822 : return m_required;
846 : }
847 :
848 : /** Return the minimum number of values for the argument. Defaults to 0.
849 : * Only applies to list type of arguments.
850 : */
851 1920 : inline int GetMinCount() const
852 : {
853 1920 : return m_minCount;
854 : }
855 :
856 : /** Return the maximum number of values for the argument.
857 : * Defaults to 1 for scalar types, and UNBOUNDED for list types.
858 : * Only applies to list type of arguments.
859 : */
860 1573 : inline int GetMaxCount() const
861 : {
862 1573 : return m_maxCount;
863 : }
864 :
865 : /** Returns whether in --help message one should display hints about the
866 : * minimum/maximum number of values. Defaults to true.
867 : */
868 339 : inline bool GetDisplayHintAboutRepetition() const
869 : {
870 339 : return m_displayHintAboutRepetition;
871 : }
872 :
873 : /** Return whether, for list type of arguments, several values, space
874 : * separated, may be specified. That is "--foo=bar,baz".
875 : * The default is true.
876 : */
877 344 : inline bool GetPackedValuesAllowed() const
878 : {
879 344 : return m_packedValuesAllowed;
880 : }
881 :
882 : /** Return whether, for list type of arguments, the argument may be
883 : * repeated. That is "--foo=bar --foo=baz".
884 : * The default is true.
885 : */
886 919 : inline bool GetRepeatedArgAllowed() const
887 : {
888 919 : return m_repeatedArgAllowed;
889 : }
890 :
891 : /** Return if the argument is a positional one. */
892 1630 : inline bool IsPositional() const
893 : {
894 1630 : return m_positional;
895 : }
896 :
897 : /** Return if the argument has a declared default value. */
898 15939 : inline bool HasDefaultValue() const
899 : {
900 15939 : return m_hasDefaultValue;
901 : }
902 :
903 : /** Return whether the argument must not be mentioned in CLI usage.
904 : * For example, "output-value" for "gdal raster info", which is only
905 : * meant when the algorithm is used from a non-CLI context.
906 : */
907 1287 : inline bool IsHiddenForCLI() const
908 : {
909 1287 : return m_hiddenForCLI;
910 : }
911 :
912 : /** Return whether the argument is only for CLI usage.
913 : * For example "--help" */
914 3121 : inline bool IsOnlyForCLI() const
915 : {
916 3121 : return m_onlyForCLI;
917 : }
918 :
919 : /** Indicate whether the value of the argument is read-only during the
920 : * execution of the algorithm. Default is true.
921 : */
922 1792 : inline bool IsInput() const
923 : {
924 1792 : return m_isInput;
925 : }
926 :
927 : /** Return whether (at least part of) the value of the argument is set
928 : * during the execution of the algorithm.
929 : * For example, "output-value" for "gdal raster info"
930 : * Default is false.
931 : * An argument may return both IsInput() and IsOutput() as true.
932 : * For example the "gdal raster convert" algorithm consumes the dataset
933 : * name of its "output" argument, and sets the dataset object during its
934 : * execution.
935 : */
936 2847 : inline bool IsOutput() const
937 : {
938 2847 : return m_isOutput;
939 : }
940 :
941 : /** Return the name of the mutual exclusion group to which this argument
942 : * belongs to, or empty string if it does not belong to any exclusion
943 : * group.
944 : */
945 2632 : inline const std::string &GetMutualExclusionGroup() const
946 : {
947 2632 : return m_mutualExclusionGroup;
948 : }
949 :
950 : /** Return if this (string) argument accepts the \@filename syntax to
951 : * mean that the content of the specified file should be used as the
952 : * value of the argument.
953 : */
954 346 : inline bool IsReadFromFileAtSyntaxAllowed() const
955 : {
956 346 : return m_readFromFileAtSyntaxAllowed;
957 : }
958 :
959 : /** Returns whether SQL comments must be removed from a (string) argument.
960 : */
961 337 : bool IsRemoveSQLCommentsEnabled() const
962 : {
963 337 : return m_removeSQLComments;
964 : }
965 :
966 : /** Returns whether the dataset should be opened automatically by
967 : * GDALAlgorithm. Only applies to GAAT_DATASET and GAAT_DATASET_LIST.
968 : */
969 571 : bool AutoOpenDataset() const
970 : {
971 571 : return m_autoOpenDataset;
972 : }
973 :
974 : /** Get user-defined metadata. */
975 : inline const std::map<std::string, std::vector<std::string>>
976 570 : GetMetadata() const
977 : {
978 570 : return m_metadata;
979 : }
980 :
981 : /** Get user-defined metadata by item name. */
982 : inline const std::vector<std::string> *
983 311 : GetMetadataItem(const std::string &name) const
984 : {
985 311 : const auto iter = m_metadata.find(name);
986 311 : return iter == m_metadata.end() ? nullptr : &(iter->second);
987 : }
988 :
989 : /** Return the default value of the argument.
990 : * Must be called with T consistent of the type of the algorithm, and only
991 : * if HasDefaultValue() is true.
992 : * Valid T types are:
993 : * - bool for GAAT_BOOLEAN
994 : * - int for GAAT_INTEGER
995 : * - double for GAAT_REAL
996 : * - std::string for GAAT_STRING
997 : * - GDALArgDatasetValue for GAAT_DATASET
998 : * - std::vector<int> for GAAT_INTEGER_LIST
999 : * - std::vector<double for GAAT_REAL_LIST
1000 : * - std::vector<std::string> for GAAT_STRING_LIST
1001 : * - std::vector<GDALArgDatasetValue> for GAAT_DATASET_LIST
1002 : */
1003 95 : template <class T> inline const T &GetDefault() const
1004 : {
1005 95 : return std::get<T>(m_defaultValue);
1006 : }
1007 :
1008 : private:
1009 : const std::string m_longName;
1010 : const std::string m_shortName;
1011 : const std::string m_description;
1012 : const GDALAlgorithmArgType m_type;
1013 : std::string m_category = GAAC_BASE;
1014 : std::string m_metaVar{};
1015 : std::string m_mutualExclusionGroup{};
1016 : int m_minCount = 0;
1017 : int m_maxCount = 0;
1018 : bool m_required = false;
1019 : bool m_positional = false;
1020 : bool m_hasDefaultValue = false;
1021 : bool m_hiddenForCLI = false;
1022 : bool m_onlyForCLI = false;
1023 : bool m_isInput = true;
1024 : bool m_isOutput = false;
1025 : bool m_packedValuesAllowed = true;
1026 : bool m_repeatedArgAllowed = true;
1027 : bool m_displayHintAboutRepetition = true;
1028 : bool m_readFromFileAtSyntaxAllowed = false;
1029 : bool m_removeSQLComments = false;
1030 : bool m_autoOpenDataset = true;
1031 : std::map<std::string, std::vector<std::string>> m_metadata{};
1032 : std::vector<std::string> m_aliases{};
1033 : std::vector<std::string> m_hiddenAliases{};
1034 : std::vector<std::string> m_choices{};
1035 : std::vector<std::string> m_hiddenChoices{};
1036 : std::variant<bool, std::string, int, double, std::vector<std::string>,
1037 : std::vector<int>, std::vector<double>>
1038 : m_defaultValue{};
1039 : };
1040 :
1041 : /************************************************************************/
1042 : /* GDALAlgorithmArg */
1043 : /************************************************************************/
1044 :
1045 : class GDALAlgorithm;
1046 :
1047 : /** Argument of an algorithm.
1048 : */
1049 : class CPL_DLL GDALAlgorithmArg /* non-final */
1050 : {
1051 : public:
1052 : /** Constructor */
1053 : template <class T>
1054 14867 : GDALAlgorithmArg(const GDALAlgorithmArgDecl &decl, T *pValue)
1055 14867 : : m_decl(decl), m_value(pValue)
1056 : {
1057 : if constexpr (!std::is_same_v<T, GDALArgDatasetValue> &&
1058 : !std::is_same_v<T, std::vector<GDALArgDatasetValue>>)
1059 : {
1060 13749 : if (decl.HasDefaultValue())
1061 2 : *std::get<T *>(m_value) = decl.GetDefault<T>();
1062 : }
1063 14867 : }
1064 :
1065 : /** Return the argument declaration. */
1066 : const GDALAlgorithmArgDecl &GetDeclaration() const
1067 : {
1068 : return m_decl;
1069 : }
1070 :
1071 : /** Alias for GDALAlgorithmArgDecl::GetName() */
1072 19251 : inline const std::string &GetName() const
1073 : {
1074 19251 : return m_decl.GetName();
1075 : }
1076 :
1077 : /** Alias for GDALAlgorithmArgDecl::GetShortName() */
1078 15538 : inline const std::string &GetShortName() const
1079 : {
1080 15538 : return m_decl.GetShortName();
1081 : }
1082 :
1083 : /** Alias for GDALAlgorithmArgDecl::GetAliases() */
1084 560 : inline const std::vector<std::string> &GetAliases() const
1085 : {
1086 560 : return m_decl.GetAliases();
1087 : }
1088 :
1089 : /** Alias for GDALAlgorithmArgDecl::GetDescription() */
1090 911 : inline const std::string &GetDescription() const
1091 : {
1092 911 : return m_decl.GetDescription();
1093 : }
1094 :
1095 : /** Alias for GDALAlgorithmArgDecl::GetMetaVar() */
1096 571 : inline const std::string &GetMetaVar() const
1097 : {
1098 571 : return m_decl.GetMetaVar();
1099 : }
1100 :
1101 : /** Alias for GDALAlgorithmArgDecl::GetType() */
1102 19187 : inline GDALAlgorithmArgType GetType() const
1103 : {
1104 19187 : return m_decl.GetType();
1105 : }
1106 :
1107 : /** Alias for GDALAlgorithmArgDecl::GetCategory() */
1108 1515 : inline const std::string &GetCategory() const
1109 : {
1110 1515 : return m_decl.GetCategory();
1111 : }
1112 :
1113 : /** Alias for GDALAlgorithmArgDecl::IsRequired() */
1114 12822 : inline bool IsRequired() const
1115 : {
1116 12822 : return m_decl.IsRequired();
1117 : }
1118 :
1119 : /** Alias for GDALAlgorithmArgDecl::GetMinCount() */
1120 1918 : inline int GetMinCount() const
1121 : {
1122 1918 : return m_decl.GetMinCount();
1123 : }
1124 :
1125 : /** Alias for GDALAlgorithmArgDecl::GetMaxCount() */
1126 1571 : inline int GetMaxCount() const
1127 : {
1128 1571 : return m_decl.GetMaxCount();
1129 : }
1130 :
1131 : /** Alias for GDALAlgorithmArgDecl::GetDisplayHintAboutRepetition() */
1132 339 : inline bool GetDisplayHintAboutRepetition() const
1133 : {
1134 339 : return m_decl.GetDisplayHintAboutRepetition();
1135 : }
1136 :
1137 : /** Alias for GDALAlgorithmArgDecl::GetPackedValuesAllowed() */
1138 344 : inline bool GetPackedValuesAllowed() const
1139 : {
1140 344 : return m_decl.GetPackedValuesAllowed();
1141 : }
1142 :
1143 : /** Alias for GDALAlgorithmArgDecl::GetRepeatedArgAllowed() */
1144 919 : inline bool GetRepeatedArgAllowed() const
1145 : {
1146 919 : return m_decl.GetRepeatedArgAllowed();
1147 : }
1148 :
1149 : /** Alias for GDALAlgorithmArgDecl::IsPositional() */
1150 1630 : inline bool IsPositional() const
1151 : {
1152 1630 : return m_decl.IsPositional();
1153 : }
1154 :
1155 : /** Alias for GDALAlgorithmArgDecl::GetChoices() */
1156 1300 : inline const std::vector<std::string> &GetChoices() const
1157 : {
1158 1300 : return m_decl.GetChoices();
1159 : }
1160 :
1161 : /** Alias for GDALAlgorithmArgDecl::GetHiddenChoices() */
1162 252 : inline const std::vector<std::string> &GetHiddenChoices() const
1163 : {
1164 252 : return m_decl.GetHiddenChoices();
1165 : }
1166 :
1167 : /** Return auto completion choices, if a auto completion function has been
1168 : * registered.
1169 : */
1170 : inline std::vector<std::string>
1171 30 : GetAutoCompleteChoices(const std::string ¤tValue) const
1172 : {
1173 30 : if (m_autoCompleteFunction)
1174 29 : return m_autoCompleteFunction(currentValue);
1175 1 : return {};
1176 : }
1177 :
1178 : /** Return whether the argument value has been explicitly set with Set() */
1179 49990 : inline bool IsExplicitlySet() const
1180 : {
1181 49990 : return m_explicitlySet;
1182 : }
1183 :
1184 : /** Alias for GDALAlgorithmArgDecl::HasDefaultValue() */
1185 825 : inline bool HasDefaultValue() const
1186 : {
1187 825 : return m_decl.HasDefaultValue();
1188 : }
1189 :
1190 : /** Alias for GDALAlgorithmArgDecl::IsHiddenForCLI() */
1191 1287 : inline bool IsHiddenForCLI() const
1192 : {
1193 1287 : return m_decl.IsHiddenForCLI();
1194 : }
1195 :
1196 : /** Alias for GDALAlgorithmArgDecl::IsOnlyForCLI() */
1197 3121 : inline bool IsOnlyForCLI() const
1198 : {
1199 3121 : return m_decl.IsOnlyForCLI();
1200 : }
1201 :
1202 : /** Alias for GDALAlgorithmArgDecl::IsInput() */
1203 1792 : inline bool IsInput() const
1204 : {
1205 1792 : return m_decl.IsInput();
1206 : }
1207 :
1208 : /** Alias for GDALAlgorithmArgDecl::IsOutput() */
1209 2847 : inline bool IsOutput() const
1210 : {
1211 2847 : return m_decl.IsOutput();
1212 : }
1213 :
1214 : /** Alias for GDALAlgorithmArgDecl::IsReadFromFileAtSyntaxAllowed() */
1215 : inline bool IsReadFromFileAtSyntaxAllowed() const
1216 : {
1217 : return m_decl.IsReadFromFileAtSyntaxAllowed();
1218 : }
1219 :
1220 : /** Alias for GDALAlgorithmArgDecl::IsRemoveSQLCommentsEnabled() */
1221 : inline bool IsRemoveSQLCommentsEnabled() const
1222 : {
1223 : return m_decl.IsRemoveSQLCommentsEnabled();
1224 : }
1225 :
1226 : /** Alias for GDALAlgorithmArgDecl::GetMutualExclusionGroup() */
1227 2632 : inline const std::string &GetMutualExclusionGroup() const
1228 : {
1229 2632 : return m_decl.GetMutualExclusionGroup();
1230 : }
1231 :
1232 : /** Alias for GDALAlgorithmArgDecl::GetMetadata() */
1233 : inline const std::map<std::string, std::vector<std::string>>
1234 570 : GetMetadata() const
1235 : {
1236 570 : return m_decl.GetMetadata();
1237 : }
1238 :
1239 : /** Alias for GDALAlgorithmArgDecl::GetMetadataItem() */
1240 : inline const std::vector<std::string> *
1241 311 : GetMetadataItem(const std::string &name) const
1242 : {
1243 311 : return m_decl.GetMetadataItem(name);
1244 : }
1245 :
1246 : /** Alias for GDALAlgorithmArgDecl::GetDefault() */
1247 93 : template <class T> inline const T &GetDefault() const
1248 : {
1249 93 : return m_decl.GetDefault<T>();
1250 : }
1251 :
1252 : /** Alias for GDALAlgorithmArgDecl::AutoOpenDataset() */
1253 571 : inline bool AutoOpenDataset() const
1254 : {
1255 571 : return m_decl.AutoOpenDataset();
1256 : }
1257 :
1258 : /** Return the value of the argument, which is by decreasing order of priority:
1259 : * - the value set through Set().
1260 : * - the default value set through SetDefault().
1261 : * - the initial value of the C++ variable to which this argument is bound to.
1262 : *
1263 : * Must be called with T consistent of the type of the algorithm:
1264 : * - bool for GAAT_BOOLEAN
1265 : * - int for GAAT_INTEGER
1266 : * - double for GAAT_REAL
1267 : * - std::string for GAAT_STRING
1268 : * - GDALArgDatasetValue for GAAT_DATASET
1269 : * - std::vector<int> for GAAT_INTEGER_LIST
1270 : * - std::vector<double for GAAT_REAL_LIST
1271 : * - std::vector<std::string> for GAAT_STRING_LIST
1272 : * - std::vector<GDALArgDatasetValue> for GAAT_DATASET_LIST
1273 : */
1274 2978 : template <class T> inline T &Get()
1275 : {
1276 2978 : return *(std::get<T *>(m_value));
1277 : }
1278 :
1279 : /** Return the value of the argument, which is by decreasing order of priority:
1280 : * - the value set through Set().
1281 : * - the default value set through SetDefault().
1282 : * - the initial value of the C++ variable to which this argument is bound to.
1283 : *
1284 : * Must be called with T consistent of the type of the algorithm:
1285 : * - bool for GAAT_BOOLEAN
1286 : * - int for GAAT_INTEGER
1287 : * - double for GAAT_REAL
1288 : * - std::string for GAAT_STRING
1289 : * - GDALArgDatasetValue for GAAT_DATASET
1290 : * - std::vector<int> for GAAT_INTEGER_LIST
1291 : * - std::vector<double for GAAT_REAL_LIST
1292 : * - std::vector<std::string> for GAAT_STRING_LIST
1293 : * - std::vector<GDALArgDatasetValue> for GAAT_DATASET_LIST
1294 : */
1295 336 : template <class T> inline const T &Get() const
1296 : {
1297 336 : return *(std::get<T *>(m_value));
1298 : }
1299 :
1300 : /** Set the value for a GAAT_BOOLEAN argument.
1301 : * It cannot be called several times for a given argument.
1302 : * Validation checks and other actions are run.
1303 : * Return true if success.
1304 : */
1305 : bool Set(bool value);
1306 :
1307 : /** Set the value for a GAAT_STRING argument.
1308 : * It cannot be called several times for a given argument.
1309 : * Validation checks and other actions are run.
1310 : * Return true if success.
1311 : */
1312 : bool Set(const std::string &value);
1313 :
1314 : /** Set the value for a GAAT_STRING argument.
1315 : * It cannot be called several times for a given argument.
1316 : * Validation checks and other actions are run.
1317 : * Return true if success.
1318 : */
1319 37 : bool Set(const char *value)
1320 : {
1321 37 : return Set(std::string(value ? value : ""));
1322 : }
1323 :
1324 : /** Set the value for a GAAT_INTEGER (or GAAT_REAL) argument.
1325 : * It cannot be called several times for a given argument.
1326 : * Validation checks and other actions are run.
1327 : * Return true if success.
1328 : */
1329 : bool Set(int value);
1330 :
1331 : /** Set the value for a GAAT_REAL argument */
1332 : bool Set(double value);
1333 :
1334 : /** Set the value for a GAAT_DATASET argument, increasing ds' reference
1335 : * counter if ds is not null.
1336 : * It cannot be called several times for a given argument.
1337 : * Validation checks and other actions are run.
1338 : * Return true if success.
1339 : */
1340 : bool Set(GDALDataset *ds);
1341 :
1342 : /** Set the value for a GAAT_DATASET argument.
1343 : * It cannot be called several times for a given argument.
1344 : * Validation checks and other actions are run.
1345 : * Return true if success.
1346 : */
1347 : bool Set(std::unique_ptr<GDALDataset> ds);
1348 :
1349 : /** Set the value for a GAAT_DATASET argument.
1350 : * It cannot be called several times for a given argument.
1351 : * Validation checks and other actions are run.
1352 : * Return true if success.
1353 : */
1354 : bool SetDatasetName(const std::string &name);
1355 :
1356 : /** Set the value for a GAAT_DATASET argument.
1357 : * It references the dataset pointed by other.m_poDS.
1358 : * It cannot be called several times for a given argument.
1359 : * Validation checks and other actions are run.
1360 : * Return true if success.
1361 : */
1362 : bool SetFrom(const GDALArgDatasetValue &other);
1363 :
1364 : /** Set the value for a GAAT_STRING_LIST argument.
1365 : * It cannot be called several times for a given argument.
1366 : * Validation checks and other actions are run.
1367 : * Return true if success.
1368 : */
1369 : bool Set(const std::vector<std::string> &value);
1370 :
1371 : /** Set the value for a GAAT_INTEGER_LIST argument.
1372 : * It cannot be called several times for a given argument.
1373 : * Validation checks and other actions are run.
1374 : * Return true if success.
1375 : */
1376 : bool Set(const std::vector<int> &value);
1377 :
1378 : /** Set the value for a GAAT_REAL_LIST argument.
1379 : * It cannot be called several times for a given argument.
1380 : * Validation checks and other actions are run.
1381 : * Return true if success.
1382 : */
1383 : bool Set(const std::vector<double> &value);
1384 :
1385 : /** Set the value for a GAAT_DATASET_LIST argument.
1386 : * It cannot be called several times for a given argument.
1387 : * Validation checks and other actions are run.
1388 : * Return true if success.
1389 : */
1390 : bool Set(std::vector<GDALArgDatasetValue> &&value);
1391 :
1392 : /** Set the value for another argument.
1393 : * For GAAT_DATASET, it will reference the dataset pointed by other.m_poDS.
1394 : * It cannot be called several times for a given argument.
1395 : * Validation checks and other actions are run.
1396 : * Return true if success.
1397 : */
1398 : bool SetFrom(const GDALAlgorithmArg &other);
1399 :
1400 : /** Advanced method used to make "gdal info" and "gdal raster|vector info"
1401 : * to avoid re-opening an already opened dataset */
1402 168 : void SetSkipIfAlreadySet(bool skip = true)
1403 : {
1404 168 : m_skipIfAlreadySet = skip;
1405 168 : }
1406 :
1407 : /** Advanced method used to make "gdal info" and "gdal raster|vector info"
1408 : * to avoid re-opening an already opened dataset */
1409 3 : bool SkipIfAlreadySet() const
1410 : {
1411 3 : return m_skipIfAlreadySet;
1412 : }
1413 :
1414 : //! @cond Doxygen_Suppress
1415 994 : void NotifyValueSet()
1416 : {
1417 994 : m_explicitlySet = true;
1418 994 : }
1419 :
1420 : //! @endcond
1421 :
1422 : protected:
1423 : friend class GDALAlgorithm;
1424 : /** Argument declaration */
1425 : GDALAlgorithmArgDecl m_decl;
1426 : /** Pointer to the value */
1427 : std::variant<bool *, std::string *, int *, double *, GDALArgDatasetValue *,
1428 : std::vector<std::string> *, std::vector<int> *,
1429 : std::vector<double> *, std::vector<GDALArgDatasetValue> *>
1430 : m_value{};
1431 : /** Actions */
1432 : std::vector<std::function<void()>> m_actions{};
1433 : /** Validation actions */
1434 : std::vector<std::function<bool()>> m_validationActions{};
1435 : /** Autocompletion function */
1436 : std::function<std::vector<std::string>(const std::string &)>
1437 : m_autoCompleteFunction{};
1438 :
1439 : private:
1440 : bool m_skipIfAlreadySet = false;
1441 : bool m_explicitlySet = false;
1442 :
1443 492 : template <class T> bool SetInternal(const T &value)
1444 : {
1445 492 : m_explicitlySet = true;
1446 492 : *std::get<T *>(m_value) = value;
1447 492 : return RunAllActions();
1448 : }
1449 :
1450 : bool ProcessString(std::string &value) const;
1451 :
1452 : bool RunAllActions();
1453 : void RunActions();
1454 : bool RunValidationActions();
1455 : };
1456 :
1457 : /************************************************************************/
1458 : /* GDALInConstructionAlgorithmArg */
1459 : /************************************************************************/
1460 :
1461 : //! @cond Doxygen_Suppress
1462 : namespace test_gdal_algorithm
1463 : {
1464 : struct test_gdal_algorithm;
1465 : }
1466 :
1467 : //! @endcond
1468 :
1469 : /** Technical class used by GDALAlgorithm when constructing argument
1470 : * declarations.
1471 : */
1472 : class CPL_DLL GDALInConstructionAlgorithmArg final : public GDALAlgorithmArg
1473 : {
1474 : friend struct test_gdal_algorithm::test_gdal_algorithm;
1475 :
1476 : public:
1477 : /** Constructor */
1478 : template <class T>
1479 14845 : GDALInConstructionAlgorithmArg(GDALAlgorithm *owner,
1480 : const GDALAlgorithmArgDecl &decl, T *pValue)
1481 14845 : : GDALAlgorithmArg(decl, pValue), m_owner(owner)
1482 : {
1483 14845 : }
1484 :
1485 : /** Add a documented alias for the argument */
1486 : GDALInConstructionAlgorithmArg &AddAlias(const std::string &alias);
1487 :
1488 : /** Add a non-documented alias for the argument */
1489 : GDALInConstructionAlgorithmArg &AddHiddenAlias(const std::string &alias);
1490 :
1491 : /** Alias for GDALAlgorithmArgDecl::SetPositional() */
1492 : GDALInConstructionAlgorithmArg &SetPositional();
1493 :
1494 : /** Alias for GDALAlgorithmArgDecl::SetRequired() */
1495 848 : GDALInConstructionAlgorithmArg &SetRequired()
1496 : {
1497 848 : m_decl.SetRequired();
1498 848 : return *this;
1499 : }
1500 :
1501 : /** Alias for GDALAlgorithmArgDecl::SetMetaVar() */
1502 3049 : GDALInConstructionAlgorithmArg &SetMetaVar(const std::string &metaVar)
1503 : {
1504 3049 : m_decl.SetMetaVar(metaVar);
1505 3049 : return *this;
1506 : }
1507 :
1508 : /** Alias for GDALAlgorithmArgDecl::SetCategory() */
1509 8824 : GDALInConstructionAlgorithmArg &SetCategory(const std::string &category)
1510 : {
1511 8824 : m_decl.SetCategory(category);
1512 8824 : return *this;
1513 : }
1514 :
1515 : /** Alias for GDALAlgorithmArgDecl::SetDefault() */
1516 : template <class T>
1517 1365 : GDALInConstructionAlgorithmArg &SetDefault(const T &value)
1518 : {
1519 1365 : m_decl.SetDefault(value);
1520 : if constexpr (!std::is_same_v<T, GDALArgDatasetValue> &&
1521 : !std::is_same_v<T, std::vector<GDALArgDatasetValue>>)
1522 : {
1523 1365 : if (m_decl.HasDefaultValue())
1524 1365 : *std::get<T *>(m_value) = value;
1525 : }
1526 1365 : return *this;
1527 : }
1528 :
1529 : /** Alias for GDALAlgorithmArgDecl::SetDefault() */
1530 139 : GDALInConstructionAlgorithmArg &SetDefault(const char *value)
1531 : {
1532 139 : return SetDefault(std::string(value));
1533 : }
1534 :
1535 : /** Alias for GDALAlgorithmArgDecl::SetMinCount() */
1536 350 : GDALInConstructionAlgorithmArg &SetMinCount(int count)
1537 : {
1538 350 : m_decl.SetMinCount(count);
1539 350 : return *this;
1540 : }
1541 :
1542 : /** Alias for GDALAlgorithmArgDecl::SetMaxCount() */
1543 195 : GDALInConstructionAlgorithmArg &SetMaxCount(int count)
1544 : {
1545 195 : m_decl.SetMaxCount(count);
1546 195 : return *this;
1547 : }
1548 :
1549 : /** Alias for GDALAlgorithmArgDecl::SetDisplayHintAboutRepetition() */
1550 : GDALInConstructionAlgorithmArg &
1551 178 : SetDisplayHintAboutRepetition(bool displayHint)
1552 : {
1553 178 : m_decl.SetDisplayHintAboutRepetition(displayHint);
1554 178 : return *this;
1555 : }
1556 :
1557 : /** Alias for GDALAlgorithmArgDecl::SetPackedValuesAllowed() */
1558 17 : GDALInConstructionAlgorithmArg &SetPackedValuesAllowed(bool allowed)
1559 : {
1560 17 : m_decl.SetPackedValuesAllowed(allowed);
1561 17 : return *this;
1562 : }
1563 :
1564 : /** Alias for GDALAlgorithmArgDecl::SetRepeatedArgAllowed() */
1565 236 : GDALInConstructionAlgorithmArg &SetRepeatedArgAllowed(bool allowed)
1566 : {
1567 236 : m_decl.SetRepeatedArgAllowed(allowed);
1568 236 : return *this;
1569 : }
1570 :
1571 : /** Alias for GDALAlgorithmArgDecl::SetChoices() */
1572 : template <typename T, typename... U>
1573 154 : GDALInConstructionAlgorithmArg &SetChoices(T &&first, U &&...rest)
1574 : {
1575 154 : m_decl.SetChoices(std::forward<T>(first), std::forward<U>(rest)...);
1576 154 : return *this;
1577 : }
1578 :
1579 : /** Alias for GDALAlgorithmArgDecl::SetHiddenChoices() */
1580 : template <typename T, typename... U>
1581 40 : GDALInConstructionAlgorithmArg &SetHiddenChoices(T &&first, U &&...rest)
1582 : {
1583 40 : m_decl.SetHiddenChoices(std::forward<T>(first),
1584 : std::forward<U>(rest)...);
1585 40 : return *this;
1586 : }
1587 :
1588 : /** Alias for GDALAlgorithmArgDecl::SetHiddenForCLI() */
1589 3950 : GDALInConstructionAlgorithmArg &SetHiddenForCLI(bool hiddenForCLI = true)
1590 : {
1591 3950 : m_decl.SetHiddenForCLI(hiddenForCLI);
1592 3950 : return *this;
1593 : }
1594 :
1595 : /** Alias for GDALAlgorithmArgDecl::SetOnlyForCLI() */
1596 7388 : GDALInConstructionAlgorithmArg &SetOnlyForCLI(bool onlyForCLI = true)
1597 : {
1598 7388 : m_decl.SetOnlyForCLI(onlyForCLI);
1599 7388 : return *this;
1600 : }
1601 :
1602 : /** Alias for GDALAlgorithmArgDecl::SetIsInput() */
1603 551 : GDALInConstructionAlgorithmArg &SetIsInput(bool isInput = true)
1604 : {
1605 551 : m_decl.SetIsInput(isInput);
1606 551 : return *this;
1607 : }
1608 :
1609 : /** Alias for GDALAlgorithmArgDecl::SetIsOutput() */
1610 551 : GDALInConstructionAlgorithmArg &SetIsOutput(bool isOutput = true)
1611 : {
1612 551 : m_decl.SetIsOutput(isOutput);
1613 551 : return *this;
1614 : }
1615 :
1616 : /** Alias for GDALAlgorithmArgDecl::SetReadFromFileAtSyntaxAllowed() */
1617 100 : GDALInConstructionAlgorithmArg &SetReadFromFileAtSyntaxAllowed()
1618 : {
1619 100 : m_decl.SetReadFromFileAtSyntaxAllowed();
1620 100 : return *this;
1621 : }
1622 :
1623 : /** Alias for GDALAlgorithmArgDecl::SetRemoveSQLCommentsEnabled() */
1624 100 : GDALInConstructionAlgorithmArg &SetRemoveSQLCommentsEnabled()
1625 : {
1626 100 : m_decl.SetRemoveSQLCommentsEnabled();
1627 100 : return *this;
1628 : }
1629 :
1630 : /** Alias for GDALAlgorithmArgDecl::SetAutoOpenDataset() */
1631 63 : GDALInConstructionAlgorithmArg &SetAutoOpenDataset(bool autoOpen)
1632 : {
1633 63 : m_decl.SetAutoOpenDataset(autoOpen);
1634 63 : return *this;
1635 : }
1636 :
1637 : /** Alias for GDALAlgorithmArgDecl::SetMutualExclusionGroup() */
1638 : GDALInConstructionAlgorithmArg &
1639 496 : SetMutualExclusionGroup(const std::string &group)
1640 : {
1641 496 : m_decl.SetMutualExclusionGroup(group);
1642 496 : return *this;
1643 : }
1644 :
1645 : /** Alias for GDALAlgorithmArgDecl::AddMetadataItem() */
1646 : GDALInConstructionAlgorithmArg &
1647 884 : AddMetadataItem(const std::string &name,
1648 : const std::vector<std::string> &values)
1649 : {
1650 884 : m_decl.AddMetadataItem(name, values);
1651 884 : return *this;
1652 : }
1653 :
1654 : /** Register an action that is executed, once and exactly once, if the
1655 : * argument is explicitly set, at the latest by the ValidateArguments()
1656 : * method. */
1657 2817 : GDALInConstructionAlgorithmArg &AddAction(std::function<void()> f)
1658 : {
1659 2817 : m_actions.push_back(f);
1660 2817 : return *this;
1661 : }
1662 :
1663 : /** Register an action that is executed, once and exactly once, if the
1664 : * argument is explicitly set, at the latest by the ValidateArguments()
1665 : * method. If the provided function returns false, validation fails. */
1666 2222 : GDALInConstructionAlgorithmArg &AddValidationAction(std::function<bool()> f)
1667 : {
1668 2222 : m_validationActions.push_back(f);
1669 2222 : return *this;
1670 : }
1671 :
1672 : /** Register a function that will return a list of valid choices for
1673 : * the value of the argument. This is typically used for autocompletion.
1674 : */
1675 2984 : GDALInConstructionAlgorithmArg &SetAutoCompleteFunction(
1676 : std::function<std::vector<std::string>(const std::string &)> f)
1677 : {
1678 2984 : m_autoCompleteFunction = std::move(f);
1679 2984 : return *this;
1680 : }
1681 :
1682 : /** Register an action to validate that the argument value is a valid
1683 : * CRS definition.
1684 : * @param noneAllowed Set to true to mean that "null" or "none" are allowed
1685 : * to mean to unset CRS.
1686 : */
1687 : GDALInConstructionAlgorithmArg &SetIsCRSArg(bool noneAllowed = false);
1688 :
1689 : private:
1690 : GDALAlgorithm *const m_owner;
1691 :
1692 : GDALInConstructionAlgorithmArg(const GDALInConstructionAlgorithmArg &) =
1693 : delete;
1694 : GDALInConstructionAlgorithmArg &
1695 : operator=(const GDALInConstructionAlgorithmArg &) = delete;
1696 : };
1697 :
1698 : /************************************************************************/
1699 : /* GDALAlgorithmRegistry */
1700 : /************************************************************************/
1701 :
1702 : /** Registry of GDAL algorithms.
1703 : */
1704 2945 : class CPL_DLL GDALAlgorithmRegistry
1705 : {
1706 : public:
1707 : /** Special value to put in m_aliases to separate public alias from
1708 : * hidden aliases */
1709 : static constexpr const char *HIDDEN_ALIAS_SEPARATOR = "==hide==";
1710 :
1711 : virtual ~GDALAlgorithmRegistry();
1712 :
1713 : /** Algorithm information */
1714 : class AlgInfo
1715 : {
1716 : public:
1717 : /** Algorithm (short) name */
1718 : std::string m_name{};
1719 : /** Aliases */
1720 : std::vector<std::string> m_aliases{};
1721 : /** Creation function */
1722 : std::function<std::unique_ptr<GDALAlgorithm>()> m_creationFunc{};
1723 : };
1724 :
1725 : /** Register the algorithm of type MyAlgorithm.
1726 : */
1727 10975 : template <class MyAlgorithm> bool Register()
1728 : {
1729 21950 : AlgInfo info;
1730 10975 : info.m_name = MyAlgorithm::NAME;
1731 10975 : info.m_aliases = MyAlgorithm::GetAliases();
1732 11940 : info.m_creationFunc = []() -> std::unique_ptr<GDALAlgorithm>
1733 1001 : { return std::make_unique<MyAlgorithm>(); };
1734 21950 : return Register(info);
1735 : }
1736 :
1737 : /** Register an algorithm by its AlgInfo structure.
1738 : */
1739 : bool Register(const AlgInfo &info);
1740 :
1741 : /** Get the names of registered algorithms.
1742 : *
1743 : * This only returns the main name of each algorithm, not its potential
1744 : * alternate names.
1745 : */
1746 : std::vector<std::string> GetNames() const;
1747 :
1748 : /** Instantiate an algorithm by its name or one of its alias. */
1749 : virtual std::unique_ptr<GDALAlgorithm>
1750 : Instantiate(const std::string &name) const;
1751 :
1752 : /** Get an algorithm by its name. */
1753 367 : const AlgInfo *GetInfo(const std::string &name) const
1754 : {
1755 367 : auto iter = m_mapNameToInfo.find(name);
1756 367 : return iter != m_mapNameToInfo.end() ? &(iter->second) : nullptr;
1757 : }
1758 :
1759 : /** Returns true if there are no algorithms registered. */
1760 821 : bool empty() const
1761 : {
1762 821 : return m_mapNameToInfo.empty();
1763 : }
1764 :
1765 : private:
1766 : std::map<std::string, AlgInfo> m_mapNameToInfo{};
1767 : std::map<std::string, AlgInfo> m_mapAliasToInfo{};
1768 : std::map<std::string, AlgInfo> m_mapHiddenAliasToInfo{};
1769 : };
1770 :
1771 : /************************************************************************/
1772 : /* GDALAlgorithm */
1773 : /************************************************************************/
1774 :
1775 : /** GDAL algorithm.
1776 : *
1777 : * An algorithm declares its name, description, help URL.
1778 : * It also defined arguments or (mutual exclusion) sub-algorithms.
1779 : *
1780 : * It can be used from the command line with the ParseCommandLineArguments()
1781 : * method, or users can iterate over the available arguments with the GetArgs()
1782 : * or GetArg() method and fill them programmatically with
1783 : * GDALAlgorithmArg::Set().
1784 : *
1785 : * Execution of the algorithm is done with the Run() method.
1786 : *
1787 : * This is an abstract class. Implementations must sub-class it and implement the
1788 : * RunImpl() method.
1789 : */
1790 :
1791 1408 : /* abstract */ class CPL_DLL GDALAlgorithm
1792 : {
1793 : friend struct test_gdal_algorithm::test_gdal_algorithm;
1794 :
1795 : public:
1796 : virtual ~GDALAlgorithm();
1797 :
1798 : /** Get the algorithm name */
1799 748 : const std::string &GetName() const
1800 : {
1801 748 : return m_name;
1802 : }
1803 :
1804 : /** Get the algorithm description (a few sentences at most) */
1805 18 : const std::string &GetDescription() const
1806 : {
1807 18 : return m_description;
1808 : }
1809 :
1810 : /** Get the long algorithm description. May be empty. */
1811 2 : const std::string &GetLongDescription() const
1812 : {
1813 2 : return m_longDescription;
1814 : }
1815 :
1816 : /** Get the algorithm help URL. If starting with '/', it is relative to
1817 : * "https://gdal.org".
1818 : */
1819 : const std::string &GetHelpURL() const
1820 : {
1821 : return m_helpURL;
1822 : }
1823 :
1824 : /** Get the algorithm full URL, resolving relative URLs. */
1825 148 : const std::string &GetHelpFullURL() const
1826 : {
1827 148 : return m_helpFullURL;
1828 : }
1829 :
1830 : /** Returns whether this algorithm has sub-algorithms */
1831 821 : bool HasSubAlgorithms() const
1832 : {
1833 821 : return !m_subAlgRegistry.empty();
1834 : }
1835 :
1836 : /** Get the names of registered algorithms.
1837 : *
1838 : * This only returns the main name of each algorithm, not its potential
1839 : * alternate names.
1840 : */
1841 100 : std::vector<std::string> GetSubAlgorithmNames() const
1842 : {
1843 100 : return m_subAlgRegistry.GetNames();
1844 : }
1845 :
1846 : /** Instantiate an algorithm by its name (or its alias). */
1847 : std::unique_ptr<GDALAlgorithm>
1848 491 : InstantiateSubAlgorithm(const std::string &name) const
1849 : {
1850 491 : auto ret = m_subAlgRegistry.Instantiate(name);
1851 491 : if (ret)
1852 : {
1853 916 : auto childCallPath = m_callPath;
1854 458 : childCallPath.push_back(name);
1855 458 : ret->SetCallPath(childCallPath);
1856 : }
1857 491 : return ret;
1858 : }
1859 :
1860 : /** Return the potential arguments of the algorithm. */
1861 : const std::vector<std::unique_ptr<GDALAlgorithmArg>> &GetArgs() const
1862 : {
1863 : return m_args;
1864 : }
1865 :
1866 : /** Return the potential arguments of the algorithm. */
1867 147 : std::vector<std::unique_ptr<GDALAlgorithmArg>> &GetArgs()
1868 : {
1869 147 : return m_args;
1870 : }
1871 :
1872 : /** Return an argument from its long name, short name or an alias */
1873 5300 : GDALAlgorithmArg *GetArg(const std::string &osName)
1874 : {
1875 : return const_cast<GDALAlgorithmArg *>(
1876 5300 : const_cast<const GDALAlgorithm *>(this)->GetArg(osName));
1877 : }
1878 :
1879 : /** Return an argument from its long name, short name or an alias */
1880 : const GDALAlgorithmArg *GetArg(const std::string &osName) const;
1881 :
1882 : /** Set the calling path to this algorithm.
1883 : *
1884 : * For example the main "gdal" CLI will set the path to the name of its
1885 : * binary before calling ParseCommandLineArguments().
1886 : */
1887 503 : void SetCallPath(const std::vector<std::string> &path)
1888 : {
1889 503 : m_callPath = path;
1890 503 : }
1891 :
1892 : /** Set hint before calling ParseCommandLineArguments() that it must
1893 : * try to be be graceful when possible, e.g. accepting
1894 : * "gdal raster convert in.tif out.tif --co"
1895 : */
1896 29 : void SetParseForAutoCompletion()
1897 : {
1898 29 : m_parseForAutoCompletion = true;
1899 29 : }
1900 :
1901 : /** Parse a command line argument, which does not include the algorithm
1902 : * name, to set the value of corresponding arguments.
1903 : */
1904 : virtual bool
1905 : ParseCommandLineArguments(const std::vector<std::string> &args);
1906 :
1907 : /** Validate that all constraints are met. This method is automatically
1908 : * executed by ParseCommandLineArguments() and Run(), and thus does
1909 : * generally not need to be explicitly called.
1910 : */
1911 : virtual bool ValidateArguments();
1912 :
1913 : /** Execute the algorithm, starting with ValidateArguments() and then
1914 : * calling RunImpl().
1915 : */
1916 : bool Run(GDALProgressFunc pfnProgress = nullptr,
1917 : void *pProgressData = nullptr);
1918 :
1919 : /** Complete any pending actions, and return the final status.
1920 : * This is typically useful for algorithm that generate an output dataset.
1921 : */
1922 : virtual bool Finalize();
1923 :
1924 : /** Usage options */
1925 : struct UsageOptions
1926 : {
1927 : /** Whether this is a pipeline step */
1928 : bool isPipelineStep;
1929 : /** Maximum width of the names of the options */
1930 : size_t maxOptLen;
1931 :
1932 53 : UsageOptions() : isPipelineStep(false), maxOptLen(0)
1933 : {
1934 53 : }
1935 : };
1936 :
1937 : /** Return the usage as a string appropriate for command-line interface
1938 : * --help output.
1939 : */
1940 : virtual std::string
1941 : GetUsageForCLI(bool shortUsage,
1942 : const UsageOptions &usageOptions = UsageOptions()) const;
1943 :
1944 : /** Return the usage of the algorithm as a JSON-serialized string.
1945 : *
1946 : * This can be used to dynamically generate interfaces to algorithms.
1947 : */
1948 : virtual std::string GetUsageAsJSON() const;
1949 :
1950 : /** Return the actual algorithm that is going to be invoked, when the
1951 : * current algorithm has sub-algorithms.
1952 : *
1953 : * Only valid after ParseCommandLineArguments() has been called.
1954 : */
1955 137 : GDALAlgorithm &GetActualAlgorithm()
1956 : {
1957 137 : if (m_selectedSubAlg)
1958 46 : return m_selectedSubAlg->GetActualAlgorithm();
1959 91 : return *this;
1960 : }
1961 :
1962 : /** Whether the --help flag has been specified. */
1963 4 : bool IsHelpRequested() const
1964 : {
1965 4 : return m_helpRequested;
1966 : }
1967 :
1968 : /** Whether the --json-usage flag has been specified. */
1969 1 : bool IsJSONUsageRequested() const
1970 : {
1971 1 : return m_JSONUsageRequested;
1972 : }
1973 :
1974 : /** Whether the --progress flag has been specified. */
1975 34 : bool IsProgressBarRequested() const
1976 : {
1977 34 : if (m_selectedSubAlg)
1978 20 : return m_selectedSubAlg->IsProgressBarRequested();
1979 14 : return m_progressBarRequested;
1980 : }
1981 :
1982 : /** Return alias names (generally short) for the current algorithm. */
1983 1 : const std::vector<std::string> &GetAliases() const
1984 : {
1985 1 : return m_aliases;
1986 : }
1987 :
1988 : /** Used by the "gdal info" special algorithm when it first tries to
1989 : * run "gdal raster info", to inherit from the potential special flags,
1990 : * such as --help or --json-usage, that this later algorithm has received.
1991 : */
1992 43 : bool PropagateSpecialActionTo(GDALAlgorithm *target)
1993 : {
1994 43 : target->m_progressBarRequested = m_progressBarRequested;
1995 43 : if (m_specialActionRequested)
1996 : {
1997 5 : target->m_specialActionRequested = m_specialActionRequested;
1998 5 : target->m_helpRequested = m_helpRequested;
1999 5 : target->m_JSONUsageRequested = m_JSONUsageRequested;
2000 5 : return true;
2001 : }
2002 38 : return false;
2003 : }
2004 :
2005 : /** Return auto completion suggestions */
2006 : virtual std::vector<std::string>
2007 : GetAutoComplete(std::vector<std::string> &args, bool showAllOptions);
2008 :
2009 : protected:
2010 : friend class GDALInConstructionAlgorithmArg;
2011 :
2012 : /** Selected sub-algorithm. Set by ParseCommandLineArguments() when
2013 : * handling over on a sub-algorithm. */
2014 : GDALAlgorithm *m_selectedSubAlg = nullptr;
2015 :
2016 : /** Call path to the current algorithm. For example, for "gdal convert raster",
2017 : * it is ["gdal", "convert"]
2018 : */
2019 : std::vector<std::string> m_callPath{};
2020 :
2021 : /** Long description of the algorithm */
2022 : std::string m_longDescription{};
2023 :
2024 : /** Whether a progress bar is requested (value of --progress argument) */
2025 : bool m_progressBarRequested = false;
2026 :
2027 : friend class GDALVectorPipelineAlgorithm;
2028 : /** Whether ValidateArguments() should be skipped during ParseCommandLineArguments() */
2029 : bool m_skipValidationInParseCommandLine = false;
2030 :
2031 : friend class GDALAlgorithmRegistry; // to set m_aliases
2032 : /** Algorithm alias names */
2033 : std::vector<std::string> m_aliases{};
2034 :
2035 : /** Special processing for an argument of type GAAT_DATASET */
2036 : bool ProcessDatasetArg(GDALAlgorithmArg *arg, GDALAlgorithm *algForOutput);
2037 :
2038 : /** Constructor */
2039 : GDALAlgorithm(const std::string &name, const std::string &description,
2040 : const std::string &helpURL);
2041 :
2042 : /** Register the sub-algorithm of type MyAlgorithm.
2043 : */
2044 3168 : template <class MyAlgorithm> bool RegisterSubAlgorithm()
2045 : {
2046 3168 : return m_subAlgRegistry.Register<MyAlgorithm>();
2047 : }
2048 :
2049 : /** Register a sub-algoritm by its AlgInfo structure.
2050 : */
2051 370 : bool RegisterSubAlgorithm(const GDALAlgorithmRegistry::AlgInfo &info)
2052 : {
2053 370 : return m_subAlgRegistry.Register(info);
2054 : }
2055 :
2056 : /** Add boolean argument. */
2057 : GDALInConstructionAlgorithmArg &AddArg(const std::string &longName,
2058 : char chShortName,
2059 : const std::string &helpMessage,
2060 : bool *pValue);
2061 :
2062 : /** Add string argument. */
2063 : GDALInConstructionAlgorithmArg &AddArg(const std::string &longName,
2064 : char chShortName,
2065 : const std::string &helpMessage,
2066 : std::string *pValue);
2067 :
2068 : /** Add integer argument. */
2069 : GDALInConstructionAlgorithmArg &AddArg(const std::string &longName,
2070 : char chShortName,
2071 : const std::string &helpMessage,
2072 : int *pValue);
2073 :
2074 : /** Add real argument. */
2075 : GDALInConstructionAlgorithmArg &AddArg(const std::string &longName,
2076 : char chShortName,
2077 : const std::string &helpMessage,
2078 : double *pValue);
2079 :
2080 : /** Add dataset argument. */
2081 : GDALInConstructionAlgorithmArg &
2082 : AddArg(const std::string &longName, char chShortName,
2083 : const std::string &helpMessage, GDALArgDatasetValue *pValue,
2084 : GDALArgDatasetValueType type = GDAL_OF_RASTER | GDAL_OF_VECTOR |
2085 : GDAL_OF_MULTIDIM_RASTER);
2086 :
2087 : /** Add list of string argument. */
2088 : GDALInConstructionAlgorithmArg &AddArg(const std::string &longName,
2089 : char chShortName,
2090 : const std::string &helpMessage,
2091 : std::vector<std::string> *pValue);
2092 :
2093 : /** Add list of integer argument. */
2094 : GDALInConstructionAlgorithmArg &AddArg(const std::string &longName,
2095 : char chShortName,
2096 : const std::string &helpMessage,
2097 : std::vector<int> *pValue);
2098 :
2099 : /** Add list of real argument. */
2100 : GDALInConstructionAlgorithmArg &AddArg(const std::string &longName,
2101 : char chShortName,
2102 : const std::string &helpMessage,
2103 : std::vector<double> *pValue);
2104 :
2105 : /** Add list of dataset argument. */
2106 : GDALInConstructionAlgorithmArg &
2107 : AddArg(const std::string &longName, char chShortName,
2108 : const std::string &helpMessage,
2109 : std::vector<GDALArgDatasetValue> *pValue,
2110 : GDALArgDatasetValueType type = GDAL_OF_RASTER | GDAL_OF_VECTOR |
2111 : GDAL_OF_MULTIDIM_RASTER);
2112 :
2113 : /** Add input dataset argument. */
2114 : GDALInConstructionAlgorithmArg &
2115 : AddInputDatasetArg(GDALArgDatasetValue *pValue,
2116 : GDALArgDatasetValueType type = GDAL_OF_RASTER |
2117 : GDAL_OF_VECTOR |
2118 : GDAL_OF_MULTIDIM_RASTER,
2119 : bool positionalAndRequired = true);
2120 :
2121 : /** Add input dataset argument. */
2122 : GDALInConstructionAlgorithmArg &
2123 : AddInputDatasetArg(std::vector<GDALArgDatasetValue> *pValue,
2124 : GDALArgDatasetValueType type = GDAL_OF_RASTER |
2125 : GDAL_OF_VECTOR |
2126 : GDAL_OF_MULTIDIM_RASTER,
2127 : bool positionalAndRequired = true);
2128 :
2129 : /** Add open option(s) argument. */
2130 : GDALInConstructionAlgorithmArg &
2131 : AddOpenOptionsArg(std::vector<std::string> *pValue);
2132 :
2133 : /** Add input format(s) argument. */
2134 : GDALInConstructionAlgorithmArg &
2135 : AddInputFormatsArg(std::vector<std::string> *pValue);
2136 :
2137 : /** Add output dataset argument. */
2138 : GDALInConstructionAlgorithmArg &
2139 : AddOutputDatasetArg(GDALArgDatasetValue *pValue,
2140 : GDALArgDatasetValueType type = GDAL_OF_RASTER |
2141 : GDAL_OF_VECTOR |
2142 : GDAL_OF_MULTIDIM_RASTER,
2143 : bool positionalAndRequired = true);
2144 :
2145 : /** Add --overwrite argument. */
2146 : GDALInConstructionAlgorithmArg &AddOverwriteArg(bool *pValue);
2147 :
2148 : /** Add --update argument. */
2149 : GDALInConstructionAlgorithmArg &AddUpdateArg(bool *pValue);
2150 :
2151 : /** Add (non-CLI) output-string argument. */
2152 : GDALInConstructionAlgorithmArg &AddOutputStringArg(std::string *pValue);
2153 :
2154 : /** Add output format argument. */
2155 : GDALInConstructionAlgorithmArg &
2156 : AddOutputFormatArg(std::string *pValue, bool bStreamAllowed = false);
2157 :
2158 : /** Add creation option(s) argument. */
2159 : GDALInConstructionAlgorithmArg &
2160 : AddCreationOptionsArg(std::vector<std::string> *pValue);
2161 :
2162 : /** Add layer creation option(s) argument. */
2163 : GDALInConstructionAlgorithmArg &
2164 : AddLayerCreationOptionsArg(std::vector<std::string> *pValue);
2165 :
2166 : /** Add (single) layer name argument. */
2167 : GDALInConstructionAlgorithmArg &AddLayerNameArg(std::string *pValue);
2168 :
2169 : /** Add (potentially multiple) layer name(s) argument. */
2170 : GDALInConstructionAlgorithmArg &
2171 : AddLayerNameArg(std::vector<std::string> *pValue);
2172 :
2173 : /** Add bbox=xmin,ymin,xmax,ymax argument. */
2174 : GDALInConstructionAlgorithmArg &
2175 : AddBBOXArg(std::vector<double> *pValue, const char *helpMessage = nullptr);
2176 :
2177 : /** Add --progress argument. */
2178 : GDALInConstructionAlgorithmArg &AddProgressArg();
2179 :
2180 : /** Validation function to use for key=value type of arguments. */
2181 : bool ValidateKeyValue(const GDALAlgorithmArg &arg) const;
2182 :
2183 : //! @cond Doxygen_Suppress
2184 : void AddAliasFor(GDALInConstructionAlgorithmArg *arg,
2185 : const std::string &alias);
2186 : void SetPositional(GDALInConstructionAlgorithmArg *arg);
2187 :
2188 : //! @endcond
2189 :
2190 : /** Set whether this algorithm should be reported in JSON usage. */
2191 110 : void SetDisplayInJSONUsage(bool b)
2192 : {
2193 110 : m_displayInJSONUsage = b;
2194 110 : }
2195 :
2196 : //! @cond Doxygen_Suppress
2197 : void ReportError(CPLErr eErrClass, CPLErrorNum err_no, const char *fmt,
2198 : ...) const CPL_PRINT_FUNC_FORMAT(4, 5);
2199 : //! @endcond
2200 :
2201 : /** Return the list of arguments for CLI usage */
2202 : std::pair<std::vector<std::pair<GDALAlgorithmArg *, std::string>>, size_t>
2203 : GetArgNamesForCLI() const;
2204 :
2205 : private:
2206 : const std::string m_name{};
2207 : const std::string m_description{};
2208 : const std::string m_helpURL{};
2209 : const std::string m_helpFullURL{};
2210 : bool m_parsedSubStringAlreadyCalled = false;
2211 : bool m_displayInJSONUsage = true;
2212 : bool m_specialActionRequested = false;
2213 : bool m_helpRequested = false;
2214 : bool m_JSONUsageRequested = false;
2215 : bool m_dummyBoolean = false; // Used for --version
2216 : bool m_parseForAutoCompletion = false;
2217 : std::vector<std::string> m_dummyConfigOptions{};
2218 : std::vector<std::unique_ptr<GDALAlgorithmArg>> m_args{};
2219 : std::map<std::string, GDALAlgorithmArg *> m_mapLongNameToArg{};
2220 : std::map<std::string, GDALAlgorithmArg *> m_mapShortNameToArg{};
2221 : std::vector<GDALAlgorithmArg *> m_positionalArgs{};
2222 : GDALAlgorithmRegistry m_subAlgRegistry{};
2223 : std::unique_ptr<GDALAlgorithm> m_shortCutAlg{};
2224 : std::function<std::vector<std::string>(const std::vector<std::string> &)>
2225 : m_autoCompleteFunction{};
2226 :
2227 : GDALInConstructionAlgorithmArg &
2228 : AddArg(std::unique_ptr<GDALInConstructionAlgorithmArg> arg);
2229 : bool ParseArgument(
2230 : GDALAlgorithmArg *arg, const std::string &name,
2231 : const std::string &value,
2232 : std::map<
2233 : GDALAlgorithmArg *,
2234 : std::variant<std::vector<std::string>, std::vector<int>,
2235 : std::vector<double>, std::vector<GDALArgDatasetValue>>>
2236 : &inConstructionValues);
2237 :
2238 : bool ValidateFormat(const GDALAlgorithmArg &arg, bool bStreamAllowed) const;
2239 :
2240 : virtual bool RunImpl(GDALProgressFunc pfnProgress, void *pProgressData) = 0;
2241 :
2242 : /** Extract the last option and its potential value from the provided
2243 : * argument list, and remove them from the list.
2244 : */
2245 : void ExtractLastOptionAndValue(std::vector<std::string> &args,
2246 : std::string &option,
2247 : std::string &value) const;
2248 :
2249 : GDALAlgorithm(const GDALAlgorithm &) = delete;
2250 : GDALAlgorithm &operator=(const GDALAlgorithm &) = delete;
2251 : };
2252 :
2253 : //! @cond Doxygen_Suppress
2254 : struct GDALAlgorithmHS
2255 : {
2256 : private:
2257 : std::unique_ptr<GDALAlgorithm> uniquePtr{};
2258 :
2259 : GDALAlgorithmHS(const GDALAlgorithmHS &) = delete;
2260 : GDALAlgorithmHS &operator=(const GDALAlgorithmHS &) = delete;
2261 :
2262 : public:
2263 : GDALAlgorithm *ptr = nullptr;
2264 :
2265 65 : GDALAlgorithmHS() = default;
2266 :
2267 538 : explicit GDALAlgorithmHS(std::unique_ptr<GDALAlgorithm> alg)
2268 538 : : uniquePtr(std::move(alg)), ptr(uniquePtr.get())
2269 : {
2270 538 : }
2271 :
2272 65 : static std::unique_ptr<GDALAlgorithmHS> FromRef(GDALAlgorithm &alg)
2273 : {
2274 65 : auto ret = std::make_unique<GDALAlgorithmHS>();
2275 65 : ret->ptr = &alg;
2276 65 : return ret;
2277 : }
2278 : };
2279 :
2280 : //! @endcond
2281 :
2282 : /************************************************************************/
2283 : /* GDALGlobalAlgorithmRegistry */
2284 : /************************************************************************/
2285 :
2286 : /** Global registry of GDAL algorithms.
2287 : */
2288 : class CPL_DLL GDALGlobalAlgorithmRegistry final : public GDALAlgorithmRegistry
2289 : {
2290 : public:
2291 : /** Name of the root "gdal" algorithm. */
2292 : static constexpr const char *ROOT_ALG_NAME = "gdal";
2293 :
2294 : /** Get the singleton */
2295 : static GDALGlobalAlgorithmRegistry &GetSingleton();
2296 :
2297 : /** Instantiate an algorithm by its name or one of its alias. */
2298 : std::unique_ptr<GDALAlgorithm>
2299 : Instantiate(const std::string &name) const override;
2300 : };
2301 :
2302 : /************************************************************************/
2303 : /* GDAL_STATIC_REGISTER_ALG() */
2304 : /************************************************************************/
2305 :
2306 : /** Static registration of an algorithm by its class name (which must implement
2307 : * GDALAlgorithm)
2308 : */
2309 : #define GDAL_STATIC_REGISTER_ALG(MyAlgorithm) \
2310 : static bool MyAlgorithm##_static_registration = \
2311 : GDALGlobalAlgorithmRegistry::GetSingleton().Register<MyAlgorithm>()
2312 :
2313 : #endif // #if defined(__cplusplus) && !defined(CPL_SUPRESS_CPLUSPLUS) && (defined(DOXYGEN_SKIP) || __cplusplus >= 201703L || _MSC_VER >= 1920)
2314 :
2315 : #endif // GDAL_ALGORITHM_INCLUDED
|
