dcodeIO/Preprocessor.js

Provides a JavaScript source file preprocessor, e.g. to build different versions of a library. It's for example used to build ProtoBuf.js (its build and main script are quite good examples).

Deprecation notice: Preprocessor.js has been deprecated in favor of MetaScript, a much more JavaScripty way for build time meta programming using JavaScript itself as the meta language. Check out the migration guide to get a quick impression of its merits.

Directives

Includes (always relative to the baseDirectory, defaults to "."):
```
...
// #include "path/to/file.js"
...
```

Static conditions:

// #ifdef FULL
console.log("Including extension");
// #include "path/to/extension.js"
// #else
console.log("Not including extension");
// #endif

Inverse static conditions:

// #ifndef FULL
console.log("Not including extension");
// #else
console.log("Including extension");
// #include "path/to/extension.js"
// #endif

Evaluable conditions:

// #if 1==2
console.log("1==2");
// #elif 2==2
console.log("2==2");
// #endif

Inline variables and functions:

// #define var PI=Math.PI
// #define function RADTODEG(x){return x*180/PI}
var angle = // #put RADTODEG(3)+";"

Writing the result of evaluated expressions:

var version = // #put '"'+VERSION+'";"'
var str = // #put "\"Hello world!\";"
var onePlusOne = // #put (1+1)+";"

Features

CommonJS compatible
RequireJS/AMD compatible
Shim compatible (include the script, then use var ByteBuffer = dcodeIO.ByteBuffer;)
node.js compatible, also available via npm
Closure Compiler ADVANCED_OPTIMIZATIONS compatible (fully annotated, Preprocessor.min.js has been compiled this way, Preprocessor.min.map is the source map)
Fully documented using jsdoc3
Well tested through nodeunit
Zero production dependencies
Small footprint

Command line utility

Install via npm: npm -g install preprocessor

Command line

Usage: preprocess sourceFile [baseDirectory] [-myKey[=myValue], ...] [> outFile]

preprocess Source.js . -FULL=true > Source.full.js

API

The API is quite simple:

var result = new Preprocessor(
    mainFileSource,
    baseDirectoryOrIncludes
).process(defines);

with baseDirectoryOrIncludes being either a string containing the path to the base directory or an object of included sources by filename. When running in a browser, only the later is supported.

node.js / CommonJS

var Preprocessor = require("preprocessor");
var source = "..."; // e.g. through fs.readFile
var pp = new Preprocessor(source, ".");
console.log(pp.process({
    FULL: true
}));

RequireJS / AMD

require(["/path/to/Preprocessor.js"], function(Preprocessor) {
    var source = "..."; // e.g. through fs.readFile / $.ajax
    var pp = new Preprocessor(source, ".");
    console.log(pp.process({
        FULL: true
    }));
});

Browser / shim

Note: To use the #include directive in the browser, do not specify the base directory but an object of included sources by filename:

<script src="https://github.com/dcodeIO/Preprocessor.js/raw/master//raw.github.com/dcodeIO/Preprocessor.js/master/Preprocessor.min.js"></script>

var Preprocessor = dcodeIO.Preprocessor;
var source = "..."; // e.g. through. $.ajax
var pp = new Preprocessor(source, {
    "./includes/extension.js": "var myVar = 2;" // <- #include "includes/extension.js"
});
alert(pp.process({
    FULL: true
}));

Using includes instead of a base directory like shown in the example above is supported regardless of the platform you are on.