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.