# Module `script`

Use script to handle script events, libraries and files.

The script global is available to every protoplug script after including the main protoplug header :

    require "include/protoplug"

## Functions

script.addHandler (event, handler) | Add a handler for a script event.
script.saveData () | Save script data.
script.loadData (data) | Load script data.
script.ffiLoad (libName[, ...]) | Load shared libraries.

## Predefined values

script.protoplugDir | Current protoplug directory.

## Functions

script.addHandler (event, handler)

  Add a handler for a script event. The following events are available :

  - `"init"` - Emitted after the script has been compiled and run.
  - `"preClose"` - Emitted before the script state gets destroyed.

  ### Parameters:

  - event string the event to handle
  - handler function a function to add the event's handlers

  ### See also:

  - plugin.addHandler
  - gui.addHandler
script.saveData ()
  Save script data. Override this function to save any custom data.

  This gets called : - when the host saves the plugin's state (eg. when saving a project) - right before the script is recompiled, to keep custom data across compilations.

  ### Returns:

  string the data to be saved
script.loadData (data)
  Load script data. Override this function to load any custom data. Be warned that the data might originate from another script, so it's a good idea to start the data with a header confirming the format.

  This gets called : - when the host loads the plugin's state (eg. when loading a project) - right after the script is recompiled, to keep custom data across compilations.

  ### Parameters:

  - data string the data to be loaded
script.ffiLoad (libName[, ...])
  Load shared libraries. Protoplug scripts should use this wrapper function instead of LuaJIT's ffi.load. It has the same behaviour as `ffi.load`, but it adds `protoplug/lib` as a search path, and can accept multiple arguments to test for different library names. The names are tested from left to right until one load successfully. If none of them work, an error is raised.

      sdl = script.ffiLoad("sdl")

  This looks for `libsdl.so` or `sdl.dll` in protoplug's lib folder and in the system paths.

      fftw = script.ffiLoad("libfftw3.so.3", "libfftw3-3.dll")

  This looks for the supplied names in the same locations as above. This is necessary for libs like FFTW, that have has platform-dependent names.

  ### Parameters:

  - libName string
  - ... string alternate names for the same library

  ### Returns:

  The library's ffi namespace

## Predefined values

script.protoplugDir
  Current protoplug directory. The full path of the `protoplug` directory currently being used. It should be alongside the protoplug fx and gen dynamic libraries.

generated by LDoc 1.4.2