goexec

Documentation

Overview

Package goexec executes cells with Go sampleCellCode for the gonb kernel.

It defines a State object, that carries all the globals defined so far. It provides the ExecuteCell method, to run a new cell.

Index

• Constants
• Variables
• type Constant
  • func (c *Constant) Render(w *WriterWithCursor, cursor *Cursor)
• type Cursor
  • func (c *Cursor) ClearCursor()
  • func (c *Cursor) CursorFrom(line, col int) Cursor
  • func (c *Cursor) HasCursor() bool
• type Declarations
  • func NewDeclarations() *Declarations
  • func (d *Declarations) ClearCursor()
  • func (d *Declarations) Copy() *Declarations
  • func (d *Declarations) MergeFrom(d2 *Declarations)
  • func (d *Declarations) RenderConstants(w *WriterWithCursor) (cursor Cursor)
  • func (d *Declarations) RenderFunctions(w *WriterWithCursor) (cursor Cursor)
  • func (d *Declarations) RenderImports(w *WriterWithCursor) (cursor Cursor)
  • func (d *Declarations) RenderTypes(w *WriterWithCursor) (cursor Cursor)
  • func (d *Declarations) RenderVariables(w *WriterWithCursor) (cursor Cursor)
• type ElementType
  • func (i ElementType) String() string
• type Function
• type Import
  • func NewImport(importPath, alias string) *Import
• type State
  • func New(uniqueID string) (*State, error)
  • func (s *State) AutoCompleteOptionsInCell(cellLines []string, skipLines map[int]bool, cursorLine, cursorCol int, ...) (err error)
  • func (s *State) BinaryPath() string
  • func (s *State) Compile(msg kernel.Message) error
  • func (s *State) DisplayErrorWithContext(msg kernel.Message, errorMsg string)
  • func (s *State) Execute(msg kernel.Message) error
  • func (s *State) ExecuteCell(msg kernel.Message, lines []string, skipLines map[int]bool) error
  • func (s *State) GoImports(msg kernel.Message) error
  • func (s *State) InspectIdentifierInCell(lines []string, skipLines map[int]bool, cursorLine, cursorCol int) (kernel.MIMEMap, error)
  • func (s *State) MainPath() string
  • func (s *State) ParseFromMainGo(msg kernel.Message, cursor Cursor, decls *Declarations) error
  • func (s *State) Reset()
• type TypeDecl
• type Variable
• type WriterWithCursor
  • func NewWriterWithCursor(w io.Writer) *WriterWithCursor
  • func (w *WriterWithCursor) CursorInFile(relativeCursor Cursor) (fileCursor Cursor)
  • func (w *WriterWithCursor) Error() error
  • func (w *WriterWithCursor) Format(format string, args ...any)
  • func (w *WriterWithCursor) Str(content string)

Constants

const LinesForErrorContext = 3

const NoCursorLine = int(-1)

Variables

var (
	ParseError = fmt.Errorf("failed to parse cell contents")
	CursorLost = fmt.Errorf("cursor position not rendered in main.go")
)

var NoCursor = Cursor{Line: NoCursorLine, Col: 0}

Types

type Constant

type Constant struct {
	Cursor
	Key                                      string
	TypeDefinition, ValueDefinition          string // Can be empty, if used as iota.
	CursorInKey, CursorInType, CursorInValue bool
	Next, Prev                               *Constant // Next and previous declaration in same Const block.
}

Constant represents the declaration of a constant. Because when appearing in block they inherit its definition form the previous line, we need to preserve the blocks. For this we use Next/Prev links.

func (*Constant) Render

func (c *Constant) Render(w *WriterWithCursor, cursor *Cursor)

Render Constant declaration (without the `const` keyword).

type Cursor

type Cursor struct {
	Line, Col int
}

Cursor represents a cursor position in a cell or file. The Col is given as bytes in the line expected to be encoded as UTF-8.

func (*Cursor) ClearCursor

func (c *Cursor) ClearCursor()

func (*Cursor) CursorFrom

func (c *Cursor) CursorFrom(line, col int) Cursor

CursorFrom returns a new Cursor adjusted

func (*Cursor) HasCursor

func (c *Cursor) HasCursor() bool

type Declarations

type Declarations struct {
	Functions map[string]*Function
	Variables map[string]*Variable
	Types     map[string]*TypeDecl
	Imports   map[string]*Import
	Constants map[string]*Constant
}

Declarations is a collection of declarations that we carry over from one cell to another.

func NewDeclarations

func NewDeclarations() *Declarations

func (*Declarations) ClearCursor

func (d *Declarations) ClearCursor()

ClearCursor wherever declaration it may be.

func (*Declarations) Copy

func (d *Declarations) Copy() *Declarations

Copy returns a new deep copy of the declarations.

func (*Declarations) MergeFrom

func (d *Declarations) MergeFrom(d2 *Declarations)

MergeFrom declarations in d2.

func (*Declarations) RenderConstants

func (d *Declarations) RenderConstants(w *WriterWithCursor) (cursor Cursor)

RenderConstants without comments for all constants in Declarations.

Constants are trickier to render because when they are defined in a block, using `iota`, their ordering matters. So we re-render them in the same order and blocks as they were originally parsed.

The ordering is given by the sort order of the first element of each `const` block.

func (*Declarations) RenderFunctions

func (d *Declarations) RenderFunctions(w *WriterWithCursor) (cursor Cursor)

RenderFunctions without comments, for all functions in Declarations.

func (*Declarations) RenderImports

func (d *Declarations) RenderImports(w *WriterWithCursor) (cursor Cursor)

RenderImports writes out `import ( ... )` for all imports in Declarations.

func (*Declarations) RenderTypes

func (d *Declarations) RenderTypes(w *WriterWithCursor) (cursor Cursor)

RenderTypes without comments.

func (*Declarations) RenderVariables

func (d *Declarations) RenderVariables(w *WriterWithCursor) (cursor Cursor)

RenderVariables writes out `var ( ... )` for all variables in Declarations.

type ElementType

type ElementType int

const (
	Invalid ElementType = iota
	FunctionType
	ImportType
	VarType
	ConstType
)

func (ElementType) String

func (i ElementType) String() string

type Function

type Function struct {
	Cursor
	Key            string
	Name, Receiver string
	Definition     string // Multi-line definition, includes comments preceding definition.

}

Function definition.

type Import

type Import struct {
	Cursor
	Key                         string
	Path, Alias                 string
	CursorInPath, CursorInAlias bool
}

Import represents an import to be included -- if not used it's automatically removed by `goimports`.

func NewImport

func NewImport(importPath, alias string) *Import

NewImport from the importPath and it's alias. If alias is empty or "<nil>", it will default to the last name part of the importPath.

type State

type State struct {
	// Temporary directory where Go program is build at each execution.
	UniqueID, Package, TempDir string

	// Building and executing go sampleCellCode configuration:
	Args    []string // Args to be passed to the program, after being executed.
	AutoGet bool     // Whether to do a "go get" before compiling, to fetch missing external modules.

	// Global elements defined mapped by their keys.
	Decls *Declarations
	// contains filtered or unexported fields
}

func New

func New(uniqueID string) (*State, error)

New returns an empty State object, that can be used to execute Cells.

func (*State) AutoCompleteOptionsInCell

func (s *State) AutoCompleteOptionsInCell(cellLines []string, skipLines map[int]bool,
	cursorLine, cursorCol int, reply *kernel.CompleteReply) (err error)

AutoCompleteOptionsInCell implements an `complete_request` from Jupyter, using `gopls`. It updates `main.go` with the cell contents (given as lines)

func (*State) BinaryPath

func (s *State) BinaryPath() string

func (*State) Compile

func (s *State) Compile(msg kernel.Message) error

Compile compiles the currently generate go files in State.TempDir to a binary named State.Package.

If errors in compilation happen, linesPos is used to adjust line numbers to their content in the current cell.

func (*State) DisplayErrorWithContext

func (s *State) DisplayErrorWithContext(msg kernel.Message, errorMsg string)

DisplayErrorWithContext in an HTML div, with a mouse-over pop-up window listing the lines with the error, and highlighting the exact position.

Any errors within here are logged and simply ignored, since this is already used to report errors

func (*State) Execute

func (s *State) Execute(msg kernel.Message) error

func (*State) ExecuteCell

func (s *State) ExecuteCell(msg kernel.Message, lines []string, skipLines map[int]bool) error

ExecuteCell takes the contents of a cell, parses it, merges new declarations with the ones from previous definitions, render a final main.go sampleCellCode with the whole content, compiles and runs it.

func (*State) GoImports

func (s *State) GoImports(msg kernel.Message) error

GoImports execute `goimports` which adds imports to non-declared imports automatically. It also runs "go get" to download any missing dependencies.

func (*State) InspectIdentifierInCell

func (s *State) InspectIdentifierInCell(lines []string, skipLines map[int]bool, cursorLine, cursorCol int) (kernel.MIMEMap, error)

InspectIdentifierInCell implements an `inspect_request` from Jupyter, using `gopls`. It updates `main.go` with the cell contents (given as lines)

func (*State) MainPath

func (s *State) MainPath() string

func (*State) ParseFromMainGo

func (s *State) ParseFromMainGo(msg kernel.Message, cursor Cursor, decls *Declarations) error

ParseFromMainGo reads main.go and parses its declarations into decls -- see object Declarations.

func (*State) Reset

func (s *State) Reset()

type TypeDecl

type TypeDecl struct {
	Cursor
	Key                       string // Same as the name here.
	TypeDefinition            string // Type definition may be empty.
	CursorInKey, CursorInType bool
}

type Variable

type Variable struct {
	Cursor
	CursorInName, CursorInType, CursorInValue bool
	Key, Name                                 string
	TypeDefinition, ValueDefinition           string // Type definition may be empty.
}

type WriterWithCursor

type WriterWithCursor struct {
	Line, Col int
	// contains filtered or unexported fields
}

WriterWithCursor keep tabs of current line/col of the file (presumably) being written.

func NewWriterWithCursor

func NewWriterWithCursor(w io.Writer) *WriterWithCursor

NewWriterWithCursor that keeps tabs of current line/col of the file (presumably) being written.

func (*WriterWithCursor) CursorInFile

func (w *WriterWithCursor) CursorInFile(relativeCursor Cursor) (fileCursor Cursor)

CursorInFile returns a cursor pointing in file, given the current position in the file (stored in w) and the position of the relativeCursor in the definition to come.

func (*WriterWithCursor) Error

func (w *WriterWithCursor) Error() error

Error returns first error that happened during writing.

func (*WriterWithCursor) Format

func (w *WriterWithCursor) Format(format string, args ...any)

Format write with formatted text. Errors can be retrieved with Error.

func (*WriterWithCursor) Str

func (w *WriterWithCursor) Str(content string)

Str writes the given content and keeps track of cursor. Errors can be retrieved with Error.