Merge pull request #2084 from rsteube/updated-release-notes

doc: updated macro examples

docs/src/release_notes/v0.25.md

@@ -1,7 +1,7 @@
-# v0.25 Window Shopping
+# v0.25 - Window Shopping
 
 ![](./v0.25/banner.png)
 
 ## Windows
 
-Support for volume prefix in path completion.
+Support for volume prefix in path completion.

docs/src/release_notes/v0.29.md

@@ -2,22 +2,32 @@
 
 ![](./v0.29/banner.png)
 
-## Macros
+One step further to exchange completions _loosely coupled_ between commands.
 
-`$_` prefix is now deprecated and needs to be replaced with `$carapace.`
+## Root Command
 
-```
-$_color.HexColors
-$carapace.color.HexColors
-```
+Restructured the `carapace` root command which was (and still is) a bit of a mess.
+Some "flags" (subcommands) were renamed/changed for consistency.
 
-```sh
-carapace _carapace macro color.HexColors ""
-```
+- `--list=json` -> `--list --format json`
+- `--scrape [spec]` -> `--codegen [spec]`
+
+## Macro
+
+`$_` prefix in specs is now deprecated and needs to be replaced with `$carapace.`
 
 ```sh
-sed 's/$_/$carapace./g' ~/.config/carapace/specs/*.yaml
+$carapace.color.HexColors
+# invokes `carapace _carapace macro color.HexColors ""`
+
+$carapace-spec.Spec(example.yaml)
+# invokes `carapace-spec _carapace macro "Spec(example.yaml)" ""`
 ```
+
+> You can replace this with the `--in-place` flag directly:
+> ```sh
+> sed 's/$_/$carapace./g' ~/.config/carapace/specs/*.yaml
+> ```
   
 ## Xonsh
 

docs/src/spec/bridge.md

@@ -19,7 +19,7 @@ Bridging completions from another engine for shells not natively supported by it
 name: az
 description: Azure Command-Line Interface
 completion:
-  positionalany: ["$_bridge.Argcomplete([az])"]
+  positionalany: ["$carapace.bridge.Argcomplete([az])"]
 ```
 
 ### Carapace
@@ -30,7 +30,7 @@ completion:
 name: freckles
 description: simple dotfile manager
 completion:
-  positionalany: ["$_bridge.Carapace([freckles])"]
+  positionalany: ["$carapace.bridge.Carapace([freckles])"]
 ```
 
 ### CarapaceBin
@@ -41,7 +41,7 @@ completion:
 name: github-cli
 description: Work seamlessly with GitHub from the command line
 completion:
-  positionalany: ["$_bridge.CarapaceBin([gh])"]
+  positionalany: ["$carapace.bridge.CarapaceBin([gh])"]
 ```
 
 ### Clap
@@ -52,7 +52,7 @@ completion:
 name: dyamic
 description: clap dynamic example
 completion:
-  positionalany: ["$_bridge.Clap([dynamic])"]
+  positionalany: ["$carapace.bridge.Clap([dynamic])"]
 ```
 
 ### Click
@@ -63,7 +63,7 @@ completion:
 name: watson
 description: Watson is a tool aimed at helping you monitoring your time
 completion:
-  positionalany: ["$_bridge.Click([watson])"]
+  positionalany: ["$carapace.bridge.Click([watson])"]
 ```
 
 ### Cobra
@@ -74,7 +74,7 @@ completion:
 name: kubectl
 description: kubectl controls the Kubernetes cluster manager
 completion:
-  positionalany: ["$_bridge.Cobra([kubectl])"]
+  positionalany: ["$carapace.bridge.Cobra([kubectl])"]
 ```
 
 ### Complete
@@ -84,7 +84,7 @@ completion:
 name: vault
 description: Manage Secrets & Protect Sensitive Data
 completion:
-  positionalany: ["$_bridge.Complete([vault])"]
+  positionalany: ["$carapace.bridge.Complete([vault])"]
 ```
 
 ### Inshellisense
@@ -94,7 +94,7 @@ Commands provided by [microsoft/inshellisense] can be bridged with the [`bridge.
 name: node
 description: Run the node interpreter
 completion:
-  positionalany: ["$_bridge.Inshellisense([node])"]
+  positionalany: ["$carapace.bridge.Inshellisense([node])"]
 ```
 
 ### Kingpin
@@ -105,7 +105,7 @@ completion:
 name: tsh
 description: Teleport Command Line Client
 completion:
-  positionalany: ["$_bridge.Kingpin([tsh])"]
+  positionalany: ["$carapace.bridge.Kingpin([tsh])"]
 ```
 
 ### Urfavecli
@@ -116,7 +116,7 @@ completion:
 name: tea
 description: command line tool to interact with Gitea
 completion:
-  positionalany: ["$_bridge.Urfavecli([tea])"]
+  positionalany: ["$carapace.bridge.Urfavecli([tea])"]
 ```
 
 ### Yargs
@@ -126,7 +126,7 @@ completion:
 name: ng
 description: CLI tool for Angular
 completion:
-  positionalany: ["$_bridge.Yargs([ng])"]
+  positionalany: ["$carapace.bridge.Yargs([ng])"]
 ```
 
 ## Shells
@@ -142,7 +142,7 @@ Commands registered in [bash] can be bridged with the [`bridge.Bash`] macro:
 name:  tail
 description: output the last part of files
 completion:
-  positionalany: ["$_bridge.Bash([tail])"]
+  positionalany: ["$carapace.bridge.Bash([tail])"]
 ```
 
 ### Fish
@@ -153,7 +153,7 @@ Commands registered in [fish-shell/fish-shell] can be bridged with the [`bridge.
 name:  git
 description: the stupid content tracker
 completion:
-  positionalany: ["$_bridge.Fish([git])"]
+  positionalany: ["$carapace.bridge.Fish([git])"]
 ```
 
 ### Powershell
@@ -164,7 +164,7 @@ Commands registered in [powershell] can be bridged with the [`bridge.Powershell`
 name:  ConvertTo-Json
 description: convert to json
 completion:
-  positionalany: ["$_bridge.Powershell([ConvertTo-Json])"]
+  positionalany: ["$carapace.bridge.Powershell([ConvertTo-Json])"]
 ```
 
 ### Zsh
@@ -175,7 +175,7 @@ Commands registered in [zsh] can be bridged with the [`bridge.Zsh`] macro:
 name:  git
 description: the stupid content tracker
 completion:
-  positionalany: ["$_bridge.Zsh([git])"]
+  positionalany: ["$carapace.bridge.Zsh([git])"]
 ```
 
 [lazycomplete]:https://github.com/rsteube/lazycomplete

docs/src/spec/embed.md

@@ -7,7 +7,7 @@ name: embed
 commands:
   - name: git
     completion:
-      positionalany: ["$chdir(~/.password-store)", "$_bridge.CarapaceBin([git])"]
+      positionalany: ["$chdir(~/.password-store)", "$carapace.bridge.CarapaceBin([git])"]
 ```
 
 ![](./embed.cast)
@@ -26,7 +26,7 @@ commands:
     name: list
     completion:
       positional:
-        - ["$_tools.gh.OwnerRepositories"]
+        - ["$carapace.tools.gh.OwnerRepositories"]
   -
     name: add
     flags:
@@ -35,14 +35,14 @@ commands:
       flag:
         permission: ["pull", "triage", "push", "maintain", "admin\t\tred"]
       positional:
-        - ["$_tools.gh.OwnerRepositories"]
-        - ["$_tools.gh.Users"]
+        - ["$carapace.tools.gh.OwnerRepositories"]
+        - ["$carapace.tools.gh.Users"]
   -
     name: remove
     completion:
       positional:
-        - ["$_tools.gh.OwnerRepositories"]
-        - ["$_tools.gh.Users"]
+        - ["$carapace.tools.gh.OwnerRepositories"]
+        - ["$carapace.tools.gh.Users"]
 ```
 
 ![](./embed-plugin.cast)

docs/src/spec/examples.md

@@ -6,8 +6,8 @@
 name: github
 completion:
   positional:
-    - ["$_tools.gh.OwnerRepositories"]  # ${C_ARG0}
-    - ["$_tools.git.LsRemoteRefs({url: 'https://github.com/${C_ARG0}', branches: true, tags: true})"]
+    - ["$carapace.tools.gh.OwnerRepositories"]  # ${C_ARG0}
+    - ["$carapace.tools.git.LsRemoteRefs({url: 'https://github.com/${C_ARG0}', branches: true, tags: true})"]
 ```
 
 ![](./examples-github.cast)
@@ -19,7 +19,7 @@ name: zipfile
 completion:
   positional:
     - ["$files([.zip])"] # ${C_ARG0}
-  positionalany: ["$_fs.ZipFileContents(${C_ARG0})"] # ${C_ARG1},${C_ARG2},...
+  positionalany: ["$carapace.fs.ZipFileContents(${C_ARG0})"] # ${C_ARG1},${C_ARG2},...
 ```
 
 ![](./examples-zipfile.cast)
@@ -34,8 +34,8 @@ flags:
   --c=: amount of commits # ${C_FLAG_C}
 completion:
   positional:
-    - ["$_tools.git.Refs({tags: ${C_FLAG_TAGS:-false}, localbranches: ${C_FLAG_LOCALBRANCHES:-false}, commits: ${C_FLAG_C:-0}})"]
-    - ["$_tools.git.Refs"] # default
+    - ["$carapace.tools.git.Refs({tags: ${C_FLAG_TAGS:-false}, localbranches: ${C_FLAG_LOCALBRANCHES:-false}, commits: ${C_FLAG_C:-0}})"]
+    - ["$carapace.tools.git.Refs"] # default
 ```
 
 ![](./examples-refs.cast)
@@ -96,7 +96,7 @@ commands:
     flags:
       -s, --staged: include staged files
     completion:
-      positionalany: ["$_tools.git.Changes({staged: ${C_FLAG_STAGED:-false}, unstaged: true})"]
+      positionalany: ["$carapace.tools.git.Changes({staged: ${C_FLAG_STAGED:-false}, unstaged: true})"]
 ```
 
 ![](./examples-g.cast)

docs/src/spec/run.md

@@ -27,8 +27,8 @@ completion:
   flag:
     sort: [version:refname, authordate]
   positional:
-    - ["$_tools.git.RepositorySearch"]
-  positionalany: ["$_tools.git.LsRemoteRefs({url: '${C_ARG0}', branches: true, tags: true})"]
+    - ["$carapace.tools.git.RepositorySearch"]
+  positionalany: ["$carapace.tools.git.LsRemoteRefs({url: '${C_ARG0}', branches: true, tags: true})"]
 ```
 
 ![](./run-script.cast)

docs/src/spec/user.md

@@ -15,7 +15,7 @@ User defined [Specs] are automatically loaded by `carapace _carapace` from [`${U
 name: kubectl
 description: kubectl controls the Kubernetes cluster manager
 completion:
-  positionalany: ["$_bridge.Cobra([kubectl])"]
+  positionalany: ["$carapace.bridge.Cobra([kubectl])"]
 ```
 
 ## JSON Schema

docs/src/variable.md

@@ -1,7 +1,5 @@
 # Variable
 
-> feature in development
-
 Complex environment variable completion is provided with `get-env`, `set-env` and `unset-env`.
 
 In `elvish` the completion is simply overridden.
@@ -23,7 +21,7 @@ variables:
 completion:
   variable:
     CUSTOM_EXAMPLE: ["0\tdisabled\tred", "1\tenabled\tgreen"]
-    CUSTOM_MACRO: ["$_tools.gh.Labels({owner: rsteube, name: carapace}) ||| $uniquelist(,)"]
+    CUSTOM_MACRO: ["$carapace.tools.gh.Labels({owner: rsteube, name: carapace}) ||| $uniquelist(,)"]
     HTTPS_PROXY: ["https://localhost:8443\tdevelopment", "https://proxy.company:443\tproduction"]
 ```