rigger

Rigger

Rigger is a build time include engine for Javascript, CSS, CoffeeScript and in general any type of text file that you wish to might want to "include" other files into.

It was created to make the process of creating Javascript libraries a more structured process, but can be used for other tasks also.

As a developer you are encouraged to write modular, reusable code but when it comes to writing client-side applications your ability to do this effectively is generally hampered by what I call the single-file principle. In most cases a good programmer rages against this and implements some kind of custom Makefile, ant build or Rakefile to help with their build.

The "build" process, however, generally involves taking a number of files and concatenating them together in a sensible order. I, however, wanted something more flexible. To be precise, I wanted the following:

• The ability to inject a file into specific line in another file.
• The ability to reuse code from other libraries.
• The ability to do includes from the web (namely github repos)

This is the functionality that Rigger provides. It was originally built 6 months ago as part of Interleave but has it's own identity, tests and is generally better.

PSA: Use Browserify

As a quick note, I think it's important to mention that for just about every project that I'm writing these days I'm using browserify. While early versions of browserify didn't do what I wanted, since version 2 onwards it's been fantastic. So I'd encourage you to take a look at whether browserif solves your needs like it does mine.

If not, then the following tools implement similar functionality to rigger and are more actively maintained:

• https://github.com/timrwood/includer

Using Rigger

First you will want to install it. You'll need npm to do this, once you do you can simply run npm install -g rigger. To get starting using rigger, you simply start placing special include comments in a file that you want rigger to process.

Javascript:

//= includes/test

CoffeeScript:

#= includes/test

CSS:

/*= includes/test */

Notice that each of the examples is using single-line comments (even if they are a block comment in the case of the CSS example). This is important to note as Rigger parses files on a line by line basis rather than through tokenizing. If you use block comments like the following CSS example, it won't work:

/*=
includes/test1
includes/test2
*/

Once you have a file that is has been properly rigged, you can use the rig command line tool to turn a rigged file into it's big brother:

rig input.js > output.js

Include All the Things

Rigger supports a number of special include formats, and these are demonstrated in examples below. While JS examples are provided, the formats will work in any of the known file formats. In addition, rigger supports recursive (nested) imports, so an imported file can have imports itself, and those imports can have imports, etc.

Remote Resources

Remote resources are those stored accessible via HTTP (or HTTPS).

HTTP(S) Include:

// include jquery from the CDN so you can run offline perhaps...
//= http://ajax.googleapis.com/ajax/libs/jquery/1.7.1/jquery.min.js

Github Include:

//= github://DamonOehlman/alignit/alignit.js

Multiple File Include

Being lazy is ok. Rigger provides some nice shortcuts to help you in your quest:

Directory Includes:

Simply specify a directory in the include string and all files of the same type as the currently parsed file will be included. In the tests/input directory have a look for the local-includedir.js and local-includedir.css files.

//= ../includes/testdir

Cherrypick Include:

In some instances you may want to cherrypick particular files from a directory / remote repository. Rather than typing multiple include lines, you can simply type one statement and use square brackets to signal to Rigger that you want to include multiple files:

//= ../includes/testdir[a, b]

Plugin Support

In addition to including files you can also use some plugins to extend the core functionality. To flag that you want to use a plugin in your core files, use add the word plugin directly after the = in the comment (e.g. //=plugin name params, /*=plugin name params */, #=plugin name params, etc).

shim plugin

The shim plugin allows to you require specific ES5 shims that you wish to include into your code so IE doesn't go and break on you:

//=shim String.trim Array.indexOf

The shim contents are sourced from the buildjs/shims repository, which is currently incomplete so feel free to help out by adding appropriate shims.

Programmatic Use

To be completed.

Streams FTW!

One of the simplest ways of composing process flows in node is to use streams, and while Interleave does not support a streaming interface, Rigger inherits from the node Stream.

This means that you can do all kinds of things prior to rigging in your inline dependencies and all kinds of things afterwards too.

License(s)

MIT

Copyright (c) 2013 Damon Oehlman [e-mail]

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the 'Software'), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.