Ghost

import "ghost:ghost"
import { abort, version } from "ghost:ghost"

The ghost module exposes the interpreter itself: its version, the names it currently knows, and the ability to run more Ghost code or load a compiled plugin.

Methods

ghost.abort()

Raises a value error carrying the given message, stopping the program. This is the one place a script raises an error deliberately, rather than an operation failing on its own. Passing null instead does nothing, so a check with nothing to report can hand back null and be aborted on unconditionally.

ghost.abort("A critical error was encountered. Aborting.")

// expected output: A critical error was encountered. Aborting.

It takes exactly one argument, and that argument must be a string or null.

ghost.execute()

Executes Ghost code represented as a string, in the current scope, and returns the result of the last expression. The string can reference variables and properties that already exist.

console.log(ghost.execute('2 + 2'))

// expected output: 4

ghost.extend()

Loads a plugin compiled through Go, allowing the ability to dynamically extend Ghost with new native functionality. The path is resolved relative to the directory of the running script.

The plugin must export a function named Register taking no arguments, which Ghost calls immediately after loading it. That is where the plugin registers its own functions and modules:

package main

import "ghostlang.org/x/ghost/ghost"

func Register() {
	ghost.RegisterModule("example", ExampleMethods, ExampleProperties)
}

To compile it, use the -buildmode=plugin build flag:

$ go build -buildmode=plugin -o example.so main.go

ghost.extend('./example.so')

Go plugins are unavailable on Windows. Go's plugin package has no Windows implementation at all, so ghost.extend() cannot be used there, even though Ghost itself ships Windows binaries. On Linux and macOS, a plugin must also be built with the same Go toolchain version, and against the same version of Ghost, as the interpreter loading it — otherwise Go refuses to open it.

A plugin's module becomes importable the moment it registers, because import resolves at the point it runs rather than ahead of time:

ghost.extend('./example.so')

import "ghost:example"

A plugin that wants a namespace of its own rather than Ghost's can call ghost.RegisterModuleForScheme instead, and be imported as import "example:thing". See Embedding.

ghost.identifiers()

Returns a list of all identifiers within the current scope.

ghost.identifiers()

Properties

ghost.version

Returns the current version of Ghost.

ghost.version

// expected value: "1.0.0-beta.3"