Subroutine Call, Labeled Parameters (AS Language)

Inside Macintosh: AppleScript Language Guide / Part 2 - AppleScript Language Reference

Chapter 8 - Handlers / Subroutine Definitions and Calls

Subroutine Call, Labeled Parameters
A subroutine call for a subroutine with labeled parameters lists parameters other than the direct parameter in any order, using the labels in the subroutine definition to identify the parameter values.

SYNTAX
subroutineName                                        �
   [ [ of | in ] directParameter ]                    �
   [ [ subroutineParamLabel parameterValue ]          �
      | [ with labelForTrueParam [, labelForTrueParam ]...�
         [ ( and | or | , ) labelForTrueParam ] ]     �
      | [ without labelForFalseParam [, labelForFalseParam ]...]�
         [ ( and | or | , ) labelForFalseParam ] ]    �
      | [ given label:parameterValue                  �
         [, label:parameterValue ]...] ]...
where
subroutineName (an identifier) is the name of the subroutine.
directParameter is the direct parameter, if one is included in the subroutine definition. It can be any valid expression. As in application commands, the direct parameter must be first if it is included at all.
subroutineParamLabel is one of the following labels used in the definition of
the subroutine: above, against, apart from, around, aside from, at, below, beneath, beside, between, by, for, from, instead of, into, on, onto, out of, over, thru (or through), under.
parameterValue is the value of a parameter, which can be any valid expression.
labelForTrueParam is the label for a Boolean parameter whose value is true. You use this form in With clauses; because the value true is implied by the word With, you provide only the label, not the value. (For an example of how to use a With clause, see page 233.) If you use or or a comma instead of and with the last parameter of a with clause, AppleScript changes the of or the comma to and during compilation.
labelForFalseParam is the label for a Boolean parameter whose value is false. You use this form in Without clauses; because the value false is implied
by the word Without, you provide only the label, not the value. If you use
or or a comma instead of and with the last parameter of a without clause, AppleScript changes the or or the comma to and during compilation.
label is any parameter label used in the definition of the subroutine that is not among the labels for subroutineParamLabel. You must use the special label given to specify these parameters. (For an example, see "Examples" later in this section.)
If you use or or a comma instead of and with the last parameter of a with clause, AppleScript changes the or or the comma to and during compiling.

NOTES
A subroutine call must include all the parameters specified in the subroutine definition. There is no way to specify optional parameters.
When calling a subroutine, you can list any parameter-value pairs except
the direct parameter after the label given, not just the parameters that were specified that way in the subroutine definition. For example, the following
two calls to the searchFiles subroutine described in the next section are interchangeable.
searchFiles of {"March Expenses", "April Expenses"} for �
   "Le Chateau"
searchFiles of {"March Expenses", "April Expenses"} �
   given for:"Le Chateau"
With the exception of the direct parameter, which must directly follow the subroutine name, labeled parameters can appear in any order. This includes parameters listed in Given, With, and Without clauses. Furthermore, you can include any number of Given, With, and Without clauses in a subroutine call.