nbview

package
v0.5.0 Latest Latest
Warning

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

 Go to latest Published: Sep 30, 2026 License: MIT Imports: 20 Imported by: 0

Documentation

Overview

Package nbview draws a notebook tab and takes its keys and clicks, as Jupyter does: cells one under another, a code cell's pipeline in a box with its [n]: prompt and a ▶ that runs it, its output under it after Out[n]:, and a note cell's Markdown drawn as text. The active cell has a bar at its left. Like Jupyter it has two modes: in command mode keys act on cells (move, select several, add, delete, move them, run), in edit mode they type into the active cell. A toolbar over the cells runs the same commands. It knows the UI only through Host: the cells and outputs, the state of runs, and running the registered commands every action is.

Index

Constants

View Source 
const Back = "back"

Back is what ToolbarAt says of the button that leaves a full-screen output, which has no command.

View Source 
const Window = window

Window is how many rows an output's window shows.

Variables

This section is empty.

Functions

func KeyLabel 

func KeyLabel(k string) string

KeyLabel is how a key of Keys shows: "d d" as dd, a letter as it is typed (G is Shift+g), others as chips show them.

Types

type Checker 

type Checker interface {
	Check(ctx context.Context, src string) []Diagnostic
}

Checker finds the problems in a pipeline.

type Completer 

type Completer interface {
	Complete(ctx context.Context, src string, offset int) []Completion
}

Completer lists what can go at the caret, a byte offset into src.

type Completion 

type Completion struct {
	Text     string
	Desc     string
	From, To int
}

Completion is a word Tab can put at the caret: Text in place of src[From:To].

type Diagnostic 

type Diagnostic struct {
	From, To int
	Msg      string
}

Diagnostic is a problem with part of a pipeline, by byte offsets.

type Drafter 

type Drafter interface{ Draft(src string) []Span }

Drafter is a slow highlighter with a quick draft, drawn until its answer comes, and in place of one while it's Instant.

type Entry 

type Entry struct {
	Cell  int    // the cell's index
	Level int    // a heading's level, 1 for #; 0 for a cell
	Title string // the heading's text, or the cell's first line
}

Entry is a place in the notebook to jump to: a heading of a note, or a cell.

type Full 

type Full struct {
	Title string
	// contains filtered or unexported fields
}

Full is an output shown full-screen, read-only: a table or record as the UI's grid at the body's size, which the UI gives the keys, and anything else as its lines, scrolled with a pointer. Esc goes back to the notebook.

func (*Full) ContextLine 

func (f *Full) ContextLine(th *theme.Theme) (string, string)

ContextLine says what's shown and the keys.

func (*Full) Grid added in v0.5.0 

func (f *Full) Grid() Grid

Grid is the output's grid, when it's drawn as one: the UI gives it the keys.

func (*Full) Key 

func (f *Full) Key(k tea.KeyPressMsg) (closed bool)

Key takes a key, reporting whether Esc left the view.

type Grid added in v0.5.0 

type Grid interface {
	// Rows is how many rows the grid has showing: the rows a filter
	// keeps, the header not counted.
	Rows() int
	// Top is the first row the window shows, counted among those.
	Top() int
	// Scroll scrolls the window d rows, reporting whether it moved.
	Scroll(d int) bool
	// Line draws line i of a window of rows rows at width, showing the
	// rows from row from on: the column header for 0, then the rows.
	Line(i, from, rows, width int) string
	// Hidden is how many of the grid's columns don't show at width.
	Hidden(width int) int
	// Entered reports whether the grid has the keys: its active cell
	// and selection show, and arrows move them.
	Entered() bool
	// Append adds more, a NUON table of n rows, under the grid's rows,
	// as a stream's rows arrive; data is the whole output now.
	Append(more []byte, n int, data []byte)
}

Grid is an output drawn as the UI's grid.

type Highlighter 

type Highlighter interface {
	Highlight(ctx context.Context, src string) []Span
}

Highlighter says what each part of a pipeline is.

type Host 

type Host interface {
	Theme() *theme.Theme
	Locale() *locale.Locale
	// Cells are the notebook's cells, and Output a cell's output.
	Cells() []notebook.Cell
	Output(id int) *notebook.Output
	// State is how a cell's run stands, and Kernel how running stands.
	State(id int) State
	Kernel() Kernel
	// Run runs a registered command, as its key would.
	Run(command string) tea.Cmd
	// Edit keeps a cell's new source, as one undo step.
	Edit(id int, source string)
	// Grid draws cell id's output, a table or record, as the UI's
	// grid: data is the grid's table as NUON (a record's fields as
	// rows), of rows rows.
	Grid(id int, data []byte, rows int) Grid
}

Host is what the notebook needs of the UI.

type Instant 

type Instant interface{ Instant() bool }

Instant is a highlighter quick enough to ask while drawing, as the built-in tokenizer is.

type Kernel 

type Kernel struct {
	Busy     bool   // a cell is running
	Waiting  int    // cells waiting to run
	Live     int    // cells running as streams
	Off      string // why cells don't run here, or ""
	Reactive bool   // cells reading a cell run again when it runs
	Clip     int    // cells copied, for Paste
}

Kernel is how running cells stands, for the toolbar: Jupyter's kernel, which here is nu started for each cell.

type Nu 

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

Nu is a notebook's language as nu itself knows it: highlighting from its --ide-ast shapes, completions from --ide-complete after the notebook's own words, and problems from --ide-check.

nu doesn't know the variables a notebook binds ($sales, $selection, $sheet.A1:C9) nor a cell's `name =`, so it's asked about the source with those declared before it, in a prelude, and the cell's name and ranges of sheets masked to as many bytes, so offsets map back by the prelude's length alone (see prepare).

func (*Nu) Check 

func (n *Nu) Check(ctx context.Context, src string) []Diagnostic

Check implements Checker: nu's problems with the pipeline, leaving out those that only say it's unfinished at its end, as it is while it's typed.

func (*Nu) Complete 

func (n *Nu) Complete(ctx context.Context, src string, offset int) []Completion

Complete implements Completer: the notebook's words, then nu's that they don't have.

func (*Nu) Draft 

func (n *Nu) Draft(src string) []Span

Draft implements Drafter: the tokenizer's answer, drawn until nu's comes.

func (*Nu) Highlight 

func (n *Nu) Highlight(ctx context.Context, src string) []Span

Highlight implements Highlighter: nu's shapes, or the tokenizer's when nu doesn't answer.

func (*Nu) Instant 

func (n *Nu) Instant() bool

Instant implements Instant: while nu isn't asked, the tokenizer answers at once.

func (*Nu) SetWords 

func (n *Nu) SetWords(names []string, words []Word)

SetWords gives the notebook's names: the variables it binds besides $selection (its cells' names and linked files'), and the built-in completer's words. It's called where the notebook changes, so no question reads the notebook itself.

type NuSession 

type NuSession struct {
	Runner nushell.Runner
	// Timeout bounds each question; 0 is a second and a half.
	Timeout time.Duration
	// contains filtered or unexported fields
}

NuSession is what a session's questions to nu share: whether nu may be asked, whether it answers, and how many questions are out. Each question is a process of its own, asked in the background once typing pauses, at most two at a time, stopped when the text it's about is stale and after Timeout. While nu can't be asked (SetOn said no, it isn't installed, it's older than nushell.MinVersion, or it timed out three times in a row) the notebook's Nu answers as the built-ins do, and nu isn't started.

func NewNuSession 

func NewNuSession(r nushell.Runner) *NuSession

NewNuSession returns a session asking nu through r, once SetOn allows it.

func (*NuSession) Asking 

func (s *NuSession) Asking() bool

Asking reports whether nu is asked: allowed, and not found missing, old or slow.

func (*NuSession) For 

func (s *NuSession) For() *Nu

For returns a notebook's Nu, asking through the session.

func (*NuSession) SetOn 

func (s *NuSession) SetOn(on bool)

SetOn says whether nu may be asked: in 012 serve only as serve-shell allows, and only about a notebook whose cells may run here without asking (docs/nushell/notebooks.md#saving-and-trust).

type Providers 

type Providers struct {
	Highlighter Highlighter
	Completer   Completer
	Checker     Checker
}

Providers are the language's answers for a notebook; any may be nil.

type Span 

type Span struct {
	From, To int
	Kind     theme.Syntax
}

Span is a stretch of a cell's source, by byte offsets, and what it is.

type State 

type State struct {
	Waiting, Running bool
	Started          time.Time // when it started running
	// Live is set while it runs as a stream, and Rows counts the rows
	// the stream has printed.
	Live  bool
	Rows  int
	Stale bool // what it read, or its source, changed since it ran
	// Problem says why it can't run as it is: its name is taken.
	Problem string
}

State is how a cell's run stands, as the runner knows it.

type Tokens 

type Tokens struct{}

Tokens is the built-in highlighter: a small tokenizer of nushell's shapes, which knows commands by where they stand rather than by name.

func (Tokens) Highlight 

func (Tokens) Highlight(_ context.Context, src string) []Span

Highlight implements Highlighter.

func (Tokens) Instant 

func (Tokens) Instant() bool

Instant implements Instant: the tokenizer is.

type View 

type View struct {

	// Keys bind command mode's keys to commands, EditKeys edit mode's;
	// "d d" is d pressed twice.
	Keys, EditKeys map[string]string
	Providers      Providers
	// contains filtered or unexported fields
}

View is a notebook tab's view and its state: the selected cells, the scroll position, the mode, and what's worked out from the cells.

func New 

func New(h Host) *View

New returns a view of the notebook h shows.

func (*View) Boxes 

func (v *View) Boxes(top int) []overlay.Box

first line is at screen row top.

func (*View) Carry added in v0.5.0 

func (v *View) Carry(id int, old, o *notebook.Output, more []byte) bool

Carry shows o, cell id's output, as old showed: o is old with the rows a stream printed since, more (a NUON list), so they go under the rows of old's grid, whose widths, pointer, selection, sort and filter stay, rather than o being read whole. It reports false, and o is read afresh when it shows, when old isn't showing as a table's grid, more isn't a table, or the grid would hold more than maxCarried rows.

func (*View) Cell 

func (v *View) Cell() (notebook.Cell, bool)

Cell is the active cell, if there is one.

func (*View) Click 

func (v *View) Click(x, y int, shift bool) tea.Cmd

Click takes a left click at column x of line y of the body; shift extends the selection to the cell clicked.

func (*View) CloseFull 

func (v *View) CloseFull()

CloseFull goes back from a full-screen output.

func (*View) Commit 

func (v *View) Commit()

Commit keeps what's typed as the cell's source, still editing.

func (*View) Completions 

func (v *View) Completions() ([]Completion, int)

Completions are the completions shown, and the highlighted one.

func (*View) ContextLine 

func (v *View) ContextLine() (string, string)

ContextLine is what the context line says in the notebook, at its left and its right: a problem, a key waiting for its pair, or what the selection is, and the keys that apply that the toolbar doesn't show.

func (*View) Cursor 

func (v *View) Cursor() (x, y int, ok bool)

Cursor is where the terminal's caret goes in the body, while a cell is edited.

func (*View) Diagnostic 

func (v *View) Diagnostic() string

Diagnostic is the problem the caret is on, for the context line, or "" when it is on none.

func (*View) Editing 

func (v *View) Editing() bool

Editing reports whether a cell is being edited.

func (*View) Fetch 

func (v *View) Fetch() tea.Cmd

Fetch asks the highlighter about the sources drawn without an answer, in the background.

func (*View) FollowOutput added in v0.5.0 

func (v *View) FollowOutput()

FollowOutput scrolls so the selected output's window shows, as far as it fits: its grid's active cell moved, or the grid changed its height.

func (*View) Full 

func (v *View) Full() *Full

Full is the output shown full-screen, or nil.

func (*View) FullOpen 

func (v *View) FullOpen() bool

FullOpen reports whether an output is shown full-screen.

func (*View) GridAt added in v0.5.0 

func (v *View) GridAt(x, y int) (g Grid, gx, gy int, ok bool)

GridAt is the grid at column x of line y of the body, with where that is in the grid: gy 0 its column header, then its rows as the window shows them.

func (*View) GridOrigin added in v0.5.0 

func (v *View) GridOrigin(g Grid) (x, y int, ok bool)

GridOrigin is where grid g's column header is drawn in the body: its first column and line, which may be off screen.

func (*View) GridWidth added in v0.5.0 

func (v *View) GridWidth() int

GridWidth is how wide an output's grid is drawn: the output's width, or the body's full-screen.

func (*View) Head 

func (v *View) Head() (name, text string)

Head is what the formula bar says of the selection: the cell's name or number, and what it reads, or what its output holds.

func (*View) Hidden 

func (v *View) Hidden(id int) bool

Hidden reports whether cell id's output is folded to a line, and Whole whether it shows every row rather than a window.

func (*View) Key 

func (v *View) Key(k tea.KeyPressMsg) (tea.Cmd, bool)

Key takes a key, reporting whether the notebook took it.

func (*View) Lines 

func (v *View) Lines() []string

Lines draws the body: height lines, each width wide or less.

func (*View) OpenFull 

func (v *View) OpenFull() bool

OpenFull shows the selected cell's output full-screen.

func (*View) Outline 

func (v *View) Outline(cells bool) []Entry

Outline is the notebook's headings in order, from its notes' Markdown: its table of contents. With cells, every cell is there too, a code cell by its first line and a note by its first heading or line.

func (*View) Paste 

func (v *View) Paste(text string) tea.Cmd

Paste types text into the cell being edited.

func (*View) Pending 

func (v *View) Pending() string

Pending is the first key of a pair waiting for its second: "d" or "0".

func (*View) Range 

func (v *View) Range() (from, to int)

Range is the selected cells, first and last: the active cell alone, or the run of cells Shift+Up and Down selected with it.

func (*View) Resize 

func (v *View) Resize(width, height int)

Resize sets the body's size: the lines under the toolbar and above the status line.

func (*View) Reveal 

func (v *View) Reveal(id int)

Reveal scrolls so cell id's block shows, as far as it fits, without selecting it: the cell running while every cell runs.

func (*View) RightClick 

func (v *View) RightClick(y int)

RightClick selects the cell at line y for its context menu, unless it's one of the cells selected.

func (*View) Rule 

func (v *View) Rule(left, right string, width int) string

Rule is the context line drawn at width: left, then a rule, then right, the rule closing off the toolbar above the cells.

func (*View) Select 

func (v *View) Select(i int, out bool)

Select makes cell i active and selects it alone, or its output with out.

func (*View) SelectGrid added in v0.5.0 

func (v *View) SelectGrid(g Grid)

SelectGrid selects the output grid g is drawn in.

func (*View) SelectRange 

func (v *View) SelectRange(from, to int)

SelectRange selects cells from to to, the last one active.

func (*View) Selected 

func (v *View) Selected() (int, bool)

Selected is the active cell's index, and whether its output is selected rather than the cell.

func (*View) SelectedGrid added in v0.5.0 

func (v *View) SelectedGrid() Grid

SelectedGrid is the selected output's grid, if it's selected and drawn as one.

func (*View) Shows added in v0.5.0 

func (v *View) Shows(g Grid) bool

Shows reports whether grid g is the selected output's, or shown full-screen.

func (*View) StartEdit 

func (v *View) StartEdit() tea.Cmd

StartEdit edits the selected cell, the caret at the end of its source.

func (*View) StopEdit 

func (v *View) StopEdit()

StopEdit leaves edit mode, keeping what was typed.

func (*View) ToggleHidden 

func (v *View) ToggleHidden()

ToggleHidden folds the selected cells' outputs to a line, or shows them again, as Jupyter's o.

func (*View) ToggleWhole 

func (v *View) ToggleWhole()

ToggleWhole shows the selected cells' outputs whole, or in their windows again, as Jupyter's Shift+O toggles scrolling.

func (*View) Toolbar 

func (v *View) Toolbar(width int) string

Toolbar draws the toolbar at width: the full-screen output's title while one is open.

func (*View) ToolbarAt 

func (v *View) ToolbarAt(x, width int) string

ToolbarAt is the command of the button at column x of the toolbar, or "".

func (*View) Update 

func (v *View) Update(msg tea.Msg) (tea.Cmd, bool)

Update takes the view's own messages, reporting whether msg was one.

func (*View) Wheel 

func (v *View) Wheel(y, d int)

Wheel scrolls d lines with the mouse at line y: the output's window under it while it has more that way, or the body.

func (*View) Whole 

func (v *View) Whole(id int) bool

type Word 

type Word struct {
	Text string // $sales, or a command: sort-by
	Desc string
}

Word is a completion the built-in completer offers.

type Words 

type Words func() []Word

Words is the built-in completer: the notebook's names at a $, nu's commands where a command goes.

func (Words) Complete 

func (ws Words) Complete(_ context.Context, src string, offset int) []Completion

Complete implements Completer.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.