XPP: General Purpose Text Preprocessor

Summary

XPP is a general purpose text preprocessor. It supports conditional output and simple text replacement. These features enable you to perform objectification and obfuscation in a much easier (and more powerful) way than XC did. And of course the conditional output feature is extremely useful. Now you can use conditional compilation in js, css, php and even in batch and make files! This conditional compilation does not occur at run-time, only at build-time.

20Dec09: There are now Ant build files that automate the use of XPP. See X Tools.

Using XPP

XPP Invocation

XPP is invoked as follows:

xpp [options] output_file input_file1 input_file2 ...

Options

Prefix an option with '+' to turn it on or '-' to turn it off.

o - Output. Generate output file. Default = true.

v - Verbose. Display info. Default = false.

d - Debug. Display more info. Default = false. +d forces +v.

XPP Directives

The '#' character of an XPP directive must be the first non-whitespace character on the line.

There is no output, and directives are not processed, inside an #ifdef block that eval'd false or an #ifndef block that eval'd true.

#define and #defword can re-define an existing symbol.

If id is found in the text it will be replaced with its value. Replacements are made in the reverse order of which the identifiers were defined.

#ifdef and #ifndef can not be nested.

In the directives, id can be enclosed with quote characters (either double or single) so id can contain whitespace. The quotes do not become part of the id. Escaped quotes are not supported.

Syntax

The currently supported directives are as follows.

#// - Comment.

#include filename - Preprocesses and outputs filename. If filename contains spaces it must be enclosed in quotes.

#define id - Defines a symbol which can be used with #ifdef and #ifndef.

#define id value - Defines a symbol and assigns it a value. The value starts at the first non-whitespace char following the id and continues to the last char on the line, including whitespace, but not including any newline characters.

#defword id value - Same as define except the search for id in the text is done by "whole-word".

#undef id - Undefines a symbol.

#ifdef id - Conditional output. Evals to true if id is defined, regardless of id's value.

#ifndef id - Conditional output. Evals to false if id is defined, regardless of id's value.

#else - Else conditional.

#endif - Closes a conditional block.

XPP Examples

Here are some interesting things you can do with XPP and the X Library.

Misc. Example

#//#define XOPTIONS-IE5-SUPPORT
#define "function X1" X.X1 = function
#defword xGetElementsByClassName X1
#undef "function X1"

#include "test_src_2.js"

function xGetElementsByClassName(c,p,t,f)
{
  var r = new Array();
  var re = new RegExp("(^|\\s)"+c+"(\\s|$)");
#ifdef XOPTIONS-IE5-SUPPORT
  var e = xGetElementsByTagName(t,p); // See xml comments.
#else
  var e = p.getElementsByTagName(t);
#endif
  for (var i = 0; i < e.length; ++i) {
    if (re.test(e[i].className)) {
      r[r.length] = e[i];
      if (f) f(e[i]);
    }
  }
#ifndef AN-ID-NOT-DEFINED
  return r;
#endif
}

Obfuscation Example

XAG can generate a project-specific obfuscation file like the following.

#defword xGetElementById         X0
#defword xGetElementsByClassName X1
#defword xGetElementsByTagName   X2
#defword xAddClass               X3
#defword xHasClass               X4
#defword xRemoveClass            X5
#defword xToggleClass            X6
#defword xEvent                  X7
#defword xAddEventListener       X8
#defword xRemoveEventListener    X9
#defword xHeight                 XA
#defword xClientHeight           XB
#defword xHttpRequest            XC
#defword xImgRollSetup           XD
#defword xGetCookie              XE
#defword xDeleteCookie           XF
#defword xSetCookie              XG
#defword xLeft                   XH
#defword xOffsetLeft             XI
#defword xPageX                  XJ
#defword xScrollLeft             XK
#defword xMoveTo                 XL
#defword xOpacity                XM
#defword xResizeTo               XN
#defword xStyle                  XO
#defword xGetComputedStyle       XP
#defword xCamelize               XQ
#defword xTop                    XR
#defword xOffsetTop              XS
#defword xPageY                  XT
#defword xScrollTop              XU
#defword xWidth                  XV
#defword xClientWidth            XW
#defword xDef                    XX
#defword xNum                    XY
#defword xStr                    XZ

Cross-Browser.com