editor

package
v0.0.5 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 11, 2026 License: Apache-2.0, Apache-2.0 Imports: 9 Imported by: 0

README

Go editor client

Package github.com/moriyoshi/gpui-go/editor provides a Go client for persistent Zed editor instances over the versioned editor protocol. The optional Rust editor component and host own text, selection, focus, and undo history.

License

The Go code in this directory is licensed under Apache-2.0, matching the project license. The editor protobuf schemas are also Apache-2.0. Third-party components retain their respective licenses and notices; see the project notice.

The optional native Rust editor component and host are GPL-3.0-or-later. Applications distributed with that backend linked in must comply with the GPL's requirements for the combined work, including corresponding source. The Go client's Apache license does not remove those requirements. See the project licensing scope.

Use

Use NewClient(ctx, transport) with an application-supplied Transport, or call Run once from main to start the supplied native host. Run owns the process-global Sable runtime and cannot share a process with another Sable runtime owner such as gpui.Run. Its application callback must return when its context is canceled.

Client.Open creates an editor handle. Each editor supports State, SetText, InsertText, SetSelection, Undo, Redo, SetReadOnly, Focus, and Close. Commands may run concurrently; use a single Client.NextEvent consumer. Events have no acknowledgement or replay guarantee. Cancellation may race a committed command, so do not automatically retry mutations.

Run opens one editor per window. To place an editor inside a scene.Div, link the combined archive with the gpui_zed_editor_embed tag, call Attach inside host.Run and use OpenEmbedded with scene.Embedded; see examples/editor-embed. It supports local plain-text buffers; syntax grammars, language servers, and file/project services are not configured. The root guide includes a Go usage example and host limits; examples/editor supplies a runnable application.

From the repository root:

make editor-lib          # build the native host archive
make editor              # build and run the example
make editor-smoke        # exercise native editor commands and lifecycle

The Makefile selects the native build tags and link flags. Without those tags, the Go client and custom transports build independently of the native backend, and Run returns ErrNativeUnavailable.

Documentation

Overview

Package editor exposes reusable Zed editor instances over protobuf and Sable. The native backend links GPL-3.0-or-later components. The Go API and custom transports can be used without linking a native backend.

Index

Constants

This section is empty.

Variables

View Source
var (
	ErrClosed            = errors.New("editor: host closed")
	ErrReadOnly          = errors.New("editor: read-only")
	ErrNotFound          = errors.New("editor: closed or unknown handle")
	ErrConcurrentEvents  = errors.New("editor: another event consumer is active")
	ErrNativeUnavailable = errors.New("editor: build with gpui_zed_editor,sable_extern_lib,sable_portable and link libgpui_go_zed_editor_host (see make editor)")
)

Functions

func Run

func Run(ctx context.Context, application func(context.Context, *Client) error) error

Run enters the standalone native host on the process main thread. Call from main, once per process. The callback runs on a goroutine and must return when its context is canceled; returning requests host shutdown. The native host owns Sable and cannot share a process with another Sable runtime owner. Rust applications embedding EditorComponent can provide their own Transport and use NewClient instead of this standalone host.

Types

type Capabilities

type Capabilities struct{ Major, MaxTextBytes, MaxEditors uint32 }

type Clamp

type Clamp int32

Clamp says where a Position inside a wide character, a tab or a grapheme cluster goes.

const (
	// ClampNone rejects the position with InvalidArgument.
	ClampNone Clamp = iota
	// ClampBefore moves before the character or tab in text order. On a
	// right-to-left line that is toward the right of the screen.
	ClampBefore
	// ClampAfter moves after the character or tab in text order.
	ClampAfter
)

type Client

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

Client supports concurrent commands and a single ordered event consumer. Handles belong to this client and the lifetime of its host process.

func Attach

func Attach(context.Context) (*Client, error)

Attach requires the gpui_zed_editor_embed tag and the combined native archive.

func NewClient

func NewClient(ctx context.Context, transport Transport) (*Client, error)

func (*Client) Capabilities

func (c *Client) Capabilities() Capabilities

func (*Client) NextEvent

func (c *Client) NextEvent(ctx context.Context) (*Event, error)

NextEvent consumes one event across all editors. Cancellation can race receipt and lose an event; no replay/retry guarantee is provided by this protocol.

func (*Client) Open

func (c *Client) Open(ctx context.Context, options Options) (*Editor, error)

func (*Client) OpenEmbedded

func (c *Client) OpenEmbedded(ctx context.Context, target EmbedTarget, options EmbedOptions) (*Editor, error)

OpenEmbedded creates an editor in target's window without showing it. Pass its ID to scene.Embedded, in a view committed after the window has opened. The editor closes with the window. Use a Client from Attach.

func (*Client) Quit

func (c *Client) Quit(ctx context.Context) error

type Code

type Code int32
const (
	InvalidArgument    Code = 1
	NotFound           Code = 2
	ReadOnly           Code = 3
	ResourceExhausted  Code = 4
	Closed             Code = 5
	Internal           Code = 6
	UnsupportedVersion Code = 7
)

type Editor

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

Editor identifies one persistent native buffer. Closing it invalidates the handle; IDs are never recycled. Closing an editor does not quit the host.

func (*Editor) Close

func (e *Editor) Close(ctx context.Context) error

func (*Editor) Focus

func (e *Editor) Focus(ctx context.Context) error

func (*Editor) ID

func (e *Editor) ID() uint64

func (*Editor) InsertText

func (e *Editor) InsertText(ctx context.Context, text string) (*State, error)

InsertText replaces the current native selections in one undo transaction.

func (*Editor) Redo

func (e *Editor) Redo(ctx context.Context) (*State, error)

func (*Editor) SetReadOnly

func (e *Editor) SetReadOnly(ctx context.Context, value bool) (*State, error)

func (*Editor) SetSelection

func (e *Editor) SetSelection(ctx context.Context, start, end Position) (*State, error)

SetSelection replaces all selections with one from start to end and scrolls it into view. Pass the same position twice for a caret. It is also allowed on a read-only editor, does not move keyboard focus and emits no Changed event. A position outside the buffer returns InvalidArgument, and so does one inside a tab or character unless its Clamp says which way to move. Clamp each end separately: the start before and the end after selects the whole character.

func (*Editor) SetText

func (e *Editor) SetText(ctx context.Context, text string) (*State, error)

SetText is an authoritative replacement, also allowed in read-only mode.

func (*Editor) State

func (e *Editor) State(ctx context.Context) (*State, error)

func (*Editor) Undo

func (e *Editor) Undo(ctx context.Context) (*State, error)

type EmbedOptions

type EmbedOptions struct {
	Text            string
	ReadOnly        bool
	HideGutter      bool
	DisableSoftWrap bool
	// WidthTable chooses how a Position counts East Asian Ambiguous characters.
	// It does not change how they are drawn.
	WidthTable WidthTable
}

EmbedOptions configure an editor that is placed inside a generic view.

type EmbedTarget

type EmbedTarget interface {
	EmbedTarget() (view uint64, generation uint32)
}

EmbedTarget is implemented by client.Window. This package has no dependency on the generic client.

type Event

type Event struct {
	Sequence, EditorID uint64
	Kind               EventKind
	State              *State
	Error              *ProtocolError
}

type EventKind

type EventKind uint8
const (
	Changed EventKind = iota + 1
	EditorClosed
	Failed
)

type Operation

type Operation uint32
const (
	OperationCommand Operation = 0x5a454401
	OperationEvents  Operation = 0x5a454402
	MaxTextBytes               = 1 << 20
)

type Options

type Options struct {
	Title           string
	Width, Height   float32
	Text            string
	ReadOnly        bool
	HideGutter      bool
	DisableSoftWrap bool
	// WidthTable chooses how a Position counts East Asian Ambiguous characters.
	// It does not change how they are drawn.
	WidthTable WidthTable
}

Options configure a new local editor window in the supplied standalone host. Zero dimensions select 1000x700. Gutter and soft wrap are enabled by default.

type Position

type Position struct {
	Line, Column, Character uint32
	Clamp                   Clamp
}

Position is a zero-based location. Line is a buffer line, and Column counts visual cells from its start, as the editor lays them out and by the East Asian Width table: a wide or fullwidth character takes two, a tab reaches its stop, and a combining mark takes none. An ambiguous character follows the editor's WidthTable. Soft wrapping does not restart the count. Column does not index a Go string.

Character is an alternative to Column when setting a selection: the number of Unicode code points from the start of the line, as counted by utf8.RuneCountInString. Setting both nonzero returns InvalidArgument.

Character and Clamp apply only when setting a selection. Reported positions leave them zero.

type ProtocolError

type ProtocolError struct {
	Code    Code
	Message string
}

func (*ProtocolError) Error

func (e *ProtocolError) Error() string

func (*ProtocolError) Is

func (e *ProtocolError) Is(target error) bool

type Selection

type Selection struct{ Start, End Position }

Selection never has Start after End. Equal positions are a caret.

type State

type State struct {
	EditorID, Revision uint64
	Text               string
	ReadOnly           bool
	Selection          Selection
}

State is an owned snapshot. Revision begins at zero and is local to EditorID. Selection is the newest selection; moving it does not change Revision.

type Transport

type Transport interface {
	Call(context.Context, Operation, []byte) ([]byte, error)
}

Transport must return independently owned response bytes and respect context cancellation. It must not retain request bytes without copying them.

type WidthTable

type WidthTable int32

WidthTable chooses how positions count East Asian Ambiguous characters. The editor draws glyphs from the font either way, so choose the table that matches the font: Japanese fonts usually draw these characters two columns wide.

const (
	// WidthNarrowAmbiguous counts every ambiguous character as one column.
	WidthNarrowAmbiguous WidthTable = iota
	// WidthWideAmbiguous counts every ambiguous character that has a width as
	// two columns, including letters such as α and é.
	WidthWideAmbiguous
	// WidthWideSymbols counts ambiguous symbols, punctuation and numbers as two
	// columns and ambiguous letters as one.
	WidthWideSymbols
)

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL