REAPER | JSFX Programming Reference

JSFX Programming Reference - EEL2 Preprocessor

Compile-time user-configurable JSFX settings

top EEL2 Preprocessor

JSFX (and ReaScript/EEL) in REAPER v6.74+ support the EEL2 preprocessor, which allows generating EEL2 code at compile-time. To make effecient JSFX/EEL2 code, it is often helpful to use named variables rather than memory, and when using a lot of variables it is often harder to write and maintain. The EEL2 preprocessor allows you to generate repetitive code dynamically.

To use the EEL2 preprocessor, one uses the tags <? and ?> in EEL2 code. Between these tags, a separate EEL2 compiler runs, using a minimal, separate, and non-persistent state, and can generate EEL2 code output using the printf() function.

Additionally, preprocessor code can suppress passthrough of existing text between its blocks by setting the _suppress variable (allowing for conditional compilation).

Examples

Suppose you have state consisting of 16 values and you wish to clear that state:

  x00=0; x01=0; x02=0; x03=0; x04=0; x05=0; x06=0; x07=0;
  x08=0; x09=0; x10=0; x11=0; x12=0; x13=0; x14=0; x15=0;

Using the EEL2 preprocessor, you could write this as:

  <? x_size = 16; /* near the start of file, perhaps */ ?>

  ...

  <?
     // x_size will still be set
     loop(i=0;x_size, printf("x%02d=0;\n", i); i += 1);
  ?>

To use _suppress for conditional compilation, one does something along the lines of:

  <? some_config = 1; ?>

  ...

  <? some_config < 5 ? _suppress = 1; ?>

  do_some_extra_code() // only compiled if some_config is >= 5
  ...

  <? _suppress = 0; ?>

Note that in the preprocessor the only functions available are built-in EEL2 math/logic functions, and printf(). REAPER 6.82+ also supports include(), which allows JSFX to include additional EEL2 files inline (rather than @import which imports the file and its JSFX sections).

top Compile-time user-configurable JSFX settings

Starting with REAPER 7.0+, individual JSFX can define compile-time preprocessor configurations which can be used for extensive reconfiguration of the underlying JSFX. If the plug-in defines one or more "config:" lines near the top of its file, these configuration items will appear in the plug-in's "+" menu for the user to configure. Note that reconfiguring these parameters only affect the existing instance of the plug-in, and it causes the plug-in to lose all state. The benefit of this is that the plug-in can redefine its I/O, parameters, etc, according to these configuration items.

For example, super8 defines the following config: line:

config: nch "Channels" 8 1 2 4 8="8 (namesake)" 12 16 24 32 48

In the above example:

"nch" is the variable name which will be set for the preprocessor's context. Additionaly, it is the key name for the configuration item as it will be saved in presets/project files/etc.
Channels is the user-visible description of the configuration item. This string can be changed and it will not affect presets/projects/etc.
The first number, 8, is the default value for "nch."
The remaining values are allowable options. Note that these all must be numeric values.
Numeric values can have =string appended to them, in which case the item will be displayed as that string