# 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](http://gruntjs.com/) before, be sure to check out the [Getting Started](http://gruntjs.com/getting-started) guide, as it explains how to create a [Gruntfile](http://gruntjs.com/sample-gruntfile) as well as install and use Grunt plugins. Once you're familiar with that process, you may install this plugin with this command:

```shell
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:

```js
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()`.

```js
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:
```js
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`
```text
//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
```text
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
```text
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:
```text
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](http://gruntjs.com/).