janet

README

janet

Package janet contains a Janet virtual machine for interoperation between Go and Janet code. Users of its API can register callbacks, define symbols in the Janet environment, execute Janet code, and convert between Go and Janet values.

This code is, admittedly, a little terrifying. Suffice it to say that Janet was not designed to be used from Go, and as a result there are a lot of silly tricks this library uses to ensure we only access memory used by the Janet VM in the goroutine where it was initialized.

Updating Janet

To update the janet version, clone the janet-lang/janet repository and run make, then copy build/c/janet.c, src/include/janet.h, and src/conf/janetconf.h to this directory.

Documentation

Index

• Variables
• func IsValidType(value interface{}) bool
• type Call
  • func CallBytes(data []byte) Call
  • func CallString(code string) Call
• type CallOptions
• type Callback
  • func (c *Callback) Source() (file string, line int)
• type Docstrings
• type Documented
• type Fiber
• type Function
  • func (f *Function) Call(ctx context.Context, params ...interface{}) error
  • func (f *Function) CallContext(ctx context.Context, user interface{}, params ...interface{}) error
  • func (f *Function) CallResult(ctx context.Context, user interface{}, params ...interface{}) (*Value, error)
• type Keyword
• type Marshalable
• type Named
  • func (n *Named[T]) Values() T
  • func (n *Named[T]) WithDefault(defaults T) T
• type Params
  • func (p Params) Error(err error)
  • func (p Params) Ok()
  • func (p Params) Out(value *Value)
  • func (p Params) Pipe() Params
  • func (p Params) WaitErr() error
  • func (p Params) WaitOut() (*Value, error)
  • func (p Params) WaitResult() (*Result, error)
  • func (p Params) Yield(value *Value)
• type PartialCallback
  • func (p *PartialCallback) Call() []reflect.Value
• type Renamable
• type Request
• type Result
• type Table
• type Unmarshalable
• type VM
  • func New(ctx context.Context) (*VM, error)
  • func (v *VM) Callback(name string, docstring string, callback interface{}) error
  • func (v *VM) Env() *Table
  • func (v *VM) Execute(ctx context.Context, code string) error
  • func (v *VM) ExecuteCall(ctx context.Context, user interface{}, call Call) (*Result, error)
  • func (v *VM) ExecuteFile(ctx context.Context, path string) error
  • func (v *VM) Lookup(name string) (callback *Callback, ok bool)
  • func (v *VM) Marshal(source interface{}) (value *Value, err error)
  • func (v *VM) Module(name string, module interface{}) error
• type Value
  • func (v *Value) Free()
  • func (v *Value) IsFree() bool
  • func (v *Value) JSON() ([]byte, error)
  • func (v *Value) Nil() bool
  • func (v *Value) Raw() ([]byte, error)
  • func (v *Value) String() string
  • func (v *Value) Unmarshal(dest interface{}) error

Variables

var DEFAULT_CALL_OPTIONS = CallOptions{
	UpdateEnv: true,
}

var ERROR_FREED = fmt.Errorf("cannot use freed value")

var GO_BOOT_FILE []byte

var JANET_TYPE_TO_STRING map[C.JanetType]string = map[C.JanetType]string{
	C.JANET_NUMBER:    "number",
	C.JANET_NIL:       "nil",
	C.JANET_BOOLEAN:   "boolean",
	C.JANET_FIBER:     "fiber",
	C.JANET_STRING:    "string",
	C.JANET_SYMBOL:    "symbol",
	C.JANET_KEYWORD:   "keyword",
	C.JANET_ARRAY:     "array",
	C.JANET_TUPLE:     "tuple",
	C.JANET_TABLE:     "table",
	C.JANET_STRUCT:    "struct",
	C.JANET_BUFFER:    "buffer",
	C.JANET_FUNCTION:  "function",
	C.JANET_CFUNCTION: "cfunction",
	C.JANET_ABSTRACT:  "abstract",
	C.JANET_POINTER:   "pointer",
}

var MARSHALABLE = reflect.TypeOf((*Marshalable)(nil)).Elem()

var (
	METHOD_REGEX = regexp.MustCompile("^# doc: (\\w+)$")
)

var UNMARSHALABLE = reflect.TypeOf((*Unmarshalable)(nil)).Elem()

Functions

func IsValidType

func IsValidType(value interface{}) bool

IsValidType returns true if the given value can be translated to a Janet value.

Types

type Call

type Call struct {
	Code       []byte
	SourcePath string
	Options    CallOptions
}

func CallBytes

func CallBytes(data []byte) Call

func CallString

func CallString(code string) Call

type CallOptions

type CallOptions struct {
	// Whether to allow the code to mutate the current environment.
	UpdateEnv bool
}

type Callback

type Callback struct {
	// contains filtered or unexported fields
}

func (*Callback) Source

func (c *Callback) Source() (file string, line int)

type Docstrings

type Docstrings interface {
	Docstrings() map[string]string
}

Docstrings provides docstrings for module methods. This is a mapping from the method's Go name to its Janet docstring.

type Documented

type Documented interface {
	Documentation() string
}

Documented provides documentation in the form of a Markdown-formatted string. All of the lines following a top-level Markdown header with a title that matches a Go method name will be included as the Janet documentation for that method.

For example, providing a string that looks like this: ``` # doc: SomeMethod This is some documentation # doc: SomeMethodB This is some other documentation ``` Will result in SomeMethod and SomeMethodB having those docstrings.

type Fiber

type Fiber struct {
	*Value
	// contains filtered or unexported fields
}

type Function

type Function struct {
	*Value
	// contains filtered or unexported fields
}

func (*Function) Call

func (f *Function) Call(ctx context.Context, params ...interface{}) error

func (*Function) CallContext

func (f *Function) CallContext(
	ctx context.Context,
	user interface{},
	params ...interface{},
) error

func (*Function) CallResult

func (f *Function) CallResult(
	ctx context.Context,
	user interface{},
	params ...interface{},
) (*Value, error)

type Keyword

type Keyword string

type Marshalable

type Marshalable interface {
	MarshalJanet() interface{}
}

Marshalable lets you define a custom (pure) transformation to perform on this type prior to translating it into a Janet value.

type Named

type Named[T any] struct {
	// contains filtered or unexported fields
}

func (*Named[T]) Values

func (n *Named[T]) Values() T

func (*Named[T]) WithDefault

func (n *Named[T]) WithDefault(defaults T) T

type Params

type Params struct {
	Context context.Context
	User    interface{}
	Result  chan Result
}

func (Params) Error

func (p Params) Error(err error)

func (Params) Ok

func (p Params) Ok()

func (Params) Out

func (p Params) Out(value *Value)

func (Params) Pipe

func (p Params) Pipe() Params

Make new Params with an overwritten Result channel.

func (Params) WaitErr

func (p Params) WaitErr() error

WaitErr waits for a fiber to finish executing, ignoring any values it returns or yields.

func (Params) WaitOut

func (p Params) WaitOut() (*Value, error)

WaitOut waits for the result of a fiber. If the fiber yields (instead of just returning a result), WaitOut will return an error.

func (Params) WaitResult

func (p Params) WaitResult() (*Result, error)

WaitResult waits for the fiber to produce a Result and returns it.

func (Params) Yield

func (p Params) Yield(value *Value)

type PartialCallback

type PartialCallback struct {
	Type reflect.Type
	// contains filtered or unexported fields
}

func (*PartialCallback) Call

func (p *PartialCallback) Call() []reflect.Value

type Renamable

type Renamable interface {
	Renames() map[string]string
}

Renamable provides a mapping from Go method names to Janet function names. This is useful for declaring Janet functions that are not valid Go, such as "boolean?".

type Request

type Request interface{}

type Result

type Result struct {
	Out   *Value
	Yield *Value
	Error error
}

Result is the value produced when a fiber finishes executing. Fibers can halt in three ways: - They can return a value, which is stored in Out. - They can yield (with (yield)), which is stored in Yield. - They can error, the message for which is stored in Error.

type Table

type Table struct {
	*Value
	// contains filtered or unexported fields
}

type Unmarshalable

type Unmarshalable interface {
	UnmarshalJanet(value *Value) error
}

Unmarshalable lets you define custom code for turning a Janet value into this type.

type VM

type VM struct {
	deadlock.RWMutex
	// contains filtered or unexported fields
}

func New

func New(ctx context.Context) (*VM, error)

func (*VM) Callback

func (v *VM) Callback(name string, docstring string, callback interface{}) error

func (*VM) Env

func (v *VM) Env() *Table

func (*VM) Execute

func (v *VM) Execute(ctx context.Context, code string) error

func (*VM) ExecuteCall

func (v *VM) ExecuteCall(
	ctx context.Context,
	user interface{},
	call Call,
) (*Result, error)

ExecuteCall executes a Call, which is the lowest-level interface for running Janet code.

func (*VM) ExecuteFile

func (v *VM) ExecuteFile(ctx context.Context, path string) error

ExecuteFile executes a file containing Janet code.

func (*VM) Lookup

func (v *VM) Lookup(name string) (callback *Callback, ok bool)

Lookup finds a previously registered callback by its Janet name and returns it.

func (*VM) Marshal

func (v *VM) Marshal(source interface{}) (value *Value, err error)

Marshal sends a marshalRequest to the VM and waits for the result.

func (*VM) Module

func (v *VM) Module(name string, module interface{}) error

type Value

type Value struct {
	deadlock.RWMutex
	// contains filtered or unexported fields
}

func (*Value) Free

func (v *Value) Free()

func (*Value) IsFree

func (v *Value) IsFree() bool

func (*Value) JSON

func (v *Value) JSON() ([]byte, error)

func (*Value) Nil

func (v *Value) Nil() bool

func (*Value) Raw

func (v *Value) Raw() ([]byte, error)

func (*Value) String

func (v *Value) String() string

func (*Value) Unmarshal

func (v *Value) Unmarshal(dest interface{}) error