Documentation
¶
Overview ¶
Package shellcore is the evaluator, formatter and built-in helpers behind the public shell package. Nothing here is covered API.
Index ¶
- Constants
- Variables
- func Balanced(src string) bool
- func ExportHelpers(session *Session, helpers map[string]any) error
- func Format(v any, limit int) string
- func Help(projectHelpers []string) string
- func Run(ctx context.Context, s IO, boot Boot, args []string) int
- func Usage() string
- type Boot
- type Example
- type History
- type IO
- type Invocation
- type Limitation
- type PanicError
- type Session
- type UsageError
- type Verbs
- func (v *Verbs) Context() context.Context
- func (v *Verbs) Count(name string, query ...map[string]any) (int, error)
- func (v *Verbs) Create(name string, row map[string]any) (map[string]any, error)
- func (v *Verbs) Delete(name string, pk any) error
- func (v *Verbs) Describe(name string) ([]map[string]any, error)
- func (v *Verbs) Functions() map[string]any
- func (v *Verbs) Get(name string, pk any) (map[string]any, error)
- func (v *Verbs) List(name string, query ...map[string]any) ([]map[string]any, error)
- func (v *Verbs) Models() []string
- func (v *Verbs) Update(name string, pk any, changes map[string]any) (map[string]any, error)
Constants ¶
const ( ExitOK = 0 ExitError = 1 ExitUsage = 2 )
Exit statuses of a session.
const ( // ExitInterrupted is the exit status of a session that Ctrl-C ended in // the middle of an evaluation. ExitInterrupted = 130 )
const HelperQualifier = "project"
HelperQualifier is how a session reaches the project's own helpers: project.Name(...).
const StartupPointer = "Go console: help() lists the helpers and `tango shell --help` what the interpreter cannot run."
StartupPointer is the one line a session prints when it starts.
Variables ¶
var ErrReadOnly = errors.New("the shell is read-only (--readonly)")
ErrReadOnly is wrapped by every write verb of a read-only session.
var Limitations = []Limitation{ { Feature: "the min and max builtins", Workaround: "compare with if, or write a small function", Examples: []Example{{Code: "min(1, 2)"}, {Code: "max(1, 2)"}}, // contains filtered or unexported fields }, { Feature: "the clear builtin", Workaround: "delete the keys in a loop: for k := range m { delete(m, k) }", Examples: []Example{{Setup: []string{`m := map[string]int{"a": 1}`}, Code: "clear(m)"}}, // contains filtered or unexported fields }, { Feature: "inferring the type arguments of a generic function whose result type differs from its argument types", Workaround: "give the type arguments explicitly, as in Map[int, string](xs, f)", Examples: []Example{{ Setup: []string{"func Map[T, U any](xs []T, f func(T) U) []U { var out []U; for _, x := range xs { out = append(out, f(x)) }; return out }"}, Code: `Map([]int{1}, func(i int) string { return "x" })`, }}, // contains filtered or unexported fields }, { Feature: "ranging over a function, or over an integer (for i := range 3)", Workaround: "use a counting for loop, or call the function with a callback", Examples: []Example{ {Code: "for v := range func(yield func(int) bool) { yield(1) } { _ = v }"}, {Code: "for i := range 3 { _ = i }"}, }, // contains filtered or unexported fields }, }
Limitations lists what is known not to run, in the order the help shows it.
Functions ¶
func Balanced ¶
Balanced reports whether src has no open bracket, string or comment, so that a line of input can be evaluated rather than continued on the next. Brackets inside strings, runes and comments do not count.
func ExportHelpers ¶
ExportHelpers makes a project's helpers callable as project.Name. Every name must be an exported Go identifier, and a nil value is refused. A helper that is a function is called like any function; anything else is a constant of the session. Only plain values (primitives, maps, slices and errors) are supported across the boundary: a value of a project type arrives, but using its fields or methods from the session is not something the shell promises.
func Format ¶
Format renders v the way the shell prints results: deterministic, one line per value, one line per row for a list of maps. A zero v prints nothing. limit is the most runes a single line may hold before it is cut with an ellipsis; 0 never truncates.
func Help ¶
Help is the text of help(): the helpers, the project's own helpers and the limits of the interpreter.
Types ¶
type Boot ¶
type Boot struct {
Registry *tango.Registry
Store *db.Store
ReadOnly bool
Helpers map[string]any
DatabaseLabel string
}
Boot is the booted project a session works on.
type History ¶
type History struct {
// contains filtered or unexported fields
}
History keeps the lines typed at the prompt, newest first for the terminal's up-arrow, and appends each to a file so the next session in the same project starts with them. It implements golang.org/x/term's History.
The file can hold secrets typed into the shell, so it is private to the user (mode 0600, in a 0700 directory).
func OpenHistory ¶
OpenHistory loads the history for the project in dir, from the user's cache directory. TANGO_SHELL_HISTORY=off, or a cache directory that cannot be used, leaves it in memory only; the second case is reported once to warn.
func (*History) Add ¶
Add records a typed line. Blank lines and a repeat of the previous line are not kept.
type Invocation ¶
type Invocation struct {
// Eval holds the -c expression; HasEval distinguishes "-c ”" from no -c.
Eval string
HasEval bool
ReadOnly bool
Help bool
}
Invocation is what the command line of a shell session asks for.
func ParseArgs ¶
func ParseArgs(args []string) (Invocation, error)
ParseArgs reads the shell's command line: -c EXPR, --readonly, --help.
type Limitation ¶
type Limitation struct {
// Feature names what does not work.
Feature string
// Workaround says what to write instead.
Workaround string
// Examples each fail today; Setup runs first, one chunk per element.
Examples []Example
// contains filtered or unexported fields
}
Limitation is a piece of Go the interpreter (Yaegi, pinned at v0.16.1) cannot run, which a person can reasonably type. The table of these is the single source for the hint printed after a failure, for help(), for `tango shell --help` and for the regression test that notices when a release of the interpreter starts supporting one. The guide's table must say the same.
type PanicError ¶
type PanicError struct {
Value any
// Interpreted is true for a panic the program itself raised (a panic
// call in typed code, or a helper that panicked) and false for one the
// interpreter raised because it could not run the Go it was given.
Interpreted bool
}
PanicError is a panic recovered from the interpreter. The session that raised it is still usable.
func (*PanicError) Error ¶
func (e *PanicError) Error() string
type Session ¶
type Session struct {
// contains filtered or unexported fields
}
Session is one interpreter whose variables and imports persist across Eval calls.
func NewSession ¶
NewSession starts an interpreter that writes what interpreted code prints to out and errOut, and reads from in.
func (*Session) Eval ¶
Eval runs code and returns what to print for it: the formatted value of a final expression, and nothing for declarations, assignments and nil. A non-nil error value, whether returned by a call or the value of the expression, comes back as the error. A panic in the interpreter comes back as a *PanicError.
type UsageError ¶
type UsageError struct{ Message string }
UsageError reports a command line the shell cannot accept; the caller exits with status 2.
func (*UsageError) Error ¶
func (e *UsageError) Error() string
type Verbs ¶
type Verbs struct {
// contains filtered or unexported fields
}
Verbs are the built-in, map-based helpers a session can call by bare name: Models, Describe, Get, List, Count, Create, Update, Delete and Context. Rows are map[string]any keyed by Go field name; models are addressed as app.Model.
func NewVerbs ¶
NewVerbs returns the verbs over models and store. readOnly makes the verbs that write fail.
func (*Verbs) Count ¶
Count returns how many rows of model match the where key of an optional query map; order, limit and offset do not affect it.
func (*Verbs) Create ¶
Create stores a new row built from the field-to-value map and returns the stored row, including the primary key the database assigned.
func (*Verbs) List ¶
List returns the rows of model matching an optional query map with the keys where (field to value, equality only), order (field names, "-" prefix for descending), limit and offset.
Source Files