A function declaration is a description of a function in the script source text. It provides the function name and a list of its arguments. It also provides a block of script code to be executed when the function is called.

Functions can be declared in the script source to add to the functions your script can make use of. When they are called, the prototype inheritance mechanism matches most local instances of the function having the name that the caller requests. This provides a way to override methods in parent prototypes or the global object.

When functions are declared in global and eval code, the new function object that is instantiated is added to the variable object for the owner of the script source text. It uses the function identifier as a name for the dictionary entry in the variable object. The functions are added in the order in which they appear in the Script Source Text and will replace any previously existing entry. Attributes are set according to the type of code being evaluated.

New functions can be added to the scripting environment as needed. They are described in the source script text with function declarators.

A function is declared with the function keyword, a set of parentheses enclosing its passed arguments and a block of executable code enclosed in curly braces.

Functions will always return a result but a function call can be cast to a void type to discard the resulting value. If you don't indicate a result to return yourself, the function mechanism would return the value undefined.

The internal mechanics of function declaration is to add a function property to the global object whose name is the function's identifier. The value of that property is a function object with the given parameter list and statement block.

If the function definition is part of the source text supplied to an eval function, then the function may be added to an internal activation object rather than the global object.

The act of executing or invoking a function is to call it.

Calling a function is accomplished by using the function property of an object as an RValue and appending the parentheses grouping operators with option arguments grouped within them.

Functions can be created and their script can refer to objects that don't yet exist. However, you may not run them until the objects they refer to have been created. This is often the case with event handlers that are defined speculatively on the basis that they may be needed but in fact they may never be called at all.

As of JavaScript version 1.2, you can declare new functions anywhere in a script source text. Prior to this, you could only define them in global code but not inside any if() blocks, loop blocks or with blocks. In JavaScript version 1.2, functions can be declared inside these contexts and inside functions themselves. This means that function availability can be localized to only be usable within a function's context scope.

Warnings:

• Debugging namespace collisions between function and variable names can be difficult to debug. For very large projects with many people working on shared code, you may want to establish some strict naming conventions to partition the namespace.

• This is an issue because function declarations occur before variable declarations. If you declare a variable with the same name as a function and assign a value to it the function will be inaccessible since you will have replaced the reference to its object with the value you just assigned to the variable.

• This will still happen even if the var declaration is placed sequentially earlier in the script block than the function declaration. The first pass declares and sets up the function. The second pass instantiates the variable.

• Remember that functions are created at compile (parse) time, and variables at run time.

Example code:

   // Here is an example function declaration:

   function circularArea (aRadius)

   {

      someGlobalValue = aRadius;

      return(Math.pow(aRadius,2)*Math.PI);

   }

   

   // We are using functions belonging to the Math object to

   // raise the passed in radius value to the power of 2

   // and multiply the result by the constant value of PI.

   // We can call this and assign its value like this:

   myArea = circularArea(12);

   alert(myArea);

   

   // If we simply wanted to execute the function and discard its

   // result we might use this form:

   void circularArea(10000);

   

   // The conseqence is just to set the global value but we don't

   // do anything with the returned value.

Cross-references:

ECMA 262 edition 2 - section - 10.1.1

ECMA 262 edition 2 - section - 10.1.3

ECMA 262 edition 2 - section - 10.1.6

ECMA 262 edition 2 - section - 13

ECMA 262 edition 2 - section - 15.3.2.1

ECMA 262 edition 3 - section - 10.1.1

ECMA 262 edition 3 - section - 13

ECMA 262 edition 3 - section - 15.3.2.1

Wrox Instant JavaScript - page - 26