Documentation
¶
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Load ¶
Load loads an elps package implemented in Go. Load restores the package that was active when it was called, whether or not fn succeeds, so that further defined symbols end up in that package by default.
A loader that returns a Go nil *LVal, rather than lisp.Nil(), is reported as an error naming the loader instead of panicking.
func Validate ¶ added in v1.50.0
Validate reports mistakes in an elps package implemented in Go that the Go type system cannot catch. It is intended to be called from an embedder's test:
func TestPackage(t *testing.T) {
if err := elpsutil.Validate(&MyPackage{}); err != nil {
t.Fatal(err)
}
}
Validate reports every problem it finds, joined into a single error. A nil return means PackageLoader will not reject the package.
Validate performs one check that PackageLoader deliberately does not: it reports a package that contributes no builtins, no special operators, no macros and has no PackageInit. Such a package is almost certainly a mistake, but "almost" is not enough to fail a load -- a namespace-only package is unusual, not illegal.
Types ¶
type Builtin ¶
type Builtin struct {
// contains filtered or unexported fields
}
Builtin captures Go functions that are callable from elps.
func Function ¶
Function is a helper to construct builtins.
formals must be a list of symbols, as returned by lisp.Formals. A function that takes no arguments is declared with lisp.Formals(), the empty list; a nil formals list is not a valid spelling of that and is rejected by PackageLoader and Validate.
A function constructed with Function has no documentation. Use FunctionDoc to give it a docstring.
func FunctionDoc ¶ added in v1.58.0
FunctionDoc is a helper to construct documented builtins. It is Function plus the docstring the function is registered with, which is what `elps doc` prints, what the language server shows on hover, and what the linter reads.
The docstring follows the same conventions as the interpreter's own builtins. In particular a paragraph beginning "Deprecated:" (or "DEPRECATED:") marks the function deprecated, exactly as it does in a Go doc comment: the `deprecated` lint check then reports every use of the function and quotes the rest of that paragraph as the reason. For example
elpsutil.FunctionDoc("blend-paths", lisp.Formals("a", "b"), blendPaths,
"Blend two paths.\n\nDeprecated: use join-paths instead.")
func (*Builtin) Docstring ¶ added in v1.58.0
Docstring returns the documentation for a function, which is empty for a function constructed with Function. It satisfies the interface lisp checks for when registering a definition, so the string reaches the registered value and everything that reads documentation from it.
type Loader ¶
Loader is a generic function to initialize/load an LEnv. A Loader should first define and switch into the package(s) it loads. The helpers in this package (Load, LoadAll, LibraryLoader and PackageLoader) restore the package that was active when they were called, whether the load succeeds or fails, so that symbols defined after a load end up where the caller expects them. A load performed from the user package -- the conventional top-level usage -- therefore ends in the user package, as it always has.
A chain of loaders may be formed to load a library.
func LibraryLoader ¶
LibraryLoader loads multiple elps packages implemented in Go.
func LoadAll ¶
LoadAll loads multiple elps files implemented in Go. Like Load, LoadAll restores the package that was active when it was called, whether or not the loaders succeed, and runs each loader from that package.
A loader that returns a Go nil *LVal, rather than lisp.Nil(), is reported as an error naming the loader and its position in the chain instead of panicking.
func PackageLoader ¶
PackageLoader loads an elps package implemented in Go.
PackageLoader restores the package that was active when it was called, whether or not the load succeeds, the same invariant the stdlib LoadPackage functions honor (https://github.com/luthersystems/elps/issues/99). It also re-establishes the loaded package after PackageInit returns, so that a PackageInit which switches packages -- directly, or indirectly through a nested Load -- does not cause the package's builtins, special operators and macros to be registered and exported somewhere else (https://github.com/luthersystems/elps/issues/352).
PackageLoader validates the package definition before registering anything, and returns an *LVal error identifying the package and the offending definition rather than letting lisp panic or deferring a nil dereference to call time. A definition lisp accepts today is still accepted.
type Package ¶
type Package interface {
PackageName() string
}
Package is an elps package implemented in Go.
type PackageBuiltins ¶
type PackageBuiltins interface {
Package
Builtins() []lisp.LBuiltinDef
}
PackageBuiltins retrieves the exposed builtins for an elps package implemented in Go.
type PackageDocumented ¶ added in v1.16.12
PackageDocumented allows an elps package to provide a documentation string.
type PackageInit ¶
PackageInit allows initialization of an elps package implemented in Go.
type PackageMacros ¶
type PackageMacros interface {
Package
Macros() []lisp.LBuiltinDef
}
PackageMacros returns the macros for an elps package implemented in Go.
type PackageSpecialOps ¶
type PackageSpecialOps interface {
Package
SpecialOps() []lisp.LBuiltinDef
}
PackageSpecialOps returns the special operators for an elps package implemented in Go.
Source Files