Alexis' ActionScript Compiler Reference

Back to the SSWF project home page

Summary

This document license

Language References

The SSWF Setup File

How do I use the Javascript compiler with SSWF?

Comments

Literals (numbers, strings, etc.) and Special Keywords

Reserved Keywords

Attributes

Expressions and Operators

expr-- expr++ expr(...) exprtype(...) expr[...] expr.expr expr::expr (expr) +expr -expr ~expr !expr

--expr ++expr new expr delete expr typeof expr void expr { name: expr, ... } [ expr, ... ] function ... expr ** expr expr * expr expr / expr

expr % expr expr + expr expr - expr expr << expr expr >> expr expr >>> expr expr !< expr expr !> expr expr < expr expr > expr expr <= expr expr >= expr

expr is expr expr as expr expr ~= expr expr in expr expr in expr ... expr expr instanceof expr expr == expr expr === expr expr != expr expr !== expr expr & expr expr ^ expr

expr | expr expr && expr expr ^^ expr expr || expr expr ?< expr expr ?> expr expr ? expr : expr expr = expr expr , expr

Functions

Control Flow Statements

break continue do for (loop) for ... in (enumeration) for each ... in (value enumeration) goto if/else

label return switch throw try/catch/finally while with

Classes, Interfaces and Enums

Packages

Pragmas

Namespaces

Compiler Internals, Known Bugs and Frequently Asked Questions

History of this reference

This document license

Thought the language for Flash is mainly devised by Macromedia, the actual reference is from Netscape. In version 7.x, the ActionScript compiler in Flash is actually a free version of the compiler from Netscape most certainly based on ECMAScript version 3 and tweaked by Macromedia to support some of the features of the following version. The current version (at time of writing) is based on a proposal by Netscape to the ECMAScript people. This is version 4 which isn't official yet (we're in 2005 and the proposal was written in 1999.)

You can find the ECMAScript 4 Netscape Proposal on the Mozilla website at this time. (Search for "ECMAScript 4 Netscape Proposal" in some search engine if the link below does not work anymore at the time you click on it...)

On that page, you have a access to a PDF which describes ECMAScript 4 as (supposedly) currently in the work by the ECMA people.

Another reference is of course the complete reference from Macromedia. You can find ActionScript v8.0 fully described. Note that includes many objects implemented by Flash developers and not actually implemented in the Flash Player. These objects are part of the mx package. Everything else should be available in the player (Sorry! I won't take the time to test that for you to make sure... we'll have to go and find problems as they arise.)

There are other sources for JavaScript, but only the Netscape Proposal is sensical in being used to write a compiler which is what I've done.

In order to accomodate the ActionScript support, SSWF now reads a setup file which includes some information about where to find the default packages and where to save the package database. It also includes a version, so we can make sure that we are reading the proper information.

The setup file is named sswf.rc and it is searched in order in this list of directories:

• Current directory ("."),
• Include directory under the current directory ("include/sswf/scripts"),
• The hidden SSWF directory in your current directory (".sswf"),
• The hidden SSWF directory in your home directory ("~/.sswf"),
• The visible SSWF directory in your home directory ("~/sswf"),
• The normal Unix setup directory ("/etc"),
• The SSWF directory within the Unix setup directory ("/etc/sswf") — note that this is the default installation directory for the SSWF setup file,
• The SSWF scripts include directory ("/usr/include/sswf/scripts"),
• The SSWF scripts directory ("/usr/share/sswf/scripts"),

The file is composed of shell like variables (<name>=<value>). The table below lists the values currently understood by SSWF. The file can also include empty lines and lines commented out. Comments are like in a shell script, they start with a hash (#) and end with the end of the line.

	version=1.7.3

	asc_path=/usr/share/sswf/scripts

	asc_db=tmp/sswf-db.txt

The actionscript compiler is actually in a library. The SSWF compiler links against that library and thus includes the functionality directly inside its language. Whenever you need to write an actionscript in an SSWF file, you now can use the actionscript object.

	do action {
		actionscript test {
			// do something useless
			var b: Integer, c: Integer, d: Integer, e: Integer;
			var a: Integer = (b + c * d) ** e;
		};
	};

The scripts themselves are mostly Javascript compliant. Some features are either not yet implemented or may work in a slightly different way than expected, but in general, it will work the same. (Most of you will be just fine. As long as you do not try all the most advance features of the language... you know!)

So, in order to learn the basics, I suggest that you read Javascript manuals. That will give you most of what you need to understand the basic flow control statements, expressions, the exception hanlding and the global classes: arrays, strings, numbers, dates, functions, math, boolean and errors. All of this is described in this documentation but only briefly. This documentation isn't a tutorial.

On the other hand, in this documentation you will find what is and what is not working in this implementation. Also, there are extensions available in the SSWF version which you may want to use in your scripts. For instance, you can use the ?< and ?> operators to retrieve the maximum or minimum of two or more expressions. Similarly, the SSWF version supports overloading of operators. Here too, we went beyond the specification and we authorize nearly all the operators to be overloaded.

Finally, this documentation describes all the objects available in the SSWF implementation: the Global objects (such as Integer and String), the System object specific to Flash and the Native objects which are used to manipulate all the objects available in Flash such as sprites (called movie clip?!), buttons, cameras, colors, etc. That you can also find on the Macromedia website.

Please, refer to the actionscript object in the Reference to the Scripting language for SWF for more information on how to include an actionscript in your SSWF scripts.

ActionScripts which include class or interface definitions can't be defined within a sprite. This is because a sprite can't be defined as a child of another sprite (it can only be referenced and viewed as a child, not defined). And internally, classes and interfaces are sprites. However, SSWF takes care of extracting these classes accordingly and thus as an end user you can declare anything anywhere it is legal in Javascript.

This implementation of ActionScript supports two types of comments.

The regular multiline C comment introduced by /* and ending with */. Note that you cannot include a comment in another comment (as per the ECMAScript documentation.) Thus, the first */ found closes a comment.

	/* my comment
	   can span
		 on multiple
		 lines */

The regular one line C++ comment introduced by // and ending with the end of the current line. Note that all the characters are ignored in that comment and thus another comment introducer (// or /*) will be ignored.

	// a one line comment

If you need to comment out a block of instructions between { and } then you can simply mark them false. This is the best way to comment out a whole block whether it includes C comments or not.

	false {
		if(quit) {
			exit();
		}
	}

This implementation of ActionScript supports the literals as described in the table below.

	class A { function test() {} }
	class B extends A { function test() { super.test(); } }

The language has a set of reserved and special meaning keywords. Reserved keywords are recognized by the low level lexer and they cannot be used as identifiers anywhere. The special meaning keywords can however be used as regular identifiers in places other than where they have that special meaning.

The ECMAScript language reference says that an identifier with an escape sequence cannot be a keyword. I do not see the point. Escape sequences are being parsed at the time the text is read and if the resulting identifier is a reserved keyword, it is reserved in SSWF. (Also, what is the point of having escape sequences in identifiers? I would think that you can use UTF-8 or Unicode if you want to write identifiers in your own language and not have to use escape sequences anywhere. A variable name such as: être will never be a keyword.)

Definitions in your code can receive a list of attributes. Definitions are functions, blocks of declarations¹, packages, classes, variables, etc.

¹a declaration is a definition or a statement.

All the definitions will always accept true and false. A definition marked true (the default when not marked either true or false,) means that the definition is to be used. A definition marked false, is a definition which needs to be ignored. This allows for dynamic compiling similar to a pre-processor. Whenever you include a package, using the true and false attributes, you can turn on and off different features. For instance, you can have a debug and a release version of some code. In the example below, the do_something() function writes some extraneous messages in a console when attr_debug is set to true.

	// NOTE: this example is not yet functional (as of v1.7.3)
	// in some package
	package that_package {
		function do_something(a, b, c)
		{
			...
			attr_debug {
				echo("We came through here");
			}
			...
		}
	}
	
	// in some program file
	const var attr_debug := true;
	const var attr_release := !attr_debug;
	...
	import that_package;
	...

In this example, we define the value for attr_debug to true. Then the echo() function is compiled. [Note: an external package will not look outside itself for variables; that's a problem for this pre-processor! I will look into a fix in a later version of SSWF to support this mechanism.]

The attributes, by definition, are a list of names put in front of a definition and understood by the system. They can be used directly or put in a constant variable. When defined in a variable name, that name can be used instead of the attribute. In effect, it makes it a dynamic attribute. Note that a variable can reference another variable. All the variables need to be constants. The name of the variables cannot be the name of any of the currently supported attributes. The special true and false attributes can be negated with the logical not operator.

The attributes understood by such and such definition are listed along that definition documentation. The following is just a list of all the attributes currently understood and which definitions understand it. The ones underlined are also reserved keywords.

¹ switch statements get their attributes defined right before their block of statements; for instance one can write the following:

	switch(expr) with(<) foreach {
	case 0:
		// executed when 'expr < 0' is true
		...
	case 1:
		// executed when 'expr < 1' is true
		...
	case 2:
		// executed when 'expr < 2' is true
		...
	default:
		// always executed
		...
	}

In this example, if expr is 1, then the statements of case 1, case 2 and default are all executed. To avoid executing default after case 2, use a break statement. (similarly, you can break any one case to avoid the foreach effect.)

This implementation of ActionScript supports the operators as descibed in the table below. Note that some of these operators are extensions to the standard. You can make sure not to use them using a pragma to turn them off. You will recognize these extensions by the asterisk following the SSWF version availability such as in: 1.7.3 (*).

The following table gives the operators in priority order. Operators with a higher priority appears first in the table. A higher priority is used first in an expression without the need to use parenthesis for proper grouping.

For instance, in a + b * c, the compiler generates b * c and then adds a to the result.

When you use one or more operators with the same priority, it usually will apply the first operation first (the one most on the left). A few operators have a right priority such as the power operator. This means the last operation is executed first.

For instance, the expression a ** b ** c is equivalent to a ** (b ** c).

The SSWF Availability column also include a flag to mark operators which can be overloaded. To overload an operator, create a function with a name written in a string that is the operator that you want to overload. For instance, the additive operator for the integers is defined like this:

	intrinsic function "+" (l: Integer, r: Integer): Integer;

Note that if you define your own class and want to override an operator you cannot specify intrinsic. It will usually reference objects of the same class, though this is not a requirement since operator functions are automatically considered static.

	class Foo {
		...
		function "()" (q: Number)
		{
			...
		}
		...
	};
	...
	var t: Foo = new Foo;
	...
	t(53.2);	// calls the "()" function
			// this = t and q = 53.2
	...

	function func(a, b, ...)
	{
		sub_func(a + 3, ...);
	}

	var a:Integer := Integer(x);

	var a:Integer := x as Integer;

	o:Object;
	o := new Object;
	...
	copy:Object;
	copy := new Object(o);

	var array = { a: 1, b: 2 };

	var array = { (a): 1, (b): 2 };

	array.first = 1;
	array.second = 2;

	class A { ... }
	class B extends A { ... };
	var b:B;
	b instanceof A === true

SSWF supports an advanced function declaration and for evaluation it will always follow the ECMAScript specification in that it will evaluate the parameters from left to right. (Flash uses a stack and if you want to just follow the stack order, the parameters would be declared from right to left!)

A function is defined with a name, a list of parameters, a type and a body. The list of parameters is mandatory, though it can be empty or marked as unprototyped. However, you only need either a name or a body. Of course, you can also have everything defined. A function defined in an expression is expected to not have a name. A function defined anywhere else is required to have a name. The function type is optional and defaults to Object when not defined.

A function defined without a name is usually right away put in an object as a new function member. Then the name of the function is the name of the member. It can also be saved in a variable. Later you can use that variable to call the function.

A function defined without a body is either intrinsic (defined internally, also called implicit) or abstract. You cannot define an intrinsic function. These are defined in the Global, System and Native packages and cannot be extended without creating an external library for the Flash Player (and I think that only works under MS-Windows). Abstract functions can be defined in interfaces and classes. The last class to extend a class or interface with an abstract function needs to define that function if it is to be used. Note that Flash doesn't support abstract functions. Once compiled, these will simply have an empty body.

The declaration of a function goes like this:

	function [get|set] name ( param1, ... ) [: type] { ... }

Note that you can declare a function within another function. This works perfectly in SSWF and Flash. However, watch out because the size limit of a function is 64Kb in Flash. You may reach that size very quickly if you have many sub-functions.

It is possible to create a function named get or set (since Flash as such functions, we've got to support them!). When a function has the get or set keyword followed by another name, then the function is considered a getter or a setter. Note that Flash does not support that syntax. The compiler will generate the necessary code to simulate that functionality. Getters and setters can never be created dynamically.

The name of a function is any valid identifier or a string. In case of a string, it is expected to be an operator overload. (i.e. "+", "**", "<=", etc.) Note that like for getters and setters, Flash does not support operator overloading. The compiler will generate the necessary code for you. But this means you cannot use dynamic operator overloading; whenever you need dynamism, use functions.

The list of parameters defines what the function accepts as input. Flash works with a stack and thus the parameters would by default be defined from right to left. To avoid this problem, the SSWF compiler either computes the parameters and saves them in registers before to stack them, or it creates an array with the parameter values and passes that array instead. The array also allows for modifiable parameters (i.e. parameters marked 'out'). Each parameter can have attributes, a name, a type and a default value. The rest parameter (...) can only be named. It cannot receive a default value, nor any attributes. Note that the expression of the default value of parameter n can use the value of parameters 1 to n - 1 (ECMAScript version 5+ if I understand...).

The following shows the list of attributes that parameters accept in SSWF:

The function itself can have the following attributes:

	throw Error("A function marked 'unused' cannot be called.")

The compiler will search for a function in the current scope, then go up in each scope it can find (backward and forward). Similarly, a function member is searched forward in a class starting at the beginning of the class.

Whenever a function matches, its prototype is checked against the list of parameters that the caller is giving that function. Note that can be a complex matter since the parameters can be given in any order and some parameters can receive default values. The compiler will always take the function that matches best the caller's list of parameters. For instance, a function with a rest will not be selected if another function without a rest matches the caller parameters. This is called overloading. If you want to avoid such selection, you will need to ensure that all your functions have a different name. Note that two functions with the same prototype (also called signature) in the same scope is an error.

As mentioned in the table above, functions can be called with a list of parameters that are named (or labelled.) The SSWF implementation is quite relax in that respect since it will accept a mix of named and unnamed parameters as long as the type of the unnamed parameters match the next unused parameters of the function being called. Note however, that the fact that a function has a rest, will not force the compiler to try to make use of it for parameters that do not match the next entry. You name a parameter in a call by putting its name (identifier) followed by a colon before the value. A rest parameter is always considered to have a lower priority than a prototyped parameter. This means if two functions match but more parameters are accepted on one of them without counting the rest, then that one function will be selected.

	function test(a, b, c) ...
	...
	a = test(c: 33, 57, b: "Hello");

In this example, the function test is called with (57, "Hello", 33). The 'b:' could be removed. Note how named and unnamed parameters can be used in the same list.

A function can be given a type. There are two special types for a function: Void and Never. Use Void whenever a function does not return anything. In this case, you can call the function a procedure. In case of Flash, the caller will be the one throwing out the return value. The Never type is very special and it means that the function never returns. This cannot be used with Flash since no function can loop forever. However, it is available in the language. Trying to use a Never function with SSWF compiler generates an error.

Overloading operators is a feature available in the SSWF implementation. Functions used to overload an operator are supposed to define the operator in a String. SSWF accepts operators as is since it does not break the syntax at all. The operators that can be overloaded and what they do are all defined in the Operators chapter.

		break [<label>];

The break statement is used to stop the current loop or switch statement and continue with the statements following that loop or switch.

The break statement can be followed by an identifier. This can be used to break all the loops up to the one named by that identifier. In effect, it is similar to using a goto statement with a label after the named loop or switch statement.

Note that the current implementation of SSWF does not allow you to break from within a try/catch/finally or with block to outside one of these blocks.

		continue [<label>];

The continue statement is used to stop the current loop try to repeat it. It will run the loop test and if true, restart the loop, if false, it stops.

The continue statement, when labelled, can also be used to continue a switch. This means the next case statements are checked and the first that is true is executed. In other words, multiple cases can be run within a single switch.

A continue with a for loop with counters goes to execute the next statements and then executes the test expression. As expected, if the test returns true, the loop repeats, otherwise it ends.

A continue with a for loop enumerating an object members sets the for variable to the next member and repeat the loop unless there was no more member names in which case the loop ends.

A continue with a do/while loop jumps to the while and runs the test. If the test returns true, then the loop is repeated. Otherwise the loop ends.

A continue with a while loop, jumps to the while and runs the test. If the test returns true, then the loop is repeated. Otherwise the loop ends.

A continue can be used to continue a switch statement. In this case, it has to be labelled. (This is because 99% of the programmers out there would otherwise be caught unaware of this special feature of SSWF since the default behavior is to continue the loop inside which the switch statement is found.) The label will be defined right before the switch statement to be continued.

The continue makes the flow control continue on to the following case statement. This would not be very useful if the cases only accepted constants and the switch statement only used the strictly equal operator. The fact is that SSWF enhanced the switch statement dramatically to where you can specify the operator to use to do comparisons with, the case expressions can be fully dynamic and also cases can specify a range. Because of that, it does make sense to have a way to continue testing the available cases. This can be achieved with the continue statement or the foreach attribute.

Note that the current implementation of SSWF does not allow you to break (continue with a label of an outer loop or switch) from within a try/catch/finally or with block to outside one of these blocks.

		[<label>] do ... while(<expr>);

The do statement is used to create loops that are executed at least once. The loop ends with a while and a boolean expression. The loop repeats as long as the expression is true.

	do {
		// executed at least once
		a++
		my_func(a);
	} while(a < 10);

The do and while statements can be used to create blocks that can be broken at any time. This can be useful whenever you have many conditions that can break the current code, but you still need some sort of clean up to happen afterward.

	do {
		if(a == b) { ... break; }
		if(c == d) { ... }
		if(e == f) { ... break; }
		...
	} while(false);
	// do my clean up here
	...

This example shows you how to use the break statement as a goto. This is usually preferable to a goto and label (and this is the only method available in all ECMAScript versions.) Note that the loop, in itself, is not really a loop since the while will never repeat the loop. This is just a block you can break.

If you want to create a loop that loops forever, you should use for(;;) instead.

		[<label>] for(<expr>; <expr>; <expr>) ...

There are three ways to use the for statement. Here we explain the for statement when used to create loops with counters. This version can also be used to create loops that loop forever: for(;;).

This for statement is expected to have three expressions: one for initialization, one for testing whether to execute the statements in the loop called the condition and one to update the counter variables called the next expression. Each expression is separated by a semi-colon. The initialization expression can include variable definitions. All expressions can be empty. When the condition expression is empty, the loop cannot stop unless you have a break or a goto within the loop.

	for(<init>; <test>; <next>) ...

Most of the time, the initialization is something like var i := 0, the condition is something like i < max and the next expression looks something like ++i. But of course, the possibilities are endless. All the expressions are supported in each of the three parts of the for. Note that the next expression (3rd) will not be evaluated if the condition expression returns false on the first try.

Note: SSWF does not prevent you from using the in operator in a for expression. The distinction between the two for's is very simple: one has two semi-colons and the other does not even have one. You can look at the source code if you are wondering how it works. It is actually pretty straight forward and it avoids us having to transform the behavior of the lexer whenever we parse a for loop.

SSWF supports having more than one variable definition in the initialization expression. So for instance, one can write the following:

	for(var i := 5, j := 0, k := 8;
		i < max && j > min && k == 8;
			++i, --j, k += magic)
	{
		...
	}

For forward and backward compatibility, it is adviced that you do not use that feature. Also, the variable types cannot properly be defined inside the for.

		[<label>] for(<name> in <object>) ...

There are three ways to use the for statement. Here we explain the for statement when used to go through all the enumerable members of an object.

This for statement is used to loop over all the members of an object. The result is to get a string that represents the name of a member and repeat the process until all the members have been named. The object member can be read using the syntax: obj[name] or obj.(name). For arrays, the members are integers.

The following example makes the integral sum of all the members of an arbitrary object:

	var total: Integer := 0;
	for(m in obj) {
		total += obj[m].toInteger();
		// or: total += obj.(m).toInteger();
	}

		[<label>] for each(<name> in <object>) ...

There are three ways to use the for statement. Here we explain the for statement when used to enumerate the values of all the enumerable members of an object.

This for statement is used to loop over the values of all the members of an object. The result is similar to the usual for ... in except that the variable is automatically set to the value of each property available in an object or an array.

The following example makes the integral sum of all the members of an arbitrary object:

	var total: Integer := 0;
	for each(m in obj) {
		total += m;
	}

Note: if a method is marked enumerable in your object, then it will be listed too. You may want to test the type of the value before to use if that can happen.

		goto <label>;

The goto statement is used to jump to a user label. The control flow changes at once from the current position to the indicated label. The goto cannot be used to jump outside or inside a function, package or program (i.e. you cannot cross the boundaries of one of these definitions).

Thought SSWF will at some point accept to go to in and out the try/catch/finally and with blocks, at this time this is not implemented. You can still use the goto intruction within or past one of these blocks.

	function test(var a: Integer := -1): String
	{
		if(a == -1) goto not_user_defined;
		with(Math) {
			...
		}
		return "User";
	not_user_defined:
		...
		return "Internal";
	}

Note that the implementation of the goto statement is an SSWF extension. It is not available in ECMAScript, only reserved.

		if(<expr>) ...
		if(<expr>) ... else ...

The if and else statements are used to test a condition and execute code when it is true and optionally when it is false. The construction is as follow:

	if(<expr>) {
		// execute when <expr> is true
		...
	}
	else {
		// execute when <expr> is false
		...
	}

The else and following block are optional.

At times, you need to use a condition to select between two values and then save the selected one in a variable. This can often be achieved with the use of the conditional expression instead, which can be faster.

	// with a conditional
	if(<expr>) {
		// execute when <expr> is true
		my_var := <value 1>;
	}
	else {
		// execute when <expr> is false
		my_var := <value 2>;
	}

	// a faster way is to write this instead:
	my_var := <expr> ? <value 1> : <value 2>;

		<label>:

The user can enter labels to use with the goto, break and continue statements.

In case of the goto statement, the control flow continues right after the label. If the goto is done from within loops, it first breaks these loops.

When used with a break statement, the control continues after the loop (for, do, while) or switch named on the break statement. Using the break with a label let's you break multiple loops at once.

When used with a continue statement, the control flow continues at a different place depending on the statement being continued. Note that when used with a label, the continue first breaks all the inner loops and switches up to the loop or switch having the specified label. Please, see the continue statement for more information about how the continue is handled.

		return [<expr>];

The return statement is used to end a function right away and to return a value to the caller. Using the return statement outside a function is an error.

Note that in ECMAScript, all functions return a value but functions marked as returning Void will actually return the special value undefined. Flash will automatically add undefined on the stack if a function does not explicitly return anything.

The return statement needs to have an expression when the function does not return Void. And vice versa, the return statement must not return an expression when the function returns Void. The return statement cannot be used when the function returns Never since this special type means the function never returns.

Note that in effect, the return statement is very similar to a goto statement which makes sure that there is one value on the stack after it jumped to the end of the current function.

		[<label>] switch(<expr>) [with(<operator>)]
			[switch attribute] {
				case <expr>: ...
				default: ...
		}

The switch statement is used to test multiple values at once. This is very similar to a set of if/else statements used in a slightly more structured form.

The SSWF support of the switch statement has been enhanced to:

• include other operators than the default strictly equal (===),
• receive attributes,
• take case expressions with a range,
• and to accept the continue statement.

Also, but I do not think this is an extension according the ECMAScript reference, the expressions following the case statements do not need to be constants.

By default, a switch statement will:

• Evaluate the expression defined within parenthesis
• Save the result in a temporary variable reused later to compare against the case expressions
• Evaluate the first case expression
• Compare, using the strictly equal operator (===), the switch statement expression and the first case expression
• Start executing the statements following the case if both expressions are equal. It stops execution on either a control flow statement that breaks that list of statements (such as break, continue, goto, return...) or the end of the switch statement is reached.
• If the first case expression wasn't equal to the switch statement expression, then the second case expression is evaluated and compared just like the first was (repeat on Evaluate the first case expression with the following case statement.)
• If no case expression was equal and there is a default label, then execute the default statements like it would execute a case statements (note that the default label does not need to be at the end of the case statement; it will be skipped until all the cases have been checked and used only if all the case expressions do not match.)

	switch(9) {
	case varA: ...
	case varB * 2: ...
	case varC + 3: ...
	   ...
	}

The enhancements change the default behavior of the switch statement by allowing you to:

• Use an attribute for auto-break/continue generation (see the attributes section for more information on how to define an attribute for a switch statement.)
• Define a case with a range (<expr> ... <expr>) which match whenever the switch expression is within the range (inclusively for both expressions.)
• Accept the continue statement when labelled.
• Label a switch statement to be able to break or continue it from itself or other inner loops defined in the statements of a case.
• Specify the comparison operator to use. The table below lists valid operators for the switch statement. Note that the operator has to be defined using the with keyword.

The with keyword is used to specify the operator. At this time, it is assumed that we want the parenthesis though SSWF does not enforce their usage (switch(my_var) with > { ...} is valid). At this time it is fine since there cannot be any confusion.

Each case statement can be defined as a range. This is done by defining two values separated by a rest (...). The values specified are included in the range. So for instance, the range 3 ... 13 includes all the values from 3 (included) to 13 (included). Note that you need to put spaces before and after the range operator. This is because the lexer would otherwise see numbers as floating points.

The continue statement is explained in depth in its own section. In brief, from any statement of a case that matched, you can request the next case to be checked instead or breaking or falling through.

		throw <expr>;

The throw statement is used to raise an exception.

By throwing, you generate an exception. The expression after the throw statement will be used as the exception expression. To catch an exception, you need to run your code in a try block and have a corresponding catch block. The expression on a throw statement can have any type. The catch statement can specify a specific type so the handling of the exception can be made specific to a type of object.

		try { ... }
		catch( <param1> : <type1> ) { ... }
		catch( <param2> : <type2> ) { ... }
		...
		catch( <paramn> : <typen> ) { ... }
		catch( <paramno-type> ) { ... }
		catch(...) { ... }
		finally { ... }

The try, catch and finally statements are used to handle exceptions. The try statement is followed by a block of statements which are executed safely meaning that they can generate an exception and the process will not just stop. Instead it will continue in a catch statement block (if there is one available). In all cases, the (clean up) statements in the finally block will be executed (when one was defined).

The try statement and block of statements has nothing specific to it. It needs to be followed by at least a catch or a finally statement. A try without any catch will only ensure that the finally statements are executed, but the exception will be thrown again as soon as the finally block exits.

Several catch statements can be specified to catch different type of exceptions. The type of an exception is determined using the type of the expression given to the throw instruction. The type of the exception expression has to match the type of the catch parameter for that specific catch statements to be executed. There is no restriction on the type a throw and catch can use to generate exceptions in SSWF, but it looks like the Flash player only accepts Error objects and objects derived from the Error object (TBD -- if it is the case the compiler should err about it!).

The order of the catch statements can be important depending on whether a type is derived from another. You may have to pay attention to that. Also, only the very last catch can be untyped or use the rest (...) operator. Such a catch will match any exception. When you do not need to check the exception expression, you can use the rest (...) operator. This ensures you do not reference the parameter if you did not want to.

When there is one or more catch statements, all have a typed parameter, and none of these types match the exception thrown, the exception is raised again. Note that the finally statements will still be executed. This is similar to the following code:

	catch(exception) {
		throw exception;
	}

It is possible to not have any catch handlers. In this case, you need to have a finally statement. Note that exceptions are caught until the finally executes, but then they are thrown again once the finally exits. If an exception happens while executing the finally block of statements, then the old exception is lost and the new one is propagated.

The finally statement must be the last if it is to be used. It defines a set of statements to be executed in order to exit the try statement cleanly. In general it will ensure that some temporary objects were properly deleted. The following examples shows you how a user object is first newed in the try statement and then deleted in the finally.

	var o: MyObject;
	try {
		o := new MyObject(p1);
		o.Init();		// this can throw
		o.Execute();
	}
	catch(e: MyError) {
		if(e.name == "Really Bad") {
			print("We're in trouble");
			throw Again(33);
		}
	}
	finally {
		delete o;
	}

Note that in such a script, the variable o would at some point be set to undefined and if there is no other reference to the object o, it would anyway be deleted. The explicit delete ensures that even if there is another reference somewhere else, it will surely be deleted.

		[<label>] while(<expr>) ...

The while statement is used to create loops. It is very similar to the do statement except that the test is run once before to execute any of the statements following the while.

Note that a while(false) ... statement is reduced to nothing. Thus, if your expression can be reduced to false at compile time (i.e. it is constant at compile time,) then the entire statement is ignored.

		with(<expr>) ...

The with statement is used to avoid having to specify an object on every single statements. Any variable or function used inside the block of statement following a with will first be looked for in the specified object, then functions and variables defined outside the with block.

This can be particularly useful if you are to use many Math functions. The following show a small example:

	function circle_surface(radius: Double)
	{
		with(Math)
		{
			return 2 * PI * pow(radius, 2);
			// In SSWF, the power can be written like this too:
			// return 2 * PI * radius ** 2;
		}
	}

Note that the SSWF implementation currently forbids you from using with with the this reference. There should be no reason for the end user to do so anyway.

Classes, interfaces and enumerations are supported in SSWF.

Enum

Enumerations are lists of names which can be assigned a value or are automatically assigned the previous value plus one.

	enum <name> {
		<name1>,
		<name2>,
		<name3>,
			...
		<namep> = <expr>,
			...
		<namen>
	};

The name of an enumeration is optional. When specified you can use it as a type. Note that an enumeration cannot be used to create an instance later. It is only a declaration.

The first value (<name₁>) is set to 0 when no value is specified.

A value can be specified using the usual assignment operator. Note that enumerations can use dynamic expressions (i.e. the expression does not need to be a constant). This is an extension of SSWF and it may be removed later. It is experimental.

Class

A class defines an object that you can later instantiate using the new operator.

A class can be composed of function members, variable members and sub-classes. Also, it can inherit of one other class and any number of interfaces. It can have a constructor.

	class extends <class name>
		implements <interface name1>, <interface name2> ... <interface namen>
	{
		// variables
		var <name> = <expr>;
		// constants
		const <name> = <expr>;
		// functions
		function <get|set> <name>(<parameter>, ...): <type>
		{
			...
		};
		// sub-classes
		class <name> { ... }
	}

Note that a class does not need to extend Object. That is the default. A variable can be a constant. A function is considered a constant (it cannot be overwritten, this is enforced at run time). All members are considered invisible and not deletable by default. If you want to make a member available to the for(... in ...) or for each(... in ...) enumerators (i.e. visible), then you need to mark it as enumerable (this is a member attribute). To make members deletable, use the dynamic member attribute.

The following table lists all the attributes which can be used with classes. Note that some attributes are expected to be defined on the class itself and others on the members in a class. Of course, since a class can be a sub-class of another class, it can be considered a member and thus all the flags are applicable to classes. Note that some attributes, such as dynamic and final are somewhat special. Note that interfaces cannot be dynamic and even less final.

	// The following is an undocumented function used to setup the
	// protections of the different properties of an object
	// OR these values for the flags; you may need to set 'allow' to true
	// to change a flag from 0 to 1
	const var PROP_FLAG_CAN_OVERWRITE = 4;
	const var PROP_FLAG_CAN_DELETE = 2;
	const var PROP_FLAG_IS_HIDDEN = 1;

	// set props to the array of properties you wish to change protections
	// (or use null for all of them)
	function ASSetPropFlags(obj: Object, props: Array, flags: Integer, allow: Boolean = false);

To see everything and make it dynamic (overwritable and deletable), use null for the array, set the flags (PROP_FLAG_CAN_OVERWRITE | PROP_FLAG_CAN_DELETE) and set allow to true to force the new value.

	ASSetPropFlags(MyObject.prototype, null, PROP_FLAG_CAN_OVERWRITE | PROP_FLAG_CAN_DELETE, true);

With this function at hand, you can list the entire system available to you in any Flash Player.

Interface

Defines an interface just like a class. The few differences are: interfaces cannot include a constructor, interfaces cannot extend anything, interfaces cannot include sub-classes.

The idea of an interface is to create variables of that type and have function prototype tested by the compiler. There is otherwise not much to interfaces. In ECMAScript, you do not otherwise need to have function prototypes, so it is not absolutly necessary to define interfaces.

SSWF accepts packages. These can be defined in the .sswf files or externally. SSWF will automatically load the system packages and make them available as they are supposed to be.

The internal packages define the Global objects available by default in ECMAScript, the System and Native Flash objects. These are the packages which are automatically loaded for you. You do not need to specify any import statement to access these objects (even though in SSWF, all of these are really defined in packages!)

SSWF also offers some extensions (such as Complex). Extensions are not part of the system and thus you need to explicitly import extension packages.

To use objects defined in one of your own packages, you also need to specify your package in an import instruction.

For SSWF to find an external package, you first need to compile the package with asc. This will ask the compiler to record the objects (classes, interfaces, variables, etc.) defined in the package in the packages database. Once in the database, the import will be able to find the package again in order to instantiate it in output files. Note that the name of the package has nothing to do with where to find the package on your file system.

The database of all the package objects is saved in a text file that you can look at. It is strongly suggested that you do not modify the file. You can, however, delete it if you delete one of your package. This will prevent SSWF and asc to try to look for that package later. If you delete your database, you will need to recompile all of the packages you still want to use with SSWF using asc.

The database file is named in your setup file. It needs to be in a directory where you can create a file and then read and write in that file.

When you create a Flash movie, the packages are not automatically implemented in the movie. You need to specifically tell the compiler to include a package in the output movie using a pragma and the import instruction.

	use pragma instantiate(true);
	import my_package;
	use pragma instantiate(false);

Packages can include classes, interfaces, variables and functions. You can make the definitions internal, in which case only the package sees these definitions. You can make a definition private. Then only functions in this specific file can access the definition.

A package can include another package. You can access sub-packages as you access sub-classes, with the use of the member operator.

SSWF supports a certain number of pragmas as defined in the table below. The system conforms to the ECMAScript reference. Most pragmas supported by SSWF are specific to SSWF.

The syntax of pragma is a list of identifiers optionally followed by one parameter and a question mark. The question mark can be used to test whether some option is turned on or off.

	use pragma <name> [ '(' <value> ')' ] [ '?' ] ... ;

The parenthesis are optional if you do not define a value. By default the value is 0 or 1 (i.e. 0 when negative and 1 when positive).

For instance, you can turn on the use of extended operators with use pragma extended_operators; or use pragma extended_operators(1);. In a package, you can test to make sure that extended operators are available (if you make use of them, that's a good idea to do so) with use pragma extended_operator?;.

You can specify multiple pragma's one after another on the same line as in:

	use pragma
		extended_operators
		octal
		strict;

Because of the pragma question feature, most pragmas will have an opposite defined. For instance, the extended_operator has the opposite no_extended_operator.

Note: in the table below, the default presents what SSWF sets as the default options. It is not automatically the default of the asc (library) compiler.

	use pragma trace(true);

	trace("My Debug", "More Info");

	Trace.Message("My Debug", __NAME__,
		__FILE__, __LINE__, "More Info");

At this time, SSWF does not support name spaces. The lexer will read them and the parser will accept most of them, but the compiler and assembler will not know how to deal with them. So do not use them.

In this chapter I will try to answer some questions before they are even asked and put what I think has value in understanding the internals of the SSWF ActionScript compiler. There are problems with this compiler just like with any compiler and I am trying here to explain why I chose to do thing one way rather than another. I also mention quirks in the grammar, lexical or Flash which we cannot really go around, or for which there isn't a clear answer.

• Internal Variables

Like most compilers, SSWF will generate temporary variables and for those it will need to use auto-generated names and registers as it sees fit. Within a function (V7+ of Flash) we have up to 254 registers available. SSWF will make use of as many as possible to avoid using variables. Registers are a lot faster to access since these are accessed by number instead of name like variables.

Registers, you don't really need to know whether they are used or not. These won't clash with anything you are doing. However, when not in a function, or in a really large function using lots of variables, you can still find yourself out of registers. At that point, the compiler will generate a name. At this time, all names will start with two underscores, a letter and a unique number (the number will be unique in the entire SWF file.) The letter will change depending on the use of the variable (see table below.) This can be important since you should NOT name one of your variables with any of these names. I don't forsee too many people using names of dynamic variables starting with two underscores anyway... right?

Letter Comments

__g<number>	Global variables use the 'g' letter. Globals are variables defined outside a function or class. SSWF automatically rename your variables unless you mark them as being dynamic (see talk about dynamic variables below). This is because if you need to share variables between different programs in SSWF, you should define them in _root or _global and not try to use global variables.
__l<number>	Local variables use the 'l' letter. Locals are variables defined inside a function. Just like with global variables, SSWF renames all of your local variables in this way. In general, however, it will save your variable in a register. If you are wondering why SSWF renames your variable, that's because otherwise it is much harder to ensure distinct variables between frames. For instance, one can write this: function test(a: Double := 3) { var b: Double := a ** 2; if(b >= 100) { var b: Double := sqrt(a); if(b <= 10) { var b: Double := a; return b; } } return b; } In this example, the variable 'b' is defined three times (which according to some references isn't legal, but it is allowed in SSWF.) In the case where the function returns prematurly (the inner most if()), it is fine since 'b' will hold the correct value. However, the last return needs to return a ** 2 and not sqrt(a). If SSWF wasn't renaming your variables, you would get the wrong result (note that if you try to compile this example, all the variables will be put in registers, but still, it will use three distinct registers.)
__c<number>	Catch parameters use the 'c' letter. In general, just like local variables, catch() parameters will make use of registers if possible. Note that if you have several catch() one after another, they all will share the same variable. This is because once assembled, the resulting try/catch/finally block includes only one set of instructions for all the catch() entries in your code.
__t<number>	Temporary variables use the 't' letter. Temporaries are used in expressions. These, you don't have a counterpart in your code. It is just often necessary to have a temporary variable to compute your expressions. Note: actually, if you look at it closely, there is really only three or four expressions which require the use of temporaries. The worst one is the function call, depending on your parameters, it can require one temporary per parameter.
__f<number>	Local functions get renamed. These have the same problem as the local variables. If you define two functions with the same name in two different frames, it would be viewed as one by Flash. This means you can use the default function name to call a function dynamically. To fix that problem, put your functions in variables and use variables instead. f1 = function (a) { ...} f2 = function (a) { ... } func = test ? f1 : f2; ... (func)(value); ...




• dynamic var <name>; & undefined (or global variables)

Example:

	if(a < b) {
		var c: Integer;
		// place of interest
		if(b & 1) c := Math.sqrt(a + b);
		magic(c);
	}

In this example, c is set only if b is odd. By default, ECMAScript says that a block of directive is a frame. Each time you enter a frame, you copy the current frame to create a sub-frame and start working in that frame. This means the variable c is created at that time. Because there isn't any initialization, the value of c is set to undefined. In Flash, that doesn't happen because Flash has no notion of frames. This means entering this if() statement when b is even, you could find yourself with c already set from the last time you entered that if() statement with an odd value in b.

To circumvent this problem, the SSWF compiler generates some extra code to set local variables to undefined whenever a frame is being exited. In other words, you get the following:

	if(a < b) {
		var c: Integer;
		// place of interest
		if(b & 1) c := Math.sqrt(a + b);
		magic(c);
		// auto-generated line:
		c := undefined;
	}

This ensures that you cannot reuse c with the wrong value anywhere in the code.

The problem now is that some variables that you want to define are globals. These variables will receive the same treatment by default and thus they would get deleted!!! But you mark them as dynamic variables and the compiler will not generate that extra line of code. Another way to avoid the problem is to use a variable member in the _root or _global objects as in:

	_root.a = 55;
	_global.b = 77.3;

Using the _root and _global objects is certainly the best way to go because these will always be available to you. The global is viewed by all the scripts and is the same object. There is one root per SWF file however. This is important only if you load movies in one of the 10 levels. Each level has its own root object.

WARNING:

As a remainder, dynamic variables do not respect frame boundaries. In other words, if you define two distinct dynamic variables with the same name in two distinct frames, it will be the same variable.

But tell us... why did you invent dynamic variables if these are so bad and you are asking us to not make use of them?!

In Flash (in Javascript in general,) you can call certain functions to create objects. These functions can accept a string as one of their parameters. The string can then be used as the name of the variable where that object will be saved. The MovieClip.createTextField() is such a function. The first parameter is the name of the new movie clip (i.e. a Sprite.) The following is an example of what you could write in SSWF to create a similar function:

	function createCar(var name: String, var weight: Float) : Void
	{
		var car := new Car(weight);
		// ... do some initialization
		(name) := car;
		// yes! 'return car;' would make more sense to me too...
	}
	...
	dynamic var myCar;
	createCar("myCar", 1299.3);
	myCar.Run();
	...

So, more or less, the name of the variable in which the car object is to be saved needs to use a dynamic variable outside of this function. I don't think it is a good practice, but since Flash is using such an approach, I need to support it in SSWF.




• Can I trace?

In version 1.7.4, I'm adding support for the trace() function that creates a sprite and a text field in it with your trace message and some additional information automatically generated by the compiler and assembler.

To use this feature, you need to turn on the trace pragma:

	use pragma trace(true);

If you want to make use of the advance trace() feature, then you need to use the trace_to_object pragma. This way the assembler will convert a straight trace() into a call to the method named Message in an class named Trace. The pragma goes like this:

	use pragma trace_to_object(true);

By default, the compiler and assembler will turn off the trace feature and no code is generated for any call to trace().

The call to trace() is changed to a call to the Trace class like this:

	trace("Hello!");
	// becomes
	Trace.Message("Hello!", "<qualified name>", __FILE__, __LINE__);

The fully qualified name includes all the names from where the trace() is found up to the package in which it is included going throught functions, classes, interfaces...




• declarations and statements

If you look at the output code, you will eventually notice that declarations are assembled before statements. This is because Flash requires that a declaration be known before it can use it. For instance, it needs to have a function declared before it can call that function. For this reason, the assembler will first assemble functions, classes, interfaces and some other declarations and then it will compile the other directives, in general that will be statements including expressions.

This shouldn't cause any problem, however, it may look weird when you look at a switch statement since all of the declarations will be done before any case is being tested.




• is versus instanceof

At this time, the SSWF compiler compiles these two operators as being the same operator. The is will behave exactly like the instanceof. I'm not too sure, but it certainly is correct simply because it is likely that the instanceof does not support comparison between function prototypes. Let me know if you find a problem with the is operator.




• Sub-classes

It is possible to declare sub-classes, however, at this time SSWF does not compile sub-classes properly. This is my next task with some other class related enhancements and bug fixes. So for now avoid any sub-class definitions.

On the other hand, SSWF accepts class definitions anywhere just as it ought to be. You gonna love that!




• Errors

The parser is done properly and it will give you a good error feedback. At this time, the compiler and assemblers are not so good and they just print something like ERROR: message without any filename or line number. I will fix that very soon. I need to create an object to take care of writing messages on screen.

From within SSWF, the line numbers do not seem to start at the right value. I am not too sure whether SSWF has the wrong value to start the ActionScript parser or whether the parser itself is wrong. That too will be fixed soon. It should be easy enough.




• Packages

In this version, user packages are not supported (that is, they will not be assembled). You can only use intrinsic definitions. This is on my TODO list along with the different class assembly which are still missing.




• Overloading

Overloading is declaring two functions with the same name but different parameters. This is supported by SSWF for common functions (those which are not defined in classes). At this time, classes do not support overloading.

There is one good thing about overloading, it make it easy to name functions! Then the system can just select which one to use. You have two ways to implement an overloaded function: (a) you create several functions with different parameters and (b) you create one function which accepts all kinds of parameters and checks its inputs at run time.

The second way (b) is always available to you in pretty much all languages as long as you can test the type of your parameters. The first way (a) is only available if your compiler and execution environment supports it. The Flash execution environment does not support overloading since it has poor data type support (at least up to version 7.x).

To circumvent the lack of overloading of Flash, SSWF will rename functions automatically and just call the proper function. You have nothing to do. You can prevent this renaming with the use of the dynamic attribute.

At this time, SSWF is not doing any function or variable member renaming. Thus, in a class definition SSWF does not support overloading (thought at this time it does not report problems.) This is because to support fully dynamic objects, the compiler cannot just rename members of a class. This problem may be fixed in version 8.x, but at some point, I will make the overloading work with version 7.x anyway. You will have to specify dynamic on members of a class that you want to call dynamically (i.e. with a name defined in a variable not known at compile time).




• typeof <expr>
 

Warning:

typeof in version 5, 6 and 7 is limited to the internal types; whenever you create your own class, it returns "object"; nothing more; I will program something to circumvent this limitation though...

Note that SSWF defines a type 'Integer' and a type 'Double' whereas Flash only has a type 'number'. This means you can't distinguish between an integer and a double in Flash. This includes the catch() statements. If you use a typed parameter named Integer or Double, the assembler will warn you and use 'number' instead. If you try to catch both types and/or number, then the assembler generates an error since you cannot catch the same type more than once.

Be careful whenever you test types. One way is to do something like this:

	typeof <var> === typeof 0

At some point, SSWF may be able to transform a typeof of a constant expression directly into its type. However, that would cause the previous statement to break since 0 would be viewed as Integer and typeof <var> would return Number. Finally, note that the type returned by typeof in Flash is given in lowercase (number, string, undefined, null, movieclip, etc.).




• Classes and interfaces and sprites

Flash up to version 8.x uses empty Sprites to create object models (i.e. classes). This means you can only declare a class in the top level of your SWF movie. SSWF doesn't pre-parse all the objects to know whether some sub-'do action' tags include a class definition. Thus, it is currently your responsilibity to define classes and interfaces in do action scripts outside of sprites.

Since Flash 9, there is a new tag to support ABC scripts. These are not currently supported by SSWF. However, it will break the scheme of having to extend an object to create a class. This most certainly fixes the problems with the typeof keyword.




• catch(i: Integer) ...

Because SSWF define Number as Double, it diverts from what it is supposed to be. The problem here is that classes in ECMAScript can only derive from one other class. Thus Number cannot derive from Double and Integer at the same time.

Also, the Flash Player (at least up to version 8) does not know anything about Double and Integer, only Number.




• Decimal point versus member, range and rest operators

I have looked in this problem and came to the conclusion that the only way was to ask the programmers to put spaces. You could find the following in a source file:

	if(a in 5..2) ...

The range should have been written with spaces as in 5 .. 2. At this time, the lexer will see this expression as 5. and .2 and the parsing will fail with a syntax error.

The problem is fairly complicated when you add all the cases. You can have a decimal point by itself (5.), a decimal point followed by an exponent (5.e+3), a member operator (5.toString() [decimal] or 5..toString() [floating point]), a range operator (5..) or a rest operator (5...). One solution is to forbid a dangling decimal point (i.e. a decimal digit would be required after the decimal point). However, the ECMAScript definition includes that dangling decimal point case.




• function get|set name(...) { ... }

The lexer and parser understand and accept getters and setters. The name of a getter is transformed by prepending "->". This a getter function named "variable" will be compiled as "->variable" in Flash. Similarly, a setter function named "variable" is compiled as "<-variable".

This means you cannot access getter and setter functions dynamically. The reason for using the <, > and - characters is simple: no other functions can be named that way by the user. Also, since you are supposed to have both a getter and a setter with the exact same, they needed to be distinguishable.

Jan 27, 2008	Added colors in the samples. Fixed the FAQ about the getters and setters that now work. Fixed the usage of the which word in English.
Nov 11, 2005	Added info about the __FILE__ and __LINE__ special identifiers (see Literals) Added trace and trace_to_object pragmas. Added FAQ about trace(). Fixed the expression table so it is not so wide. Fixed several styles in different tables. Fixed 'pragma' to 'use pragma' instead.
Sep 3, 2005	Created this documentation. Until I consider it mostly done I will not be changing the history since it is just part of the creation of the document.

This document was last modified on .

• Reference directory
• Home page of this reference
• Download reference