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 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").
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