program

type BellHost ¶ added in v0.0.5

type BellHost interface{ Bell() }

BellHost rings the user-facing host's audible or visible bell.

type ByteBatch ¶ added in v0.1.0

type ByteBatch struct {
	Data  []byte
	Err   error
	Final bool
}

ByteBatch is one owner-side delivery from a ByteIngress.

Data is the ordered concatenation of bytes accepted since the previous delivery. The consumer owns it and may retain or change it after the callback returns. Final is true exactly once, after every accepted byte; Err is meaningful only then. A nil Err is successful completion.

type ByteIngress ¶ added in v0.1.0

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

ByteIngress carries a lossless ordered byte stream to an interface owner.

Write may block when limit bytes are waiting for the owner, applying backpressure at the producer rather than growing Dispatcher's general task queue. Adjacent writes are combined and at most one delivery task is pending at a time. The consumer is always called on the interface goroutine.

Close or CloseWithError completes the stream after all accepted bytes. When the program stops first, blocked writes return ErrStopped, pending bytes are released, and the consumer is not called from a background goroutine. A ByteIngress must be closed by its producer; its internal cancellation waiter then exits. The zero value is stopped. A ByteIngress must not be copied after construction: its pending bytes, backpressure and final delivery belong to one stream.

func NewByteIngress(config ByteIngressConfig) (*ByteIngress, error)

func (i *ByteIngress) Close() error

func (i *ByteIngress) CloseWithError(err error) error

func (i *ByteIngress) Done() <-chan struct{}

func (i *ByteIngress) Write(p []byte) (n int, err error)

type ByteIngressConfig ¶ added in v0.13.0

type ByteIngressConfig struct {
	Dispatcher Dispatcher
	Limit      int
	Consume    func(ByteBatch)
}

ByteIngressConfig owns the complete construction contract of a ByteIngress. Dispatcher and Consume are required. Limit is the maximum number of bytes accepted but not yet taken by the interface owner and must be positive.

type Clipboard ¶ added in v0.0.5

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

Clipboard is the clipboard associated with the user-facing host. Its zero value refuses writes and reads.

func (c Clipboard) Copy(text string) bool

func (c Clipboard) Paste() bool

type ColorHost ¶ added in v0.11.0

type ColorHost interface{ Color() grid.Depth }

ColorHost supplies the colour depth of the user-facing terminal.

type Component ¶

type Component interface {
	Draw(view grid.View)
	Handle(event input.Event) bool
}

Component is an interface a program can run: it draws itself into the space it is given, and says whether it wants an event.

It is handed a view that is already positioned and clipped, so its coordinates are its own. An event it does not consume is dropped by the program — a component is the root of its own tree and there is nobody above it to pass one on to.

type Config ¶

type Config struct {
	// Root builds the component to run on a screen of its own. It is given the runtime
	// first, so the component can hold it from the moment it exists. Returning nil is
	// an error.
	Root func(*Runtime) Component

	// Inline builds the component to run as a block in the terminal's own screen,
	// with output that is finished printed above it. Its component is given an
	// [InlineRuntime], which is a [Runtime] that can also print.
	// Returning nil is an error.
	Inline func(*InlineRuntime) Component

	// Terminal says which optional terminal features to request. Run applies them
	// when opening the local terminal; a transport adapter may interpret them before
	// supplying Host. A Host passed directly to Run already owns its setup and
	// receives none of these settings.
	//
	// Screen ownership is deliberately absent. Root owns the alternate screen and
	// Inline owns the terminal's ordinary screen, so the rendering model has exactly
	// one entry point and cannot be contradicted by terminal configuration.
	Terminal term.Features

	// Color says how much colour the terminal can show. The zero value, [grid.Auto],
	// asks the host's optional [ColorHost]. A local terminal derives that answer with
	// [term.DetectDepth]; a host without the capability safely uses no colour.
	//
	// Setting it is how a program that already knows — from its own configuration,
	// or because it is writing to something that is not a terminal at all — takes
	// that decision back.
	Color grid.Depth

	// Host overrides where input comes from and frames go. Nil opens the real terminal
	// and gives it back on the way out.
	Host Host

	// FrameInterval is the shortest time between redraws. Zero uses
	// [DefaultFrameInterval]; a negative duration is invalid.
	FrameInterval time.Duration
}

Config is what a program needs to run.

Exactly one of Root and Inline says what to run, and which one it is decides where the interface is drawn: Root takes a screen of its own, Inline draws in the terminal's own screen and prints finished output into its scrollback.

package main

import (
	"fmt"
	"time"

	"github.com/Tangerg/oolong/core/grid"
	"github.com/Tangerg/oolong/core/input"
	"github.com/Tangerg/oolong/core/program"
	"github.com/Tangerg/oolong/core/term"
)

// clock is a component: it draws itself, and says whether it wants an event. There is
// no base type to embed and no lifecycle to implement.
type clock struct {
	runtime *program.Runtime
	now     time.Time
}

func (c *clock) Draw(view grid.View) {
	view.Text(0, 0, c.now.Format(time.TimeOnly), grid.Style{})
	view.Text(0, 2, "q to quit", grid.Style{Attr: grid.Dim})
}

func (c *clock) Handle(event input.Event) bool {
	key, ok := event.(input.Key)
	if !ok || !key.Down() || key.Rune != 'q' {
		return false
	}
	c.runtime.Quit()
	return true
}

func main() {
	config := program.Config{
		Root: func(runtime *program.Runtime) program.Component {
			c := &clock{runtime: runtime, now: time.Now()}
			runtime.Every(time.Second, func() { c.now = time.Now() })
			return c
		},
		// Optional terminal behaviours are requested, never assumed.
		Terminal: term.Features{Mouse: true, Focus: true},
	}
	fmt.Println(config.Validate())

}

Output:
<nil>

package main

import (
	"fmt"
	"time"

	"github.com/Tangerg/oolong/core/grid"
	"github.com/Tangerg/oolong/core/input"
	"github.com/Tangerg/oolong/core/program"
)

// clock is a component: it draws itself, and says whether it wants an event. There is
// no base type to embed and no lifecycle to implement.
type clock struct {
	runtime *program.Runtime
	now     time.Time
}

func (c *clock) Draw(view grid.View) {
	view.Text(0, 0, c.now.Format(time.TimeOnly), grid.Style{})
	view.Text(0, 2, "q to quit", grid.Style{Attr: grid.Dim})
}

func (c *clock) Handle(event input.Event) bool {
	key, ok := event.(input.Key)
	if !ok || !key.Down() || key.Rune != 'q' {
		return false
	}
	c.runtime.Quit()
	return true
}

func main() {
	inline := program.Config{
		Inline: func(runtime *program.InlineRuntime) program.Component {
			return &clock{runtime: runtime.Runtime, now: time.Now()}
		},
	}
	fmt.Println("inline:", inline.Validate())

	both := inline
	both.Root = func(*program.Runtime) program.Component { return nil }
	fmt.Println("both:", both.Validate() == nil)

}

Output:
inline: <nil>
both: false

func (c Config) TerminalConfig() term.Config

func (c Config) Validate() error

type CopyHost ¶ added in v0.0.5

type CopyHost interface{ Copy(text string) bool }

CopyHost writes to the clipboard associated with the user-facing host.

type DirectoryHost ¶ added in v0.0.5

type DirectoryHost interface {
	ReportDirectory(path string) error
}

DirectoryHost tells a terminal how to resolve relative paths in program output.

type Dispatcher ¶ added in v0.0.5

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

Dispatcher is a copyable, concurrency-safe handle into a running program. Its zero value drops work. It deliberately exposes no owner-only operation.

func (d Dispatcher) Done() <-chan struct{}

func (d Dispatcher) Post(fn func())

type Environment ¶ added in v0.0.5

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

Environment is the stable set of terminal facts learned before a program runs. Its zero value reports that nothing was learned.

func (e Environment) Color() grid.Depth

func (e Environment) Ground() grid.Ground

func (e Environment) Keyboard() (input.KeyboardFeatures, bool)

func (e Environment) Locale() string

func (e Environment) Wheel() input.Wheel

type EventSource ¶ added in v0.1.0

type EventSource interface {
	Events() <-chan input.Event
	Err() error
}

EventSource is one ordered input stream and its terminal result.

Events closes after the last event. Once it has closed, Err reports why the stream ended: nil means a clean end of input, while a non-nil error is the transport failure that ended it. Err must not report end-of-file as a failure.

The two methods form one lifecycle. Keeping the result on the source avoids a race between an event channel closing and a separate error channel becoming readable, and follows the same iteration-then-error shape as a scanner.

type FrameWriter ¶ added in v0.0.5

type FrameWriter interface {
	// Queue takes ownership of frame. The caller does not read or change the slice
	// after the call; an asynchronous implementation may retain it without copying.
	// Every accepted call returns a non-zero sequence strictly greater than earlier
	// sequences from the same writer. Written reports a watermark in that sequence
	// space.
	Queue(frame []byte) uint64
	// Changes coalesces state changes; the receiver must re-read Written and Err.
	Changes() <-chan struct{}
	Written() uint64
	Err() error
	Drain(timeout time.Duration) error
}

FrameWriter is the part of a frame queue the program needs.

It is defined by the consumer rather than exposing term.Writer through Host. Implementations must preserve queue order, report successful completion as a watermark and be safe for concurrent use. Changes returns one stable, single-consumer channel for the writer's lifetime; a receive means Written or Err may have changed. Closing it means the writer has permanently stopped and Err must report the cause. Drain returns nil only after every frame accepted before the call has either been written or accounted for. term.Writer is the standard implementation.

type GroundHost ¶ added in v0.0.5

type GroundHost interface{ Ground() grid.Ground }

GroundHost supplies the colours discovered before a program starts.

type HandoverHost ¶ added in v0.0.5

type HandoverHost interface {
	Hand(run func() error) error
}

HandoverHost temporarily gives exclusive ownership of its display to run.

type Host ¶

type Host interface {
	// Input is the ordered input stream and the reason it eventually ends.
	Input() EventSource
	// Writer is where frames go. The interface is defined here, where it is used;
	// a host is not coupled to the terminal package's concrete writer.
	Writer() FrameWriter
	// Size is the terminal's size in cells. The result must satisfy [ValidateSize].
	Size() (w, h int, err error)
}

Host is where a program's input comes from and its frames go.

A program opens the real terminal unless it is given one of these. Being able to supply it is what lets an interface be driven and inspected in a test, with no terminal in sight.

Everything beyond transport is optional. Each independently useful operation is represented by a small consumer interface such as GroundHost, CopyHost or NotifyHost, so implementing one never silently depends on implementing its neighbours. ImageHost is the exception because its transport and geometry form one protocol. Absent capabilities receive harmless defaults.

type ImageHost ¶ added in v0.0.5

type ImageHost interface {
	Graphics() graphics.Protocol
	CellSize() (image.Point, bool)
	Transmit(png []byte) (graphics.Image, error)
}

ImageHost transmits images and reports the protocol geometry needed to place them. These methods form one capability: a handle from Transmit cannot be placed without the protocol and cell geometry that interpret it.

type Images ¶ added in v0.0.5

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

Images is the host's image transport. Its zero value reports no protocol and refuses transmission.

func (i Images) CellSize() (image.Point, bool)

func (i Images) Protocol() graphics.Protocol

func (i Images) Transmit(png []byte) (graphics.Image, error)

type InlineRuntime ¶ added in v0.0.5

type InlineRuntime struct{ *Runtime }

InlineRuntime is a Runtime that can publish completed output into terminal scrollback. It is only constructed for Config.Inline, and its zero value is inert.

func (r *InlineRuntime) Append(draw func(grid.View) bool)

func (r *InlineRuntime) Print(p grid.Drawable)

type KeyboardHost ¶ added in v0.0.5

type KeyboardHost interface {
	Keyboard() (input.KeyboardFeatures, bool)
}

KeyboardHost supplies keyboard protocol features negotiated with the host.

type LocaleHost ¶ added in v0.8.0

type LocaleHost interface{ Locale() string }

LocaleHost supplies the character locale of the user-facing terminal.

type NotifyHost ¶ added in v0.0.5

type NotifyHost interface{ Notify(text string) }

NotifyHost sends a notification through the user-facing host.

type PasteHost ¶ added in v0.0.5

type PasteHost interface{ Paste() bool }

PasteHost requests text from the clipboard associated with the user-facing host. Paste reports whether the request was accepted; answers arrive asynchronously through EventSource.Events as an input.Paste.

type ProgressHost ¶ added in v0.5.0

type ProgressHost interface{ SetProgress(progress term.Progress) }

ProgressHost presents task progress outside the interface's cell grid.

type Runtime ¶ added in v0.0.5

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

Runtime is the program resource owned by the interface goroutine.

It is concrete rather than a provider-defined interface: consumers that need only a subset declare that interface where they use it. Background work receives only Runtime.Dispatcher, preserving ownership in the type system. Host features are grouped into the concrete Environment, Clipboard, Session and Images values rather than flattened into one capability catalogue. The zero value is inert; it is safe to embed in an object that has not been attached to a program.

func (r *Runtime) After(d time.Duration, fn func()) (stop func())

func (r *Runtime) Clipboard() Clipboard

func (r *Runtime) Dispatcher() Dispatcher

package main

import (
	"fmt"
	"io"
	"net/http"

	"github.com/Tangerg/oolong/core/program"
)

func main() {
	type page struct {
		runtime *program.Runtime
		status  string
	}

	const endpoint = "https://example.test/status"
	load := func(p *page) {
		// Taken here because this is the goroutine that owns the runtime; asking the
		// runtime for one from inside the goroutine below would be the race this
		// whole arrangement exists to remove.
		post := p.runtime.Dispatcher()
		go func() {
			response, err := http.Get(endpoint) //nolint:noctx // an example, not a client
			// Back on the program goroutine: assigning p.status here is safe, and
			// assigning it in the goroutine above would not have been.
			post.Post(func() {
				if err != nil {
					p.status = "unreachable"
					return
				}
				defer func() {
					_, _ = io.Copy(io.Discard, response.Body)
					_ = response.Body.Close()
				}()
				p.status = response.Status
			})
		}()
	}
	_ = load

	fmt.Println("work returns to the goroutine that owns the state")
}

Output:
work returns to the goroutine that owns the state

func (r *Runtime) Environment() Environment

func (r *Runtime) Every(d time.Duration, fn func()) (stop func())

func (r *Runtime) Images() Images

func (r *Runtime) Quit()

func (r *Runtime) Refresh()

func (r *Runtime) Session() Session

type Session ¶ added in v0.0.5

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

Session controls the live terminal session around rendered frames. It groups operations that must remain ordered with the interface owner's state. Its zero value performs harmless notification no-ops and can hand control to a callback, but cannot suspend a process.

It holds the runtime rather than the resolved services the other capabilities hold, because two of its methods need the owner itself and not what the host can answer: see Session.Hand.

func (s Session) Bell()

func (s Session) Hand(run func() error) error

func (s Session) Notify(text string)

func (s Session) ReportDirectory(path string) error

func (s Session) SetProgress(progress term.Progress)

func (s Session) SetTitle(title string)

func (s Session) Suspend() error

type TitleHost ¶ added in v0.0.5

type TitleHost interface{ SetTitle(title string) }

TitleHost names the user-facing host window.

type WheelHost ¶ added in v0.0.5

type WheelHost interface{ Wheel() input.Wheel }

WheelHost supplies the host's wheel-event scale.