html-script-hook v1.0.0
html-script-hook
About
Calls a callback function with the code for each <script>
tag found in a HTML file. Whatever the callback returns becomes the new code in the <script>
section. To leave the code exactly the same, simply callback with the same argument that was passed in.
Originally this was created to help Istanbul instrument JavaScript in a HTML file so that it can be recognized for code coverage. But it can also support other tools that would want to have access to or modify the <script>
tag. For example: documentation generators, code analysis tools, style analysis, linters, obfuscation, etc.
Install
npm install html-script-hook
Usage
Start with a HTML file:
<!-- test.html -->
<!DOCTYPE html>
<html>
<title>Just a test file</title>
<script>
console.log ("This is a test");
</script>
</html>
<body>
This is a test.
</body>
Run the parser on test.html
:
var fs = require("fs");
var testParser = require("html-script-hook");
var html = fs.readFileSync("test.html", {
encoding: "utf8"
});
// callback receives code from <script> section and replaces it with return value
function gotScript(code) {
// prints: "\nconsole.log (\"this is a test.\\n\");\n"
// which is the line from between the script tags in the HTML
console.log (code);
// replace the current code with a single comment
return "// no more console log";
}
// the `ret` variable will contain the new HTML
var ret = testParser(testhtml, {
// tell the parser to call the gotScript() function for each <script> section
scriptCallback: gotScript
});
End up with a modified <script>
section:
<!-- test.html -->
<!DOCTYPE html>
<html>
<title>Just a test file</title>
<script>// no more console log</script>
</html>
<body>
This is a test.
</body>
Usage With Istanbul
As a bit more of a real world example, here's how to instrument a HTML file for Istanbul code coverage:
var istanbul = require('istanbul');
var scriptHook = require('html-script-hook');
var fs = require("fs");
// create a new Istanbul instrumenter
var instrumenter = new istanbul.Instrumenter();
// read in a HTML file
var html = fs.readFileSync(htmlFilePath, 'utf8');
// parse the HTML file and replace it with a HTML file where the code has been instrumented
// (using the gotScript() callback)
html = scriptHook (html, {scriptCallback: gotScript});
// catch the code in the script section
function gotScript(code, loc) {
// replace the existing code with instrumented code
return instrumenter.instrumentSync(code, htmlFilePath);
}
For the complete example, see the example code from web-component-tester-istanbul, which instruments the files on the server as the files are being requested by the browser.
Options
The parser that is returned by require('html-script-hook')
takes the following arguments:
parser (html, options)
html
required : the string containing the HTML fileoptions
optional : an object with the configuration options for the parser. Those options include the following properties:scriptCallback (code, details)
function, default=undefined : if defined, this function will be called with the code from inside each<script>
section. It takes the form ofscriptCallback (code, details)
and the return value fromscriptCallback
replaces the code for the<script>
section. AssumingpadLineNo
is not set, simply return thecode
argument to leave the code unchanged. Thedetails
argument is experimental, and contains an object describing the location of the code, an object describing start location of the<script>
tag, an object describing start location of the</script>
tag, and aunexpectedEof
flag that indicates that thescriptCallback
was called even though a final</script>
tag wasn't found.padLineNo
boolean, default=true : whether the JavaScript passed to the script callback should start with a number of newlines ("\n") so that it matches the line numbers of the code in the HTML file. Useful for making sure that tools that pick up line numbers use the same line numbers. *htmlCallback (html)
function, default=undefined : if defined, this function will be called with a single argument that is the final HTML with any modified JavaScript. It is the exact same as the return value fromparser
and rather silly, since theparser
is synchronous.
The parser
returns the HTML that was modified by scriptCallback
.
Tests
npm test