Merge pull request #294 from alextremblay/patch-1

add details to `exec` macro documentation
carapace-sh · Aug 30, 2024 · 1420ee3 · 1420ee3
2 parents 3a8906c + 2b42568
commit 1420ee3
Showing 1 changed file with 30 additions and 0 deletions.
diff --git a/docs/src/carapace-spec/macros/core.md b/docs/src/carapace-spec/macros/core.md
@@ -17,6 +17,36 @@ Core macros provided by [carapace-spec](https://github.com/carapace-sh/carapace-
 ["$(echo -e 'a\nb\nc')"]
 ```
 
+Any arguments or options or flags already parsed by carapace will be included in the executed command's environment variables, prefixed with `C_`
+
+For example, with a spec like 
+```yaml
+# yaml-language-server: $schema=https://carapace.sh/schemas/command.json
+name: context
+persistentflags:
+  -p, --persistent: persistent flag
+commands:
+  - name: sub
+    flags:
+      -s, --string=: string flag
+      -b, --bool: bool flag
+      --custom=: custom flag
+    completion:
+      flag:
+        custom: ["$(env)"]
+```
+Typing `context sub --custom ` and hitting the **TAB** key will execute the unix `env` command and return all environment variables as completion options.
+Typing `context --persistent sub --string one -b arg1 arg2 --custom C_` and hitting **TAB** will produce the following terminal completion options:
+```console
+C_ARG0=arg1                                                                                                                              
+C_ARG1=arg2                                                                                                                              
+C_FLAG_BOOL=true                                                                                                                         
+C_FLAG_STRING=one                                                                                                                        
+C_VALUE=C_
+```
+
+Every variable listed in [Variables](https://carapace-sh.github.io/carapace-spec/carapace-spec/variables.html) which has a value will be included in the executed command's environment
+
 ## executables
 
 [`$executables`](https://carapace-sh.github.io/carapace/carapace/defaultActions/actionExecutables.html) completes executables either from [PATH] or given directories.