KEYWORD-COMMANDS.html -- ACL2 Version 6.3

## KEYWORD-COMMANDS

how keyword commands are processed

    Major Section:  MISCELLANEOUS

    Examples:
    user type-in                 form evaluated
    :pc 5                        (ACL2::PC '5)
    :pcs app rev                 (ACL2::PCS 'app 'rev)
    :length (1 2 3)              (ACL2::LENGTH '(1 2 3))
    :quit                        (ACL2::QUIT) ; Note: avoid optional argument

When a keyword, `:key`, is read as a command, ACL2 determines whether the symbol with the same name in the `"ACL2"` package, `acl2::key`, is a function or simple macro of n arguments. If so, ACL2 reads `n` more objects, `obj1`, ..., `objn`, and then acts as though it had read the following form (for a given `key`):

    (ACL2::key 'obj1 ... 'objn)

Thus, by using the keyword command hack you avoid typing the parentheses, the `"ACL2"` package name, and the quotation marks.

See ld-keyword-aliases for how to customize this behavior.

Note the generality of this hack. Any function or macro in the `"ACL2"` package can be so invoked, not just ``commands.'' Indeed, there is no such thing as a distinguished class of commands. Users may take advantage of the keyword command hack by defining functions and macros in the `"ACL2"` package.

The one caveat is that when the keyword hack is used to invoke a macro, only the required arguments for that macro are read before calling that macro: none of the `&optional`, `&rest`, `&body`, or `&key` arguments are read for that call. The macro is thus called with only its required arguments. The following log illustrates this caveat.

    ACL2 !>:set-iprint t

    ACL2 Query (:SET-IPRINT):  Action  (T, NIL, RESET, RESET-ENABLE, SAME,
    Q or ?):
    ACL2 Observation in SET-IPRINT:  Iprinting has been enabled.
    ACL2 !>

What happened? First, the command `:set-iprint` was read. Since the macro `set-iprint` has no required arguments, the ACL2 evaluator was then called on the form `(set-iprint)`, that is, calling the macro on no arguments. `Set-iprint` is defined to query the ACL2 user when its first argument is omitted. The log shows that query, which is set up to read the next form from the input stream. That form was available immediately: the form `t` that had been supplied by the user. So the query returned immediately and the `set-iprint` call was completed.