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.
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.
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.