From 0f58a8bfda79caccf5c412c75da96ad810d4e9a6 Mon Sep 17 00:00:00 2001 From: John Gee Date: Fri, 7 Apr 2023 11:57:23 +1200 Subject: [PATCH 1/3] Add parsing life cycle and hooks --- docs/parsing-and-hooks.md | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) create mode 100644 docs/parsing-and-hooks.md diff --git a/docs/parsing-and-hooks.md b/docs/parsing-and-hooks.md new file mode 100644 index 000000000..a285fa867 --- /dev/null +++ b/docs/parsing-and-hooks.md @@ -0,0 +1,23 @@ +# Parsing life cycle and hooks + +The processing starts with an array of args. Each command processes and removes the options it understands, and passes the remaining args to the next subcommand. +The final command calls the action handler. + +Starting with top-level command (program): + +- parse options: parse recognised options (for this command) and remove from args +- parse env: look for environment variables (for this command) +- process implied: set any implied option values (for this command) +- if the first arg is a subcommand + - call `preSubcommand` hook + - pass remaining arguments to subcommand, and process same way + +Once reach final (leaf) command: + + - check for missing mandatory options + - check for conflicting options + - check for unknown options + - process remaining args as command-arguments + - call `preAction` hook + - call action handler + - call `postAction` hook From a41194f073bab69c08ab02e0685ee74ff7f99c9b Mon Sep 17 00:00:00 2001 From: John Gee Date: Fri, 7 Apr 2023 14:20:08 +1200 Subject: [PATCH 2/3] Add new documentation to README --- Readme.md | 3 +++ docs/parsing-and-hooks.md | 14 +++++++------- 2 files changed, 10 insertions(+), 7 deletions(-) diff --git a/Readme.md b/Readme.md index 5f0444dde..6434770ba 100644 --- a/Readme.md +++ b/Readme.md @@ -730,6 +730,8 @@ The supported events are: | `preAction`, `postAction` | before/after action handler for this command and its nested subcommands | `(thisCommand, actionCommand)` | | `preSubcommand` | before parsing direct subcommand | `(thisCommand, subcommand)` | +For an overview of the life cycle events see [parsing life cycle and hooks](./docs/parsing-and-hooks.md). + ## Automated help The help information is auto-generated based on the information commander already knows about your program. The default @@ -1114,6 +1116,7 @@ There is more information available about: - [deprecated](./docs/deprecated.md) features still supported for backwards compatibility - [options taking varying arguments](./docs/options-taking-varying-arguments.md) +- [parsing life cycle and hooks](./docs/parsing-and-hooks.md) ## Support diff --git a/docs/parsing-and-hooks.md b/docs/parsing-and-hooks.md index a285fa867..a03da54d4 100644 --- a/docs/parsing-and-hooks.md +++ b/docs/parsing-and-hooks.md @@ -14,10 +14,10 @@ Starting with top-level command (program): Once reach final (leaf) command: - - check for missing mandatory options - - check for conflicting options - - check for unknown options - - process remaining args as command-arguments - - call `preAction` hook - - call action handler - - call `postAction` hook +- check for missing mandatory options +- check for conflicting options +- check for unknown options +- process remaining args as command-arguments +- call `preAction` hook +- call action handler +- call `postAction` hook From 2525087d29957a6d4f7210f1cc1daf110fa70e62 Mon Sep 17 00:00:00 2001 From: John Gee Date: Fri, 7 Apr 2023 14:22:01 +1200 Subject: [PATCH 3/3] Could be multiple hooks, pluralise --- docs/parsing-and-hooks.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/parsing-and-hooks.md b/docs/parsing-and-hooks.md index a03da54d4..122cad6f7 100644 --- a/docs/parsing-and-hooks.md +++ b/docs/parsing-and-hooks.md @@ -9,7 +9,7 @@ Starting with top-level command (program): - parse env: look for environment variables (for this command) - process implied: set any implied option values (for this command) - if the first arg is a subcommand - - call `preSubcommand` hook + - call `preSubcommand` hooks - pass remaining arguments to subcommand, and process same way Once reach final (leaf) command: @@ -18,6 +18,6 @@ Once reach final (leaf) command: - check for conflicting options - check for unknown options - process remaining args as command-arguments -- call `preAction` hook +- call `preAction` hooks - call action handler -- call `postAction` hook +- call `postAction` hooks