nushell

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: 16 Imported by: 0

Documentation

Overview

Package nushell runs a notebook's code cells: each is a nushell pipeline run by `nu` as a separate process, reading other cells' outputs and ranges of sheets as variables ($sales, $selection), and printing what it made as NUON, which the notebook keeps as the cell's output. Tables reach nu as NUON in files it opens, never as text spliced into the pipeline. The package knows neither the terminal nor the notebook: the UI hands it a Job and gets back NUON.

Index

Constants

View Source
const MinVersion = "0.100.0"

MinVersion is the oldest nu asked about scripts.

Variables

View Source
var ErrMissing = errors.New("nu isn't installed or isn't on your PATH: see docs/nushell/notebooks.md")

ErrMissing is what running a cell says when nu isn't installed.

View Source
var ErrOld = errors.New("nu is too old to ask about pipelines")

ErrOld is a nu too old to ask, or one whose answers don't read.

View Source
var ErrTooLarge = errors.New("the output is too large to keep")

ErrTooLarge is a run that printed more than it may keep.

Functions

func AtLeast

func AtLeast(v, oldest string) bool

AtLeast reports whether version v is oldest or later; one that doesn't read as major.minor.patch isn't.

func Commands

func Commands(ctx context.Context, r Runner, timeout time.Duration) ([]string, error)

Commands lists nu's command names, for completing them.

func Complete

func Complete(ctx context.Context, r Runner, script string, offset int) ([]string, error)

Complete is what nu would complete at offset, a byte of script, in its order. nu says what goes there, not what it replaces.

func Exec

func Exec(ctx context.Context, r Runner, job Job, timeout time.Duration, maxBytes int) ([]byte, error)

Exec runs job and returns what it printed, NUON, at most maxBytes of it, within timeout.

func ExecVars added in v0.5.0

func ExecVars(ctx context.Context, r Runner, job Job, timeout time.Duration, maxBytes int) ([]byte, map[string][]byte, error)

ExecVars runs job as Exec does, returning its output and, when it hands back variables (Job.Vars), their values, each as NUON. They're the last lines it printed, each a name and its NUON as base64, so what the pipeline printed itself before them doesn't mix in.

func Message

func Message(stderr string, err error) string

Message is the line of nu's standard error that says what went wrong: the one marked ×, or the first, or how the process ended.

func ParseComplete

func ParseComplete(out []byte) ([]string, error)

ParseComplete reads what --ide-complete printed.

func Script

func Script(job Job, names []string) string

Script is what nu runs for job: the tables bound to their names, then the pipeline, its output as NUON. The files are named by environment variables (NU012_TABLE_0 and so on) the runner sets, so no data and no path is written into the script.

func Stream added in v0.5.0

func Stream(ctx context.Context, r Runner, job Job, w io.Writer) error

Stream runs job as a stream, writing to w a line of NUON for each value the pipeline yields, until the pipeline ends or ctx is done. It has no timeout: the stream runs until it's stopped.

func StreamScript added in v0.5.0

func StreamScript(job Job, names []string) string

StreamScript is what nu runs for job as a stream: the tables bound to their names, as Script binds them, then the pipeline, each value it yields printed as NUON on a line of its own.

func Version

func Version(ctx context.Context, r Runner) (string, error)

Version is nu's version, checked against MinVersion: ErrOld when it's older or doesn't read as one.

Types

type Error

type Error struct {
	Msg    string
	Stderr string
}

Error is a pipeline that failed: nu's message, and all it wrote to standard error.

func (*Error) Error

func (e *Error) Error() string

func (*Error) Help

func (e *Error) Help() string

Help is the help line of nu's message, "help: ...", or "".

type Job

type Job struct {
	Command string
	// Tables are what the pipeline reads, by variable name, as NUON:
	// each becomes the variable of its name.
	Tables map[string][]byte
	// Config runs nu with the user's config files rather than without.
	Config bool
	// Vars are the variables the run hands back beside its output: the
	// command ends in a record of its output, as __out, and each of
	// them, and the run prints each as a line of its own (ExecVars).
	Vars []string
	// IDE asks nu about the script rather than running it: the flags
	// that ask (--ide-ast, or --ide-complete 14), nu reading the script
	// from a file named after them, without config files or the
	// standard library (see ide.go).
	IDE []string
}

Job is a pipeline to run.

type Nu

type Nu struct {
	// Path is the program; "" finds nu on the PATH.
	Path string
}

Nu is the real runner: `nu -c` in a process of its own.

func (Nu) Run

func (n Nu) Run(ctx context.Context, job Job, script string, stdout io.Writer) error

Run implements Runner.

type Problem

type Problem struct {
	From, To int
	Severity string // Error or Warning
	Msg      string
}

Problem is what nu's check found wrong with a stretch of a script.

func Check

func Check(ctx context.Context, r Runner, script string, limit int) ([]Problem, error)

Check is what nu's check finds wrong with script, at most limit problems, each once.

func ParseCheck

func ParseCheck(out []byte) ([]Problem, error)

ParseCheck reads what --ide-check printed: its diagnostics, each once, leaving out its hints (the types it inferred).

type Runner

type Runner interface {
	Run(ctx context.Context, job Job, script string, stdout io.Writer) error
}

Runner runs a job's script, writing what it prints to stdout. A test substitutes a fake for the real nu.

type Shape

type Shape struct {
	From, To int
	Shape    string
}

Shape is a stretch of a script, by byte offsets, and nu's name for what it is: shape_internalcall, shape_string.

func AST

func AST(ctx context.Context, r Runner, script string) ([]Shape, error)

AST is nu's shapes of script's tokens, in order.

func ParseAST

func ParseAST(out []byte) ([]Shape, error)

ParseAST reads what --ide-ast printed.

Directories

Path Synopsis
Package module holds 012.nu, the nushell module that gives 012 the command `sheet`, so nushell users needn't type `^012` (a bare 012 is a number to nushell).
Package module holds 012.nu, the nushell module that gives 012 the command `sheet`, so nushell users needn't type `^012` (a bare 012 is a number to nushell).

Jump to

Keyboard shortcuts

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