js:MTScript: Difference between revisions

From RPTools Wiki
Jump to navigation Jump to search
VisualWikitext
No edit summary
m (Removed some extra semicolons where they didn't belong)
 
(9 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.9.4
|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=
<source lang="javascript" line>
<syntaxhighlight lang="javascript" line>
MTScript.abort()
MTScript.abort()
</source>
</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.9.4
|version=1.10.0
|description=
|description=
Like the {{func|assert}} macro.
Like the {{func|assert}} macro.


|usage=
|usage=
<source lang="javascript" line>
<syntaxhighlight lang="javascript" line>
MTScript.mtsAssert(check, message, pad=true)
MTScript.mtsAssert(check, message, pad=true)
</source>
</syntaxhighlight>


'''Parameters'''
'''Parameters'''
Line 41: Line 41:


{{MacroFunction
{{MacroFunction
|name=MTScript.evalMacro;
|name=MTScript.setVariable
|trusted=true
|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
|trusted=true
|version=1.9.4
|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=
<source lang="javascript" line>
<syntaxhighlight lang="javascript" line>
MTScript.evalMacro(macro)
MTScript.evalMacro(macro)
</source>
</syntaxhighlight>


'''Parameters'''
'''Parameters'''
Line 60: Line 94:


{{MacroFunction
{{MacroFunction
|name=MTScript.execMacro;
|name=MTScript.execMacro
|trusted=true
|trusted=true
|version=1.9.4
|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=
<source lang="javascript" line>
<syntaxhighlight lang="javascript" line>
MTScript.execMacro(macro)
MTScript.execMacro(macro)
</source>
</syntaxhighlight>


'''Parameters'''
'''Parameters'''
Line 78: Line 112:
}}
}}
{{MacroFunction
{{MacroFunction
|name=MTScript.getMTScriptCallingArgs;
|name=MTScript.getMTScriptCallingArgs
|trusted=true
|trusted=true
|version=1.9.4
|version=1.10.0
|description=
|description=
Returns the arguments passed to {{func|js.eval}} as a list.
Returns the arguments passed to {{func|js.eval}} as a list.
|usage=
|usage=
<source lang="javascript" line>
<syntaxhighlight lang="javascript" line>
MTScript.getMTScriptCallingArgs()
MTScript.getMTScriptCallingArgs()
</source>
</syntaxhighlight>


'''Parameters'''
'''Parameters'''
Line 94: Line 128:
}}
}}
{{MacroFunction
{{MacroFunction
|name=MTScript.registerMacro;
|name=MTScript.registerMacro
|trusted=true
|trusted=true
|version=1.10.0
|version=1.10.0
Line 101: Line 135:


|usage=
|usage=
<source lang="javascript" line>
<syntaxhighlight lang="javascript" line>
MTScript.registerMacro(macroName, callable)
MTScript.registerMacro(macroName, callable)
</source>
</syntaxhighlight>


'''Parameters'''
'''Parameters'''
Line 112: Line 146:
|example=
|example=
Using {{code|MTScript.registerMacro}}.
Using {{code|MTScript.registerMacro}}.
<source lang="javascript" line>
<syntaxhighlight lang="javascript" line>
function yell(str) {
function yell(str) {
   MapTool.chat.broadcast(str.toUpperCase());
   MapTool.chat.broadcast(str.toUpperCase());
Line 118: Line 152:


MTScript.registerMacro("yell", yell);
MTScript.registerMacro("yell", yell);
</source>
</syntaxhighlight>




<source lang="mtmacro" line>
<syntaxhighlight lang="mtmacro" line>
[h: js.yell("hello world")]
[h: js.yell("hello world")]
</source>
</syntaxhighlight>


'''Output:'''
'''Output:'''
<source>
<syntaxhighlight>
HELLO WORLD
HELLO WORLD
</source>
</syntaxhighlight>


}}
}}

Latest revision as of 23:59, 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

• Introduced in version 1.10.0
Similar to the abort() macro, but accepts no arguments. Immediately halts macro execution with no message.

Usage

MTScript.abort()

Parameters

  • throws - AbortFunctionException


MTScript.mtsAssert() Function

 Note: This function can only be used in a Trusted Macro

• Introduced in version 1.10.0
Like the assert() macro.

Usage

MTScript.mtsAssert(check, message, pad=true)

Parameters

  • check Value to check: if true, do nothing.
  • message Message to include in the error if check is false.
  • pad If true, wrap the error in a localized error string.
  • throws AssertFunctionException if check is false.


MTScript.setVariable() Function

 Note: This function can only be used in a Trusted Macro

• Introduced in version 1.10.0
Sets an MTScript variable. Like {{{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

• Introduced in version 1.10.0
Reads an MTScript variable. Counterpart to 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

• Introduced in version 1.10.0
Run a mtscript macro in the current macro context.

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

• Introduced in version 1.10.0
Run a mtscript macro in a new macro context. This is similar to 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

• Introduced in version 1.10.0
Returns the arguments passed to js.eval() as a list.

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

• Introduced in version 1.10.0
Registers a javascript function as a MT UDF under the js. prefix.

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

Using MTScript.registerMacro. 
function yell(str) {
  MapTool.chat.broadcast(str.toUpperCase());
}

MTScript.registerMacro("yell", yell);



[h: js.yell("hello world")]

Output: 

HELLO WORLD



See Also

JS: MapTool

Retrieved from "https://wiki.rptools.info/index.php?title=js:MTScript&oldid=35195"