### istanbul-lib-hook

`1.0.0-alpha.2`

## Exports

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.

#### Examples

    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

## hookCreateScript(matcher, transformer, options, opts)

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.

#### Parameters

- matcher :

  {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

- transformer :

  {Function(code, filePath)} a function called with the original code and the filename passed to `vm.createScript`. Should return the transformed code.

- options :

  {Object} options Optional.

- `[`Boolean`]` options.verbose

  write a line to standard error every time the transformer is called

- opts :

## hookRequire(matcher, transformer, options)

hooks `require` to return transformed code to the node module loader. Exceptions in the transform result in the original code being used instead.

#### Parameters

- matcher :

  {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

- transformer :

  {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.

- options :

  {Object} options Optional.

- `[`Boolean`]` options.verbose

  write a line to standard error every time the transformer is called

- `[`Function`]` options.postLoadHook

  a function that is called with the name of the file being required. This is called after the require is processed irrespective of whether it was transformed.

## hookRunInThisContext(matcher, transformer, opts)

hooks `vm.runInThisContext` to return transformed code.

#### Parameters

- matcher :

  {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

- transformer :

  {Function(code, filePath)} a function called with the original code and the filename passed to `vm.createScript`. Should return the transformed code.

- opts :

  {Object} [opts={}] options

- `[`Boolean`]` opts.verbose

  write a line to standard error every time the transformer is called

## unhookCreateScript

unhooks vm.createScript, restoring it to its original state.

## unhookRequire

unhook `require` to restore it to its original state.

## unhookRunInThisContext

unhooks vm.runInThisContext, restoring it to its original state.

## unloadRequireCache(matcher)

unloads the required caches, removing all files that would have matched the supplied matcher.

#### Parameters

- `Function` matcher :

  the match function that accepts a file name and returns if that file should be unloaded from the cache.