1.0.0-alpha.2
istanbul-lib-hook provides mechanisms to transform code in the scope of require
,
vm.createScript
, vm.runInThisContext
etc.
This mechanism is general and relies on a user-supplied matcher
function that
determines when transformations should be performed and a user-supplied transformer
function that performs the actual transform. Instrumenting code for coverage is
one specific example of useful hooking.
Note that both the matcher
and transformer
must execute synchronously.
var hook = require('istanbul-lib-hook'),
myMatcher = function (file) { return file.match(/foo/); },
myTransformer = function (code, file) {
return 'console.log("' + file + '");' + code;
};
hook.hookRequire(myMatcher, myTransformer);
var foo = require('foo'); //will now print foo's module path to console
hooks vm.createScript
to return transformed code out of which a Script
object will be created.
Exceptions in the transform result in the original code being used instead.
{Function(filePath)} a function that is called with the filename passed to vm.createScript
Should return a truthy value when transformations need to be applied to the code, a falsy value otherwise
{Function(code, filePath)} a function called with the original code and the filename passed to
vm.createScript
. Should return the transformed code.
{Object} options Optional.
[Boolean
]
options.verbose
write a line to standard error every time the transformer is called
hooks require
to return transformed code to the node module loader.
Exceptions in the transform result in the original code being used instead.
{Function(filePath)} a function that is called with the absolute path to the file being
require
-d. Should return a truthy value when transformations need to be applied to the code, a falsy value otherwise
{Function(code, filePath)} a function called with the original code and the associated path of the file from where the code was loaded. Should return the transformed code.
{Object} options Optional.
hooks vm.runInThisContext
to return transformed code.
{Function(filePath)} a function that is called with the filename passed to vm.createScript
Should return a truthy value when transformations need to be applied to the code, a falsy value otherwise
{Function(code, filePath)} a function called with the original code and the filename passed to
vm.createScript
. Should return the transformed code.
{Object} [opts={}] options
[Boolean
]
opts.verbose
write a line to standard error every time the transformer is called
unloads the required caches, removing all files that would have matched the supplied matcher.
Function
matcher
:
the match function that accepts a file name and returns if that file should be unloaded from the cache.