@@ -504,19 +504,32 @@ Before parsing, you can set the following options:
504504 parsed vs. at the end of all parsing. This could cause the callback to be
505505 executed multiple times. Also works with positional options.
506506- ` ->callback_priority(CallbackPriority priority) ` : 🚧 changes the order in
507- which the option callback is executed. ` CallbackPriority::PreHelpCheck ` runs
508- the option callback or value setting prior to help checks and requirements
509- checking. ` CallbackPriority::PreRequirementsCheck ` runs the option callback
510- after the help check but prior to checking for other requirements.
511- ` CallbackPriority::Normal ` is the default and runs the callbacks after
512- requirements and help have been checked and processed.
513- ` CallbackPriority::Last ` runs after all normal priority callbacks have been
514- executed. This allows fine grained manipulation of when option values are set
515- and when errors or checks can be triggered from the options. The help pointer
516- may also be modified to make it run later by default, it normally runs before
517- the requirements checking but can be modified to run later by giving it
518- ` Normal ` or ` Last ` priority, as opposed to modifying individual options. The
519- version flag has ` PreRequirementsCheck ` priority by default.
507+ which the option callback is executed. Four principal callback call-points
508+ are available. ` CallbackPriority::First ` executes at the very beginning of
509+ processing, before configuration files are read and environment variables are
510+ interpreted. ` CallbackPriority::PreRequirementsCheck ` executes after
511+ configuration and environment processing but before requirements checking.
512+ ` CallbackPriority::Normal ` executes after the requirements check but before any
513+ previously potentially raised exceptions are re-thrown. ` CallbackPriority::Last `
514+ executes after exception handling is completed.
515+ For each position, both ordinary option callbacks and help callbacks are
516+ invoked. The relative order between them can be controlled using the
517+ corresponding ` PreHelp ` variants. ` CallbackPriority::FirstPreHelp ` executes
518+ ordinary option callbacks before help callbacks at the very beginning of
519+ processing. ` CallbackPriority::PreRequirementsCheckPreHelp ` executes ordinary
520+ option callbacks before help callbacks after configuration and environment
521+ processing but before requirements checking. ` CallbackPriority::NormalPreHelp `
522+ executes ordinary option callbacks before help callbacks after the requirements
523+ check but before exception re-throwing. ` CallbackPriority::LastPreHelp ` executes
524+ ordinary option callbacks before help callbacks after exception handling has
525+ completed. When using the standard priorities (` CallbackPriority::First ` ,
526+ ` CallbackPriority::PreRequirementsCheck ` , ` CallbackPriority::Normal ` ,
527+ ` CallbackPriority::Last ` ), help callbacks are executed before ordinary option
528+ callbacks. By default, help callbacks use ` CallbackPriority::First ` , and
529+ ordinary option callbacks use ` CallbackPriority::Normal ` . This mechanism provides
530+ fine-grained control over when option values are set and when help or
531+ requirement checks occur, enabling precise customization of the processing
532+ sequence.
520533
521534These options return the ` Option ` pointer, so you can chain them together, and
522535even skip storing the pointer entirely. The ` each ` function takes any function
@@ -656,7 +669,7 @@ setting `CLI11_ENABLE_EXTRA_VALIDATORS` to 1
656669 write permission. Requires C++17.
657670- `CLI::ExecPermission`: Requires that the file given exist and have execution
658671 permission. Requires C++17.
659- -
672+ -
660673
661674#### Validator Usage
662675
0 commit comments