Skip to content

Commit 9af36a7

Browse files
Update Readme.md describing callback priorities in detail
1 parent 95af66d commit 9af36a7

File tree

1 file changed

+28
-14
lines changed

1 file changed

+28
-14
lines changed

README.md

Lines changed: 28 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -504,19 +504,33 @@ 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
513+
any previously potentially raised exceptions are re-thrown.
514+
`CallbackPriority::Last` 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
523+
requirements check but before exception re-throwing.
524+
`CallbackPriority::LastPreHelp` executes ordinary option callbacks before help
525+
callbacks after exception handling has completed. When using the standard
526+
priorities (`CallbackPriority::First`,
527+
`CallbackPriority::PreRequirementsCheck`, `CallbackPriority::Normal`,
528+
`CallbackPriority::Last`), help callbacks are executed before ordinary option
529+
callbacks. By default, help callbacks use `CallbackPriority::First`, and
530+
ordinary option callbacks use `CallbackPriority::Normal`. This mechanism
531+
provides fine-grained control over when option values are set and when help or
532+
requirement checks occur, enabling precise customization of the processing
533+
sequence.
520534

521535
These options return the `Option` pointer, so you can chain them together, and
522536
even skip storing the pointer entirely. The `each` function takes any function
@@ -656,7 +670,7 @@ setting `CLI11_ENABLE_EXTRA_VALIDATORS` to 1
656670
write permission. Requires C++17.
657671
- `CLI::ExecPermission`: Requires that the file given exist and have execution
658672
permission. Requires C++17.
659-
-
673+
-
660674
661675
#### Validator Usage
662676

0 commit comments

Comments
 (0)