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="//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.

Downloads

• ZIP-Archive
• Tarball

Documentation

• View documentation

Tests (& Examples)

• View source
• View report

License

Apache License, Version 2.0 - http://www.apache.org/licenses/LICENSE-2.0.html