README.tmpl

<%=scriptName = pkg.name[0].toUpperCase() + pkg.name.slice(1)%>
<%=Array(scriptName.length+1).join("=")%>

> <%=pkg.description%>


Summary
-------

**<%=scriptName%>** bundles up your _node_ JavaScript files by following the `require("moduleName")` statements in your source file(s), and then bundles it all up, and _uglifies_ (minimizes) it into one JavaScript file.

In addition, **<%=pkg.name%>** can replace symbols found in the source file with JavaScript values _defined_ either with command line arguments, or through the use of another _node_ module.

Coupled with [`uglify-js`'](https://github.com/mishoo/UglifyJS) ability to remove dead code, **<%=pkg.name%>** acts as a pre-processor of sorts on your _uglified_ file when using the `--define` and `--define-module` options.


Installation
------------

~~~
% npm install -g <%=pkg.name%>
~~~


Command Line Usage
------------------

~~~
% <%=pkg.name%> -h

<%=usage%>
~~~


### Dependencies ###

These are installed when **<%=pkg.name%>** is installed.
<% var  fw = Object.keys(pkg.dependencies).reduce(function (t, c) {
            var len = c.length;
            return len > t ? len : t;
        }, 0),
        deps = Object.keys(pkg.dependencies).map(function (key) {
            var pad = Array(fw - key.length + 1).join(" ");
            return key + ": " + pad + pkg.dependencies[key];
        }).join("\n");%>
~~~
<%=deps%>
~~~


### Development Dependencies ###

Installed when you run `npm link` in the package directory.
<% var  fw = Object.keys(pkg.devDependencies).reduce(function (t, c) {
            var len = c.length;
            return len > t ? len : t;
        }, 0),
        devDeps = Object.keys(pkg.devDependencies).map(function (key) {
            var pad = Array(fw - key.length + 1).join(" ");
            return key + ": " + pad + pkg.devDependencies[key];
        }).join("\n");%>
~~~
<%=devDeps%>
~~~


Defines
-------

**<%=scriptName%>** now processes all `defines` itself, and the values returned from `defines` are translated into the appropriate AST structure. No need for your `define/define-module` to return an AST formatted array.

By having **<%=pkg.name%>** handle the `defines` in the pre-mangled/squeezed AST, if you supply the `--no-minify` flag to **<%=pkg.name%>** you can see the _beautified_ `uglify-js` generated output without any dead-code being removed (this is helpful when reviewing what your defines are returning/generating).


### Example ###

~~~js
// contents my-defines.js

var env = process.env.ENVIRONMENT || "dev",
    tokens = {
        appName: "My Great WebApp",
        authorName: "Me"
    },
    isDebug = env === "dev"
;

module.exports = {
    ENVIRONMENT: env,
    DEBUG: isDebug,
    TOKEN: function (key) {
        return tokens[key];
    },
    MY_METHOD: function () {
        return isDebug ?
            function () {
                return "is debug";
            } :
            function () {
                return "is not debug";
            }
    },
    CONFIG: {
        foo: "foo",
        baz: [1, 2, 3],
        doSomething: function () {
            return "something";
        },
        isDebug: isDebug
    }
};

// contents of my-script.js

var appConfig   = CONFIG;

if (ENVIRONMENT === "dev") {
    console.log("A note to the developer...");
}

function MyClass () {}

MyClass.prototype = {
    appName: TOKEN("appName"),
    authorName: TOKEN("authorName"),
    
    specialMethod: MY_METHOD(),
};
~~~

Running `<%=pkg.name%> my-script.js script.js -d ./my-defines.js -N` (assuming `ENVIRONMENT` is set to "dev") the following would be produced:

~~~js
// contents of script.js

var appConfig = {
    foo: "foo",
    baz: [ 1, 2, 3 ],
    doSomething: function() {
        return "something";
    },
    isDebug: true
};

if ("dev" === "dev") {
    console.log("A note to the developer...");
}

function MyClass() {}

MyClass.prototype = {
    appName: "My Great WebApp",
    authorName: "Me",
    specialMethod: function() {
        return "is debug";
    }
};
~~~

And the minified result (`<%=pkg.name%> my-script.js script.js -d ./my-defines.js`) would be:

~~~js
// contents of script.js
function b(){}var a={foo:"foo",baz:[1,2,3],doSomething:function(){return"something"},isDebug:true};console.log("A note to the developer..."),b.prototype={appName:"My Great WebApp",authorName:"Me",specialMethod:function(){return"is debug"}}
~~~

Note how the `if` block was removed around the `console.log` statement, since this is "dev" mode. If `ENVIRONMENT` was set to some other value, `console.log` would be removed too.

There are more examples in the "examples" directory. Install the development dependencies, and then run:

~~~
sake examples ENVIRONMENT=[dev|prod] BUILD_TYPE=[debug|release]
~~~


Embedding
---------

The **<%=pkg.name%>** `-E, --embed` option will _infuse_ required modules as `strings` and lazy-evaluate them when used in the final script. In the case of a browser, this means appending a script element to the `head` of the document temporarily. In other cases, **<%=pkg.name%>** goes to the _dark side_ and uses `eval`.

The **advantage** of embedding is that the required JavaScript modules are not evaluated until the strings are put into a script node, or `eval`'d, when needed. This facilitates faster loading of the _infused_ JavaScript file, since it is, mostly, one large string.


A Poor Man's Minifier
---------------------

You can get started quickly with **<%=pkg.name%>** by using the `-i, --infuse PATH` option:

~~~
infuse -i path/one.js -i path/two.js -i path/three.js > compiled.js
~~~

This basically **<%=pkg.name%>s** up the individual files and automatically _de-fuses_ them when the compiled script runs.


Caveats
-------

### Run-time variables ###

Currently, **<%=pkg.name%>** does not compute local variables, and can not determine require statements with variables defined at run-time.

For example, this **will not** work, and **<%=pkg.name%>** will throw an error:

~~~
// script.js

var pkgModule = require("./" + process.env.ENVIRONMENT + "-pkg.js");
~~~

This will however:

~~~
// script.js <%=pkg.name%>d with `--define PKG=prod-pkg.js`

var pkgModule = require(PKG);
~~~


### Global scope leakage ###

Since **<%=pkg.name%>** does not do any computing of local variables, it can not determine if variables leak outside of a required module's scope. In _node_ this is not so much a problem, since each module is run in it's own context and only the items explicitly exported through `module.exports` are exposed. **<%=scriptName%>** uses an anonymous function to simulate what _node_ does, however if the **<%=pkg.name%>d** module doesn't locally scope a variable with the `var` keyword, that variable will be set on the _global object_ (usually the window).


In the future, plans are to resolve the _caveats_ with more introspection of the AST parsed by _UglifyJS_. Stay tuned.


Report an Issue
---------------

* [Bugs](<%=pkg.bugs.url%>)
* Contact the author: <jhamlet@hamletink.com>


License
-------

<%=license.split("\n").map(function (line) { return "> " + line; }).join("\n")%>