Documentation
¶
Overview ¶
Package native lets Go code define Kukel modules: functions, constants and native classes, whose objects carry a Go value and whose member functions are written in Go. A program uses one with "use name;", like a module written in Kukel, and reaches its names as name::x.
A module registers itself (Register, usually from an init function); the loader, the compiler and the VM look modules up by name. Native classes have no data members: everything goes through member functions. A Kukel class can derive from a native class that has a constructor; its objects then hold the Go value too, once the derived constructor has called the native one.
Index ¶
- Variables
- func Duration(seconds float64) time.Duration
- func Flush(env value.Env)
- func Generator(env value.Env, name string, next func() (value.Value, bool, error)) (value.Value, error)
- func Global(qualified string) (value.Value, bool)
- func IOError(a Args, err error) error
- func IOMessage(err error) string
- func Names() []string
- func NetMessage(err error) string
- func Omit(name, why string)
- func Omitted(name string) (string, bool)
- func Prepare(m *Module)
- func Program(env value.Env) string
- func Register(m *Module)
- func SetProgram(env value.Env, path string)
- func SetTerminal(env value.Env, in, out *os.File)
- func Terminal(env value.Env) (in, out *os.File)
- func TypeName(v value.Value) string
- type Args
- func (a Args) Errorf(kind string, format string, args ...any) error
- func (a Args) Has(i int) bool
- func (a Args) Int(i int) (int64, error)
- func (a Args) NotSetUp(what string, c *Class, v value.Value) error
- func (a Args) Number(i int) (float64, error)
- func (a Args) Object(i int, c *Class) (any, error)
- func (a Args) Seconds(i int, what string) (time.Duration, error)
- func (a Args) String(i int) (string, error)
- func (a Args) TypeError(i int, want string) error
- type Class
- type Config
- type Func
- type Module
- type Waiter
Constants ¶
This section is empty.
Variables ¶
var MaxSocketPath = func() int { if runtime.GOOS == "linux" || runtime.GOOS == "android" { return 107 } return 103 }()
MaxSocketPath is the longest path of a Unix socket the system takes, in bytes: a longer one fails with just "invalid argument".
Functions ¶
func Duration ¶ added in v0.27.0
Duration converts seconds (not negative) to a duration. Beyond the longest duration, about 292 years, it gives the longest: as good as no limit.
func Flush ¶ added in v0.27.0
Flush writes out what the program's standard output and standard error hold in a buffer (kukel buffers standard output; the writers of a Go program that embeds Kukel may not buffer). A function that waits, for time, a message or an event, calls it first: what the program wrote before the wait is seen during it.
func Generator ¶ added in v0.34.0
func Generator(env value.Env, name string, next func() (value.Value, bool, error)) (value.Value, error)
Generator makes a generator (Q86) whose values come from next: it gives the next value, or false at the end; an error ends the generator too. for-each walks it as one written in Kukel, so that a member function iter() returning it makes the objects of a native class iterable. name is how it shows ("fs::File::iter").
func Global ¶
Global returns what a qualified name of a registered module stands for at run time: a function ("json::encode"), a static member function ("time::Time::parse") or a class ("time::Time"). The VM links the global slots of a program with it.
func IOMessage ¶ added in v0.31.0
IOMessage is what went wrong with a file, without Go's name of the operation: "nope.kkl: no such file or directory" for "open nope.kkl: no such file or directory", and "from -> to: ..." for a rename. Module fs words its IOErrors so; other modules that read files follow it.
func NetMessage ¶ added in v0.31.0
NetMessage is what went wrong in reaching or listening on a network address, without Go's words around it: "connection refused" for "dial tcp 127.0.0.1:1: connect: connection refused", "host x not found" for a name that cannot be looked up. The caller names the address.
func Omit ¶ added in v0.12.0
func Omit(name, why string)
Omit records that module name is not in this kukel, and why: "it was built with the build tag nozmq", "it was built without the build tag tk".
func Omitted ¶ added in v0.12.0
Omitted gives why module name is not in this kukel, if a build tag left it out.
func Prepare ¶
func Prepare(m *Module)
Prepare readies m for use without registering it: for a module that belongs to one program (Config.Modules). Register prepares a module itself.
func Register ¶
func Register(m *Module)
Register adds module m. It panics on a second module with the same name (a programming error).
func SetProgram ¶ added in v0.33.1
SetProgram sets what program() gives in the interpreter of env: the path of the program's file as it was given (kukel run a.kkl: "a.kkl").
func SetTerminal ¶ added in v0.38.0
SetTerminal tells the interpreter of env that its standard input and output are the files in and out of the process (kukel run and exec), so that module term may make them raw and ask the size of the terminal they are, if they are one. An interpreter without it (one a Go program makes) has no terminal: term reads keys from its standard input as it is, and changes no terminal.
Types ¶
type Args ¶
type Args struct {
Name string // as in messages: "json::encode", "time::Time::format"
V []value.Value
}
Args are the arguments of a call of a native function, for checking them with messages like those of the built-ins.
func (Args) Errorf ¶
Errorf returns a Kukel exception of the given kind (value.ValueError, value.TypeError, ...), prefixed with the function's name.
func (Args) NotSetUp ¶ added in v0.31.0
NotSetUp is the ValueError for v, an object of a class derived from c whose constructor did not call c's; what says where v is ("argument 2", "element 1 of argument 1").
func (Args) Object ¶
Object returns the Go value of argument i, which must be an object of class c or of a class derived from it.
func (Args) Seconds ¶ added in v0.27.0
Seconds returns argument i, a number of seconds that is not negative, as a duration; what names it in the message for another number ("a usable timeout"). See Duration for very long times.
type Class ¶
type Class struct {
Name string
New value.NativeMethod
Methods map[string]value.NativeMethod
Statics map[string]Func
Show func(o *value.ObjectObj) string
// contains filtered or unexported fields
}
Class is a native class. Methods and Statics are its instance and static member functions. New is its constructor (for "new name::C(...)"): it sets this.State; without one, objects only come from the module's functions (Class.Object). Show formats an object for str() and println; without it an object shows as "name::C{}".
func (*Class) Derived ¶ added in v0.31.0
Derived reports whether v is an object of class c, or of a class derived from it, set up or not (see NotSetUp).
func (*Class) Is ¶ added in v0.9.0
Is reports whether v is an object of class c, or of a class derived from it, with its Go value set up.
func (*Class) QualifiedName ¶
QualifiedName is "module::Class".
type Config ¶
type Config struct {
Modules []*Module // this program's own modules (prepared), found before the registered ones
AllowedModules map[string]bool // registered modules the program may use; nil: all
DeniedBuiltins map[string]bool // built-ins the program may not use
Path []string // directories where "use" looks for name.kkl after the using file's directory
NoFileModules bool // "use" never reads .kkl files (modules written in Go only)
}
Config is what one program may use beyond its own code: modules written for it (by a Go program that embeds Kukel), which of the registered modules and built-ins are allowed, and where "use" finds modules written in Kukel. The compiler, the loader and the VM (also of the program's workers) follow it. A nil *Config allows everything and finds Kukel modules only next to the files that use them.
func (*Config) BuiltinDenied ¶
BuiltinDenied reports whether the program may not use built-in name.
func (*Config) Disallowed ¶
Disallowed reports whether name is a registered module the program may not use (for a clearer message than "not found").
type Module ¶
type Module struct {
Name string
Doc string // one line: what the module is for
Funcs map[string]Func
Consts map[string]value.Value // nil, booleans, numbers and strings
Classes []*Class
// contains filtered or unexported fields
}
Module is a module written in Go.
type Waiter ¶ added in v0.31.0
type Waiter struct {
// contains filtered or unexported fields
}
Waiter is a wait that Wait began; Done ends it.
func Wait ¶ added in v0.31.0
Wait is called by a function that begins to wait, for time, a message, an event or input: it flushes output (see Flush), and the Done of what it gives tells when the wait ended, so that a profile of running time (kukel profile -cpu) can leave the wait out:
defer native.Wait(env).Done()
When nothing profiles the program, it costs no more than Flush.
Source Files