From 28928ed712f653d7213a97b0946b85304bdda447 Mon Sep 17 00:00:00 2001
From: John Gee <john@ruru.gen.nz>
Date: Fri, 7 Apr 2023 11:57:23 +1200
Subject: [PATCH] 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