input

type Action interface {
	// Name must be a unique name identifying this Action.  In rare
	// occasions, some plugins MAY choose to override an existing
	// Action by naming one of their Action types the same as the
	// Action to be overridden.  They MUST NOT rely on their
	// overriding Action to be bound, however, as the user may
	// choose to disable their action.
	Name(context.Context) string
}

type Actions interface {
	// Named looks for and returns the Action with a Name() matching name.
	// Returns nil if no matching Action was found.
	Named(_ context.Context, name string) Action
}

type Binder interface {
	// Set sets some state on the Binder bound to a given Action type. Plugins
	// that need to track state over time that isn't directly implemented by the
	// binder in question may store their state here.
	//
	// The Action argument ensures that the value is set on the Binder that the
	// Action was bound to, especially in the case of PickyAction types.
	//
	// Returns false if the no Binder can be found for the Action argument.
	//
	// Typically, key will be an unexported local empty struct type. Think of
	// this like context.WithValue, except that the Binder is modified in-place
	// instead of returning a copy with the new value added.
	//
	// Set and Get are goroutine-safe.
	Set(_ context.Context, _ Action, key, value any) bool

	// Get retrieves state previously stored on the Binder bound to the Action.
	// See Set for more info.
	//
	// If no value has been set, the return value will be (nil, true).
	Get(_ context.Context, _ Action, key any) (any, bool)

	// Bound returns the Actions that are bound to the Binder and all of the
	// Binder's parents. Any Actions that are bound to one of the Binder's
	// parents but not to the Binder will execute against the parent instead
	// when they are passed to Run.
	Bound(context.Context) Actions

	// Run will run the Action passed in. Only core Operation types (which have
	// access to internal packages) are able to *directly* manipulate the
	// Binder's state, so anything that is *not* a core operation should
	// manipulate state by looking up other Operations bound to the Binder and
	// passing them to this method.
	Run(context.Context, Action) error
}

type Command interface {
	Action

	// Type is required to be implemented by the Command so that it cannot also
	// implement Operation or Hook. This is done to encourage decoupling among
	// Actions.
	Type(Command)

	// Menu returns the toolbar menu that this Command should be listed under.
	Menu(context.Context) string

	// Op looks up and returns the Operation value that should be executed when
	// this Command is triggered. If the Command needs to execute multiple
	// Operations, look up and use 'multi-operation' on the Binder (see
	// core/op/multi.go).
	Op(context.Context, Binder) (Operation, error)
}

type Dialog interface {
	// Inform is used to show information to the user.
	//
	// The returned function must be called to clear the message. While I
	// would prefer to use a sum type as an argument to inform the dialog
	// how long messages should be displayed for (either a time.Duration or
	// a context.Context, for instance), go doesn't have sum types. This is
	// the cleanest alternative that I could think of.
	//
	// It is the responsibility of the caller to ensure that the function
	// will eventually be called.
	Inform(_ context.Context, uiElement any) (done func(), err error)

	// Prompt is used to request information from the user. Text input will
	// be processed by whatever input handler is loaded (note: it is
	// possible for a different input handler to load for the dialog than
	// for the main editor); once the input handler has received a signal
	// that the user is done, it will be returned.
	//
	// The uiMessage argument should be the prompt. The Dialog
	// implementation will take care of creating a text box to read back
	// user input, because the Dialog needs to know which element to
	// focus/unfocus and process events for.
	Prompt(_ context.Context, uiMessage any) (string, error)
}

type Edit struct {
	At  int
	Len int
	New []rune
}

type Handler interface {
	// Name implements Action, allowing input handlers to be bound to Binders as
	// normal action values so that they can be looked up via Bound().Named()
	//
	// Normally, this should return HandlerName; but in some circumstances, it
	// may be okay to provide extra Handler implementations that do not directly
	// override the primary Handler.
	Name(context.Context) string

	// SetDefaultKeys takes an action and attempts to set defaults for the
	// action in this Handler's preferences.
	//
	// The set of Actions bound to various Binders may change frequently, and
	// each time they change they should pass new (and possibly existing) Action
	// values to this method. Handler implementations must be ready for that,
	// and avoid overriding any already-bound Actions in their preferences.
	SetDefaultKeys(context.Context, Binder, Action)

	//KeyPressed will be called for every key down that
	// is received through the UI library's keyboard events.
	KeyPressed(context.Context, Binder, KeyEvent)

	// CharInput will be called for each character that is received through
	// system text input.
	CharInput(context.Context, Binder, rune)
}

type Hook interface {
	Action

	// Type is required to be implemented by the Hook so that it
	// cannot also implement Command or Operation.  This is done
	// to encourage decoupling among Actions.
	Type(Hook)

	// OpNames returns a list of operation names which this Hook
	// must be bound to.
	//
	// While it's much more common for a Hook to bind to a single
	// Operation than to multiple, implementing branching logic
	// for a SingleOpHook vs MultiOpHook is much more trouble
	// than it's worth.
	OpNames(context.Context) []string
}

type HookedOperation interface {
	Operation

	// Empty returns an empty copy of this HookedOperation, with no hooks bound.
	// This is important in case extra hooks need to be bound with a specific
	// type of file (e.g. syntax highlighting hooks) - the returned
	// HookedOperation *must* be in an empty state.
	Empty(context.Context) HookedOperation

	// SetHook sets the Hook in the HookedOperation, so that when certain
	// actions are performed by the Operation it will trigger the actions on the
	// Hook.
	//
	// Each HookedOperation may support as many Hook interface types as it would
	// like. See the documentation for the specific Operation to see which
	// interface type(s) it supports.
	SetHook(context.Context, Hook) error
}

type Key int

type KeyEvent struct {
	// Code is the key code that triggered the event.
	Code Key

	// Mods is a list of keys that were held down at the time of the event.
	//
	// Vidar passes *all* keys that were down at the time of the event in this
	// slice, ordered by key code (i.e. key code 12 will be before key code 113,
	// etc). This is intended to allow implementations of input.Handler to bind
	// things like c+a in non-input modes, if desired.
	//
	// Unfortunately, this slice makes the KeyEvent non-hashable, so creating a
	// map requires some translation back and forth. We make sure that the Mods
	// slice has a consistent order to make this easier.
	//
	// See the reference Handler implementation (core/input.Handler) for a very
	// simple (albeit not super fast) method of translating events to strings.
	Mods []Key
}

type LineEdit struct {
	StartLine, StartCol int
	EndLine, EndCol     int
	New                 []rune
}

type NamedConstructor struct {
	// Name must be the name of the Handler that would be returned.
	Name string

	// Construct must initalize the Handler, launching any required goroutines
	// and setting up any initial state.
	//
	// The ui.Creator is passed in to provide access to the UI goroutine for
	// applying text edits.
	Construct func() (Handler, error)
}

type Operation interface {
	Action

	// Type is required to be implemented by the Operation so that it cannot
	// also implement Command or Hook. This is done to encourage decoupling
	// among Actions.
	Type(Operation)

	// Run runs the Operation as configured against the Binder. Plugins will
	// *almost always* need to look up other Operations and call
	// Binder.Run(Operation) in order to manipulate state. Methods which
	// manipulate Binders' state are almost always unexported to ease
	// development of hooks that need to be triggered every time the editor's
	// state changes.
	Run(context.Context, Binder) error
}

type PickyAction interface {
	Action

	// Valid returns nil if the Action can/should be bound to b, or a non-nil
	// error that explains the reason it cannot be bound if not.
	//
	// Note: once an Action has been bound to a Binder, it cannot be un-bound.
	// This means that if Valid checks for bound actions, it should be aware
	// of the order in which actions are bound to Binder types. See the package
	// documentation for details.
	Valid(context.Context, Binder) error
}

type SetupOperation interface {
	Operation

	// Setup will be called after all Hook and Operation types are bound, but
	// before any Command types are bound.
	Setup(context.Context, Binder) error
}