1 |
|
/* |
2 |
|
Copyright (c) 2012, Yahoo! Inc. All rights reserved. |
3 |
|
Copyrights licensed under the New BSD License. See the accompanying LICENSE file for terms. |
4 |
|
*/ |
5 |
|
|
6 |
|
/** |
7 |
|
* provides a mechanism to transform code in the scope of `require` or `vm.createScript`. |
8 |
|
* This mechanism is general and relies on a user-supplied `matcher` function that determines when transformations should be |
9 |
|
* performed and a user-supplied `transformer` function that performs the actual transform. |
10 |
|
* Instrumenting code for coverage is one specific example of useful hooking. |
11 |
|
* |
12 |
|
* Note that both the `matcher` and `transformer` must execute synchronously. |
13 |
|
* |
14 |
|
* For the common case of matching filesystem paths based on inclusion/ exclusion patterns, use the `matcherFor` |
15 |
|
* function in the istanbul API to get a matcher. |
16 |
|
* |
17 |
|
* It is up to the transformer to perform processing with side-effects, such as caching, storing the original |
18 |
|
* source code to disk in case of dynamically generated scripts etc. The `Store` class can help you with this. |
19 |
|
* |
20 |
|
* Usage |
21 |
|
* ----- |
22 |
|
* |
23 |
|
* var hook = require('istanbul').hook, |
24 |
|
* myMatcher = function (file) { return file.match(/foo/); }, |
25 |
|
* myTransformer = function (code, file) { return 'console.log("' + file + '");' + code; }; |
26 |
|
* |
27 |
|
* hook.hookRequire(myMatcher, myTransformer); |
28 |
|
* |
29 |
|
* var foo = require('foo'); //will now print foo's module path to console |
30 |
|
* |
31 |
|
* @class Hook |
32 |
|
*/ |
33 |
|
/*jslint nomen: true */ |
34 |
1 |
var path = require('path'), |
35 |
|
fs = require('fs'), |
36 |
|
Module = require('module'), |
37 |
|
vm = require('vm'), |
38 |
|
originalLoader = Module._extensions['.js'], |
39 |
|
originalCreateScript = vm.createScript, |
40 |
|
lastMatcher; |
41 |
|
|
42 |
1 |
function transformFn(matcher, transformer, verbose) { |
43 |
|
|
44 |
9 |
return function (code, filename) { |
45 |
6 |
var shouldHook = matcher(filename), |
46 |
|
transformed, |
47 |
|
changed = false; |
48 |
|
|
49 |
6 |
if (shouldHook) { |
50 |
5 |
if (verbose) { |
51 |
1 |
console.error('Module load hook: transform [' + filename + ']'); |
52 |
|
} |
53 |
5 |
try { |
54 |
5 |
transformed = transformer(code, filename); |
55 |
4 |
changed = true; |
56 |
|
} catch (ex) { |
57 |
1 |
console.error('Transformation error; return original code'); |
58 |
1 |
console.error(ex); |
59 |
1 |
transformed = code; |
60 |
|
} |
61 |
|
} else { |
62 |
1 |
transformed = code; |
63 |
|
} |
64 |
6 |
return { code: transformed, changed: changed }; |
65 |
|
}; |
66 |
|
} |
67 |
|
|
68 |
1 |
function unloadRequireCache(matcher) { |
69 |
11 |
Eif (matcher && typeof require !== 'undefined' && require && require.cache) { |
70 |
11 |
Object.keys(require.cache).forEach(function (filename) { |
71 |
1343 |
if (matcher(filename)) { |
72 |
3 |
delete require.cache[filename]; |
73 |
|
} |
74 |
|
}); |
75 |
|
} |
76 |
|
} |
77 |
|
/** |
78 |
|
* hooks `require` to return transformed code to the node module loader. |
79 |
|
* Exceptions in the transform result in the original code being used instead. |
80 |
|
* @method hookRequire |
81 |
|
* @static |
82 |
|
* @param matcher {Function(filePath)} a function that is called with the absolute path to the file being |
83 |
|
* `require`-d. Should return a truthy value when transformations need to be applied to the code, a falsy value otherwise |
84 |
|
* @param transformer {Function(code, filePath)} a function called with the original code and the associated path of the file |
85 |
|
* from where the code was loaded. Should return the transformed code. |
86 |
|
* @param options {Object} options Optional. |
87 |
|
* @param {Boolean} [options.verbose] write a line to standard error every time the transformer is called |
88 |
|
*/ |
89 |
1 |
function hookRequire(matcher, transformer, options) { |
90 |
8 |
options = options || {}; |
91 |
8 |
lastMatcher = matcher; |
92 |
8 |
var fn = transformFn(matcher, transformer, options.verbose), |
93 |
|
postLoadHook = options.postLoadHook |
94 |
|
&& typeof options.postLoadHook === 'function' ? options.postLoadHook : null; |
95 |
|
|
96 |
8 |
Module._extensions['.js'] = function (module, filename) { |
97 |
5 |
var ret = fn(fs.readFileSync(filename, 'utf8'), filename); |
98 |
5 |
if (ret.changed) { |
99 |
3 |
module._compile(ret.code, filename); |
100 |
|
} else { |
101 |
2 |
originalLoader(module, filename); |
102 |
|
} |
103 |
5 |
if (postLoadHook) { |
104 |
1 |
postLoadHook(filename); |
105 |
|
} |
106 |
|
}; |
107 |
8 |
unloadRequireCache(matcher); |
108 |
|
} |
109 |
|
/** |
110 |
|
* unhook `require` to restore it to its original state. Also unloads the modules in |
111 |
|
* the `require` cache that would have matched the matcher provide in the |
112 |
|
* `hookRequire` method. |
113 |
|
* @method unhookRequire |
114 |
|
* @static |
115 |
|
*/ |
116 |
1 |
function unhookRequire() { |
117 |
3 |
Module._extensions['.js'] = originalLoader; |
118 |
3 |
unloadRequireCache(lastMatcher); |
119 |
|
} |
120 |
|
/** |
121 |
|
* hooks `vm.createScript` to return transformed code out of which a `Script` object will be created. |
122 |
|
* Exceptions in the transform result in the original code being used instead. |
123 |
|
* @method hookCreateScript |
124 |
|
* @static |
125 |
|
* @param matcher {Function(filePath)} a function that is called with the filename passed to `vm.createScript` |
126 |
|
* Should return a truthy value when transformations need to be applied to the code, a falsy value otherwise |
127 |
|
* @param transformer {Function(code, filePath)} a function called with the original code and the filename passed to |
128 |
|
* `vm.createScript`. Should return the transformed code. |
129 |
|
* @param options {Object} options Optional. |
130 |
|
* @param {Boolean} [options.verbose] write a line to standard error every time the transformer is called |
131 |
|
*/ |
132 |
1 |
function hookCreateScript(matcher, transformer, opts) { |
133 |
1 |
opts = opts || {}; |
134 |
1 |
var fn = transformFn(matcher, transformer, opts.verbose); |
135 |
1 |
vm.createScript = function (code, file) { |
136 |
1 |
var ret = fn(code, file); |
137 |
1 |
return originalCreateScript(ret.code, file); |
138 |
|
}; |
139 |
|
} |
140 |
|
|
141 |
|
/** |
142 |
|
* unhooks vm.createScript, restoring it to its original state. |
143 |
|
* @method unhookCreateScript |
144 |
|
* @static |
145 |
|
*/ |
146 |
1 |
function unhookCreateScript() { |
147 |
1 |
vm.createScript = originalCreateScript; |
148 |
|
} |
149 |
|
|
150 |
1 |
module.exports = { |
151 |
|
hookRequire: hookRequire, |
152 |
|
unhookRequire: unhookRequire, |
153 |
|
hookCreateScript: hookCreateScript, |
154 |
|
unhookCreateScript: unhookCreateScript |
155 |
|
}; |
156 |
|
|
157 |
|
|
158 |
|
|