README

Purpose:

This preprocessor is used to build JavaScript files together into a single file
while enabling various features.

I have elected to provide a suset of what the original C preprocessor does. I choose
to implement in nodejs because I am trying to learn node. I am in the middle of
building a couple of projects and found I have a need to frequently do this kind
of manipulation and my tools were limited.

Guiding principles:
1)  Unobtusive, I did not want any positional sensitivity so my code was still easy
    to read.
2)  I wanted to use a marker that would not interfere with javascript in any way
3)  I wanted to easily see what file and what code was in effect and what was left
    out
4)  I wanted to prevent infinite loops through inclusion
5)  A single source file could produce output suitable for testing, production,
    and other environments

Commands:
Commands are not case sensitive, files names may be. Defined variable are case sensitive.
Commands are placed anywhere on a line they do no have to appear in the first column
Commands cannot follow code on the same line.
A processed file comments out the commands so they will not work. So the following
becomes:

//@include somefile.js -> // //@include somefile.js

e.g. Valid
//@include sample.js
                    //@include sample.js

The commands for the preprocessor are:
//@include filename.js

    The include command will only a file to be included one. Please note that a comment
    line will be inserted into the output file to indicate the source file. A check
    is done to ensure that the same include file is not used more than once. pp.js will
    throw an error if the same include sime is attempted in a single job.

//@define var,var,var

    The define command creates a variable. Unlike the C preprocessor you cannot assign
    a value. All test are simply for existance. More than one define can be done
    at a time.

//@if var,var,var

    The if command checks for the existance of a given variable. If more than one is
    specified then the result is OR'd together. Which just means if one is define its
    true.

//@else

    Hopefully self explainitory.

//@endif

    Hopefully self explainitory.

How to use:

usage: npm start Node-JavaScript-Preprocessor with the following options

Source file(s) e.g. --src=file1.js,file2.js
    --src *required
Destination to write the file e.g. --dst=output.js
    --dst *required
Definition(s) to create e.g. --def=DEBUG,NODE,BROWSER
    --def
Enable Debugging
    --debug
Help. This Message.
    --help

Tests:

Sample test file in:
FILE: test.js
/* 
*   a simple test of the if endif logic
*
*/
//@define Hello

//@if Hello
    This should show
//@else
    This should be commented
//@endif

//@include nestedfile3.js

//@if DEBUG
    This should be commented
//@else
    This should show
//@endif

//@if DEBUG
    //@if WIRE
        This should be commented
    //@else
        This should be commented (because its nested out)
    //@endif
//@else
    This should show
//@endif

//@if DEBUG
    This should be commented
//@endif
//@if DEBUG
    //@include nofile.js
//@endif

FILE: nestedfile3.js
This is the nested file 3

//@if Hello
    This should show
//@endif    

Command

Result
/* 
*   a simple test of the if endif logic
*
*/
// //@define Hello

// //@if Hello
    This should show
// //@else
//     This should be commented
// //@endif

// //@include nestedfile3.js

// //@if DEBUG
//     This should be commented
// //@else
//     This should show
// //@endif

// //@if DEBUG
//     //@if WIRE
//         This should be commented
//     //@else
//         This should be commented (because its nested out)
//     //@endif
// //@else
    This should show
// //@endif

// //@if DEBUG
//     This should be commented
// //@endif
// //@if DEBUG
//     //@include nofile.js
// //@endif

How to install:

    npm install Node-JavaScript-Preprocessor
    
To run:
    npm start Node-JavaScript-Preprocessor