analysis

type Cell struct {
	Index  int    // position among the notebook's code cells
	Source string // the cell's source
	Lang   string // Go, or Ruby (see AnalyzeRubyCell)

	// Dynamic marks a cell whose names are not statically resolvable (see
	// Names).
	Dynamic bool

	Chunks []Chunk

	// Defines lists the notebook variables the cell defines: those of its
	// declarations, then those of its statements, each in order of
	// appearance. Funcs and Types are the subsets declared with func and
	// type. Imports maps a package name to its import path.
	Defines []string
	Funcs   []string
	Types   []string
	Imports map[string]string

	// Consts are the constants, classes and modules a Ruby cell defines.
	Consts []string

	// RubyDisplay reports that a Ruby cell ends in an expression, whose value
	// it shows. (A Go cell's is Display.)
	RubyDisplay bool

	// Uses lists the free identifiers the cell reads, sorted: notebook
	// variables, package names other cells import, builtins, and names
	// that are not defined anywhere (the compiler reports those).
	Uses []string

	// OwnPackages lists, sorted, the names of the packages the cell imports
	// itself and refers to.
	OwnPackages []string

	// Display is the cell's final expression statement, if any, and its
	// byte range in Source.
	Display                  ast.Expr
	DisplayStart, DisplayEnd int

	// Assigns lists the free identifiers the cell assigns to (=, op=, ++,
	// --), with the offset of each assignment.
	Assigns []Use

	// Errors are syntax errors, with offsets in Source.
	Errors []Error
}

type CellAnalyzer interface {
	AnalyzeCell(index int, src string) *Cell
}

type Chunk struct {
	Decl       bool
	Start, End int // byte offsets in the cell's source
}

type Diagnostic = Error

type Error struct {
	Cell int
	Pos  int
	Msg  string
}

type Graph struct {
	Cells []*Cell

	// Owner maps each notebook variable to the cell that defines it.
	Owner map[string]int

	// Deps[i] lists the cells cell i reads from, sorted; Dependents is the
	// reverse relation.
	Deps, Dependents [][]int

	// Order is an execution order: every cell after the cells it reads, and
	// otherwise in document order. It holds every cell when Errors is empty.
	Order []int

	// Errors lists syntax errors, names defined twice, assignments to
	// another cell's variable, and dependency cycles.
	Errors []Error
}

type Highlighter interface {
	Lexer() string
}

type Language interface {
	// Name is the fence word: "go", "ruby", "julia"…
	Name() string

	// Analyze finds the names a cell defines and uses, and its syntax errors.
	// It returns an error, not a panic, when src exceeds lim.
	Analyze(src string, lim Limits) (Names, []Diagnostic, error)

	// Crosses reports whether cell user, of another language, sees name,
	// which cell owner, of this language, defines. Within a language every
	// name is shared and Crosses is not asked.
	Crosses(owner, user *Cell, name string) bool

	// Run is the run capability of the language.
	Run() Run
}

type Limits struct {
	MaxBytes int // the longest source, in bytes
	MaxDepth int // the deepest nesting of brackets and blocks
}

type Module struct {
	Path    string // the import path of the package the generated program imports
	Module  string // the module that holds Path
	Version string // the version the work module requires by default
}

type NameChecker interface {
	ValidName(name string) bool
}

type Names struct {
	Defines, Uses []string

	// Dynamic marks a cell whose names cannot be resolved statically: it
	// assigns or reads names computed at run time (R's <<-, assign, get,
	// eval(parse()), attach, library()). The graph makes such a cell depend on
	// every earlier cell, and every later cell that reads any name depend on
	// it.
	Dynamic bool
}

type Run struct {
	// Runs is true when the language's cells execute.
	Runs bool

	// The rest is set when Runs is false: a cell is parsed and checked only.
	// NotRun is the cell's own failure. Blocked(c) is the failure of a cell
	// that reads, through the graph, what cell c defines; Reads(c) and
	// ReadsBlocked(c) say the same when the generator defers a Go cell that
	// reads cell c directly, or reads a cell blocked by cell c.
	NotRun       string
	Blocked      func(cell int) string
	Reads        func(cell int) string
	ReadsBlocked func(cell int) string
}

type Runtime interface {
	Runtime() Module
}

type Source struct {
	Lang   string // Go or Ruby; "" is Go
	Source string
}

type TypeLearner interface {
	LearnsTypes() bool
}

type Use struct {
	Name string
	Pos  int
}