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

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.