Mark Gillard
Programmer.Gamer.

JSPP

JSPP logo

A command-line utility for conditionally compiling a Javascript "project" from many separate javascript files using a C-like preprocessor syntax.

JSPP is also capable of generating Javadoc-like HTML documentation from special documentation directives. See here for an example of the output.

Download

Installation and Basic Usage

  1. Place jspp.exe in your Windows directory (or anywhere on the system PATH).
  2. Invoke it on the command line using the parameters detailed below to produce a preprocessed javascript file.

Command Line Parameters

jspp [/?] [/in inpath] [/out outpath] [/doc docpath] [/define key [value]] [/min [0-3]]

inpath Path to the .JS or .JSPP file to use as the "entry point". If /in is omitted .\build.jspp is assumed.
outpath Path to which the final .JS file will be written. If /out is omitted .\dist\build.js is assumed.
docpath Path to a folder to which JSPP will output HTML documentation, parsed from documentation directives in your code. If /doc is omitted documentation will not be generated.
key [value] Defines a preprocessor macro in the same way the #DEFINE directive does. The value parameter is optional. /define may be used multiple times.
min [0-3] Initial level of Javascript minimization, from 0 (none) to 3 (high). This can be altered during preprocessing using the #MINIMIZATION directive. If the level argument is omitted, 2 (medium) is used.
/? Prints help text to the console and exits.

Preprocessor Syntax

Because of how well-known the C preprocessor syntax is I've tried to keep mine as close to it as possible, reusing keyword names where possible, and adding a few short-cuts and improvements.

An example .JSPP file:

/* Guarding against multiple inclusions */
#GUARD BUILD_JS
//The 'GUARD' directive is shorthand for this:
#IF !DEFINED BUILD_JS
#DEFINE BUILD_JS


/* Including other files in your project */
#INCLUDE "somefile.jspp"
#INCLUDE "plain_javascript.js"
#INCLUDE ONCE "anotherfile.jspp"
//Files with the .jspp extension will be preprocessed, others will just be echoed directly.
//The "ONCE" flag tells JSPP not to include it if it has been included somewhere else already,
similar to PHP's include_once().


/* Defining preprocessor macro variables
  Unlike the C preprocessor, which records defines as plaintext,
  JSPP parses them as typed variables;
  they can be strings, floats (doubles), integers (longs),
  or names of other defined variables (must match the regular expression [A-Z][A-Z0-9_]*).
  They may also have no content at all, and be defined only with the intention of
  checking them in an IF DEFINED directive. */
#DEFINE BLANK_VAR
#DEFINE FLOAT_VAR 0.55
#DEFINE INT_VAR 100
#DEFINE STRING_VAR "this is a string variable"
#DEFINE NAME_VAR INT_VAR


/* Javascript and generating HTML documentation */
#DOC [NAMESPACE someNamespace]
    A namespace containing my project's functions, objects and classes, because polluting
    the global 'window' namespace is for plebs.
#END
someNamespace = {};

#DOC [FUNCTION someNamespace.exampleFunction]
    Displays a message box containing STRING_VAR.
    [parameter log] Something to log to the Javascript console.
    [returns] The meaning of life.
    [remarks] Don't call this if necessary, Alert() is bloody annoying to users!
#END
someNamespace.exampleFunction = function(log)
{
    Console.log(log);
    Alert(STRING_VAR); //becomes Alert("this is a string variable");
    return 42;
}


/* Inline javascript minimization control
  The minimization directive accepts 4 different levels as a parameter:
  none - Pass one of: 0, NONE, OFF
  low - Pass one of: 1, LOW, LOWEST, MIN, MINIMUM
  medium - Pass one of: 2, MED, MEDIUM, MID, MIDDLE
  high - Pass one of: 3, MAX, MAXIMUM, HIGH, HIGHEST */
#MINIMIZATION OFF


/* Undefining variables */
#UNDEFINE INT_VAR


/* Conditional compilation */
#IF DEFINED INT_VAR
    ...
#ELIF FLOAT_VAR < 0.4 || !INCLUDED "plain_javascript.js"
    #IF DEFINED SOMETHING
        //block-type directives may be nested
    #ELSE
        //but don't forget the inner #END!
    #END
#ELSE IF !DEFINED STRING_VAR
    ...
#END


#END //GUARD BUILD_JS
		

Exit Error Codes

1: You ran the executable with the /? switch, triggering usage-output-only mode.

2: The path provided for the initial input file was invalid or the file didn't exist.

3: The path provided for the output file was invalid or the folder hierarchy could not be created (do you need admin permissions?).

4: The path provided for the documentation folder was invalid or the folder hierarchy could not be created (do you need admin permissions?).

5: The parser aborted due to a syntax error.

6: There was an I/O issue reading or writing a file.