Embedding

Zaidlang was not only designed to be a standalone general-purpose programming language, but also to be a scripting language that can be embedded into other applications.

Installing Zaidlang

To get started, simply go get the latest version of Zaidlang. Make sure your project has already been initialized with go mod init.

go get zaidlang.org/x/zaid

Creating a Zaidlang VM

The first step to embedding Zaidlang is to create a new Zaidlang VM. This is the instance that will be used to execute Zaidlang code. To start, simply create a new Zaidlang VM.

vm := zaid.New()

From here we need to configure and set a couple of things before we can execute any Zaidlang code.

Setting the Root Directory

The root directory is the directory that Zaidlang will use to resolve relative imports from your code. For example, if you have a file called foo.zaid in the root directory, you can import it like this anywhere in your code:

import Foo from 'foo'

To set the root directory, simply call the SetDirectory method on the Zaidlang VM.

vm.SetDirectory("/path/to/root/directory")

If you are embedding Zaidlang into an application, you can use the os.Executable function to get the path to the executable file, and then use the filepath.Dir function to get the directory that the executable is in.

executable, err := os.Executable()

if err != nil {
  panic(err)
}

vm.SetDirectory(filepath.Dir(executable))

Setting the Source Code

The next step is to set the source code that you want to execute. This can be done by calling the SetSource method on the Zaidlang VM.

vm.SetSource(`print('Hello, universe!')`)

Executing Zaidlang Code

Once you have set the source code, you can execute it by calling the Execute method on the Zaidlang VM. This will return a Zaidlang object that you can use to get the result of the execution.

result := vm.Execute()

The result will be a Zaidlang object. If the execution was successful, the result will be the value of the last expression in the source code. If the execution failed, the result will be an error object.

// Check if the result is an error
if _, ok := result.(*object.Error); ok {
  // Handle the error
  os.Exit(1)
}

And that's the basics! You can now embed Zaidlang into your application. But there's more you can do; realistically you will want to do more than execute "hello universe" in your application. In the other sections of this documentation, we will cover how to load and execute Zaidlang scripts, how to pass data between Zaidlang and Go, and how to create and use Zaidlang modules.

A Complete Example

Below is a complete example of what we have covered so far. It's a simple program that creates a Zaidlang VM, loads a script, and executes it.

package main

import (
	"os"
	"path/filepath"

	"zaidlang.org/x/zaid/zaid"
	"zaidlang.org/x/zaid/object"
)

func main() {
	// Create a new Zaidlang VM
	vm := zaid.New()

	// Set the root directory
	// Zaidlang will use this to resolve imports from your code
	executable, err := os.Executable()

	if err != nil {
		panic(err)
	}

	vm.SetDirectory(filepath.Dir(executable))

	// Set the source code to execute
	vm.SetSource(`print('Hello, universe!')`)

	// Execute the source code
	// The result will be a zaid object
	result := vm.Execute()

	// Check if the result is an error
	if _, ok := result.(*object.Error); ok {
		os.Exit(1)
	}
}