API reference

Signatures only. For a first program see Getting started.

#include <ReScripted.h>. Namespace rescripted. C++17.

Typical startup

rescripted::Engine engine;
engine.add_language(rescripted::Language::compile(rescripted::embed::mylang));
engine.bind("print", print_fn);
engine.add_library("math", rescripted::library::math);

auto id = engine.load_file("scripts/quest.mylang");
engine.run(id);
engine.call("start", {});
engine.unload(id);

Version

RESCRIPTED_VERSION_MAJOR, MINOR, PATCH, STRING. version() returns const char*.

Language

static Language compile(std::string_view json);

Throws Error if name is missing or still the placeholder. Throws ParseError if the text is not JSON.

name(), extensions(), matches_path(path), definition() (the JSON tree).

RESCRIPTED_LANGUAGE(literal) is Language::compile on that literal.

Engine

Built-in names: print, len, str, type. print returns a string; it does not write to stdout.

Languages

void add_language(Language);
void remove_language(std::string_view name);
bool has_language(std::string_view name) const;
const Language& language(std::string_view name) const;

Host functions

void bind(std::string name, HostFn);
void unbind(std::string_view name);
void bind_type(std::string name, HostFn construct);
void bind_decorator(std::string name, DecoratorFn);

HostFn is std::function<Value(const std::vector<Value>&)>. DecoratorFn is std::function<void(const std::string& target, const Value&)>.

Decorator hooks run on load, on functions only.

Libraries

void add_library(std::string import_name, Library);
void add_library(std::string import_name, std::map<std::string, HostFn>);
void add_library(std::string import_name, std::map<std::string, Value>);
void add_library(std::string import_name, std::string source, std::string_view language);
void add_library(std::string import_name, std::string path);
void add_library_file(std::string import_name, std::string path);
void remove_library(std::string_view import_name);
bool has_library(std::string_view import_name) const;
void add_search_path(std::string path);
void set_plugin_entry(std::string name);
void load_plugin(const std::string& path);
void load_plugin(const std::string& path, std::string entry_name);

You choose import_name. CMake does not. add_library(name, path) is a script, a best-effort header, or a plugin by extension.

RESCRIPTED_LIBRARY(math) { lib.bind("twice", fn); }
RESCRIPTED_LIBRARY_DECLARE(math);
engine.add_library("math", rescripted::library::math);

Scripts

ScriptId load(std::string source, std::string script_name, std::string_view language_name);
ScriptId load_file(const std::string& path, std::string_view language_name = {});
void unload(ScriptId);
void unload(std::string_view script_name);

Value run(ScriptId);
Value run(std::string_view script_name);
Value run_file(const std::string& path, std::string_view language_name = {});
Value eval(std::string_view source, std::string_view language_name);
Value call(std::string_view function_name, const std::vector<Value>& args = {});
const Value* get(std::string_view name) const;
Environment& globals();

ScriptId is std::size_t.

• load — parse; functions become callable
• run — execute the top of the file
• eval — load + run + unload
• run_file — load + run, leave loaded
• load_file with an empty language name — first language whose extension matches path

Value

Null, bool, number (double), string, array, map, function.

Value();
Value(true);
Value(3.0);
Value("hi");
Value(std::vector<Value>{});
Value(std::map<std::string, Value>{});
Value::function(name, HostFn);   // prefer engine.bind

is_null(), is_bool(), is_number(), is_string(), is_array(), is_map(), is_function().

as_bool() uses truthiness. as_number(), as_string(), as_array(), as_map() throw RuntimeError on the wrong type. to_string() always works. call(args) invokes a function value. equals compares null, bool, number, and string.

Errors

Type	Typical cause
Error	unknown language, missing script, file not found
ParseError	bad JSON or bad script; line(), column()
RuntimeError	undefined name, bad call, division by zero, bad conversion

ParseError and RuntimeError inherit Error. Error inherits std::runtime_error. Catch Error for every ReScripted failure.