command

type Command struct {
	// Name is the command's identity, in kebab-case.
	Name string

	// Doc is a one-line description shown by describe-key and M-x.
	Doc string

	// Fn implements the command.
	Fn Func

	// Interactive reports whether the command appears in M-x completion.
	// Commands driven only by the event loop, such as self-insert-command,
	// are registered but not interactive.
	Interactive bool
}

type CompleteFunc func(input string) []string

type Env interface {

	// Win returns the active window: the buffer being edited, where point is,
	// and which lines are on screen.
	//
	// While a prompt is open, Win reports the MINIBUFFER's window, not the
	// text window. That is deliberate and is what makes prompts editable for
	// free: C-a, C-e, C-k, M-b and the kill ring are ordinary commands, and
	// they must act on the prompt the user is typing into.
	//
	// The exception is ReadOpts.OnChange and ReadOpts.Session, which run
	// against the pre-prompt text window — see the note on OnChange. Anything
	// else that needs the text window while a prompt is open is asking for
	// trouble; there is no accessor for it, by design.
	Win() *view.Window

	// Buf returns the active window's buffer. Shorthand for Win().Buf.
	Buf() *text.Buffer

	// TextHeight reports how many rows of buffer text the active window shows,
	// excluding its modeline. Needed by every command that moves by screenfuls
	// or repositions the viewport: scroll-up-command, scroll-down-command and
	// recenter-top-bottom cannot be written without it.
	TextHeight() int

	// Arg reports the prefix argument. n is 1 when none was given, and
	// explicit distinguishes a bare command from C-u 1, which some commands
	// treat differently.
	Arg() (n int, explicit bool)

	// KillForward records text killed forward of point; KillBackward records
	// text killed backward of it. The ring handles kill-run accumulation, so a
	// command states only the direction.
	KillForward(s string)
	KillBackward(s string)

	// Yank returns the current kill-ring entry without consuming it.
	Yank() (string, error)

	// YankPop rotates to the next-older entry and returns the full replacement
	// text. It is valid only immediately after a yank.
	YankPop() (string, error)

	// LastCommand names the command that ran immediately before this one, or
	// "" at the start of a session. This is emacs's last-command.
	LastCommand() string

	// Seq returns the sequencing state shared across consecutive commands.
	//
	// The pointer is stable for the life of the session, so commands mutate
	// the struct in place: e.Seq().RecenterCycle++ is the intended idiom.
	Seq() *Seq

	// ReadString prompts in the minibuffer and returns what the user typed,
	// or ErrQuit if they pressed C-g.
	ReadString(opts ReadOpts) (string, error)

	// ReadChar prompts for a single keystroke, accepting only the runes in
	// valid (all runes when valid is empty), and returns it. This is what
	// query-replace's y/n/!/q loop and save-some-buffers are built from; a
	// ReadString would force the user to press RET after every answer.
	ReadChar(prompt string, valid []rune) (rune, error)

	// ReadKey prompts for one raw keystroke and returns it undecoded, for
	// describe-key.
	ReadKey(prompt string) (keymap.Key, error)

	// Echo shows a message in the echo area.
	Echo(format string, a ...any)

	// Buffers lists every live buffer, most recently visited first.
	Buffers() []*text.Buffer

	// BufferName is the buffer's display name: the basename of its file, or a
	// generated name such as "*scratch*" for one with no file.
	BufferName(b *text.Buffer) string

	// BufferByName finds a buffer by display name, for switch-to-buffer.
	BufferByName(name string) (*text.Buffer, bool)

	// NewBuffer creates a live, file-less buffer under the given display name.
	// list-buffers renders into one of these, as does the startup *scratch*.
	NewBuffer(name string) *text.Buffer

	// OpenFile returns the buffer visiting path, reading it from disk if it is
	// not already open. A path that does not exist yields an empty buffer, as
	// find-file does.
	OpenFile(path string) (*text.Buffer, error)

	// KillBuffer removes a buffer from the live list. It is an error to kill
	// the last remaining buffer.
	KillBuffer(b *text.Buffer) error

	// SaveBuffer writes b to disk. An empty path saves to b's own path; a
	// non-empty path saves there and adopts it, which is write-file.
	//
	// Commands go through Env rather than calling text.Buffer.Save directly so
	// that tests can intercept saves and inject failures. That matters more
	// here than anywhere else in this interface: saving is the one operation
	// where a bug costs the user the work they were trying to protect.
	SaveBuffer(b *text.Buffer, path string) error

	// SplitWindow splits the active window, side by side when vertical is
	// true and stacked otherwise, and makes the new window active.
	SplitWindow(vertical bool) error

	// OtherWindow moves the selection n windows forward in cycle order,
	// wrapping; negative n moves backward.
	OtherWindow(n int)

	// DeleteWindow removes the active window. It is an error to remove the
	// sole window.
	DeleteWindow() error

	// DeleteOtherWindows makes the active window fill the frame.
	DeleteOtherWindows()

	// Run executes another command by name, which is how M-x and the Lua
	// nem.run bridge invoke commands.
	Run(name string) error

	// CommandNames lists every interactive command name, sorted, for M-x
	// completion.
	CommandNames() []string

	// Bindings maps every bound key sequence to its command name, for
	// describe-bindings.
	Bindings() map[string]string

	// Where lists the key sequences bound to a command, for describe-key and
	// for showing a command's binding in M-x.
	Where(command string) []string

	// Quit ends the editing session. Without force it fails if any buffer has
	// unsaved changes.
	Quit(force bool) error
}

type Func func(Env) error

type Isearch struct {
	// contains filtered or unexported fields
}

type KillRing struct {
	// contains filtered or unexported fields
}

type ReadOpts struct {
	// Prompt is shown at the start of the minibuffer line, e.g. "Find file: ".
	Prompt string

	// Initial pre-fills the minibuffer with editable text.
	Initial string

	// Complete supplies completion candidates. Nil means no completion at all:
	// no candidate panel is built and TAB does nothing, which is what an
	// incremental search prompt wants.
	Complete CompleteFunc

	// RequireMatch governs what RET does when no candidate is highlighted.
	//
	// Whenever one is highlighted, RET takes it, whatever this says: that is
	// what the highlight is for, and a prompt that returned the fragment typed
	// instead would open a new file called "rea" with readme.txt highlighted
	// right under it. A candidate typed out in full is always ranked first, so
	// typing main.go never opens domain.go.
	//
	// The flag decides only the case where the typed text matches nothing. When
	// false, RET returns it as typed, so find-file and switch-to-buffer can name
	// something that does not exist yet. When true, RET refuses it with a
	// message; execute-extended-command sets this, because inventing a command
	// name is meaningless.
	//
	// M-RET returns the typed text whatever is highlighted, which is how a new
	// name is given when it happens to fuzzy-match an existing one. It is
	// refused where RequireMatch holds.
	RequireMatch bool

	// Descend, when non-nil, reports whether candidate is somewhere to walk
	// into rather than an answer. RET on such a candidate puts it in the prompt
	// and keeps the prompt open, so the list shows what is inside it.
	//
	// find-file sets it for directories, so RET on a highlighted src/ lists
	// src/ instead of trying to visit a directory. It is a hook rather than a
	// rule about trailing slashes because the minibuffer cannot know what its
	// candidates are: a buffer name may end in a slash and mean nothing by it.
	// M-RET ignores it, as it ignores the highlight.
	Descend func(candidate string) bool

	// OnChange, when non-nil, is called with the full contents after every
	// edit of the minibuffer — typed, backspaced, killed or yanked alike.
	//
	// This is the hook that makes search-as-you-type fall out of the ordinary
	// prompt mechanism rather than needing one of its own.
	//
	// It runs with Win reporting the PRE-PROMPT TEXT WINDOW, not the
	// minibuffer's, because a hook that reacts to the pattern needs to move
	// point in the buffer being searched. Write an OnChange that assumes the
	// minibuffer window and it will move point in the prompt instead, which
	// reads as a rendering bug rather than as the mistake it is.
	OnChange func(string)

	// Session, when non-nil, is the incremental-search session this prompt
	// drives. The minibuffer calls its Update after every edit and its Advance
	// when the search key is pressed again inside the prompt, so the prompt and
	// the search share one session.
	//
	// It exists because Advance cannot be expressed as a callback: a repeated
	// C-s must step to the next match, which is a property of the session
	// rather than of the pattern, and is not recoverable from an OnChange
	// closure. Passing the session explicitly is what keeps the editor from
	// having to guess which prompts are searches from their command names.
	//
	// Like OnChange, it runs against the pre-prompt text window. Session and
	// OnChange are independent: set both and both are called.
	Session *Isearch
}

type Registry struct {
	// contains filtered or unexported fields
}

type Seq struct {
	// LastYankFrom and LastYankTo bound the text the most recent yank
	// inserted; HasLastYank reports whether they are meaningful.
	//
	// yank-pop cannot work without them: it must delete what the preceding
	// yank inserted before putting the rotated entry in its place.
	LastYankFrom, LastYankTo text.Pos
	HasLastYank              bool

	// RecenterCycle is recenter-top-bottom's position in its centre, top,
	// bottom cycle across successive C-l presses.
	RecenterCycle int

	// LastRune is the rune of the key that triggered the current command. The
	// event loop sets it immediately before dispatch.
	//
	// It is meaningful only for a command invoked by a self-inserting key, and
	// self-insert-command is the one command that needs it: it must insert the
	// character that was typed, and nothing else in Env reports which key ran
	// the command. ReadKey would prompt the user, which is not the same thing
	// at all.
	//
	// Carrying this here rather than as an Env method is what lets
	// self-insert-command be an ordinary registered command, reachable from
	// M-x and bindable from Lua, instead of a stub that only the event loop
	// can call.
	LastRune rune
}