multi-shell multi-command argument completer
MIT License
Bot releases are visible (Hide)
Published by rsteube over 1 year ago
pulumi stack graph
Published by rsteube over 1 year ago
Published by rsteube over 1 year ago
Published by rsteube over 1 year ago
Published by rsteube over 1 year ago
Published by rsteube over 1 year ago
os.PathExecutables
as executables
Published by rsteube over 1 year ago
Moved bridge actions to carapace-bridge.
The shell bridges now use custom configs at ${UserConfigDir}/carapace/bridge
(e.g. ~/.config/carapace/bridge/fish/config.fish
instead of ~/.config/fish/config.fish
).
Removed --bridge
and --spec
flags as user specs are preferred and there are carapace-bridge and carapace-spec as well.
--bridge
from carapace--spec
flagPublished by rsteube over 1 year ago
Bridge actions now take multiple arguments.
Analogue to Alias this enables embedding of subcommands in macros.
Specs need to be updated though by adding []
brackets to the bridge macro arguments:
completion:
# positionalany: ["$_bridge.CarapaceBin(git)"] # OLD
positionalany: ["$_bridge.CarapaceBin([git])"] # NEW
Overlays are essentially Spec files placed in ${UserConfigDir}/carapace/overlays
that provide additional completions.
These are merged with the existing completion and provide a workaround for issues that have yet to be fixed in upstream.
Overlays implicitly set
CARAPACE_LENIENT
to allow unknown flags.
# ~/.config/carapace/overlays/doctl.yaml
name: doctl
persistentflags:
--output=: Desired output format [text|json]
completion:
flag:
output: [text, json]
commands:
- name: compute
description: Display commands that manage infrastructure
commands:
- name: region
description: Display commands to list datacenter regions
commands:
- name: list
description: List datacenter regions
flags:
--format=: Columns for output in a comma-separated list
completion:
flag:
format: ["$uniquelist(,)", Slug, Name, Available]
Using zip as archive for windows releases for winget compability.
Published by rsteube over 1 year ago
Specs now support a run
field enabling cross shell aliases and simple nested custom commands.
run
can either contain an alias ([command, arg1, arg2]
) which bridges completion or a shell macro ($(echo example)
) with custom completions / flag parsing.
name: runnable
description: runnable spec
commands:
- name: sub1
description: alias
run: "[git, log]"
- name: sub2
description: shell
run: "$(git show $1)"
completion:
positional:
- - "$(git branch --format '%(refname:short)\t%(subject)\tblue')"
- "$(git tag --format '%(refname:short)\t\tyellow')"
- name: sub3
description: shell with flags
run: "$(git log --author \"${C_FLAG_AUTHOR}\" $1)"
flags:
-a, --author=: limit to author
completion:
flag:
author: ["$(git shortlog --summary --email HEAD | sed -e 's/^.*\t//' -e 's/ </\t</')"]
positional:
- - "$(git branch --format '%(refname:short)\t%(subject)\tblue')"
- "$(git tag --format '%(refname:short)\t\tyellow')"
carapace _carapace
now prepends ${UserConfigDir}/carapace/bin
to PATH
unless it already exists.
In
nushell
this needs to be done manually (see output ofcarapace _carapace nushell
):let-env PATH = ($env.PATH | prepend "/home/rsteube/.config/carapace/bin")
It also creates Shims in ${UserConfigDir}/carapace/bin
to execute the specs.
For unix systems this is a simple shell script, but for windows an embedded binary is used.
#!/bin/sh
carapace --run "/home/rsteube/.config/carapace/specs/runnable.yaml" "$@"
The
${UserConfigDir}/carapace/bin
directory is fully managed by carapace and unrelated files within it are removed.
Initial support for flags consuming multiple arguments as seen in argparse and various nix
commands.
XDG base directories for XDG_CACHE_HOME
and XDG_CONFIG_HOME
are now supported.
Published by rsteube over 1 year ago
Replaced command traversal with a full rewrite.
This provides more fine-grained control and improved logging.
It is a complex core component though and while tests are looking good so far some edge cases are likely to fail.
Improved logging output (export CARAPACE_LOG=1
):
// /tmp/carapace/carapace.log
2023/01/29 11:46:28.310133 elvish []string{"/home/rsteube/go/bin/carapace", "_carapace", "elvish", "git", "-C", "../carapace-bin/", "log", "--author", ""}
2023/01/29 11:46:28.310165 elvish traverse called for "git" with args []string{"-C", "../carapace-bin/", "log", "--author", ""}
2023/01/29 11:46:28.310167 elvish executing PreRun for "git" with args []string{"-C", "../carapace-bin/", "log", "--author", ""}
2023/01/29 11:46:28.310185 elvish arg "-C" is a flag
2023/01/29 11:46:28.310207 elvish arg "../carapace-bin/" is a flag argument
2023/01/29 11:46:28.310210 elvish arg "log" is a subcommand
2023/01/29 11:46:28.310211 elvish parsing flags for "git" with args []string{"-C", "../carapace-bin/"}
2023/01/29 11:46:28.310215 elvish traverse called for "log" with args []string{"--author", ""}
2023/01/29 11:46:28.310247 elvish arg "--author" is a flag
2023/01/29 11:46:28.310259 elvish removing arg "--author" since it is a flag missing its argument
2023/01/29 11:46:28.310260 elvish parsing flags for "log" with args []string{}
2023/01/29 11:46:28.310262 elvish completing flag argument of "author" for arg ""
Added bridge for yargs:
name: ng
description: CLI tool for Angular
completion:
positionalany: ["$_bridge.Yargs(ng)"]
Published by rsteube over 1 year ago
Published by rsteube almost 2 years ago
Published by rsteube almost 2 years ago
Published by rsteube almost 2 years ago
Contains breaking changes on the export format.
Since there is no backward compability any embedded external carapace based completion must be >= v0.31.0
.
When environment variable CARAPACE_LENIENT
is set (e.g. export CARAPACE_LENIENT=1
) unknown flags are ignored.
Completers are supposed to be aware of all existing flags but can out of date or not yet working correctly.
This can be used to suppress the errors until issues are fixed.
Published by rsteube almost 2 years ago
Published by rsteube almost 2 years ago
Multiple error message are now supported.
In elvish
and zsh
these are shown separate from the completion values.
Added Usage message which defaults to flag description / command usage.
This is only supported in elvish
and zsh
.
Since notifications are persistent in elvish
it is only shown when there are no values to complete.
Completion values can now be tagged. Based on this they are grouped in zsh
.
Subcommands can now be grouped and will be highlighted in different colors.
Group names can be shown in zsh
with the following zstyle
.
zstyle ':completion:*' format $'\e[2;37mCompleting %d\e[m'
Order of the groups can be configured in zsh
with the following zstyle
.
zstyle ':completion:*:git:*' group-order 'main commands' 'alias commands' 'external commands'
_describe
is now used in zsh
which enables the grouping of tags.
With this aliased commands and flags are now also arranged side by side.
Published by rsteube almost 2 years ago
edit -json
Published by rsteube almost 2 years ago
Specs can now be generated from clap based commands with carapace-spec-clap.
For advanced completion these can further be converted to Go code with carapace --scrape [spec]
.
A JSON Schema is now written to ${UserConfigDir}/carapace/schema.json
.
It can be used by adding the following header to a user spec:
# yaml-language-server: $schema=../schema.json
$(shell command)
is now executed in Powershell on windows.
Published by rsteube about 2 years ago
carapace --list=json
Published by rsteube about 2 years ago
Specs are now first-class citizens in carapace. They are integrated on root level and should behave similar to the existing completers (carapace [spec.name] <TAB>
).
Completers based on Specs are highlighted in shells that support colors (details: carapace --list=json
):
Using Specs for bridging is from now on the recommended approach.
As these are auto-loaded with carapace _carapace
and provide support for embedded completion like sudo [spec.name] <TAB>
.
Existing completers with the same name will also be overridden.
E.g. kubectl
(which is currently a bit outdated) can be configured to use the official completer:
# ${UserConfigDir}/carapace/specs/kubectl.yaml
name: kubectl
description: kubectl controls the Kubernetes cluster manager
completion:
positionalany: ["$_bridge.Cobra(kubectl)"]
Note that bridging adds a slight overhead (~7-9ms?) for each invocation and is limited to supported frameworks / commands.
Taking this one step further plugin completion like cargo-[plugin]
, gh-[plugin]
, git-[plugin]
can now also be defined by Specs.
E.g. the gh-repo-collab extension for github-cli:
# ${UserConfigDir}/carapace/specs/gh-repo-collab.yaml
name: gh-repo-collab
description: manage repository collaborators
commands:
-
name: list
completion:
positional:
- ["$_tools.gh.OwnerRepositories"]
-
name: add
flags:
--permission=: set permission
completion:
flag:
permission: ["pull", "triage", "push", "maintain", "admin\t\tred"]
positional:
- ["$_tools.gh.OwnerRepositories"]
- ["$_tools.gh.Users"]
-
name: remove
completion:
positional:
- ["$_tools.gh.OwnerRepositories"]
- ["$_tools.gh.Users"]
With https://github.com/nushell/nushell/pull/6652 (upcoming v0.70.0) the nushell integration is now working on positional arguments.
The recommended configuration is equivalent to the example configuration in config.nu
:
let carapace_completer = {|spans|
carapace $spans.0 nushell $spans | from json
}
let-env config = {
external_completer: $carapace_completer
}
Be sure to remove the
module completions
example so that it won't override the carapace completion
synching channel updates