WarpScript Shadow Extension
The Shadow
extension allows you to shadow existing WarpScript functions, either core ones or coming from other extensions. This shadowing process can take several forms, functions can be renamed (rename
), undefined (undef
), made inoperant (noop
), forced to fail (failure
), or replaced by a macro call
.
The shadowing possibility enables you for example to select which functions from an extension should be made available.
Installation
In a configuration file, usually etc/conf.d/70--extensions.conf
, set:
warpscript.extension.shadow = zzz#io.warp10.script.ext.shadow.ShadowWarpScriptExtension
The zzz#
prefix is a sorting key used to ensure that the shadow extension is loaded last so it can shadow any function, even those defined in other extensions.
Operation
The shadow extension will treat the various options of shadowing in the following order: rename, macro call, noop, failure, undef. Any function for which multiple options were defined will only be treated by the one further at the end of the above order.
rename
Functions can be renamed by defining shadow.rename.NAME
keys in the Warp 10 configuration file.
The value associated with shadow.rename.NAME
is the new name of the function.
Once a function is renamed, it is undefined for the original name.
macro call
Functions can be replaced by a macro call when they appear in the comma separated list associated with the configuration key shadow.macro
.
The macro associated with each function will be the name of the function prefixed with the value of the shadow.macroprefix
configuration followed by /
.
Specific macros can be specified for a function by declaring the name of the macro in the shadow.macro.FUNCTION
configuration.
Any use of the function will trigger an execution of the macro associated with it. The macro resolution is performed at execution time, not attempt is made to validate the macro when the extension is loaded.
Due to the macro resolution being performed at execution time, it might be desirable that the symbol table be looked up for the macro. This behavior is disabled by default, but it can be re-enabled by configuring shadow.unsafemacro
or shadow.unsafemacro.FUNCTION
to true
.
noop
Functions appearing in the comma separated list associated with the configuration key shadow.noop
will be replaced by a call to the NOOP
function.
failure
Functions appearing in the comma separated list associated with the configuration key shadow.fail
will be replaced by a call to the FAIL
function.
If shadow.failmsg
is defined, the functions will be replaced by a call to MSGFAIL
with the configured message.
If shadow.fail.FUNCTION
is defined, the associated value will be used as a custom message when replacing FUNCTION
by MSGFAIL
.
undef
Functions appearing in the comma separated list associated with the configuration key shadow.undef
will be undefined and their use will cause a Function not found error.