12.2.3 Parameter lists

A function's parameter list is specified in the function definition. (If Dylan implicitly defines a function, such as the getter and setter functions for a slot, Dylan also defines the parameter list for that function.) In a function definition, the parameter list follows the function name and consists of zero or more parameter specifications, separated by commas and enclosed in parentheses. A parameter list can have three kinds of parameters:

1. Required parameters specify required arguments, or arguments that must be supplied when the function is called. All required parameters appear before other kinds of parameters in the parameter list.

2. A function can have at most one rest parameter, which allows the function to accept a variable number of arguments. The rest parameter is identified in the parameter list by #rest followed by the name of the parameter. When the function is called, all arguments that follow the required arguments are put into a sequence. This sequence is the initial value of the rest parameter in the function body.

3. Keyword parameters specify optional keyword arguments. In the parameter list, keyword parameters are identified by #key followed by the names of the parameters (and possibly by other information). Keyword parameters must follow all required parameters and the rest parameter (if any). When the function is called, the caller can supply any or none of the specified keyword arguments, in any order, after supplying all required arguments. The caller supplies each keyword argument as a symbol (usually in the form of the parameter name followed by a colon), followed by the argument value. This argument is the initial value of the corresponding keyword parameter in the function body.

The specification for each parameter in the parameter list includes the name of the parameter. In addition, a required parameter (or, for a method, a keyword parameter) can be specialized to correspond to an argument of a given type. The type specializer follows the parameter name and is identified by :: followed by a type. When the function is called, the argument that corresponds to the parameter must be of the specified type, or Dylan signals an error. The default argument type is <object>.

The specification for a keyword parameter can have two additional pieces of information:

1. It may include a keyword for the caller to use in its argument list, if this keyword must be different from the parameter name. The keyword precedes the parameter name in the parameter list.

2. It may include a default value for the keyword argument, which is used if the caller does not supply that argument. The default expression appears at the end of the parameter specification, followed by =. If no default expression is supplied and the caller does not supply the keyword argument, the argument's value is #f.

The following example shows how we could use a rest parameter to implement a function to sum an arbitrary number of values:

// Sum one or more values
define method sum (value, #rest more-values)
  for (next in more-values)
    value := value + next;
  end for;
  value;
end method sum;
? sum(3);
3
? sum(1, 2, 3, 4, 5);
15

In the preceding example, the for iteration statement performs the addition once for every element of more-values.

The following example shows how we could use keyword parameters in defining a method similar to encode-total-seconds:

// Convert days, hours, minutes, and seconds to seconds.
// Named (keyword) arguments are optional
define method convert-to-seconds 
    (#key hours :: <integer> = 0, minutes :: <integer> = 0,
     seconds :: <integer> = 0) => (seconds :: <integer>)
  ((hours * 60) + minutes) * 60 + seconds;
end method convert-to-seconds;
? convert-to-seconds(minutes: 3, seconds: 9);
189
? convert-to-seconds(minutes: 1, hours: 2);
7260

Note from the preceding example that we can supply keyword arguments in any order. Note also that all keyword arguments are optional; however, if we try to call a function with a keyword argument that the function does not accept — such as days:, in this example — Dylan signals an error. For more information on function calls and keyword arguments, see Section 12.2.7, page 178.

Following are additional features and restrictions of keyword arguments:

• If a parameter list ends with #all-keys following #key, the function accepts (but ignores) any keyword argument. A parameter list can have specific keyword parameters and also end with #all-keys. In this case, the function accepts any keyword argument, and also has local variables whose values are the keyword-argument values (or their defaults) that correspond to the keyword parameters.

• If the parameter list of a method contains both #rest and #key, the sequence that is the value of the rest parameter contains alternating symbols and argument values representing the keyword arguments passed to the function. In this case, all optional arguments must be keyword arguments. A generic function's parameter list can have either #rest or #key, but cannot have both.

• Keyword parameters for a generic function cannot be specialized.

The restrictions on a generic function's parameter list have to do with parameter-list congruency and keyword-argument checking in generic function calls. For more information, see Sections 12.2.5 and 12.2.7.