grunt-dead-simple-include v0.1.1
grunt-dead-simple-include
An awesome little utility for no fuss source file includes through grunt, compatible with all file types in your arsenal.
Getting Started
This plugin requires Grunt ~0.4.1
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-dead-simple-include --save-dev
Once the plugin has been installed, it may be enabled inside your Gruntfile with this line of JavaScript:
grunt.loadNpmTasks('grunt-dead-simple-include');
The "dead_simple_include" task
Overview
In your project's Gruntfile, add a section named dead_simple_include
to the data object passed into grunt.initConfig()
.
grunt.initConfig({
dead_simple_include: {
options: {
// Task-specific options go here.
},
your_target: {
// Target-specific file lists and/or options go here.
},
},
})
Options
options.extensions
Type: Array
Default value: ['js', 'coffee']
An array of file extensions that should be included in the result set.
options.autoInclude
Type: Boolean
Default value: true
A flag to signal whether nor the task should include files that are not explicitly included through _include.inc files.
With this flag set to false, only files referenced in an _include.inc
file will be part of the output.
options.commentString
Type: String
Default value: //
You can include comments in _include.inc files, comments are denoted by the given commentString which can be any string value except for the directives 'include' and 'skip'
####options.pathPrefix
Type: String
Default value: ''
When the task finishes you may optionally add a string that will prefix the resulting paths. An example use
might be ../
or src/
####options.wrapper
Type Object
Default value: {}
When the task finishes running you may optionally define a wrapping string for each file extension type given. Example:
options: {
wrapper: {
js: ['<script type="text/javascript" src="', '"></script>'],
css: ['<link rel=stylesheet href="', '">']
}
}
The output result would then be: <script type="text/javascript" src="path/to/your/file.js"></script>
instead of
path/to/your/file.js
If no wrapper is defined for an extension, it will not be wrapped. Wrapping is defined by a two element array where
wrapper[extension][0]
is the start of the wrap and wrapper[extension][1]
is the end.
####options.src
Type String
Default value: null
This is the file path to the location of your source tree. If a value is not supplied the task will not run.
####options.dest
Type String
Default value: `tmp/includes.txt'
This is the output destination of the task.
Usage Examples
This task will traverse your source tree in directory-then-file-alphabetical order and write the encountered
file paths to an output file that you can then feed other grunt tasks to process further. You can alter the order of
inclusion or explicitly skip a file or directory by adding _include.inc
files to your source tree.
The format of these files is simple, on each line you can add one of two directives: include
or skip
along with
a relative file path. Here is an example _include.inc
//this is a comment!
include utils
include app.js
include models/user.js
skip style.css
Given this file structure
- src
- models
- user.js
- utils
- math.js
- random.js
- app.js
- style.css
- models
The output of this task would be
src/models/user.js
src/utils/math.js
src/utils/random.js
src/app.js
src/style.css
If we were to add the above _include.inc
to the src
directory, the output would be
src/utils/math.js
src/utils/random.js
src/app.js
src/models/user.js
Note that _include.inc
files are not included in the output.
Paths within an _include.inc
file are relative, but you are allowed to backtrack via ../
. Assuming these files
exist in some structure, these are both valid paths in an include file:
include ../user/phone_number.js
include my_file.js
You may not explicitly include an include file, the targets of an include may be a directory, in which case the
directory is checked for an _include.inc
file. If one exists, includes proceed as defined in that file. Otherwise
the directory is traversed normally, in directory-then-file-alphabetical order.
Contributing
In lieu of a formal styleguide, take care to maintain the existing coding style. Add unit tests for any new or changed functionality. Lint and test your code using Grunt.