Documentation
¶
Overview ¶
Package shell wires the sh interpreter to an in-memory filesystem and a set of built-in applets, forming a self-contained bash-like shell that runs anywhere Go runs — including js/wasm, where it backs an xterm-go terminal.
Index ¶
- func AppletNames() []string
- func Base(path string) string
- func CopyLines(r io.Reader, fn func(line string))
- func Print(w io.Writer, a ...any)
- func Printf(w io.Writer, format string, a ...any)
- func Println(w io.Writer, a ...any)
- func ReadAll(r io.Reader) ([]byte, error)
- func ReadFile(s *Shell, hc *interp.HandlerContext, path string) ([]byte, error)
- func RegisterApplet(name, help string, ...)
- func Resolve(hc *interp.HandlerContext, path string) string
- func Seed(vfs afero.Fs) error
- func Write(w io.Writer, b []byte)
- func WriteFile(s *Shell, hc *interp.HandlerContext, path string, data []byte) (string, error)
- type LineEditor
- type Shell
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func AppletNames ¶
func AppletNames() []string
AppletNames returns the registered applet names, sorted.
func CopyLines ¶
CopyLines calls fn for each newline-terminated line read from r, without the trailing newline. It returns when r is exhausted.
func Printf ¶
Printf, Println, Print and Write are the applet-output wrappers used by applets in other packages (see shell/browser). They drop the write error for the reason documented in write.go: a shell that cannot write its output has nowhere left to report that.
func ReadFile ¶
ReadFile reads a file from the shell's filesystem, resolving relative paths against its working directory.
func RegisterApplet ¶
func RegisterApplet(name, help string, run func(ctx context.Context, s *Shell, hc *interp.HandlerContext, args []string) int)
RegisterApplet adds (or replaces) an applet — used by embedders to expose environment-specific commands.
func Resolve ¶
func Resolve(hc *interp.HandlerContext, path string) string
Resolve makes path absolute against the shell's current directory.
Types ¶
type LineEditor ¶
type LineEditor struct {
// Echo writes to the terminal.
Echo func(s string)
// Submit receives a completed line (without the newline).
Submit func(line string)
// Interrupt is called on Ctrl+C.
Interrupt func()
// EOF is called on Ctrl+D at an empty line.
EOF func()
// ClearScreen is called on Ctrl+L.
ClearScreen func()
// Redraw must repaint prompt+content with the cursor n runes back
// from the end (used by history navigation and mid-line edits).
Redraw func(content string, cursorBack int)
// Complete returns candidates for the word being completed. When
// isFirstWord, the word is a command name; otherwise a path.
// Directory candidates should end in "/".
Complete func(word string, isFirstWord bool) []string
// contains filtered or unexported fields
}
LineEditor implements a small readline-style line discipline over a terminal byte stream: cursor movement, history, and the usual control keys. It is terminal-agnostic — echo happens through the Echo callback with standard escape sequences.
func (*LineEditor) AddHistory ¶
func (e *LineEditor) AddHistory(line string)
AddHistory appends a line to the history.
func (*LineEditor) ClearHistory ¶
func (e *LineEditor) ClearHistory()
ClearHistory discards the history, as `history -c` does.
func (*LineEditor) History ¶
func (e *LineEditor) History() []string
History returns the lines entered so far, oldest first. It backs the interpreter's history builtin, which has no list of its own.
func (*LineEditor) Input ¶
func (e *LineEditor) Input(data string)
Input feeds terminal input (the OnData stream) into the editor.
func (*LineEditor) Line ¶
func (e *LineEditor) Line() string
Line returns the current buffer contents.
func (*LineEditor) Reset ¶
func (e *LineEditor) Reset()
Reset clears the buffer (after Submit or Interrupt).
type Shell ¶
type Shell struct {
FS afero.Fs
Runner *interp.Runner
// RawMode, when set by the embedder, toggles raw terminal input:
// no echo and no newline translation (used by full-screen applets
// like less).
RawMode func(on bool)
// Size, when set, reports the terminal dimensions.
Size func() (cols, rows int)
// contains filtered or unexported fields
}
Shell is an interpreter bound to a virtual filesystem.
func New ¶
New creates a shell over the given filesystem (nil = fresh in-memory fs seeded with a small home directory).
func (*Shell) CancelPending ¶
func (s *Shell) CancelPending()
CancelPending discards buffered continuation lines (Ctrl+C).
func (*Shell) Pending ¶
Pending reports whether the shell is waiting for continuation lines of an incomplete statement (e.g. an unterminated for loop).
func (*Shell) PopulateBin ¶
PopulateBin creates a stub file in /bin for every registered applet so the command set is discoverable with ls. Call again after registering extra applets.
func (*Shell) Run ¶
Run feeds one input line to the shell. It returns needMore=true when the statement is incomplete and further lines are expected.
func (*Shell) UseHistory ¶
UseHistory gives the interpreter's history builtin a history list. The interpreter never reads input lines itself, so only the line editor above it has one; call this with LineEditor.History and LineEditor.ClearHistory once the editor exists.
Source Files
¶
Directories
¶
| Path | Synopsis |
|---|---|
|
Package browser adds the applets that only make sense in a browser: the JavaScript console (`js`, `logs`), transfers to and from the host machine (`download`, `upload`), the network (`curl`, `nc`) and the clipboard (`pbcopy`, `pbpaste`).
|
Package browser adds the applets that only make sense in a browser: the JavaScript console (`js`, `logs`), transfers to and from the host machine (`download`, `upload`), the network (`curl`, `nc`) and the clipboard (`pbcopy`, `pbpaste`). |