From 8c683919538269d809bf94cf831344d5e0d771ba Mon Sep 17 00:00:00 2001 From: rsteube Date: Fri, 22 Dec 2023 15:42:01 +0100 Subject: [PATCH] doc: updated macro examples --- docs/src/release_notes/v0.25.md | 4 ++-- docs/src/release_notes/v0.29.md | 30 ++++++++++++++++++++---------- docs/src/spec/bridge.md | 30 +++++++++++++++--------------- docs/src/spec/embed.md | 12 ++++++------ docs/src/spec/examples.md | 12 ++++++------ docs/src/spec/run.md | 4 ++-- docs/src/spec/user.md | 2 +- docs/src/variable.md | 4 +--- 8 files changed, 53 insertions(+), 45 deletions(-) diff --git a/docs/src/release_notes/v0.25.md b/docs/src/release_notes/v0.25.md index 4aa0e54ead..b4c296faf9 100644 --- a/docs/src/release_notes/v0.25.md +++ b/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. \ No newline at end of file +Support for volume prefix in path completion. diff --git a/docs/src/release_notes/v0.29.md b/docs/src/release_notes/v0.29.md index 35b3369151..cc80000a5e 100644 --- a/docs/src/release_notes/v0.29.md +++ b/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 diff --git a/docs/src/spec/bridge.md b/docs/src/spec/bridge.md index d91a27eda6..f41b26dffa 100644 --- a/docs/src/spec/bridge.md +++ b/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 diff --git a/docs/src/spec/embed.md b/docs/src/spec/embed.md index c1cc168976..4a3d8d1782 100644 --- a/docs/src/spec/embed.md +++ b/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) diff --git a/docs/src/spec/examples.md b/docs/src/spec/examples.md index f08aa44a45..7e2ea044f2 100644 --- a/docs/src/spec/examples.md +++ b/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) diff --git a/docs/src/spec/run.md b/docs/src/spec/run.md index 673bd8ad6a..1ed7399207 100644 --- a/docs/src/spec/run.md +++ b/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) \ No newline at end of file diff --git a/docs/src/spec/user.md b/docs/src/spec/user.md index b63a86e566..42462d96f0 100644 --- a/docs/src/spec/user.md +++ b/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 diff --git a/docs/src/variable.md b/docs/src/variable.md index d400d5982a..788b3a24ef 100644 --- a/docs/src/variable.md +++ b/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"] ```