REAPER | JSFX Programming Reference - User Functions and Namespace Pseudo-Objects

JSFX Programming Reference - User Functions and Namespace Pseudo-Objects

User defined functions and namespace pseudo-objects

top User defined functions and namespace pseudo-objects

Note: the functionality available in this section requires REAPER 4.25+

JS now supports user defined functions, as well as some basic object style data access.

Functions can be defined anywhere in top level code (i.e. not within an existing () block, but before or after existing code), and in any section, although functions defined in @init can be used from other sections (whereas functions defined in other sections are local to those sections). Functions are not able to be called recursively -- this is enforced by functions only being able to call functions that are declared before the current function, and functions not being able to call themselves. Functions may have 0 to 40 parameters. To define a function, use the following syntax:


     function getSampleRate()
     (
       srate; // return srate
     );

     function mySine(x)
     (
       // taylor approximation
       x - (x^3)/(3*2) + (x^5)/(5*4*3*2) - (x^7)/(7*6*5*4*3*2) + (x^9)/(9*8*7*6*5*4*3*2);
     );

     function calculateSomething(x y)
     (
       x += mySine(y);
       x/y;
     );

Which would then be callable from other code, such as:

     y = mySine($pi * 18000 / getSampleRate());
     z = calculateSomething(1,2);

Note that the parameters for functions are private to the function, and will not affect global variables. If you need more private variables for a function, you can declare additional variables using a local() statement between the function declaration and the body of the function. Variables declared in the local() statement will be local to that function, and persist across calls of the function (though calls to a function from two different sections (such as @init and @sample) will have two different local states. Example:

     function mySine(x) local(lastreq lastvalue)
     (
       lastreq != x ? (
         lastreq = x; // save last input
         // taylor approximation
         lastvalue = x - (x^3)/(3*2) + (x^5)/(5*4*3*2) - (x^7)/(7*6*5*4*3*2) + (x^9)/(9*8*7*6*5*4*3*2);
       );
       lastvalue; // result of function is cached value
     );

In the above example, mySine() will cache the last value used and not perform the calculation if the cached value is available. Note that the local variables are initialized to 0, which happens to work for this demonstration but if it was myCosine(), additional logic would be needed.

JS also supports relative namespaces on global variables, allowing for pseudo object style programming. Accessing the relative namespace is accomplished either by using a "this." prefix for variable/function names, or by using the instance() declaration in the function definition for variable names:

  function set_foo(x) instance(foo)
  (
    foo = x;
  );
  // or
  function set_foo(x)
  (
    this.foo = x;
  );

  whatever.set_foo(32); // whatever.foo = 32;
  set_foo(32); // set_foo.foo = 32;

  function test2()
  (
    this.set_foo(32);
  );
  whatever.test2(); // whatever.foo = 32

Additionally functions can use the "this.." prefix for navigating up the namespace hierarchy, such as:

  function set_par_foo(x) 
  (
    this..foo = x;
  );
  a.set_par_foo(1); // sets foo (global) to 1
  a.b.set_par_foo(1); // sets  a.foo to 1