js:MTScript: Difference between revisions
No edit summary |
m (Removed some extra semicolons where they didn't belong) |
||
(10 intermediate revisions by 4 users not shown) | |||
Line 1: | Line 1: | ||
{{Experimental}} | {{Experimental}} | ||
Within the javascript environment used by {{code|js.eval}}, {{code|MTScript}} is the entry point for interacting with mtscript variables and macros. | Within the javascript environment used by {{code|js.eval}}, {{code|MTScript}} is the entry point for interacting with mtscript variables and macros. (This is separate from and independent of the JavaScript environment used in {{func|frame5}} and similar panels.) | ||
{{MacroFunction | {{MacroFunction | ||
|name=MTScript.abort | |name=MTScript.abort | ||
|trusted=true | |trusted=true | ||
|version=1. | |version=1.10.0 | ||
|description= | |description= | ||
Similar to the {{func|abort}} macro, but accepts no arguments. Immediately halts macro execution with no message. | Similar to the {{func|abort}} macro, but accepts no arguments. Immediately halts macro execution with no message. | ||
|usage= | |usage= | ||
< | <syntaxhighlight lang="javascript" line> | ||
MTScript.abort() | MTScript.abort() | ||
</ | </syntaxhighlight> | ||
'''Parameters''' | '''Parameters''' | ||
* {{code|throws}} - AbortFunctionException | * {{code|throws}} - AbortFunctionException | ||
Line 20: | Line 20: | ||
}} | }} | ||
{{MacroFunction | {{MacroFunction | ||
|name=MTScript.mtsAssert | |name=MTScript.mtsAssert | ||
|trusted=true | |trusted=true | ||
|version=1. | |version=1.10.0 | ||
|description= | |description= | ||
Like the {{func|assert}} macro. | Like the {{func|assert}} macro. | ||
|usage= | |usage= | ||
< | <syntaxhighlight lang="javascript" line> | ||
MTScript.mtsAssert(check, message, pad=true) | MTScript.mtsAssert(check, message, pad=true) | ||
</ | </syntaxhighlight> | ||
'''Parameters''' | '''Parameters''' | ||
Line 41: | Line 41: | ||
{{MacroFunction | {{MacroFunction | ||
|name=MTScript. | |name=MTScript.setVariable | ||
|trusted=true | |trusted=true | ||
|version=1. | |version=1.10.0 | ||
|description= | |||
Sets an MTScript variable. Like {{code|[h: variable = value]}}. For use with {{code|MTScript.evalMacro}}. | |||
|usage= | |||
<syntaxhighlight lang="javascript" line> | |||
MTScript.setVariable(variable, value) | |||
</syntaxhighlight> | |||
'''Parameters''' | |||
* {{code|variable}} - String, Variable name to set. | |||
* {{code|value}} - Any javascript object. Value to set. | |||
}} | |||
{{MacroFunction | |||
|name=MTScript.getVariable | |||
|trusted=true | |||
|version=1.10.0 | |||
|description= | |||
Reads an MTScript variable. Counterpart to {{code|MTScript.setVariable}}. | |||
|usage= | |||
<syntaxhighlight lang="javascript" line> | |||
MTScript.getVariable(variable) | |||
</syntaxhighlight> | |||
'''Parameters''' | |||
* {{code|variable}} - String, Variable name to get. | |||
}} | |||
{{MacroFunction | |||
|name=MTScript.evalMacro | |||
|trusted=true | |||
|version=1.10.0 | |||
|description= | |description= | ||
Run a mtscript macro in the current macro context. | Run a mtscript macro in the current macro context. | ||
|usage= | |usage= | ||
< | <syntaxhighlight lang="javascript" line> | ||
MTScript.evalMacro(macro) | MTScript.evalMacro(macro) | ||
</ | </syntaxhighlight> | ||
'''Parameters''' | '''Parameters''' | ||
Line 60: | Line 94: | ||
{{MacroFunction | {{MacroFunction | ||
|name=MTScript.execMacro | |name=MTScript.execMacro | ||
|trusted=true | |trusted=true | ||
|version=1. | |version=1.10.0 | ||
|description= | |description= | ||
Run a mtscript macro in <b>a new macro context</b>. This is similar to {{code|evalMacro}}, except variables from the previous macro context are unavailable, and changes to mtscript variables from within this macro are discarded when the macro exits. | Run a mtscript macro in <b>a new macro context</b>. This is similar to {{code|evalMacro}}, except variables from the previous macro context are unavailable, and changes to mtscript variables from within this macro are discarded when the macro exits. | ||
|usage= | |usage= | ||
< | <syntaxhighlight lang="javascript" line> | ||
MTScript.execMacro(macro) | MTScript.execMacro(macro) | ||
</ | </syntaxhighlight> | ||
'''Parameters''' | '''Parameters''' | ||
Line 78: | Line 112: | ||
}} | }} | ||
{{MacroFunction | {{MacroFunction | ||
|name=MTScript.getMTScriptCallingArgs | |name=MTScript.getMTScriptCallingArgs | ||
|trusted=true | |trusted=true | ||
|version=1. | |version=1.10.0 | ||
|description= | |description= | ||
Returns the arguments passed to | Returns the arguments passed to {{func|js.eval}} as a list. | ||
|usage= | |usage= | ||
< | <syntaxhighlight lang="javascript" line> | ||
MTScript.getMTScriptCallingArgs() | MTScript.getMTScriptCallingArgs() | ||
</ | </syntaxhighlight> | ||
'''Parameters''' | '''Parameters''' | ||
* {{code|return}} list of arguments passed to the current | * {{code|return}} list of arguments passed to the current {{func|js.eval}} call. | ||
}} | }} | ||
{{MacroFunction | |||
|name=MTScript.registerMacro | |||
|trusted=true | |||
|version=1.10.0 | |||
|description= | |||
Registers a javascript function as a MT UDF under the js. prefix. | |||
|usage= | |||
<syntaxhighlight lang="javascript" line> | |||
MTScript.registerMacro(macroName, callable) | |||
</syntaxhighlight> | |||
'''Parameters''' | |||
* {{code|macroName}} Name for the new UDF. Note that "js." will be prepended to the name. | |||
* {{code|callable}} Any javascript callable. | |||
|example= | |||
Using {{code|MTScript.registerMacro}}. | |||
<syntaxhighlight lang="javascript" line> | |||
function yell(str) { | |||
MapTool.chat.broadcast(str.toUpperCase()); | |||
} | |||
MTScript.registerMacro("yell", yell); | |||
</syntaxhighlight> | |||
<syntaxhighlight lang="mtmacro" line> | |||
[h: js.yell("hello world")] | |||
</syntaxhighlight> | |||
'''Output:''' | |||
<syntaxhighlight> | |||
HELLO WORLD | |||
</syntaxhighlight> | |||
}} | |||
Latest revision as of 05:05, 5 July 2023
This article describes a feature or macro function that is experimental and may be subject to change.
Within the javascript environment used by js.eval
, MTScript
is the entry point for interacting with mtscript variables and macros. (This is separate from and independent of the JavaScript environment used in frame5() and similar panels.)
MTScript.abort() Function
Note: This function can only be used in a Trusted Macro
Usage
MTScript.abort()
Parameters
throws
- AbortFunctionException
MTScript.mtsAssert() Function
Note: This function can only be used in a Trusted Macro
Usage
MTScript.mtsAssert(check, message, pad=true)
Parameters
check
Value to check: iftrue
, do nothing.message
Message to include in the error ifcheck
is false.pad
If true, wrap the error in a localized error string.throws
AssertFunctionException ifcheck
is false.
MTScript.setVariable() Function
Note: This function can only be used in a Trusted Macro
{{{1}}}
. For use with MTScript.evalMacro
.Usage
MTScript.setVariable(variable, value)
Parameters
variable
- String, Variable name to set.value
- Any javascript object. Value to set.
MTScript.getVariable() Function
Note: This function can only be used in a Trusted Macro
MTScript.setVariable
.Usage
MTScript.getVariable(variable)
Parameters
variable
- String, Variable name to get.
MTScript.evalMacro() Function
Note: This function can only be used in a Trusted Macro
Usage
MTScript.evalMacro(macro)
Parameters
macro
String to run as a macro.return
Any mtscript type.
MTScript.execMacro() Function
Note: This function can only be used in a Trusted Macro
evalMacro
, except variables from the previous macro context are unavailable, and changes to mtscript variables from within this macro are discarded when the macro exits.Usage
MTScript.execMacro(macro)
Parameters
macro
String to run as a macro.return
Any mtscript type.
MTScript.getMTScriptCallingArgs() Function
Note: This function can only be used in a Trusted Macro
Usage
MTScript.getMTScriptCallingArgs()
Parameters
return
list of arguments passed to the current js.eval() call.
MTScript.registerMacro() Function
Note: This function can only be used in a Trusted Macro
Usage
MTScript.registerMacro(macroName, callable)
Parameters
macroName
Name for the new UDF. Note that "js." will be prepended to the name.callable
Any javascript callable.
Example
MTScript.registerMacro
.
function yell(str) {
MapTool.chat.broadcast(str.toUpperCase());
}
MTScript.registerMacro("yell", yell);
[h: js.yell("hello world")]
Output:
HELLO WORLD