Documentation
¶
Overview ¶
Package notebook is a notebook's document: its cells (code cells holding a nushell pipeline, note cells holding Markdown), the names cells give their outputs, what each cell reads, the order cells run in, and what a cell's last run left (its output). It knows nothing of sheets, terminals or nu itself: the engine (internal/sheet) keeps a notebook tab's cells in its undo history and its file, and the UI runs them and draws them.
Index ¶
- Constants
- Variables
- func Dependents(cells []Cell, i int) []int
- func Inputs(cells []Cell, i int, output func(id int) *Output) []int
- func Kept(cells []Cell, output func(id int) *Output, caps Caps) map[int]bool
- func Names(cells []Cell) map[string]int
- func Order(cells []Cell, want []int) (order, cycle []int)
- func Readable(c Cell, name string, o *Output) bool
- func Reads(cells []Cell, vars map[string]int, i int) []int
- func Settle(cells []Cell, outputs map[int]*Output)
- func Stale(cells []Cell, output func(id int) *Output) map[int]bool
- func Taken(cells []Cell, i int) string
- func ValidName(name string) error
- func Vars(cells []Cell) map[string]int
- func WithName(src, name string) string
- type Caps
- type Cell
- type Kind
- type Output
- type Run
- type SheetRef
- type Source
- type Stmt
Constants ¶
const OutputVar = "__out"
OutputVar is the name of the variable that holds a cell's output in the record a run hands back when it also hands back variables (nushell.ExecVars).
const Selection = "selection"
Selection is the variable that holds the selection.
Variables ¶
var DefaultCaps = Caps{Cell: 1 << 20, Total: 8 << 20}
DefaultCaps keep 1 MB of a cell's output and 8 MB of a notebook's.
var Reserved = []string{"in", "env", "nu", "it", "selection", "sheet"}
Reserved are nushell's own variables and the notebook's: $selection is the selection on a sheet, $sheet.A1:C9 a range of one.
Functions ¶
func Dependents ¶
Dependents returns the cells that read cell i, directly or through others, in the notebook's order.
func Inputs ¶
Inputs returns the cells cell i reads, directly or through others, whose outputs don't hold what it reads (Readable), in the notebook's order: what has to run before it can.
func Kept ¶
Kept returns the cells, by ID, whose outputs a file keeps within caps: in the notebook's order, each that fits in what's left.
func Order ¶
Order returns the code cells of want, each after the cells it reads among them, in want's order otherwise, and the cells left out for reading themselves, directly or through others.
func Readable ¶ added in v0.5.0
Readable reports whether o, the output of cell c, holds the variable name: c's output when c is named so, else a variable it assigns, which a file doesn't keep.
func Reads ¶
Reads returns the indices of the cells cell i reads, in the order it names them; vars is Vars(cells).
func Settle ¶
Settle makes outputs read from a file what their cells' runs would have left: made from the source as it is, having read the outputs as they are, so none is stale until something changes.
func Stale ¶
Stale returns the cells, by ID, whose output may not be what running them now would give: their source changed since, or an output they read changed or is stale itself.
func Taken ¶
Taken says why cell i can't use its name: an earlier cell gives it (names ignore case there, as formulas' nu.name do), or "".
func ValidName ¶
ValidName checks that name can name a cell's output: a nushell variable's name of letters, digits and _, not starting with a digit, not one of Reserved, and not starting with __, which the notebook's own variables do.
Types ¶
type Caps ¶
type Caps struct{ Cell, Total int }
Caps are how much of the outputs a file keeps, in bytes of NUON: at most Cell of one cell's, Total of all of them.
type Cell ¶
type Cell struct {
// ID identifies the cell for as long as the workbook is open: its
// output is kept by it. It isn't saved.
ID int
Kind Kind
Source string
}
Cell is one cell of a notebook. Cells are values: a change makes a new one, so the undo history can keep the list it replaced.
type Output ¶
type Output struct {
// NUON is what the pipeline printed, as NUON; nil when it failed or
// its output wasn't saved.
NUON []byte
// Err is nu's message when the run failed, and Detail the rest of
// what it said (its help line).
Err, Detail string
// Note says what was left out.
Note string
// Count is the run's number in this session, [3]; 0 for an output
// read from the file.
Count int
// Seq identifies the output among the workbook's, for telling
// whether what a cell read has changed since.
Seq int
// Vars are the values, as NUON, of the variables the cell assigns
// other than its output, which later cells read by name. A file
// doesn't keep them: a cell reading one runs its cell first.
Vars map[string][]byte
// Took is how long the run took.
Took time.Duration
// Source is the cell's source when it ran.
Source string
// Reads are the Seqs of the outputs the run read, by name.
Reads map[string]int
// Selection is the range the run read as $selection, "Sheet1!A1:C9".
Selection string
// Unsaved is set on an output the file didn't keep, being larger
// than the caps allowed: there's nothing to show until it runs.
Unsaved bool
}
Output is what a code cell's last run left: what it printed, as NUON, or why it failed. Outputs are values too, replaced whole.
type Run ¶ added in v0.5.0
type Run struct {
// Command is what nu runs (Source.Command), and Exports the
// variables it hands back beside the output.
Command string
Exports []string
// Stream is what nu runs to stream the cell (Source.StreamCommand).
Stream string
// Tables are the other cells' outputs and variables it reads, by
// name, as NUON, and Reads the Seqs of the outputs they came from.
Tables map[string][]byte
Reads map[string]int
// Others are the names it reads that no cell gives: linked files,
// or nothing nu will say so of.
Others []string
// Ranges are the ranges of sheets it reads, and Selection whether it
// reads $selection.
Ranges []SheetRef
Selection bool
}
Run is what running a code cell takes that the notebook knows: what nu runs, and the variables it reads from other cells. The screen and the headless runner each add what only they know: linked files, the selection and ranges of sheets.
type SheetRef ¶
type SheetRef struct {
// Ref is the range as written after $sheet.: "A1:C9", "Sales!A1:C9".
Ref string
// Var is the variable it's read as once renamed: __sheet1.
Var string
}
SheetRef is a range of a sheet a pipeline reads, $sheet.A1:C9.
type Source ¶ added in v0.5.0
type Source struct {
Text string
// Stmts are its statements, in order.
Stmts []Stmt
// Comments are its comments' bytes, # to the end of the line, and
// Strings its strings', quotes included.
Comments, Strings [][2]int
// Ranges are where it reads ranges of sheets, each $sheet.A1:C9
// whole.
Ranges [][2]int
// contains filtered or unexported fields
}
Source is a code cell's source as 012 reads it.
func (Source) Assigned ¶ added in v0.5.0
Assigned are the names the statements assign, in the order they first do.
func (Source) Command ¶ added in v0.5.0
Command is what nu runs for the source: each statement but the last that assigns a name as `let name = ...`, the last without its `name =` (its value is the output), the ranges of sheets renamed to variables of their own ($__sheet1), and the comments blanked, so what's left keeps its place. When statements before the last assign names the last doesn't, those are exports, and the command ends in a record of the output (as __out) and each of them.
func (Source) Heads ¶ added in v0.5.0
Heads are the bytes of each assignment's `name =`, up to what it runs.
func (Source) Name ¶ added in v0.5.0
Name is what the source's last statement assigns: the cell's output's name, or "".
func (Source) ReadsSelection ¶ added in v0.5.0
ReadsSelection reports whether the source reads $selection.
func (Source) Refs ¶ added in v0.5.0
Refs are the names the source reads as $name from outside it, in the order it first names them: not a name an earlier statement assigns or binds with let, nor nushell's variables and the notebook's own ($selection, $sheet), nor one in a comment or a string.
func (Source) StreamCommand ¶ added in v0.5.0
StreamCommand is what nu runs for the source as a stream: Command without the record, so the last statement's values stream as they come, and the names the statements before it assign stay the run's.
type Stmt ¶ added in v0.5.0
type Stmt struct {
// From and To are its bytes, without the spaces and comments around.
From, To int
// Body is where what it runs starts: after `name =`, or From.
Body int
// Name is what `name = pipeline` assigns, or "".
Name string
// Local is the variable `let name = ...` or `mut name = ...` binds,
// which only the cell's later statements read, or "".
Local string
}
Stmt is a statement of a source, by byte offsets into it.
Source Files