Core

Core macros provided by carapace-spec.

directories

$directories completes directories.

["$directories"]

exec

$(<command>) executes given command in a sh / pwsh shell.

["$(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-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:

C_ARG0=arg1                                                                                                                              
C_ARG1=arg2                                                                                                                              
C_FLAG_BOOL=true                                                                                                                         
C_FLAG_STRING=one                                                                                                                        
C_VALUE=C_

Every variable listed in Variables which has a value will be included in the executed command's environment

executables

$executables completes executables either from PATH or given directories.

["$executables", "$executables([~/.local/bin])"]

files

$files([<suffixes>]) completes files with an optional list of suffixes to filter on.

["$files([.go, go.mod, go.sum])"]

message

$message(<message>) adds given error message to completion.

["$message(some error)"]

spec

$spec(<file>) completes arguments using the given spec file. This implicitly disables flag parsing for the corresponding (sub)command.

["$spec(example.yaml)"]