[AS3] Class r1.deval.D

This is the only class in the D.eval API for using the eval() functionality in Adobe^® ActionScript™ 3.

Background

The eval() function in JavaScript is used to execute textual dynamic code at runtime. ActionScript 3 chooses to break away from this backward compatibility and deprecated eval(). Yet, some programmers and designers still feel strongly about its need. Hence, this D.eval API, where basically all you need to do is invoke D.eval() in AS3 as you would with eval() in JavaScript. The interface is simple enough; what is intriguing is the language actually supported by D.eval.

The D.eval Dynamic Language in a Nutshell

The language supported by D.eval is essentially a full JavaScript with some minor differences. The following summarizes its major features:

1. Supports all the operators and flow control statements of JavaScript/AS3.
2. Supports all E4X operators and operations.
3. Supports user function declaration.
4. Supports the syntax of AS3-style type declarations for var and function return values and parameters. Type, however, is simply discarded.
5. Supports import statement to import AS3 classes; they can be used to either create a new instance via the new operator or call their static methods.
6. All Flash top-level functions are available to dynamic code.
7. A number of built-in functions, including printf(), importFunction() and importStaticMethods().
8. Provides interaction with the hosting AS3 environment, with supports from the built-in language functions and programmatic support of this D class.
9. Does not support JavaScript object-orientation afterthoughts, such as prototype and JavaScript-style object constructors. In other words, the language does not support defining classes in any ways. Object usage, i.e., the dot-notation, is supported.
10. Extended keyword support of and, or, not, xor, nand, and nor. They are useful for taking end-user input with more English-like logical expressions.

Executing Dynamic Code

The eval(program, context, thisObject) is the key method; in fact, it is part of the D.eval name itself! Its program parameter normally is a String of textual program code, but can also be an executable object returned by the parseProgram() method. The return value is either that of a return statement, or, if no return is present, that of the last expression in the code.

The context and thisObject parameters provides more sophisticated communication between the dynamic code and the hosting environment. The thisObject is referenced by the this. The context object can hold prepolulated values as named variables accessible by the dynamic code. Often times, the context is omitted and thisObject is used to pass a value object. The top-level variables in the dynamic code are stored in the context object; or you can use this to set values to thisObject, so on exit, values set in either objects can be used by the calling AS3 code.

So why we need these two parameters rather than a single one? The context is needed when a) the thisObject is not a dynamic AS3 class instance, and b) you intend to use the values set by the dynamic code. This is probably not happening very often, but it may.

The following is an example.

 import r1.deval.D;
 // example 1
 var code:String =
   '   switch(fruit) {\n' +
   '     case "apple": return "sweet";\n' +
   '     case "lemon": return "sour";\n' +
   '     default:      return "unknown";\n' +
   '   }';
 var taste:String = D.eval(code, { fruit:'apple' });
 // example 2
 var purchase:Object = { price:3.95, count:12 };
 var cost:Number = D.evalToNumber('price count', purchase);

Pre-Import AS3 Resources for Dynamic Code to Use

If you know the AS3 classes to be used by the dynamic code, you can pre-import them via the importClass() method before calling eval(). This method does exactly what the import statement does from within the dynamic code.

If you have AS3 functions to be used by the dynamic code, you can pre-import them via the importFunction() method. This method does exactly the same as the name-sake built-in function from within the dynamic code.

You can also pre-import a AS3 class's static methods as simple functions with the importStaticMethods() method. This method does exactly the same as the name-sake built-in function from within the dynamic code.

Dynamically Defined User Functions

Functions declared in the dynamic code are stored like a named variable within the context object. You can retrieve them by a) explicitly passing a context object to the eval() call, and b) on exit, call the helper method, collectUserFunctions(), to cleanse non-function data in the context object. You can pass that object as a context object to following eval() calls to reuse those user functions. This enables a library mechanism of dynamically declared functions.

You can also call the parseFunctions() to simply retrieve the function declarations, as in this example:

 import r1.deval.D;
 // Compile the user library:
 var libCode:String =
   'function sum(data:Array):Number {\n' +
   '  var ret:Number = 0;\n' +
   '  for each(var x in data) ret += x;\n' +
   '  return ret;\n' +
   '}\n\n' +
   'function avg(data:Array):Number {\n' +
   '  return (data == null) ? 0 : (sum(data) / data.length);\n' +
   '}';
 var userlib:Object = D.parseFunctions(libCode);
 // Use the library to execute dynamic code:
 var prog:String =
   'var data = [ 1, 3, 5, 7 ];\n' +
   'printf("Sum is:     {0}", sum(data));\n' +
   'printf("Average is: {0}", avg(data));\n';
 D.eval(prog, userlib);

Logging and Output

The D.eval API output, including that of the output of the built-in function, printf(), is written to a destination. The default destination is trace(). You can set a function or a "receiver", which is an array containing the host and the property name, via the setOutput() static method.

 <mx:Script><![CDATA[
   import r1.util.TextComponentLogger;
   import r1.deval.D;
   // creationComplete handler.
   private function init():void {
     // stdout is a <mx:TextArea>.
     var logger:TextComponentLogger = new TextComponentLogger(stdout);
     logger.includeCategory = logger.includeDate = logger.includeTime = false;
     D.setOutput(logger);
   }
 ]]></mx:Script>

Optimization

Parsing is fairly computationally intensive. This API optimizes by caching the dynamic code if its length does not exceed a limit. You can control this behavior via the useCache() method.

More Information

For more information, please refer to The D.eval API User's Guide, the ultimate reference for the API, the dynamic language and their usages.