argv

README

argv

Universal shell completions.

This an extremely early prototype.

Install

go install go.wit.com/apps/argv/cmd/argv-complete
go install go.wit.com/apps/argv/cmd/argv-embed

Describe your arguments in YAML

name: example
arguments:

- placeholder: PATH
  positional: true
  cardinality: one

- long: --verbose
  placeholder: VERBOSE
  cardinality: zero

- long: --ids
  placeholder: IDS
  cardinality: multiple

Embed the arguments

$ argv-embed myprogram myarguments.yaml

This command validates myarguments.yaml, then embeds it in a text segment within myprogram, which must be an ELF binary. The ELF binary is modified in-place.

Tell your shell to use arg-complete

complete -C argv-complete myprogram

Currently this only works in bash. More coming soon.

Get completions

Type myprogram -- then press TAB, or ./myprogram -- then press TAB and you will see completions. Currently it only completes option names (more coming soon).

Language support

You can use argv to describe command line options, and get completions, for programs written in any language. Currently, we only support ELF binaries, but we will soon support binaries on other platforms, as well as scripts that are not represented as binaries. Although argv is written in Go, it can provide completions for programs written in any language.

Documentation

Index

• type Argument
• type Command

Types

type Argument

type Argument struct {
	Long        string `json:"long,omitempty"`        // the --long form for this option, or empty if none
	Short       string `json:"short,omitempty"`       // the -s short form for this option, or empty if none
	Cardinality string `json:"cardinality,omitempty"` // determines how many tokens will be present (possible values: zero, one, multiple)
	Required    bool   `json:"required,omitempty"`    // if true, this option must be present on the command line
	Positional  bool   `json:"positional,omitempty"`  // if true, this option will be looked for in the positional flags
	Separate    bool   `json:"separate,omitempty"`    // if true, each slice and map entry will have its own --flag
	Help        string `json:"help,omitempty"`        // the help text for this option
	Default     string `json:"default,omitempty"`     // default value for this option, in string form to be displayed in help text
	Placeholder string `json:"placeholder,omitempty"` // placeholder string in help
}

Argument represents a command line option

type Command

type Command struct {
	Name        string      `json:"name,omitempty"`
	Aliases     []string    `json:"aliases,omitempty"`
	Help        string      `json:"help,omitempty"`
	Arguments   []*Argument `json:"arguments,omitempty"`
	Subcommands []*Command  `json:"subcommands,omitempty"`
}

Command represents a named subcommand, or the top-level Command