Structural Informatics Group (SIG) logo
Home | Projects | Demos | Downloads | Publications | Local Info | About Us | New site
Go to the first, previous, next, last section, table of contents.

&key

&key

type: keyword
location: built-in
source file: xleval.c
Common LISP compatible: yes
supported on: all machines

SYNTAX

&key <key-arg> ...
&key ( <key-arg> [  [  ] ] ) ...
&key ( ( <key-symbol>  ) [  [  ] ] ) ...
        <key-arg>       -       keyword argument
        <key-symbol>    -       keyword argument symbol
        <key-value>     -       keyword argument initialization
        <exist-symbol>  -       keyword argument existence symbol

DESCRIPTION

In XLISP, there are several times that you define a formal argument list for a body of code (like DEFUN, DEFMACRO, :ANSWER and LAMBDA). All of the formal arguments that are defined are required to appear in the invocation of the defined function or operation. If there are any &OPTIONAL arguments defined, they will be filled in order. There are other optional arguments called KEYWORD arguments. These arguments are not position dependent but can be specified in any order by a preceding keyword (a symbol with a leading ':'). If there is no <key-symbol> specified in the argument list, the keyword will be constructed from the <key-arg> name by adding a leading ':'. (For example a <key-arg> of FURTER will generate a keyword symbol of :FURTER).

Like the &OPTIONAL arguments, there can be initialization values provided via the <key-value> argument. If there is no <key-value> argument and no value is provided by the function call, the <key-arg> value will be NIL.

The <exist-symbol>, if it is specified, will contain a T if the <key-arg> value was supplied by the function call and a NIL if it was not supplied by the function call. This <exist-symbol> allows the programmer to test for an argument's existence. At the end of the function or operation execution, these local symbols and their values are are removed.

EXAMPLES

(defun foo                              ; define function FOO
  (a &key b c )                         ;   with some optional args
  (print a) (print b) (print c))        ;
(foo)                                   ; error: too few arguments 
(foo 1)                                 ; prints 1 NIL NIL
(foo 1 2)                               ; prints 1 NIL NIL
(foo 1 :b 2 :c 3)                       ; prints 1 2 3 
(foo 1 :c 3 :b 2)                       ; prints 1 2 3 
(foo 1 :b 3 :b 2)                       ; prints 1 3 NIL
                                        ;
(defun fee                              ; define function FEE
  (a &key (b 9 b-passed) )              ;   with some optional args
  (print a) (print b)                   ;
  (if b-passed (print "b was passed")   ;
               (print "b not passed"))) ;
(fee)                                   ; error: too few arguments
(fee 1)                                 ; prints 1 9 "b not passed"
(fee 1 2)                               ; prints 1 9 "b not passed"
(fee 1 :b 2)                            ; prints 1 2 "b was passed"
                                        ;
(defun fi                               ; define function FI
  (a &key ((:mykey b) 9 b-passed) )     ;   with some optional args
  (print a) (print b)                   ;
  (if b-passed (print "b was passed")   ;
               (print "b not passed"))) ;
(fi)                                    ; error: too few arguments
(fi 1)                                  ; prints 1 9 "b not passed"
(fi 1 2)                                ; prints 1 9 "b not passed"
(fi 1 :b 2)                             ; prints 1 9 "b not passed"
(fi 1 :mykey 2)                         ; prints 1 2 "b was passed"

NOTE: There is a &ALLOW-OTHER-KEYS keyword in XLISP and Common LISP. In the case of XLISP, this keyword is extraneous since the default for keyword arguments is to allow other keys (without errors).


Go to the first, previous, next, last section, table of contents.