doc: 1.x - added spec example

carapace-sh · Dec 14, 2024 · 3166ec1 · 3166ec1
1 parent 3376720
commit 3166ec1
Show file tree

Hide file tree

Showing 2 changed files with 84 additions and 0 deletions.
diff --git a/docs/src/release_notes/v1.x.md b/docs/src/release_notes/v1.x.md
@@ -11,3 +11,23 @@ Extracted the `set-env <NAME> <VALUE>` completion as generic action.
 ![](./v1.x/env.cast)
 
 > Completions use the **local** environment so there are some limitations.
+
+### Spec
+
+In specs it can be used **attached** (default) or **positional** (use `shift` to skip previous arguments).
+
+```yaml
+# yaml-language-server: $schema=https://carapace.sh/schemas/command.json
+name: variable
+completion:
+  positional:
+  - ["$carapace.env.NameValues"] # attached (NAME[=VALUE])
+  - ["$carapace.env.NameValues(true) ||| $shift(1)"] # positional (NAME)
+  - ["$carapace.env.NameValues(true) ||| $shift(1)"] # positional (VALUE)
+```
+
+![](./v1.x/env-spec.cast)
+
+> Renamed:
+> - `env.KnownEnvironmentVariables` to `env.Names`
+> - `env.EnvironmentVariableValues` to `env.Values`