[Go to first, previous, next page;   contents;   index]

Chapter 23

kw.ss: Keyword Arguments

To load: (require (lib "kw.ss"))

The kw.ss library provides the lambda/kw and define/kw forms.

(lambda/kw formals body-expr ···1)      SYNTAX

Like lambda, but with optional and keyword-based argument processing. This form is similar to an extended version of Common Lisp procedure arguments. When used with plain variable names, lambda/kw expands to a plain lambda, so lambda/kw is suitable for a language module that will use it to replace lambda. This form uses MzScheme keyword values (see section 3.8 in PLT MzScheme: Language Manual) for its implementation.

In addition to lambda/kw, this library provides a define/kw form that is similar to the built-in define (see section 2.8.1 in PLT MzScheme: Language Manual), except that the formals as as in lambda/kw. Like define, this form can be used with nested parenthesis for curried functions (the MIT-style generalization of section 2.8.1 in PLT MzScheme: Language Manual).

The syntax of lambda/kw is the same as lambda, except for the list of formal argument specifications. These specifications can hold (zero or more) plain argument names, then a default section that begins after an #:optional marker, then a keyword section that is marked by #:keyword, and finally a section holding rest and ``rest-like'' arguments which are described below, together with argument processing flag directives. Each section is optional, but the order of the sections must be as listed.

More formally, the syntax is: 

(lambda/kw kw-formals body ...)

kw-formals is one of
  variable
  (variable ··· [#:optional optional-spec ···]
                   [#:key key-spec ···]
                   [rest/mode-spec ···])
  (variable ··· . variable)

optional-spec is one of
  variable
  (variable default-expr)

key-spec is one of
  variable
  (variable default-expr)
  (variable keyword default-expr)

rest/mode-spec is one of
  #:rest variable
  #:other-keys variable
  #:other-keys+body variable
  #:all-keys variable
  #:body kw-formals
  #:allow-other-keys
  #:forbid-other-keys
  #:allow-duplicate-keys
  #:forbid-duplicate-keys
  #:allow-body
  #:forbid-body
  #:allow-anything
  #:forbid-anything

Of course, all bound identifiers must be unique. The following section describes each part of a kw-formals.

23.1  Required Arguments

Required arguments correspond to identifiers that appear before any keyword marker in the argument list. They determine the minimum arity of the resulting procedure.

23.2  Optional Arguments

The optional-arguments section follows an #:optional marker in the kw-formals. Each optional argument can take the form of a parenthesized variable and a default expression; the latter is used if a value is not given at the call site. The default expression can be omitted (along with the parentheses), in which case #f is the default.

The default expression's environment includes all previous arguments, both required and optional names. With k optionals after n required arguments, and with no keyword arguments or rest-like arguments, the resulting procedure has an arity '(n + k ... n + 1 n). Adding keywords or rest-like arguments makes the first arity (make-arity-at-least n + k).

The treatment of optionals is efficient, with an important implication: default expressions appear multiple times in the resulting case-lambda. For example, the default expression for the last optional argument appears k - 1 times (but no expression is ever evaluated more than in a function call). This expansion risks exponential blow-up is if lambda/kw is used in a default expression of a lambda/kw, etc. The bottom line, however, is that lambda/kw is a sensible choice, due to its enhanced efficiency, even when you need only optional arguments.

23.3  Keyword Arguments

A keyword argument section is marked by a #:key. If it is used with optional arguments, then the keyword specifications must follow the optional arguments (which mirrors the use in call sites; it is not possible to specify keyword arguments in a call without giving values for all optional arguments first).

Like optional arguments, each keyword argument is specified as a parenthesized variable name and a default expression. The default expression can be omitted (with the parentheses), in which case #f is the default value. The keyword used at a call site for the corresponding variable has the same name as the variable; a third form of keyword arguments has three parts -- a variable name, a keyword, and a default expression -- to allow the name of the locally bound variable to differ from the keyword used at call sites.

When calling a function with keyword arguments, the required argument (and all optional arguments, if specified) must be followed by an even number of arguments, where the first argument is a keyword that determines which variable should get the following value, etc. If the same keyword appears multiple times (and if multiple instances of the keyword are allowed; see section 23.6), the value after the first occurrence is used for the variable: 

((lambda/kw (#:key x [y 2] [z #:zz 3] #:allow-duplicate-keys) (list x y z))
 #:x 'x #:zz 'z #:x "foo")
 => '(x 2 z)

Default expressions are evaluated only for keyword arguments that do not receive a value for a particular call. Like optional arguments, each default expression is evaluated in an environment that includes all previous bindings (required, optional, and keywords that were specified on its left).

See section 23.6 for information on when duplicate or unknown keywords are allowed at a call site.

23.4  Rest and Rest-like Arguments

The last kw-formals section -- after the required, optional, and keyword arguments -- may contain specifications for rest-like arguments and/or mode keywords. Up to five rest-like arguments can be declared, each with a variable to bind:

In the following example, all rest-like arguments are used and have different bindings: 

((lambda/kw (#:key x y
             #:rest r
             #:other-keys+body rk
             #:all-keys ak
             #:other-keys ok
             #:body b)
   (list r rk b ak ok))
 #:z 1 #:x 2 2 3 4)
 =>
  '((#:z 1 #:x 2 2 3 4)
    (#:z 1 2 3 4)
    (2 3 4)
    (#:z 1 #:x 2)
    (#:z 1))

Note that the following invariants always hold:

To write a function that uses a few keyword argument values, and that also calls another function with the same list of arguments (including all keywords), use #:other-keys (or #:other-keys+body). The Common Lisp approach is to specify :allow-other-keys, so that the second function call will not cause an error due to unknown keywords, but the :allow-other-keys approach risks confusing the two layers of keywords.

23.5  Body Argument

The most notable divergence from Common Lisp in lambda/kw is the #:body argument, and the fact that it is possible at a call site to pass plain values after keyword-value pairs. The #:body binding is useful for function calls that use keyword-value pairs as sort of an attribute list before the actual arguments to the function. For example, consider a function that accepts any number of numeric arguments and will apply a function to them, but the function can be specified as an optional keyword argument. It is easily implemented with a #:body argument: 

(define/kw (mathop #:key [op +] #:body b)
  (apply op b))
(mathop 1 2 3) ; => 6
(mathop #:op max 1 2 3) ; => 3

(Note that the first body value cannot itself be a keyword.)

A #:body declaration works as an arbitrary kw-formals, not just a single variable like b in the above example. For example, to make the above mathop work only on three arguments that follow the keyword, use (x y z) instead of b: 

(define/kw (mathop #:key [op +] #:body (x y z))
  (op x y z))

In general, #:body handling is compiled to a sub procedure using lambda/kw, so that a procedure can use more then one level of keyword arguments. For example: 

(define/kw (mathop #:key [op +]
                   #:body (x y z #:key [convert values]))
  (op (convert x) (convert y) (convert z)))
(mathop #:op * 2 4 6 #:convert exact->inexact) --> 48.0

Obviously, nested keyword arguments works only when non-keyword arguments separate the sets.

Run-time errors during such calls report a mismatch for a function with a name that is based on the original name plus a ~body suffix: 

(mathop #:op * 2 4)
 => procedure mathop body: expects at least 3 arguments, given 2: 2 4

23.6  Mode Keywords

Finally, the argument list of a lambda/kw can contain keywords that serve as mode flags to control error reporting.

These mode markers are rarely needed, because the default modes are determined by the declared rest-like arguments:

Here's an alternate specification, which maps rest-like arguments to the behavior that they imply:

23.7  Property Lists

(keyword-get args keyword [not-found-thunk])      PROCEDURE

Searches a list of keyword arguments (a ``property list'' or ``plist'' in Lisp jargon) for the given keyword, and returns the associated value. It is the facility that is used by lambda/kw to search for keyword values.

The args list is scanned from left to right, if the keyword is found, then the next value is returned. If the keyword was not found, then the not-found-thunk value is used to produce a value by applying it. If the keyword was not found, and not-found-thunk is not given, #f is returned. (No exception is raised if the args list is imbalanced, and the search stops at a non-keyword value.)

[Go to first, previous, next page;   contents;   index]