spec

package module

v1.6.1 Latest Latest Go to latest Published: Jun 6, 2026 License: MIT Imports: 32 Imported by: 14

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/carapace-sh/carapace-spec

Links

Open Source Insights

README ¶

carapace-spec

Define simple completions using a spec file (based on carapace).

The carapace-spec binary can be used to complete spec files, but carapace-bin is recommended as it supports a range of custom macros.

name: mycmd
description: my command
flags:
  --optarg?: optarg flag
  -r, --repeatable*: repeatable flag
  -v=: flag with value
persistentflags:
  --help: bool flag
completion:
  flag:
    optarg: ["one", "two\twith description", "three\twith style\tblue"]
    v: ["$files"]
commands:
- name: sub
  description: subcommand
  completion:
    positional:
      - ["$list(,)", "1", "2", "3"]
      - ["$directories"]

Generators

carapace-spec-clap spec generation for clap-rs/clap
carapace-spec-kingpin spec generation for alecthomas/kingpin
carapace-spec-kong spec generation for alecthomas/kong
carapace-spec-man spec generation for manpages
carapace-spec-urfavecli spec generation for urfave/cli
carapace-spec-oclif spec generation for oclif

Documentation ¶

Index ¶

func ActionMacro(s string, a ...any) carapace.Action
func ActionSpec(path string) carapace.Action
func AddMacro(s string, m Macro, opts ...string)
func AddMacroI[T any](f func(t T) carapace.Action, opts ...string)
func AddMacroV[T any](f func(t ...T) carapace.Action, opts ...string)
func Codegen(cmd *cobra.Command) error
func NewAction(s []string) action
func Register(cmd *cobra.Command)
func Schema() string
type Command
type Macro
- func (m Macro) Parse(s string) carapace.Action
- func (m Macro) Signature() string
type MacroMap
- func ScanMacros(pkgs ...string) (MacroMap, error)
- func (m MacroMap) Format(pkg string) (string, error)

Constants ¶

This section is empty.

Variables ¶

This section is empty.

Functions ¶

func AddMacro ¶

func AddMacro(s string, m Macro, opts ...string)

AddMacro adds a custom macro with explicit name

func AddMacroI ¶ added in v1.6.1

func AddMacroI[T any](f func(t T) carapace.Action, opts ...string)

AddMacroI adds a custom macro inferring the name from the function. Strips the ".../actions/" path prefix and "Action" function prefix. First string arg is description, any further strings are joined with "\n" as example.

func AddMacroV ¶ added in v1.6.1

func AddMacroV[T any](f func(t ...T) carapace.Action, opts ...string)

AddMacroV adds a custom macro inferring the name from the function. Strips the ".../actions/" path prefix and "Action" function prefix. First string arg is description, any further strings are joined with "\n" as example.

func Codegen ¶

func Codegen(cmd *cobra.Command) error

func NewAction ¶

func NewAction(s []string) action

func Register ¶

func Register(cmd *cobra.Command)

func Schema ¶

func Schema() string

Types ¶

type Command ¶

type Command command.Command

func (Command) Codegen ¶

func (c Command) Codegen() error

func (Command) ToCobra ¶

func (c Command) ToCobra() *cobra.Command

func (Command) ToCobraE ¶

func (c Command) ToCobraE() (*cobra.Command, error)

type Macro ¶

type Macro struct {
	Name        string                       `json:"name"`
	Description string                       `json:"description,omitempty"`
	Example     string                       `json:"example,omitempty"`
	Function    string                       `json:"function,omitempty"`
	Args        string                       `json:"args,omitempty"` // TODO shouldn't be necessary
	Macro       macro.Macro[carapace.Action] `json:"-"`              // TODO public?
}

TODO lots of overlapping `macro` terms. Macro[I|V|N] don't match the embedded generic `macro.Macro` well.

func MacroI ¶

func MacroI[T any](f func(t T) carapace.Action) Macro

func MacroN ¶

func MacroN(f func() carapace.Action) Macro

func MacroV ¶

func MacroV[T any](f func(t ...T) carapace.Action) Macro

func (Macro) Parse ¶

func (m Macro) Parse(s string) carapace.Action

func (Macro) Signature ¶

func (m Macro) Signature() string

type MacroMap ¶ added in v1.5.0

type MacroMap macro.MacroMap[Macro]

func ScanMacros ¶ added in v1.5.0

func ScanMacros(pkgs ...string) (MacroMap, error)

TODO experimental - internal use

func (MacroMap) Format ¶ added in v1.5.0

func (m MacroMap) Format(pkg string) (string, error)