Documentation
¶
Overview ¶
Package live reads the sources of linked regions as they change: a file followed as it grows or is rewritten (File), and anything else that yields a table's rows over time behind the same Source.
A Source is polled on its owner's schedule, one poll at a time, from a goroutine of the owner's (a Bubble Tea command), and answers with an Update: rows to add, or all of them again, which the owner turns into a sheet.LiveOp for the region (Update.Op) and applies on the goroutine that owns the workbook. Sources never touch the workbook.
Index ¶
Constants ¶
const Interval = 250 * time.Millisecond
Interval is how often a followed source is polled.
const StreamKeep = 10000
StreamKeep is how many of the last values a stream keeps.
Variables ¶
This section is empty.
Functions ¶
Types ¶
type File ¶
type File struct {
// Name is how the file is named to the user, in errors.
Name string
// Debounce is how long a file read whole must hold still.
Debounce time.Duration
// MaxRead bounds what one poll reads of a growing file, so a large
// file comes in over several polls, each a short step for the UI.
MaxRead int64
// Now is the clock; tests replace it.
Now func() time.Time
// contains filtered or unexported fields
}
File follows a file with the standard library's stat alone (no inotify or kqueue, which differ by OS and need cgo or a module), which polling every Interval makes cheap enough: one stat a poll while nothing changes.
A text table (CSV, TSV, JSON lines, NUON; fileio.Kind.Grows) is read as it grows: each poll reads what was appended, and a record cut off at the end waits for the rest (fileio.Tail). The file is read again whole when it shrinks (truncated), is another file (rotated: the path names a new inode), or its bytes before where reading stopped differ (rewritten in place). Any other format is read again whole when its size or modification time changes, once they have held still for Debounce, so a file being written isn't read half done.
func NewFile ¶
NewFile follows the file at path (on disk) in format k, with opt's table, query and locale (fileio.Options); name is how the user named it.
type Snapshot ¶ added in v0.5.0
type Snapshot struct {
NUON []byte // the values kept, as NUON gives them
// More are the values printed after the first seen (Snapshot's
// argument), as a NUON list, so what shows the output can add them
// to what it shows rather than read it all again; nil when some of
// them are kept no more.
More []byte
// Values and Rows are how many values and rows have been printed.
Values, Rows int
}
Snapshot is what a stream has printed, read at one moment.
type Source ¶
type Source interface {
// Poll looks once for what changed since the last poll. It reports
// false when nothing did. Polls never overlap.
Poll(ctx context.Context) (Update, bool)
// Reload has the next poll read the table again, whole.
Reload()
// Close lets the source go; it is polled no more.
Close()
}
A Source yields a table's rows as they change.
type Stream ¶ added in v0.5.0
type Stream struct {
// Wait is how long a poll waits for the program to print.
Wait time.Duration
// Keep is how many of the last values are kept.
Keep int
// Now is the clock; tests replace it.
Now func() time.Time
// contains filtered or unexported fields
}
Stream follows a program that prints a table as it makes it: NUON values one after another, one to a line, as a notebook cell run as a stream prints them (nushell.Stream). The program starts with the stream and runs on a goroutine of its own until it ends or the stream is closed. A poll waits up to Wait for something to arrive, so rows reach the region as soon as the program prints them, and the owner polls again at once rather than after Interval.
It keeps the last Keep values printed, for the cell's output (NUON) and for reading the table whole again (Reload).
func NewStream ¶ added in v0.5.0
NewStream starts run, which prints the table to w until ctx is done, and follows what it prints.
func (*Stream) Close ¶ added in v0.5.0
func (s *Stream) Close()
Close stops the program; the stream is polled no more.
func (*Stream) Ended ¶ added in v0.5.0
Ended reports whether the program has ended and the last poll gave what it printed, and why it failed if it did (nil when it ended well or was stopped).
func (*Stream) NUON ¶ added in v0.5.0
NUON is the values kept, as a NUON list: the cell's output so far.
func (*Stream) Poll ¶ added in v0.5.0
Poll waits up to Wait for the program to print, and returns the rows it completed: all of those kept again after Reload, and the reason it failed once it ends with an error.
func (*Stream) Reload ¶ added in v0.5.0
func (s *Stream) Reload()
Reload has the next poll give every row kept again.
type Update ¶
type Update struct {
// Reset has Rows replace every row; otherwise they follow the last.
Reset bool
// Header is the table's first row when it's new or changed.
Header sheet.LiveRow
Rows []sheet.LiveRow
// Err says why the source can't be read, "" once it can.
Err string
// Note says what was left out or changed in reading.
Note string
// More is set when more is waiting to be read at once, rather than
// after the next interval.
More bool
// At is when the poll found it.
At time.Time
}
Update is what a poll found.
Source Files