API Reference

Initialization and termination

• script_env* script_init(const char* namespace)
  Initializes LibScript and returns a pointer to the virtual environment. The namespace parameter indicates the name to be used in structures that will be created in the namespaces of the various virtual machines used to represent the virtual environment.
• void script_done(script_env* env)
  Terminates the virtual environment.

Registration of functions

• typedef script_err (*script_fn)(script_env*)
  Type of C functions to be registered in the virtual environment. When exposing an existing API to LibScript, the function will typically be a wrapper that loads the input parameters from the environment, calls the function and then sends the output parameters back to the environment.
• script_err script_new_function(script_env* env, script_fn fn, const char* name)
  Registers a function in the virtual environment.

Parameters buffer

• double script_get_double(script_env* env, int index)
  int script_get_int(script_env* env, int index)
  int script_get_bool(script_env* env, int index)
  const char* script_get_string(script_env* env, int index)
  Obtains data from the buffer. These functions must be called in the beginning of wrapper functions. For each input parameter, a call to one of these functions should be made. After all parameters are collected, one can invoke the SCRIPT_CHECK_INPUTS(env) macro, which terminates the function returning an error code if any of the preceding calls could not find a value of the expected type. (The API does not perform automatic conversions between strings and numbers.) In script_get_string, the string to be returned belongs to the caller, who becomes responsible for deallocating it.
• script_type script_get_type(script_env* env, int index)
  int script_buffer_len(script_env* env)
  These functions allow one to write C functions that perform verification on the type and number of parameters in runtime. The script_get_type function obtains the type of the item at the requested buffer index and script_buffer_len returns the number of items in the buffer.
• void script_put_double(script_env* env, int index, double value)
  void script_put_int(script_env* env, int index, int value)
  void script_put_bool(script_env* env, int index, int value)
  void script_put_string(script_env* env, int index, const char* value)
  Inserts data in the buffer. At the end of a registered C function, the return values should be passed as calls to these functions and a SCRIPT_OK error code should be passed as the function result.
• void script_reset_buffer(script_env* env)
  Empties the buffer.

Executing code

• script_err script_run(script_env* env, const char* language, const char* code)
  Executes a string of code in a given langugage. If necessary, the appropriate plugin is loaded and initialized.
• script_err script_run_file(script_env* env, const char* filename)
  Convenience function; loads the text of a file and executes it with script_run. The language is detected based on the filename extension or the #! identifier in the first line.
• script_err script_call(script_env* env, const char* fn)
  Calls a function. The input parameters should be given beforehand with script_put_* calls; return values can be obtained with script_get_*. Initially, the table of registered C functions from the virtual environment in consulted. If there is no function registered there with the given name, the plugins are queried for the availability of the function. Functions registered in the languages' data structures that represent the virtual environment become accessible through script_call.
• script_err script_error(script_env* env)
  const char* script_error_message(script_env* env)
  void script_set_error_message(script_env* env, const char* message)
  Obtains the error message and code from the most recent error of an environment. After a script_error call, the error code is cleared back to SCRIPT_OK. The error message is not cleared. The script_set_error_message function defines a new value for the environment's error message. This allows a plugin to propagate to the application the virtual machine error messages.
• const char* script_get_namespace(script_env* env)
  Returns the name of the namespace registered with script_init for the given virtual environment.

API to be exported by plugins

Calls to plugins (libraries that implement interfaces with the various virtual machines) are performed internally by the main LibScript library. The main library expects to find the following symbols declared in a plugin:

• script_plugin_state script_plugin_init_language(script_env* env)
  Responsible for initializing the plugin. During its initialization, the namespace of the virtual environment should be exposed to the virtual machine in some appropriate way (as a table in Lua, as a module in Python, as a class in Ruby, etc.). The initialization routine can return a handle that will be passed back to it in subsequent calls. The virtual machine state and the pointer to the LibScript environment should be stored in a way so they can be accessible from this handle.
• script_err script_plugin_run_language(script_plugin_state st, char* text)
  Sends code to be executed by the virtual machine. This function is used internally by script_run and script_run_file. It should return SCRIPT_OK in case of succes, SCRIPT_ERRLANGCOMP for compilation errors or SCRIPT ERRLANGRUN for runtime errors, preferrably setting an error message with script_set_error_message.
• script_err script_plugin_call_language(script_plugin_state st, char* fn)
  Calls a function defined natively in the namespace of the virtual machine in the plugin. When calling a function in the namespace, through script_call or running code in another plugin, LibScript will use this function to try to the requested function fn in this plugin. If the function was not defined in this plugin, the value SCRIPT_ERRFNUNDEF must be returned. Otherwise, the function should be executed, obtaining input parameters with script_get_* and returning output values with script_put_*, and the error codes SCRIPT_OK or SCRIPT_ERRLANGRUN should be returned, as appropriate.
• void script_plugin_done_language(script_plugin_state st)
  Responsible for terminating an environment.

---