8.3 Syntax of Defining and Calling a Handler

The parameters, if there are any, follow the name of the handler in both the definition and the call. In the definition, you're saying how many parameters there are, and supplying the names of the local variables to which they will be assigned; in the call, you're supplying their values. There are four syntactic cases that must be distinguished, depending on whether the handler has parameters and, if so, how they are specified. (Personally, I think the third and fourth ways to define a handler are silly, and I never use them. But you need to know about them anyway.)

It is not an error to refer to a handler by its name alone, with no parentheses or parameters. This can be a useful thing to do, if you wish to refer to the handler as a value (see Section 8.6, later in this chapter); but it doesn't call the handler. If you refer to a handler by its name alone, intending to call it, your script will misbehave in ways that can be difficult to track down.

8.3.1 No Parameters

If a handler has no parameters, the name of the handler in the definition is followed by empty parentheses:

on handlerWithNoParameters(  )
        -- code
end handlerWithNoParameters

The call consists of the name of the handler followed by empty parentheses:

handlerWithNoParameters(  )

8.3.2 Unnamed Parameters

Unnamed parameters are sometimes referred to as positional parameters. This is because the pairing between each parameter value passed and the local variable in the handler that receives it is performed by looking at their respective positions: the first parameter is assigned to the first variable, the second parameter is assigned to second variable, and so forth.

If a handler has positional parameters, the name of the handler in the definition is followed by one or more variable names in parentheses, separated by comma:

on handlerWithOneParameter(x)
        -- code
end handlerWithOneParameter
on handlerWithFourParameters(a, b, c, d)
        -- code
end handlerWithFourParameters

The call then consists of the name of the handler followed by parentheses containing the parameter value or values, separated by comma:

handlerWithOneParameter(7)
handlerWithFourParameters("hey", "ho", "hey", "nonny no")

It is not an error to call a handler with more unnamed parameters than the handler requires, but the extra values are ignored.

8.3.3 Prepositional Parameters

Prepositional parameters are also called labeled parameters. Each parameter is preceded by a preposition drawn from a fixed repertoire. The use of prepositional parameters has two supposed advantages:

• The prepositions may give an indication of the purpose of each parameter.

• The prepositions are used to pair the parameter values with the variables in the handler, so the parameters may be passed in any order.

The preposition names from which you get to choose are limited to those listed in Table 8-1.

Table 8-1. The prepositions

above	beneath	into
against	beside	on
apart from	between	onto
around	by	out of
aside from	for	over
at	from	thru
below	instead of	under

In addition to the prepositions in Table 8-1, there is also a preposition of. This is used in a special way: if you use it, it must come first, and there must be more than one parameter. This odd rule seems to be due to a mistake in the original design of AppleScript. In AppleScript 1.0, the of parameter was intended as a way of distinguishing the "direct object" (the handler's main parameter). Then it was realized that where there was just one parameter and it was the of parameter, an unresolvable ambiguity with the of operator was introduced. So AppleScript 1.1 resolved the ambiguity by forbidding of to be used that way. But no alternative way of distinguishing the direct object was supplied, so in a sense this feature has been broken ever since.

If a handler has prepositional parameters, the name of the handler in the definition is followed by a preposition and a variable name, and then possibly another preposition and another variable name, and so on.

In the call, the name of the handler is followed by a preposition and a value, and then possibly another preposition and another value, and so forth. The prepositions used must match those of the definition, but they may appear in any order, except for of, which must be first if it appears at all.

Here are some examples of handlers with prepositional parameters and calls to them:

on firstLetter from aWord
        return character 1 of aWord
end firstLetter
display dialog (firstLetter from "hello")

on sum of x beside y
        return x + y
end sum
display dialog (sum of 1 beside 2)

on stopping by woods on aSnowyEvening
        return woods & aSnowyEvening
end stopping
display dialog (stopping on "horse" by "farm")

In the call, if the value you wish to pass is a boolean, you may use with or without (to indicate true and false respectively) followed by the preposition. If you don't use this syntax, AppleScript may use it for you when it compiles the script: any prepositional parameters for which you pass the literal value true or false will end up as with or without followed by the preposition. Multiple with clauses or without clauses can be joined using and. This looks quite silly when the labels are prepositions, but here goes:

on stopping by woods on aSnowyEvening
        if woods and aSnowyEvening then
                return "lovely, dark and deep"
        else
                return "ugly and shallow"
        end if
end stopping
display dialog (stopping with on and by)
display dialog (stopping with by without on)

It is a runtime error for the call to omit any defined prepositional parameter. It is not an error to toss some extra prepositional parameters into the call, but they are ignored by the handler.

The real value of labeled parameter syntax emerges when targeting scriptable applications. Application commands, unlike handlers in your scripts, can define their own labels beyond the list of prepositions in Table 8-1. For an example, see the dictionary listing for FrameMaker's find command under Section 3.2.3, where the parameters are called with value, with properties, in, and using. It would be nice if handlers could do this too, but they can't. The closest they come is named parameters, described in the next section.

8.3.4 Named Parameters

Named parameters are a way to take advantage of labeled parameters while escaping the circumscribed repertoire of built-in prepositions. You get to make up your own names, though of course you mustn't use a word that's already reserved by the language for something else.

You may combine named parameters with prepositional parameters; if you do, the named parameters must come after the prepositional parameters.

The syntax for defining named parameters is this:

on handlerName ... given paramName1:varName1, paramName2:varName2, ...

The first ellipsis in that syntax schema is the definition for the prepositional parameters, if there are any. The second ellipsis is for as many further named parameters as you like.

The call works just the same way: the keyword given must appear, it must appear after all prepositional parameters if there are any, and the same colon-based syntax is used:

handlerName ... given paramName1:value1, paramName2:value2, ...

As with prepositional parameters, boolean values can be passed using with or without and the parameter name, and for these there is no need to say given. Again, AppleScript will use this syntax for you if you pass the literal value true or false.

Here are some examples of handlers with named parameters, and calls to them. For the sake of simplicity, none of these handlers also take prepositional parameters.

on sum given theOne:x, theOther:y
        return x + y
end sum
display dialog (sum given theOther:2, theOne:3)

on scout given loyal:loyal, trustworthy:trustworthy
        if loyal and trustworthy then
                return "eagle"
        else
                return "sparrow"
        end if
end scout
display dialog (scout with loyal and trustworthy)

The first example demonstrates that the order of parameters is free. The second example demonstrates the use of with, and also shows that the parameter labels can be the same as the local variable names.