LibUserScript

A library to create user specified scripts.

This uses ideas similar to Outfitter's user scripts.

Current version is 1.0

This addon does nothing by itself. It does not register events, and it does not directly register any slash commands or Blizzard Options frames. However, it does present an AceConfig3 table for accessing and modifying created scripts.

It is mainly meant for allowing users to create scripts that respond to events.

See the Script API for the interface provided to created scripts.

Features

• Scripts can declare inline with the script text
  • Interested WoW events
  • Settings that can be modified outside the script
  • User visible description
• Error reporting
• Abuse prevention
  • Limited base environment
  • Specified global environment
  • Limiting frequency (using a 1 second sliding window)
  • Limiting duration

Using the library

1. Create an environment for running scripts.
   This is a simple table where each key is the name of the global variable and the value is a reference to a Lua object (function, table, or value). While possible, it is not recommended to pass _G as this defeats all security (expect irate users whose gold has been lost in many creative ways).
   Lets call this environment environment and set it to { TakeScreenshot = TakeScreenshot }.
   This value is not modified by the library and can be shared amongst scripts.
2. Create a new script object
   script = LibStub("LibUserScript-1.0"):New(environment)
3. Set the script text using the SetText function
   script:SetText("TakeScreenshot()")
4. Execute the script
   • a. Run the script directly
     script:Execute()
   • b. Register for an event using AceEvent-3.0 (similar for CallbackHandler-1.0) embedded in the current addon (self)
     self.RegisterEvent(script, event_name_string, script.Execute, script)
     Where event_name_string is something like "PLAYER_DEAD".

Script Callbacks

The state of the library can be tracked by registering for callbacks using RegisterCallback. The current list of callbacks include:

• OnSettingChanged
• OnStateChanged
• OnTextChanged
• OnResetSettings
• OnEnabledChanged
• OnMaxDurationChanged
• OnMaxFrequencyChanged

Script Functions

Execute

Runs the script defined by SetText.

Takes no arguments.

RegisterCallback/UnregisterCallback/UnregisterAllCallbacks

These are CallbackHandler-1.0 functions. Everything that applies to that library applies here.

IsStateNormal

Check if the current script state is not an error or warning.

Possible states include, Init, Ready and Running. Takes no arguments.

IsStateWarning

Check if the current script state is a warning.

Warnings cause the script to be temporarily suspended for 5 seconds. Warnings are cause for concern. Currently warnings are produced when exceeding the MaxDuration setting or executing more frequently that MaxFrequency. Takes no arguments.

IsStateError

Check if the current script state is an error.

Errors prevent scripts from running. The only way to clear an error is to change the text with SetText. Takes no arguments.

GetText/SetText

Get and set the text of the script.

See Script API for more information. SetText takes a string to run and returns true on success.

ResetSettings

Resets all settings to their default values.

The settings object is not directly visible to outside code, but this will reset all script settings to their default values. Takes no arguments.

GetSetting (also GetSettingConfigValue)/SetSetting (also SetSettingSafe)

Get and set a script setting.

These settings are defined using special comments in the script. GetSettingConfigValue retrieves values appropriate for GetConfig. SetSetting will call assert on failure. SetSettingSafe returns true on success or false and a localized error string on error. The first argument to these functions is the name of the setting. The second argument to SetSetting/SetSettingSafe is the new value.

GetEnabled/SetEnabled

Enables or disables running the script.

The enabled state of a script is separate from its "State".

GetMaxFrequency/SetMaxFrequency

Gets and sets the maximum frequency with which a script may execute.

This value is in executions per second. Setting this value to 0 disables checking script frequency (this is useful for anything that will listen to the combat log). Currently uses an indexed array of size frequency, so do not set this value too large. For values larger than 128, you should probably just disable this feature.

GetMaxDuration/SetMaxDuration

Gets and sets the maximum duration with which a script may execute.

This value is in seconds of execution time.

GetUserData/SetUserData

Gets and sets a user provided value.

This value is not used by the script object, but stored with it.

GetState

Gets the current script execution state.

If the state is not Normal, then the second value contains a localized message string.

GetDescription

Gets the scripts description as defined by the text passed to SetText.

GetEvents

Gets a list of events the script is interested in.

The script object does not register for events.

GetConfig

Gets an AceConfig3 table.

Todo

• Provide ability to specify a set of initialization steps