Move completion package into cli

tools/cli/completion/bash.go

@@ -0,0 +1,57 @@
+// License: GPLv3 Copyright: 2022, Kovid Goyal, <kovid at kovidgoyal.net>
+
+package completion
+
+import (
+	"fmt"
+	"strings"
+
+	"kitty/tools/utils"
+)
+
+var _ = fmt.Print
+
+func bash_output_serializer(completions []*Completions, shell_state map[string]string) ([]byte, error) {
+	output := strings.Builder{}
+	f := func(format string, args ...any) { fmt.Fprintf(&output, format+"\n", args...) }
+	n := completions[0].Delegate.NumToRemove
+	if n > 0 {
+		f("compopt +o nospace")
+		f("COMP_WORDS[%d]=%s", n, utils.QuoteStringForSH(completions[0].Delegate.Command))
+		f("_command_offset %d", n)
+	} else {
+		for _, mg := range completions[0].Groups {
+			mg.remove_common_prefix()
+			if mg.NoTrailingSpace {
+				f("compopt -o nospace")
+			} else {
+				f("compopt +o nospace")
+			}
+			if mg.IsFiles {
+				f("compopt -o filenames")
+				for _, m := range mg.Matches {
+					if strings.HasSuffix(m.Word, utils.Sep) {
+						m.Word = m.Word[:len(m.Word)-1]
+					}
+				}
+			} else {
+				f("compopt +o filenames")
+			}
+			for _, m := range mg.Matches {
+				f("COMPREPLY+=(%s)", utils.QuoteStringForSH(m.Word))
+			}
+		}
+	}
+	// debugf("%#v", output.String())
+	return []byte(output.String()), nil
+}
+
+func bash_init_completions(completions *Completions) {
+	completions.split_on_equals = true
+}
+
+func init() {
+	input_parsers["bash"] = shell_input_parser
+	output_serializers["bash"] = bash_output_serializer
+	init_completions["bash"] = bash_init_completions
+}

tools/cli/completion/files.go

@@ -0,0 +1,280 @@
+// License: GPLv3 Copyright: 2022, Kovid Goyal, <kovid at kovidgoyal.net>
+
+package completion
+
+import (
+	"fmt"
+	"mime"
+	"os"
+	"path/filepath"
+	"strings"
+
+	"golang.org/x/sys/unix"
+
+	"kitty/tools/utils"
+)
+
+var _ = fmt.Print
+
+func absolutize_path(path string) string {
+	path = utils.Expanduser(path)
+	q, err := filepath.Abs(path)
+	if err == nil {
+		path = q
+	}
+	return path
+}
+
+type FileEntry struct {
+	name, completion_candidate, abspath string
+	mode                                os.FileMode
+	is_dir, is_symlink, is_empty_dir    bool
+}
+
+func complete_files(prefix string, callback func(*FileEntry), cwd string) error {
+	if cwd == "" {
+		var err error
+		cwd, err = os.Getwd()
+		if err != nil {
+			return err
+		}
+	}
+	location := absolutize_path(prefix)
+	base_dir := ""
+	joinable_prefix := ""
+	switch prefix {
+	case ".":
+		base_dir = "."
+		joinable_prefix = ""
+	case "./":
+		base_dir = "."
+		joinable_prefix = "./"
+	case "/":
+		base_dir = "/"
+		joinable_prefix = "/"
+	case "~":
+		base_dir = location
+		joinable_prefix = "~/"
+	case "":
+		base_dir = cwd
+		joinable_prefix = ""
+	default:
+		if strings.HasSuffix(prefix, utils.Sep) {
+			base_dir = location
+			joinable_prefix = prefix
+		} else {
+			idx := strings.LastIndex(prefix, utils.Sep)
+			if idx > 0 {
+				joinable_prefix = prefix[:idx+1]
+				base_dir = filepath.Dir(location)
+			}
+		}
+	}
+	if base_dir == "" {
+		base_dir = cwd
+	}
+	if !strings.HasPrefix(base_dir, "~") && !filepath.IsAbs(base_dir) {
+		base_dir = filepath.Join(cwd, base_dir)
+	}
+	// fmt.Printf("prefix=%#v base_dir=%#v joinable_prefix=%#v\n", prefix, base_dir, joinable_prefix)
+	entries, err := os.ReadDir(base_dir)
+	if err != nil {
+		return err
+	}
+
+	for _, entry := range entries {
+		q := joinable_prefix + entry.Name()
+		if !strings.HasPrefix(q, prefix) {
+			continue
+		}
+		abspath := filepath.Join(base_dir, entry.Name())
+		dir_to_check := ""
+		data := FileEntry{
+			name: entry.Name(), abspath: abspath, mode: entry.Type(), is_dir: entry.IsDir(),
+			is_symlink: entry.Type()&os.ModeSymlink == os.ModeSymlink, completion_candidate: q}
+		if data.is_symlink {
+			target, err := filepath.EvalSymlinks(abspath)
+			if err == nil && target != base_dir {
+				td, err := os.Stat(target)
+				if err == nil && td.IsDir() {
+					dir_to_check = target
+					data.is_dir = true
+				}
+			}
+		}
+		if dir_to_check != "" {
+			subentries, err := os.ReadDir(dir_to_check)
+			data.is_empty_dir = err != nil || len(subentries) == 0
+		}
+		if data.is_dir {
+			data.completion_candidate += utils.Sep
+		}
+		callback(&data)
+	}
+	return nil
+}
+
+func complete_executables_in_path(prefix string, paths ...string) []string {
+	ans := make([]string, 0, 1024)
+	if len(paths) == 0 {
+		paths = filepath.SplitList(os.Getenv("PATH"))
+	}
+	for _, dir := range paths {
+		entries, err := os.ReadDir(dir)
+		if err == nil {
+			for _, e := range entries {
+				if strings.HasPrefix(e.Name(), prefix) && !e.IsDir() && unix.Access(filepath.Join(dir, e.Name()), unix.X_OK) == nil {
+					ans = append(ans, e.Name())
+				}
+			}
+		}
+	}
+	return ans
+}
+
+func is_dir_or_symlink_to_dir(entry os.DirEntry, path string) bool {
+	if entry.IsDir() {
+		return true
+	}
+	if entry.Type()&os.ModeSymlink == os.ModeSymlink {
+		p, err := filepath.EvalSymlinks(path)
+		if err == nil {
+			s, err := os.Stat(p)
+			if err == nil && s.IsDir() {
+				return true
+			}
+		}
+	}
+	return false
+}
+
+func fname_based_completer(prefix, cwd string, is_match func(string) bool) []string {
+	ans := make([]string, 0, 1024)
+	complete_files(prefix, func(entry *FileEntry) {
+		if entry.is_dir && !entry.is_empty_dir {
+			entries, err := os.ReadDir(entry.abspath)
+			if err == nil {
+				for _, e := range entries {
+					if is_match(e.Name()) || is_dir_or_symlink_to_dir(e, filepath.Join(entry.abspath, e.Name())) {
+						ans = append(ans, entry.completion_candidate)
+						return
+					}
+				}
+			}
+			return
+		}
+		q := strings.ToLower(entry.name)
+		if is_match(q) {
+			ans = append(ans, entry.completion_candidate)
+		}
+	}, cwd)
+	return ans
+
+}
+
+func complete_by_fnmatch(prefix, cwd string, patterns []string) []string {
+	return fname_based_completer(prefix, cwd, func(name string) bool {
+		for _, pat := range patterns {
+			matched, err := filepath.Match(pat, name)
+			if err == nil && matched {
+				return true
+			}
+		}
+		return false
+	})
+}
+
+func complete_by_mimepat(prefix, cwd string, patterns []string) []string {
+	all_allowed := false
+	for _, p := range patterns {
+		if p == "*" {
+			all_allowed = true
+			break
+		}
+	}
+	return fname_based_completer(prefix, cwd, func(name string) bool {
+		if all_allowed {
+			return true
+		}
+		idx := strings.Index(name, ".")
+		if idx < 1 {
+			return false
+		}
+		ext := name[idx:]
+		mt := mime.TypeByExtension(ext)
+		if mt == "" {
+			ext = filepath.Ext(name)
+			mt = mime.TypeByExtension(ext)
+		}
+		if mt == "" {
+			return false
+		}
+		for _, pat := range patterns {
+			matched, err := filepath.Match(pat, mt)
+			if err == nil && matched {
+				return true
+			}
+		}
+		return false
+	})
+}
+
+type relative_to int
+
+const (
+	CWD relative_to = iota
+	CONFIG
+)
+
+func get_cwd_for_completion(relative_to relative_to) string {
+	switch relative_to {
+	case CONFIG:
+		return utils.ConfigDir()
+	}
+	return ""
+}
+
+func make_completer(title string, relative_to relative_to, patterns []string, f func(string, string, []string) []string) CompletionFunc {
+	lpats := make([]string, 0, len(patterns))
+	for _, p := range patterns {
+		lpats = append(lpats, strings.ToLower(p))
+	}
+	cwd := get_cwd_for_completion(relative_to)
+
+	return func(completions *Completions, word string, arg_num int) {
+		q := f(word, cwd, lpats)
+		if len(q) > 0 {
+			mg := completions.add_match_group(title)
+			mg.IsFiles = true
+			for _, c := range q {
+				mg.add_match(c)
+			}
+		}
+	}
+}
+
+func fnmatch_completer(title string, relative_to relative_to, patterns ...string) CompletionFunc {
+	return make_completer(title, relative_to, patterns, complete_by_fnmatch)
+}
+
+func mimepat_completer(title string, relative_to relative_to, patterns ...string) CompletionFunc {
+	return make_completer(title, relative_to, patterns, complete_by_mimepat)
+}
+
+func directory_completer(title string, relative_to relative_to) CompletionFunc {
+	if title == "" {
+		title = "Directories"
+	}
+	cwd := get_cwd_for_completion(relative_to)
+
+	return func(completions *Completions, word string, arg_num int) {
+		mg := completions.add_match_group(title)
+		mg.NoTrailingSpace = true
+		mg.IsFiles = true
+		complete_files(word, func(entry *FileEntry) {
+			if entry.mode.IsDir() {
+				mg.add_match(entry.completion_candidate)
+			}
+		}, cwd)
+	}
+}

tools/cli/completion/files_test.go

@@ -0,0 +1,125 @@
+// License: GPLv3 Copyright: 2022, Kovid Goyal, <kovid at kovidgoyal.net>
+
+package completion
+
+import (
+	"fmt"
+	"kitty/tools/utils"
+	"os"
+	"path/filepath"
+	"reflect"
+	"sort"
+	"strings"
+	"testing"
+)
+
+var _ = fmt.Print
+
+func TestCompleteFiles(t *testing.T) {
+	tdir := t.TempDir()
+	cwd, _ := os.Getwd()
+	if cwd != "" {
+		defer os.Chdir(cwd)
+	}
+	os.Chdir(tdir)
+
+	create := func(parts ...string) {
+		f, _ := os.Create(filepath.Join(tdir, filepath.Join(parts...)))
+		f.Close()
+	}
+	create("one.txt")
+	create("two.txt")
+	os.Mkdir(filepath.Join(tdir, "odir"), 0700)
+	create("odir", "three.txt")
+	create("odir", "four.txt")
+
+	test_candidates := func(prefix string, expected ...string) {
+		if expected == nil {
+			expected = make([]string, 0)
+		}
+		sort.Strings(expected)
+		actual := make([]string, 0, len(expected))
+		complete_files(prefix, func(entry *FileEntry) {
+			actual = append(actual, entry.completion_candidate)
+			if _, err := os.Stat(entry.abspath); err != nil {
+				t.Fatalf("Abspath does not exist: %#v", entry.abspath)
+			}
+		}, "")
+		sort.Strings(actual)
+		if !reflect.DeepEqual(expected, actual) {
+			t.Fatalf("Did not get expected completion candidates for prefix: %#v\nExpected: %#v\nActual:   %#v", prefix, expected, actual)
+		}
+	}
+
+	test_abs_candidates := func(prefix string, expected ...string) {
+		e := make([]string, len(expected))
+		for i, x := range expected {
+			if filepath.IsAbs(x) {
+				e[i] = x
+			} else {
+				e[i] = filepath.Join(tdir, x)
+				if strings.HasSuffix(x, utils.Sep) {
+					e[i] += utils.Sep
+				}
+			}
+		}
+		test_candidates(prefix, e...)
+	}
+
+	test_cwd_prefix := func(prefix string, expected ...string) {
+		e := make([]string, len(expected))
+		for i, x := range expected {
+			e[i] = "./" + x
+		}
+		test_candidates("./"+prefix, e...)
+	}
+
+	test_cwd_prefix("", "one.txt", "two.txt", "odir/")
+	test_cwd_prefix("t", "two.txt")
+	test_cwd_prefix("x")
+
+	test_abs_candidates(tdir+utils.Sep, "one.txt", "two.txt", "odir/")
+	test_abs_candidates(filepath.Join(tdir, "o"), "one.txt", "odir/")
+
+	test_candidates("", "one.txt", "two.txt", "odir/")
+	test_candidates("t", "two.txt")
+	test_candidates("o", "one.txt", "odir/")
+	test_candidates("odir", "odir/")
+	test_candidates("odir/", "odir/three.txt", "odir/four.txt")
+	test_candidates("odir/f", "odir/four.txt")
+	test_candidates("x")
+
+}
+
+func TestCompleteExecutables(t *testing.T) {
+	tdir := t.TempDir()
+	create := func(base string, name string, mode os.FileMode) {
+		f, _ := os.OpenFile(filepath.Join(tdir, base, name), os.O_CREATE, mode)
+		f.Close()
+	}
+	os.Mkdir(filepath.Join(tdir, "one"), 0700)
+	os.Mkdir(filepath.Join(tdir, "two"), 0700)
+
+	create("", "not-in-path", 0700)
+	create("one", "one-exec", 0700)
+	create("one", "one-not-exec", 0600)
+	create("two", "two-exec", 0700)
+	os.Symlink(filepath.Join(tdir, "two", "two-exec"), filepath.Join(tdir, "one", "s"))
+	os.Symlink(filepath.Join(tdir, "one", "one-not-exec"), filepath.Join(tdir, "one", "n"))
+
+	t.Setenv("PATH", strings.Join([]string{filepath.Join(tdir, "one"), filepath.Join(tdir, "two")}, string(os.PathListSeparator)))
+	test_candidates := func(prefix string, expected ...string) {
+		if expected == nil {
+			expected = make([]string, 0)
+		}
+		actual := complete_executables_in_path(prefix)
+		sort.Strings(expected)
+		sort.Strings(actual)
+		if !reflect.DeepEqual(expected, actual) {
+			t.Fatalf("Did not get expected completion candidates for prefix: %#v\nExpected: %#v\nActual:   %#v", prefix, expected, actual)
+		}
+	}
+	test_candidates("", "one-exec", "two-exec", "s")
+	test_candidates("o", "one-exec")
+	test_candidates("x")
+}

tools/cli/completion/fish.go

@@ -0,0 +1,45 @@
+// License: GPLv3 Copyright: 2022, Kovid Goyal, <kovid at kovidgoyal.net>
+
+package completion
+
+import (
+	"fmt"
+	"strings"
+
+	"kitty/tools/cli/markup"
+	"kitty/tools/utils"
+)
+
+var _ = fmt.Print
+
+func fish_output_serializer(completions []*Completions, shell_state map[string]string) ([]byte, error) {
+	output := strings.Builder{}
+	f := func(format string, args ...any) { fmt.Fprintf(&output, format+"\n", args...) }
+	n := completions[0].Delegate.NumToRemove
+	fm := markup.New(false) // fish freaks out if there are escape codes in the description strings
+	if n > 0 {
+		words := make([]string, len(completions[0].all_words)-n+1)
+		words[0] = completions[0].Delegate.Command
+		copy(words[1:], completions[0].all_words[n:])
+		for i, w := range words {
+			words[i] = fmt.Sprintf("(string escape -- %s)", utils.QuoteStringForFish(w))
+		}
+		cmdline := strings.Join(words, " ")
+		f("set __ksi_cmdline " + cmdline)
+		f("complete -C \"$__ksi_cmdline\"")
+		f("set --erase __ksi_cmdline")
+	} else {
+		for _, mg := range completions[0].Groups {
+			for _, m := range mg.Matches {
+				f("echo -- %s", utils.QuoteStringForFish(m.Word+"\t"+fm.Prettify(m.Description)))
+			}
+		}
+	}
+	// debugf("%#v", output.String())
+	return []byte(output.String()), nil
+}
+
+func init() {
+	input_parsers["fish"] = shell_input_parser
+	output_serializers["fish"] = fish_output_serializer
+}

tools/cli/completion/kitty.go

@@ -0,0 +1,131 @@
+// License: GPLv3 Copyright: 2022, Kovid Goyal, <kovid at kovidgoyal.net>
+
+package completion
+
+import (
+	"bufio"
+	"bytes"
+	"fmt"
+	"kitty/tools/utils"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"strings"
+
+	"golang.org/x/sys/unix"
+)
+
+var _ = fmt.Print
+
+func complete_kitty(completions *Completions, word string, arg_num int) {
+	if arg_num > 1 {
+		completions.Delegate.NumToRemove = completions.current_cmd.index_of_first_arg + 1 // +1 because the first word is not present in all_words
+		completions.Delegate.Command = completions.all_words[completions.current_cmd.index_of_first_arg]
+		return
+	}
+	exes := complete_executables_in_path(word)
+	if len(exes) > 0 {
+		mg := completions.add_match_group("Executables in PATH")
+		for _, exe := range exes {
+			mg.add_match(exe)
+		}
+	}
+
+	if len(word) > 0 {
+		mg := completions.add_match_group("Executables")
+		mg.IsFiles = true
+
+		complete_files(word, func(entry *FileEntry) {
+			if entry.is_dir && !entry.is_empty_dir {
+				// only allow directories that have sub-dirs or executable files in them
+				entries, err := os.ReadDir(entry.abspath)
+				if err == nil {
+					for _, x := range entries {
+						if x.IsDir() || unix.Access(filepath.Join(entry.abspath, x.Name()), unix.X_OK) == nil {
+							mg.add_match(entry.completion_candidate)
+							break
+						}
+					}
+				}
+			} else if unix.Access(entry.abspath, unix.X_OK) == nil {
+				mg.add_match(entry.completion_candidate)
+			}
+		}, "")
+	}
+}
+
+func complete_kitty_override(title string, names []string) CompletionFunc {
+	return func(completions *Completions, word string, arg_num int) {
+		mg := completions.add_match_group(title)
+		mg.NoTrailingSpace = true
+		for _, q := range names {
+			if strings.HasPrefix(q, word) {
+				mg.add_match(q + "=")
+			}
+		}
+	}
+}
+
+func complete_kitty_listen_on(completions *Completions, word string, arg_num int) {
+	if !strings.Contains(word, ":") {
+		mg := completions.add_match_group("Address family")
+		mg.NoTrailingSpace = true
+		for _, q := range []string{"unix:", "tcp:"} {
+			if strings.HasPrefix(q, word) {
+				mg.add_match(q)
+			}
+		}
+	} else if strings.HasPrefix(word, "unix:") && !strings.HasPrefix(word, "unix:@") {
+		fnmatch_completer("UNIX sockets", CWD, "*")(completions, word[len("unix:"):], arg_num)
+		completions.add_prefix_to_all_matches("unix:")
+	}
+}
+
+func complete_plus_launch(completions *Completions, word string, arg_num int) {
+	if arg_num == 1 {
+		fnmatch_completer("Python scripts", CWD, "*.py")(completions, word, arg_num)
+		if strings.HasPrefix(word, ":") {
+			exes := complete_executables_in_path(word[1:])
+			mg := completions.add_match_group("Python scripts in PATH")
+			for _, exe := range exes {
+				mg.add_match(":" + exe)
+			}
+		}
+	} else {
+		fnmatch_completer("Files", CWD, "*")(completions, word, arg_num)
+	}
+}
+
+func complete_plus_runpy(completions *Completions, word string, arg_num int) {
+	if arg_num > 1 {
+		fnmatch_completer("Files", CWD, "*")(completions, word, arg_num)
+	}
+}
+
+func complete_plus_open(completions *Completions, word string, arg_num int) {
+	fnmatch_completer("Files", CWD, "*")(completions, word, arg_num)
+}
+
+func complete_themes(completions *Completions, word string, arg_num int) {
+	kitty, err := utils.KittyExe()
+	if err == nil {
+		out, err := exec.Command(kitty, "+runpy", "from kittens.themes.collection import *; print_theme_names()").Output()
+		if err == nil {
+			mg := completions.add_match_group("Themes")
+			scanner := bufio.NewScanner(bytes.NewReader(out))
+			for scanner.Scan() {
+				theme_name := strings.TrimSpace(scanner.Text())
+				if theme_name != "" && strings.HasPrefix(theme_name, word) {
+					mg.add_match(theme_name)
+				}
+			}
+		}
+	}
+}
+
+func completion_for_wrapper(wrapped_cmd string) func(*Command, []string, *Completions) {
+	return func(cmd *Command, args []string, completions *Completions) {
+		completions.Delegate.NumToRemove = completions.current_word_idx + 1
+		completions.Delegate.Command = wrapped_cmd
+	}
+}

tools/cli/completion/main.go

@@ -0,0 +1,93 @@
+// License: GPLv3 Copyright: 2022, Kovid Goyal, <kovid at kovidgoyal.net>
+
+package completion
+
+import (
+	"encoding/json"
+	"fmt"
+	"io"
+	"os"
+
+	"kitty/tools/tty"
+	"kitty/tools/utils"
+)
+
+func debug(args ...any) {
+	tty.DebugPrintln(args...)
+}
+
+func debugf(format string, args ...any) {
+	debug(fmt.Sprintf(format, args...))
+}
+
+func json_input_parser(data []byte, shell_state map[string]string) ([][]string, error) {
+	ans := make([][]string, 0, 32)
+	err := json.Unmarshal(data, &ans)
+	return ans, err
+}
+
+func json_output_serializer(completions []*Completions, shell_state map[string]string) ([]byte, error) {
+	return json.Marshal(completions)
+}
+
+type parser_func func(data []byte, shell_state map[string]string) ([][]string, error)
+type serializer_func func(completions []*Completions, shell_state map[string]string) ([]byte, error)
+
+var input_parsers = make(map[string]parser_func, 4)
+var output_serializers = make(map[string]serializer_func, 4)
+var init_completions = make(map[string]func(*Completions), 4)
+
+func init() {
+	input_parsers["json"] = json_input_parser
+	output_serializers["json"] = json_output_serializer
+}
+
+var registered_exes = make(map[string]func(root *Command))
+
+func Main(args []string) error {
+	output_type := "json"
+	if len(args) > 0 {
+		output_type = args[0]
+		args = args[1:]
+	}
+	n := len(args)
+	if n < 1 {
+		n = 1
+	}
+	shell_state := make(map[string]string, n)
+	for _, arg := range args {
+		k, v, found := utils.Cut(arg, "=")
+		if !found {
+			return fmt.Errorf("Invalid shell state specification: %s", arg)
+		}
+		shell_state[k] = v
+	}
+	input_parser := input_parsers[output_type]
+	output_serializer := output_serializers[output_type]
+	if input_parser == nil || output_serializer == nil {
+		return fmt.Errorf("Unknown output type: %s", output_type)
+	}
+	data, err := io.ReadAll(os.Stdin)
+	if err != nil {
+		return err
+	}
+	// debugf("%#v", string(data))
+	all_argv, err := input_parser(data, shell_state)
+	if err != nil {
+		return err
+	}
+	var root = Command{Options: make([]*Option, 0), Groups: make([]*CommandGroup, 0, 8)}
+	for _, re := range registered_exes {
+		re(&root)
+	}
+
+	all_completions := make([]*Completions, 0, 1)
+	for _, argv := range all_argv {
+		all_completions = append(all_completions, root.GetCompletions(argv, init_completions[output_type]))
+	}
+	output, err := output_serializer(all_completions, shell_state)
+	if err == nil {
+		_, err = os.Stdout.Write(output)
+	}
+	return err
+}

tools/cli/completion/parse-args.go

@@ -0,0 +1,207 @@
+// License: GPLv3 Copyright: 2022, Kovid Goyal, <kovid at kovidgoyal.net>
+
+package completion
+
+import (
+	"fmt"
+	"os"
+	"strings"
+)
+
+var _ = fmt.Print
+var _ = os.Getenv
+
+func (self *Completions) add_group(group *MatchGroup) {
+	if len(group.Matches) > 0 {
+		self.Groups = append(self.Groups, group)
+	}
+}
+
+func (self *Command) find_option(name_including_leading_dash string) *Option {
+	var q string
+	if strings.HasPrefix(name_including_leading_dash, "--") {
+		q = name_including_leading_dash[2:]
+	} else if strings.HasPrefix(name_including_leading_dash, "-") {
+		q = name_including_leading_dash[len(name_including_leading_dash)-1:]
+	} else {
+		q = name_including_leading_dash
+	}
+	for _, opt := range self.Options {
+		for _, alias := range opt.Aliases {
+			if alias == q {
+				return opt
+			}
+		}
+	}
+	return nil
+}
+
+func (self *Completions) add_options_group(options []*Option, word string) {
+	group := self.add_match_group("Options")
+	if strings.HasPrefix(word, "--") {
+		if word == "--" {
+			group.Matches = append(group.Matches, &Match{Word: "--", Description: "End of options"})
+		}
+		prefix := word[2:]
+		for _, opt := range options {
+			for _, q := range opt.Aliases {
+				if len(q) > 1 && strings.HasPrefix(q, prefix) {
+					group.Matches = append(group.Matches, &Match{Word: "--" + q, Description: opt.Description})
+					break
+				}
+			}
+		}
+	} else {
+		if word == "-" {
+			group.Matches = append(group.Matches, &Match{Word: "--", Description: "End of options"})
+			for _, opt := range options {
+				has_single_letter_alias := false
+				for _, q := range opt.Aliases {
+					if len(q) == 1 {
+						group.add_match("-"+q, opt.Description)
+						has_single_letter_alias = true
+						break
+					}
+				}
+				if !has_single_letter_alias {
+					group.add_match("--"+opt.Aliases[0], opt.Description)
+				}
+			}
+		} else {
+			runes := []rune(word)
+			last_letter := string(runes[len(runes)-1])
+			for _, opt := range options {
+				for _, q := range opt.Aliases {
+					if q == last_letter {
+						group.add_match(word, opt.Description)
+						return
+					}
+				}
+			}
+		}
+	}
+}
+
+func complete_word(word string, completions *Completions, only_args_allowed bool, expecting_arg_for *Option, arg_num int) {
+	cmd := completions.current_cmd
+	if expecting_arg_for != nil {
+		if expecting_arg_for.Completion_for_arg != nil {
+			expecting_arg_for.Completion_for_arg(completions, word, arg_num)
+		}
+		return
+	}
+	if !only_args_allowed && strings.HasPrefix(word, "-") {
+		if strings.HasPrefix(word, "--") && strings.Contains(word, "=") {
+			idx := strings.Index(word, "=")
+			option := cmd.find_option(word[:idx])
+			if option != nil {
+				if option.Completion_for_arg != nil {
+					option.Completion_for_arg(completions, word[idx+1:], arg_num)
+					completions.add_prefix_to_all_matches(word[:idx+1])
+				}
+			}
+		} else {
+			completions.add_options_group(cmd.Options, word)
+		}
+		return
+	}
+	if cmd.has_subcommands() && cmd.sub_command_allowed_at(completions, arg_num) {
+		for _, cg := range cmd.Groups {
+			group := completions.add_match_group(cg.Title)
+			if group.Title == "" {
+				group.Title = "Sub-commands"
+			}
+			for _, sc := range cg.Commands {
+				if strings.HasPrefix(sc.Name, word) {
+					group.add_match(sc.Name, sc.Description)
+				}
+			}
+		}
+		if cmd.First_arg_may_not_be_subcommand && cmd.Completion_for_arg != nil {
+			cmd.Completion_for_arg(completions, word, arg_num)
+		}
+		return
+	}
+
+	if cmd.Completion_for_arg != nil {
+		cmd.Completion_for_arg(completions, word, arg_num)
+	}
+	return
+}
+
+func default_parse_args(cmd *Command, words []string, completions *Completions) {
+	completions.current_cmd = cmd
+	if len(words) == 0 {
+		complete_word("", completions, false, nil, 0)
+		return
+	}
+	completions.all_words = words
+
+	var expecting_arg_for *Option
+	only_args_allowed := false
+	arg_num := 0
+
+	for i, word := range words {
+		cmd = completions.current_cmd
+		completions.current_word_idx = i
+		completions.current_word_idx_in_parent++
+		is_last_word := i == len(words)-1
+		is_option_equal := completions.split_on_equals && word == "=" && expecting_arg_for != nil
+		if only_args_allowed || (expecting_arg_for == nil && !strings.HasPrefix(word, "-")) {
+			if !is_option_equal {
+				arg_num++
+			}
+			if arg_num == 1 {
+				cmd.index_of_first_arg = completions.current_word_idx
+			}
+		}
+		if is_last_word {
+			if is_option_equal {
+				word = ""
+			}
+			complete_word(word, completions, only_args_allowed, expecting_arg_for, arg_num)
+		} else {
+			if expecting_arg_for != nil {
+				if is_option_equal {
+					continue
+				}
+				expecting_arg_for = nil
+				continue
+			}
+			if word == "--" {
+				only_args_allowed = true
+				continue
+			}
+			if !only_args_allowed && strings.HasPrefix(word, "-") {
+				if !strings.Contains(word, "=") {
+					option := cmd.find_option(word)
+					if option != nil && option.Has_following_arg {
+						expecting_arg_for = option
+					}
+				}
+				continue
+			}
+			if cmd.has_subcommands() && cmd.sub_command_allowed_at(completions, arg_num) {
+				sc := cmd.find_subcommand_with_name(word)
+				if sc == nil {
+					only_args_allowed = true
+					continue
+				}
+				completions.current_cmd = sc
+				cmd = sc
+				arg_num = 0
+				completions.current_word_idx_in_parent = 0
+				only_args_allowed = false
+				if cmd.Parse_args != nil {
+					cmd.Parse_args(cmd, words[i+1:], completions)
+					return
+				}
+			} else if cmd.Stop_processing_at_arg > 0 && arg_num >= cmd.Stop_processing_at_arg {
+				return
+			} else {
+				only_args_allowed = true
+				continue
+			}
+		}
+	}
+}

tools/cli/completion/types.go

@@ -0,0 +1,277 @@
+// License: GPLv3 Copyright: 2022, Kovid Goyal, <kovid at kovidgoyal.net>
+
+package completion
+
+import (
+	"kitty/tools/utils"
+	"kitty/tools/wcswidth"
+	"path/filepath"
+	"strings"
+)
+
+type Match struct {
+	Word        string `json:"word,omitempty"`
+	Description string `json:"description,omitempty"`
+}
+
+type MatchGroup struct {
+	Title           string   `json:"title,omitempty"`
+	NoTrailingSpace bool     `json:"no_trailing_space,omitempty"`
+	IsFiles         bool     `json:"is_files,omitempty"`
+	Matches         []*Match `json:"matches,omitempty"`
+}
+
+func (self *MatchGroup) remove_common_prefix() string {
+	if self.IsFiles {
+		if len(self.Matches) > 1 {
+			lcp := self.longest_common_prefix()
+			if strings.Contains(lcp, utils.Sep) {
+				lcp = strings.TrimRight(filepath.Dir(lcp), utils.Sep) + utils.Sep
+				self.remove_prefix_from_all_matches(lcp)
+				return lcp
+			}
+		}
+	} else if len(self.Matches) > 1 && strings.HasPrefix(self.Matches[0].Word, "--") && strings.Contains(self.Matches[0].Word, "=") {
+		lcp, _, _ := utils.Cut(self.longest_common_prefix(), "=")
+		lcp += "="
+		if len(lcp) > 3 {
+			self.remove_prefix_from_all_matches(lcp)
+			return lcp
+		}
+	}
+	return ""
+}
+
+func (self *MatchGroup) add_match(word string, description ...string) *Match {
+	ans := Match{Word: word, Description: strings.Join(description, " ")}
+	self.Matches = append(self.Matches, &ans)
+	return &ans
+}
+
+func (self *MatchGroup) add_prefix_to_all_matches(prefix string) {
+	for _, m := range self.Matches {
+		m.Word = prefix + m.Word
+	}
+}
+
+func (self *MatchGroup) remove_prefix_from_all_matches(prefix string) {
+	for _, m := range self.Matches {
+		m.Word = m.Word[len(prefix):]
+	}
+}
+
+func (self *MatchGroup) has_descriptions() bool {
+	for _, m := range self.Matches {
+		if m.Description != "" {
+			return true
+		}
+	}
+	return false
+}
+
+func (self *MatchGroup) max_visual_word_length(limit int) int {
+	ans := 0
+	for _, m := range self.Matches {
+		if q := wcswidth.Stringwidth(m.Word); q > ans {
+			ans = q
+			if ans > limit {
+				return limit
+			}
+		}
+	}
+	return ans
+}
+
+func (self *MatchGroup) longest_common_prefix() string {
+	limit := len(self.Matches)
+	i := 0
+	return utils.LongestCommon(func() (string, bool) {
+		if i < limit {
+			i++
+			return self.Matches[i-1].Word, false
+		}
+		return "", true
+	}, true)
+}
+
+type Delegate struct {
+	NumToRemove int    `json:"num_to_remove,omitempty"`
+	Command     string `json:"command,omitempty"`
+}
+
+type Completions struct {
+	Groups   []*MatchGroup `json:"groups,omitempty"`
+	Delegate Delegate      `json:"delegate,omitempty"`
+
+	current_cmd                *Command
+	all_words                  []string // all words passed to parse_args()
+	current_word_idx           int      // index of current word in all_words
+	current_word_idx_in_parent int      // index of current word in parents command line 1 for first word after parent
+
+	split_on_equals bool // true if the cmdline is split on = (BASH does this because readline does this)
+}
+
+func (self *Completions) add_prefix_to_all_matches(prefix string) {
+	for _, mg := range self.Groups {
+		mg.add_prefix_to_all_matches(prefix)
+	}
+}
+
+func (self *Completions) add_match_group(title string) *MatchGroup {
+	for _, q := range self.Groups {
+		if q.Title == title {
+			return q
+		}
+	}
+	ans := MatchGroup{Title: title, Matches: make([]*Match, 0, 8)}
+	self.Groups = append(self.Groups, &ans)
+	return &ans
+}
+
+type CompletionFunc func(completions *Completions, word string, arg_num int)
+
+type Option struct {
+	Name               string
+	Aliases            []string
+	Description        string
+	Has_following_arg  bool
+	Completion_for_arg CompletionFunc
+}
+
+type CommandGroup struct {
+	Title    string
+	Commands []*Command
+}
+
+type Command struct {
+	Name        string
+	Description string
+
+	Options []*Option
+	Groups  []*CommandGroup
+
+	Completion_for_arg              CompletionFunc
+	Stop_processing_at_arg          int
+	First_arg_may_not_be_subcommand bool
+	Subcommand_must_be_first        bool
+
+	Parse_args func(*Command, []string, *Completions)
+
+	// index in Completions.all_words of the first non-option argument to this command.
+	// A value of zero means no arg was found while parsing.
+	index_of_first_arg int
+}
+
+func (self *Command) clone_options_from(other *Command) {
+	for _, opt := range other.Options {
+		self.Options = append(self.Options, opt)
+	}
+}
+
+func (self *Command) add_group(name string) *CommandGroup {
+	for _, g := range self.Groups {
+		if g.Title == name {
+			return g
+		}
+	}
+	g := CommandGroup{Title: name, Commands: make([]*Command, 0, 8)}
+	self.Groups = append(self.Groups, &g)
+	return &g
+}
+
+func (self *Command) add_command(name string, group_title string) *Command {
+	ans := Command{Name: name}
+	ans.Options = make([]*Option, 0, 8)
+	ans.Groups = make([]*CommandGroup, 0, 2)
+	g := self.add_group(group_title)
+	g.Commands = append(g.Commands, &ans)
+	return &ans
+}
+
+func (self *Command) add_clone(name string, group_title string, clone_of *Command) *Command {
+	ans := *clone_of
+	ans.Name = name
+	g := self.add_group(group_title)
+	g.Commands = append(g.Commands, &ans)
+	return &ans
+}
+
+func (self *Command) find_subcommand(is_ok func(cmd *Command) bool) *Command {
+	for _, g := range self.Groups {
+		for _, q := range g.Commands {
+			if is_ok(q) {
+				return q
+			}
+		}
+	}
+	return nil
+}
+
+func (self *Command) find_subcommand_with_name(name string) *Command {
+	return self.find_subcommand(func(cmd *Command) bool { return cmd.Name == name })
+}
+
+func (self *Command) has_subcommands() bool {
+	for _, g := range self.Groups {
+		if len(g.Commands) > 0 {
+			return true
+		}
+	}
+	return false
+}
+
+func (self *Command) sub_command_allowed_at(completions *Completions, arg_num int) bool {
+	if self.Subcommand_must_be_first {
+		return arg_num == 1 && completions.current_word_idx_in_parent == 1
+	}
+	return arg_num == 1
+}
+
+func (self *Command) add_option(opt *Option) {
+	self.Options = append(self.Options, opt)
+}
+
+func (self *Command) GetCompletions(argv []string, init_completions func(*Completions)) *Completions {
+	ans := Completions{Groups: make([]*MatchGroup, 0, 4)}
+	if init_completions != nil {
+		init_completions(&ans)
+	}
+	if len(argv) > 0 {
+		exe := argv[0]
+		cmd := self.find_subcommand_with_name(exe)
+		if cmd != nil {
+			if cmd.Parse_args != nil {
+				cmd.Parse_args(cmd, argv[1:], &ans)
+			} else {
+				default_parse_args(cmd, argv[1:], &ans)
+			}
+		}
+	}
+	non_empty_groups := make([]*MatchGroup, 0, len(ans.Groups))
+	for _, gr := range ans.Groups {
+		if len(gr.Matches) > 0 {
+			non_empty_groups = append(non_empty_groups, gr)
+		}
+	}
+	ans.Groups = non_empty_groups
+	return &ans
+}
+
+func names_completer(title string, names ...string) CompletionFunc {
+	return func(completions *Completions, word string, arg_num int) {
+		mg := completions.add_match_group(title)
+		for _, q := range names {
+			if strings.HasPrefix(q, word) {
+				mg.add_match(q)
+			}
+		}
+	}
+}
+
+func chain_completers(completers ...CompletionFunc) CompletionFunc {
+	return func(completions *Completions, word string, arg_num int) {
+		for _, f := range completers {
+			f(completions, word, arg_num)
+		}
+	}
+}

tools/cli/completion/zsh.go

@@ -0,0 +1,144 @@
+// License: GPLv3 Copyright: 2022, Kovid Goyal, <kovid at kovidgoyal.net>
+
+package completion
+
+import (
+	"bufio"
+	"fmt"
+	"kitty/tools/cli/markup"
+	"kitty/tools/tty"
+	"kitty/tools/utils"
+	"kitty/tools/wcswidth"
+	"strings"
+)
+
+var _ = fmt.Print
+
+func shell_input_parser(data []byte, shell_state map[string]string) ([][]string, error) {
+	raw := string(data)
+	new_word := strings.HasSuffix(raw, "\n\n")
+	raw = strings.TrimRight(raw, "\n \t")
+	scanner := bufio.NewScanner(strings.NewReader(raw))
+	words := make([]string, 0, 32)
+	for scanner.Scan() {
+		words = append(words, scanner.Text())
+	}
+	if new_word {
+		words = append(words, "")
+	}
+	return [][]string{words}, nil
+}
+
+func zsh_input_parser(data []byte, shell_state map[string]string) ([][]string, error) {
+	matcher := shell_state["_matcher"]
+	q := ""
+	if matcher != "" {
+		q = strings.Split(strings.ToLower(matcher), ":")[0][:1]
+	}
+	if q != "" && strings.Contains("lrbe", q) {
+		// this is zsh anchor based matching
+		// https://zsh.sourceforge.io/Doc/Release/Completion-Widgets.html#Completion-Matching-Control
+		// can be specified with matcher-list and some systems do it by default,
+		// for example, Debian, which adds the following to zshrc
+		// zstyle ':completion:*' matcher-list '' 'm:{a-z}={A-Z}' 'm:{a-zA-Z}={A-Za-z}' 'r:|[._-]=* r:|=* l:|=*'
+		// For some reason that I dont have the
+		// time/interest to figure out, returning completion candidates for
+		// these matcher types break completion, so just abort in this case.
+		return nil, fmt.Errorf("ZSH anchor based matching active, cannot complete")
+	}
+	return shell_input_parser(data, shell_state)
+}
+
+func fmt_desc(word, desc string, max_word_len int, f *markup.Context, screen_width int) string {
+	if desc == "" {
+		return word
+	}
+	line, _, _ := utils.Cut(strings.TrimSpace(desc), "\n")
+	desc = f.Prettify(line)
+
+	multiline := false
+	max_desc_len := screen_width - 2
+	word_len := wcswidth.Stringwidth(word)
+	if word_len > max_word_len {
+		multiline = true
+	} else {
+		word += strings.Repeat(" ", max_word_len-word_len)
+		max_desc_len = screen_width - max_word_len - 3
+	}
+	if wcswidth.Stringwidth(desc) > max_desc_len {
+		desc = wcswidth.TruncateToVisualLength(desc, max_desc_len-2) + "…"
+	}
+	if multiline {
+		return word + "\n  " + desc
+	}
+	return word + "  " + desc
+}
+
+func serialize(completions *Completions, f *markup.Context, screen_width int) ([]byte, error) {
+	output := strings.Builder{}
+	if completions.Delegate.NumToRemove > 0 {
+		for i := 0; i < completions.Delegate.NumToRemove; i++ {
+			fmt.Fprintln(&output, "shift words")
+			fmt.Fprintln(&output, "(( CURRENT-- ))")
+		}
+		service := utils.QuoteStringForSH(completions.Delegate.Command)
+		fmt.Fprintln(&output, "words[1]="+service)
+		fmt.Fprintln(&output, "_normal -p", service)
+	} else {
+		for _, mg := range completions.Groups {
+			cmd := strings.Builder{}
+			cmd.WriteString("compadd -U -J ")
+			cmd.WriteString(utils.QuoteStringForSH(mg.Title))
+			cmd.WriteString(" -X ")
+			cmd.WriteString(utils.QuoteStringForSH("%B" + mg.Title + "%b"))
+			if mg.NoTrailingSpace {
+				cmd.WriteString(" -S ''")
+			}
+			if mg.IsFiles {
+				cmd.WriteString(" -f")
+			}
+			lcp := mg.remove_common_prefix()
+			if lcp != "" {
+				cmd.WriteString(" -p ")
+				cmd.WriteString(utils.QuoteStringForSH(lcp))
+			}
+			if mg.has_descriptions() {
+				fmt.Fprintln(&output, "compdescriptions=(")
+				limit := mg.max_visual_word_length(16)
+				for _, m := range mg.Matches {
+					fmt.Fprintln(&output, utils.QuoteStringForSH(fmt_desc(m.Word, m.Description, limit, f, screen_width)))
+				}
+				fmt.Fprintln(&output, ")")
+				cmd.WriteString(" -l -d compdescriptions")
+			}
+			cmd.WriteString(" --")
+			for _, m := range mg.Matches {
+				cmd.WriteString(" ")
+				cmd.WriteString(utils.QuoteStringForSH(m.Word))
+			}
+			fmt.Fprintln(&output, cmd.String(), ";")
+		}
+	}
+	// debugf("%#v", output.String())
+	return []byte(output.String()), nil
+}
+
+func zsh_output_serializer(completions []*Completions, shell_state map[string]string) ([]byte, error) {
+	var f *markup.Context
+	screen_width := 80
+	ctty, err := tty.OpenControllingTerm()
+	if err == nil {
+		sz, err := ctty.GetSize()
+		ctty.Close()
+		if err == nil {
+			screen_width = int(sz.Col)
+		}
+	}
+	f = markup.New(false) // ZSH freaks out if there are escape codes in the description strings
+	return serialize(completions[0], f, screen_width)
+}
+
+func init() {
+	input_parsers["zsh"] = zsh_input_parser
+	output_serializers["zsh"] = zsh_output_serializer
+}

tools/cli/option-from-string.go

@@ -99,12 +99,15 @@ type multi_scan struct {
 
 var mpat *regexp.Regexp
 
+func (self *Option) init_option() {
+	self.values_from_cmdline = make([]string, 0, 1)
+	self.parsed_values_from_cmdline = make([]any, 0, 1)
+}
 func option_from_spec(spec OptionSpec) (*Option, error) {
 	ans := Option{
-		Help:                       spec.Help,
-		values_from_cmdline:        make([]string, 0, 1),
-		parsed_values_from_cmdline: make([]any, 0, 1),
+		Help: spec.Help,
 	}
+	ans.init_option()
 	parts := strings.Split(spec.Name, " ")
 	ans.Name = camel_case_dest(parts[0])
 	ans.Aliases = make([]Alias, len(parts))
@@ -173,6 +176,7 @@ func option_from_spec(spec OptionSpec) (*Option, error) {
 	if ans.IsList {
 		ans.parsed_default = []string{}
 	}
+	ans.CompletionFunc = spec.CompletionFunc
 	if ans.Aliases == nil || len(ans.Aliases) == 0 {
 		return nil, fmt.Errorf("No --aliases specified for option")
 	}

tools/cli/types.go

@@ -10,6 +10,7 @@ import (
 	"strconv"
 	"strings"
 
+	"kitty/tools/cli/completion"
 	"kitty/tools/utils"
 
 	"golang.org/x/exp/slices"
@@ -42,26 +43,28 @@ func (self *Alias) String() string {
 }
 
 type OptionSpec struct {
-	Name    string
-	Type    string
-	Dest    string
-	Choices string
-	Depth   int
-	Default string
-	Help    string
+	Name           string
+	Type           string
+	Dest           string
+	Choices        string
+	Depth          int
+	Default        string
+	Help           string
+	CompletionFunc *completion.CompletionFunc
 }
 
 type Option struct {
-	Name       string
-	Aliases    []Alias
-	Choices    []string
-	Default    string
-	OptionType OptionType
-	Hidden     bool
-	Depth      int
-	Help       string
-	IsList     bool
-	Parent     *Command
+	Name           string
+	Aliases        []Alias
+	Choices        []string
+	Default        string
+	OptionType     OptionType
+	Hidden         bool
+	Depth          int
+	Help           string
+	IsList         bool
+	Parent         *Command
+	CompletionFunc *completion.CompletionFunc
 
 	values_from_cmdline        []string
 	parsed_values_from_cmdline []any
@@ -241,6 +244,7 @@ func (self *OptionGroup) Clone(parent *Command) *OptionGroup {
 	ans := OptionGroup{Title: self.Title, Options: make([]*Option, len(self.Options))}
 	for i, o := range self.Options {
 		c := *o
+		c.init_option()
 		c.Parent = parent
 		ans.Options[i] = &c
 	}