5.9 with

JavaScript interfaces with the web browser through an "object hierarchy" that contains quite a few arrays nested within objects and objects nested within arrays. In order to refer to the components that make up a web page, you may find yourself referring to objects with cumbersome expressions like the following:

frames[1].document.forms[0].address_field.value

The with statement provides a way to simplify expressions like this one, and reduce your typing. It has the following syntax:

with (object)
    statement

object is an expression that evaluates to an object. This specified object becomes the default object for all expressions in statement, which is a primitive statement or statement block. Any time an identifier appears within statement, that identifier is looked up as a property of object first. If the identifier is defined as a property of object, then this is the definition used. If the identifier is not defined there, then JavaScript looks up its value as it normally would.

For example, you might use the with statement to simplify the following code:

x = Math.sin(i * Math.PI / 20);
y = Math.cos(i * Math.PI / 30);

with(Math) {
    x = sin(i * PI / 20);
    y = cos(i * PI / 30);
}

Similarly, instead of calling document.write() over and over again in a JavaScript program, you could use a with(document) statement, and then invoke write() over and over again instead.

You can nest with statements arbitrarily. Note that the object expression in a nested with statement may itself be interpreted depending on the object in a containing with statement.

If the object in a with statement contains properties that have the same name as top-level variables, the with statement effectively hides the top-level variable--when you use the name of that variable you now refer to the object's property instead. If you need to explicitly refer to a hidden top-level variable var, you can usually use this syntax:

top.var

We'll see why this works when we study the Window object in Chapter 11, Windows and the JavaScript Name Space. Note that this technique will not work if top is the name of a property of the object in any enclosing with statement.

It is important to understand that the with statement only works with properties that already exist in the specified object. If you assign a value to a variable that does not exist as a property of the specified object, then that property is not created in the object. Instead, JavaScript searches the containing with statements, if any, for a property with that name, and then searches for a top-level variable with that name. If no such property or variable is found, then a new top-level variable is created. The rule to remember is that new properties cannot be added to an object if you refer to the object implicitly through a with statement. To create a new property in the object, you must refer to it explicitly.

To really understand how the with statement works, we need to briefly consider how variables are looked up in JavaScript. We'll return to this topic in detail in Chapter 11, Windows and the JavaScript Name Space. Suppose JavaScript needs to look up the value of the name n. It proceeds as follows:

• If n is referred to within a with statement, then it first checks to see if n is a property of the object of that statement. If so, it uses the value of this property.

• If the first enclosing with statement does not provide a definition for n, then JavaScript checks any other enclosing with statements in order (remember that they can be nested to any depth). If any of objects specified in these statements define a property n, then that definition is used.

• If the reference to n occurs within a function, and no enclosing with statements yield a definition for it, then JavaScript checks to see if the function has any local variables or arguments named n. If so, it uses this value.

• Finally, if no definition for n has been found then JavaScript checks to see if there is a top-level variable named n, and uses it if so.

• If n is not defined in any of these places, then an error occurs.