grunt-expand-include
v0.9.5grunt-expand-include
Grunt Task for Expanding Include Directives
Getting Started
This plugin requires Grunt ~0.4.0
If you haven't used Grunt before, be sure to check out the Getting Started guide, as it explains how to create a Gruntfile as well as install and use Grunt plugins. Once you're familiar with that process, you may install this plugin with this command:
npm install grunt-expand-include --save-dev
Once the plugin has been installed, it may be enabled inside your Gruntfile with this line of JavaScript:
grunt.loadNpmTasks("grunt-expand-include");
Task Options
directiveSyntax
: (defaultjs
) either the name of a pre-defined directive syntax (js
,css
orxml
) or alternatively defining a new syntax from scratch. The pre-defined syntax are:```js directiveSyntax: { /* style: valid JavaScript (JS) */ /* header: // foo */ /* include: include("foo", { bar: "quux", baz: "quux" }); */ /* expand: $bar */ /* adjust: require("quux") */ include: /([ \t]*)include\(\s*(["'])((?:\\\2|(?!\2).)+)\2\s*(?:,\s*(\{(?:[\r\n]|.)*?\}))?\s*\)\s*;?([ \t]*(\r?\n)?)/g, define: /\s*(["']?)([a-zA-Z][a-zA-Z0-9_-]*)\1\s*:\s*(["'])((?:\\\3|(?!\3).)*)\3\s*/g, expand: /\$([a-zA-Z][a-zA-Z0-9_-]*)/g, header: /^(?:\/\*[^!](?:[\r\n]|.)*?\*\/|(?:\/\/[^\r\n]*\r?\n)*)\r?\n/, adjust: /(\brequire\((["']))((?:\\\2|(?!\2).)+)(\2\))/g } directiveSyntax: { /* style: valid Cascading Style Sheets (CSS) */ /* header: // foo */ /* include: @import "foo"; */ /* expand: @bar */ /* adjust: url("quux") */ include: /([ \t]*)include\(\s*(["'])((?:\\\2|(?!\2).)+)\2\s*(?:,\s*(\{(?:[\r\n]|.)*?\}))?\s*\)\s*;?([ \t]*(\r?\n)?)/g, define: /\s*(["']?)([a-zA-Z][a-zA-Z0-9_-]*)\1\s*:\s*(["'])((?:\\\3|(?!\3).)*)\3\s*/g, expand: /\$([a-zA-Z][a-zA-Z0-9_-]*)/g, header: /^(?:\/\*[^!](?:[\r\n]|.)*?\*\/|(?:\/\/[^\r\n]*\r?\n)*)\r?\n/, adjust: /(\burl\((["']))((?:\\\2|(?!\2).)+)(\2\))/g } directiveSyntax: { /* style: valid eXtensible Markup Language (XML) */ /* header: <!-- foo --> */ /* include: <include file="foo" bar="quux" baz="quux"/> */ /* expand: &bar; */ /* adjust: href="quux" or src="quux" */ include: /([ \t]*)<include\s+file=(["'])((?:\\\2|(?!\2).)+)\2((?:\s*[a-zA-Z][a-zA-Z0-9_-]*=(["'])(?:\\\5|(?!\5).)*\5)*)\s*\/>([ \t]*(\r?\n)?)/g, define: /\s*()([a-zA-Z][a-zA-Z0-9_-]*)=(["'])((?:\\\3|(?!\3).)*)\3\s*/g, expand: /\&([a-zA-Z][a-zA-Z0-9_-]*);/g, header: /^<!--[^!](?:[\r\n]|.)*?-->\r?\n/, adjust: /(\s(?:href|src)=(["']))((?:\\\2|(?!\2).)+)(\2)/g } ```
ATTENTION: when providing an own
directiveSyntax
for parsing other languages, ensure that you are providing the same number of capturing groups and in the same order. The underlying implementation depends on them for processing the parsed input snippets!expandIncludes
: (defaulttrue
) whether to expand thedirectiveSyntax.include
directives (a primary functionality of this plugin).expandDefines
: (defaulttrue
) whether to expand thedirectiveSyntax.expand
directives (a secondary functionality of this plugin). Disable in case this expansion functionality causes trouble to you.adjustReferences
: (defaulttrue
) whether to expand thedirectiveSyntax.adjust
directives (a secondary functionality of this plugin). Disable in case this expansion functionality causes trouble to you.onUndefinedVariable
: (defaultkeep
) action in case of a variable expansion where the variable is not defined:keep
for keeping the directive as-is,empty
for replacing the directive with an empty string orerror
to bail out.stripHeaderOfInclude
: (defaulttrue
) whether to strip the initial header comment (seedirectiveSyntax.header
) of include files.keepWhitespaceProlog
: (defaultfalse
) whether to keep the whitespace prolog (see capture group 1 ofdirectiveSyntax.include
).keepWhitespaceEpilog
: (defaultfalse
) whether to keep the whitespace epilog (see capture group 4 ofdirectiveSyntax.include
).repeatWhitespaceProlog
: (defaulttrue
) whether to repeat the whitespace epilog (see capture group 1 ofdirectiveSyntax.include
) on all lines of the included file.lineTerminator
: (default"\n"
) the line terminator character(s) which should be applied onto the entire expanded destination file.globalDefines
: (default{}
) the global variable defines passed into the expansion process (can be expanded withdirectiveSyntax.expand
).
Expand Include Task
Run this task with the grunt expand-include
command.
Task targets, files and options may be specified according to the Grunt Configuring tasks guide.
Usage Example
Assuming we have the following source files, compromising a JavaScript library:
src/foo-lib.js
:
/* Universal Module Definition (UMD) */
(function (root, factory) {
if (typeof define === "function" && define.amd)
define('foo', function () { return factory(root); });
else if (typeof module === "object" && typeof exports === "object")
module.exports = factory(root);
else
root.foo = factory(root);
}(this, function (root) {
var foo = {};
include("foo-version.js", { minor: "99", micro: "42" });
include("foo-bar.js");
include("foo-baz.js");
return foo;
}));
src/foo-version.js
:
foo.version = { major: $major, minor: $minor, micro: $micro };
src/foo-bar.js
:
foo.bar = function () {
/* [...bar functionality...] */
};
src/foo-baz.js
:
foo.baz = function () {
/* [...baz functionality...] */
};
Assuming we have the following build environment:
Gruntfile.js
:
// [...]
grunt.initConfig({
pkg: grunt.file.readJSON("package.json"),
"expand-include": {
"foo": {
src: [ "src/foo-lib.js" ],
dest: "build/foo.js",
options: {
directiveSyntax: "js",
globalDefines: {
major: "<%= pkg.version.split('.')[0] %>",
minor: "<%= pkg.version.split('.')[1] %>",
micro: "<%= pkg.version.split('.')[2] %>"
}
}
}
}
});
// [...]
package.json
:
{
"version": "0.9.0",
[...]
}
Then we get the following generated file as the output:
build/foo.js
:
/* Universal Module Definition (UMD) */
(function (root, factory) {
if (typeof define === "function" && define.amd)
define('foo', function () { return factory(root); });
else if (typeof module === "object" && typeof exports === "object")
module.exports = factory(root);
else
root.foo = factory(root);
}(this, function (root) {
var foo = {};
foo.version = { major: 0, minor: 9, micro: 0 };
foo.bar = function () {
/* [...bar functionality...] */
};
foo.baz = function () {
/* [...baz functionality...] */
};
return foo;
}));
Metadata
- MIT
- >=0.10.0
- Ralf S. Engelschall
- released 10/10/2013