% -*- Mode: LaTeX; Package: CLIM-USER -*-

\chapter {Command Processing}
\label {command-processor}

\section {Commands}

A \concept{command} is an object that represents a user interaction.  Commands
are stored as a cons of the command name and a list of the command's arguments.
All positional arguments will be represented in the command object, but only
those keywords arguments that were explicitly supplied by the user will be
included.  When the first element of the cons is \cl{apply}'ed to the rest of
the cons, the code representing that interaction is executed.

A \concept{partial command} is a command object with the value of
\cl{*unsupplied-argument-marker*} in place of any argument that needs to be
filled in.

Every command is named by \concept{command name}, which is a symbol.  To avoid
collisions among command names, application frames should reside in their own
package; for example, the \cl{com-show-chart} command might be defined for both
a spreadsheet and a medical application.

\Defun {command-name} {command}

Given a command object \arg{command}, returns the command name.

\Defun {command-arguments} {command}

Given a command object \arg{command}, returns the command's arguments.

\Defun {partial-command-p} {command}

Returns \term{true} if the \arg{command} is a partial command, that is, has any
occurrences of \cl{*unsupplied-argument-marker*} in it.  Otherwise,
\cl{partial-command-p} returns \term{false}.


\def\DefineFrameCommand{\cl{define-{\it frame}-command}}


\Defmacro {define-command} {name-and-options arguments \body body}

This is the most basic command-defining form.  Usually, the programmer will not
use \cl{define-command} directly, but will instead use a \DefineFrameCommand\ 
form that is automatically generated by \cl{define-application-frame}.
\DefineFrameCommand\  adds the command to the application frame's command table.
By default, \cl{define-command} does not add the command to any command table.

\arg{name-and-options} is either a command name, or a cons of the command name
and a list of keyword-value pairs.

\cl{define-command} defines two functions.  The first function has the same name
as the command name, and implements the body of the command.  It takes as
arguments the arguments to the command as specified by the \cl{define-command}
form, as required and keyword arguments.

The name of the other function defined by \cl{define-command} is unspecified.
It implements the code used by the command processor for parsing and returning
the command's arguments.

The keywords from \arg{name-and-options} can be:

\begin{itemize}
\item \cl{:command-table} \arg{command-table-name}, where
\arg{command-table-name} either names a command table to which the command will
be added, or is \cl{nil} (the default) to indicate that the command should not
be added to any command table.  If the command table does not exist, the
\cl{command-table-not-found} error will be signalled.  This keyword is only
accepted by \cl{define-command}, not by \DefineFrameCommand.

\item \cl{:name} \arg{string}, where \arg{string} is a string that will be used
as the command-line name for the command for keyboard interactions in the
command table specified by the \cl{:command-table} option.  The default is
\cl{nil}, meaning that the command will not be available via command-line
interactions.  If \arg{string} is \cl{t}, then the command-line name will be
generated automatically, as described in \cl{add-command-to-command-table}.

\item \cl{:menu} \arg{menu-item}, where \arg{menu-item} will be an item in the
menu of the command table specified by the \cl{:command-table} option.  The
default is \cl{nil}, meaning that the command will not be available via menu
interactions.  If \arg{menu-item} is a string, then that string will be used as
the menu name.  If \arg{menu-item} is \cl{t}, then the menu name will be
generated automatically, as described in \cl{add-command-to-command-table}.
Otherwise, \arg{menu-item} must be a cons of the form \cl{(\arg{string} .
\arg{menu-options})}, where \arg{string} is the menu name and \arg{menu-options}
consists of keyword-value pairs.  The valid keywords are \cl{:after},
\cl{:documentation}, and \cl{:text-style}, which are interpreted as for
\cl{add-menu-item-to-command-table}.

\item \cl{:keystroke} \arg{gesture}, where \arg{gesture} is a keyboard gesture
name that specifies a keystroke accelerator to use for this command in the
command table specified by the \cl{:command-table} option.  The default is
\cl{nil}, meaning that there is no keystroke accelerator.
\end{itemize}

The \cl{:name}, \cl{:menu-item}, and \cl{:keystroke} options are only allowed if
the \cl{:command-table} option was supplied explicitly or implicitly, as in
\DefineFrameCommand.

\arg{arguments} is a list consisting of argument descriptions.  A single occurrence of
the symbol \cl{\key} may appear in \arg{arguments} to separate required command arguments
from keyword arguments.  Each argument description consists of a parameter
variable, followed by a presentation type specifier, followed by keyword-value
pairs.  The keywords can be:

\begin{itemize}
\item \cl{:default} \arg{value}, where \arg{value} is the default that should
be used for the argument, as for \cl{accept}.

\item \cl{:default-type} is the same as for \cl{accept}.

\item \cl{:display-default} is the same as for \cl{accept}.

\item \cl{:mentioned-default} \arg{value}, where \arg{value} is the default
that should be used for the argument when a keyword is explicitly supplied via
the command-line processor, but no value is supplied for it.
\cl{:mentioned-default} is only allowed on keyword arguments.

\item \cl{:prompt} \arg{string}, where \arg{string} is a prompt to print out
during command-line parsing, as for \cl{accept}.

\item \cl{:documentation} \arg{string}, where \arg{string} is a documentation
string that describes what the argument is.

\item \cl{:when} \arg{form}.  \arg{form} is evaluated in a scope where the
parameter variables for the required parameters are bound, and if the result is
\cl{nil}, the keyword argument is not available.  \cl{:when} is only allowed on
keyword arguments, and \arg{form} cannot use the values of other keyword
arguments.

\item \cl{:gesture} \arg{gesture}, where \arg{gesture} is either a pointer
gesture name or a list of a pointer gesture name followed by keyword-value
pairs.  When a gesture is supplied, a presentation translator will be defined
that translator that translates from the argument to a command.  The
keyword-value pairs are used as options for the translator.  Valid keywords are
\cl{:tester}, \cl{:menu}, \cl{:priority}, \cl{:echo}, \cl{:documentation}, and
\cl{:pointer-documentation}.  The default for \arg{gesture} is \cl{nil}, meaning
no translator will be written.  \cl{:gesture} is only allowed when the
\cl{:command-table} option was supplied to the command-defining form.
\end{itemize}

\arg{body} implements the body of the command.  It has lexical access to all of
the commands arguments.  If the body of the command needs access to the
application frame itself, it should use \cl{*application-frame*}.  The returned
values of body are ignored.  \arg{body} may have zero or more declarations as
its first forms. 

\cl{define-command} must arrange for the function that implements the body of
the command to get the proper values for unsupplied keyword arguments.

\arg{name-and-options} and \arg{body} are not evaluated.  In the argument
descriptions, the parameter variable name is not evaluated, and everything else
is evaluated at run-time when argument parsing reaches that argument, except
that the value for \cl{:when} is evaluated when parsing reaches the keyword
arguments, and \cl{:gesture} isn't evaluated at all.


\section {Command Tables}

There are four main styles of interaction: keyboard interaction using a command-
line processor, keyboard interaction using keystroke accelerators, mouse
interaction via command menus, and mouse interaction via translators.  A
\concept{command table} is an object that serves to mediate between an
application frame, a set of commands, and the four interaction styles.  Command
tables contain the following information:

\begin{itemize}
\item The name of the command table, which is a symbol.

\item An ordered list of command tables to inherit from.

\item The set of commands that are present in this command table.

\item A table that associates command-line names to command names (used to
support command-line processor interactions).

\item A set of presentation translators, defined via
\cl{define-presentation-translator} and
\cl{define-presentation-to-command-translator}.

\item A table that associates keyboard gesture names to menu items (used to
support keystroke accelerator interactions).  The keystroke accelerator table
does not contain any items inherited from superior command tables.

\item A menu that associates menu names to menu items (used to support
interaction via command menus).  The menu items can invoke commands or
sub-menus.  The menu does not contain any items inherited from superior command
tables.
\end{itemize}

We say that a command is \concept{present} in a command table when it has been
added to that command table.  We say that a command is \concept{accessible} in a
command table when it is present in that command table or is present in any of
the command tables from which that command table inherits.


\Defprotoclass {command-table}

The protocol class that corresponds to command tables.
\IfYouWantClass {a} {command table} {command-table}
\Mutable

\Defun {command-table-p} {object}

Returns \term{true} if \arg{object} is a \term{command table}, otherwise returns
\term{false}.

\Defclass {standard-command-table}

The instantiable class that implements command tables, a subclass of
\cl{command-table}.  \cl{make-command-table} returns objects that are members of
this class.

\issue {SWM} {Do we really want to advertise these classes, since all the
functions below are vanilla functions instead of generic functions?  Or should
we make those functions be generic functions?}


\Defgeneric {command-table-name} {command-table}

Returns the name of the \term{command table} \arg{command-table}.

\Defgeneric {command-table-inherit-from} {command-table}

Returns a list of the command tables from which the \term{command table}
\arg{command-table} inherits.
\ReadOnly


\Defmacro {define-command-table} {name \key inherit-from menu}

Defines a command table whose name is the symbol \arg{name}.  The new command
table inherits from all of the command tables specified by \arg{inherit-from},
which is a list of \concept{command table designators} (that is, either a command
table or a symbol that names a command table).  The inheritance is done by union
with shadowing.  If no inheritance is specified, the command table will be made
to inherit from CLIM's global command table.  (This command table contains such
things as the ``menu'' translator that is associated with the right-hand button
on pointers.)

\arg{menu} can be used to specify a menu for the command table.  The value of
\arg{menu} is a list of clauses.  Each clause is a list with the syntax
\cl{(\arg{string} \arg{type} \arg{value} \key \arg{keystroke}
\arg{documentation} \arg{text-style})}, where \arg{string}, \arg{type},
\arg{value}, \arg{keystroke}, \arg{documentation}, and \arg{text-style} are as
for \cl{add-menu-item-to-command-table}.

If the command table named by \arg{name} already exists,
\cl{define-command-table} will modify the existing command table to have the new
value for \arg{inherit-from} and \arg{menu}, and leaves the other attributes for
the existing command table alone.

None of \cl{define-command-table}'s arguments are evaluated.


\Defun {make-command-table} {name \key inherit-from menu (errorp t)}

Creates a command table named \arg{name}.  \arg{inherit-from} and \arg{menu} are
the same as for \cl{define-command-table}.  \cl{make-command-table} does not
implicitly include CLIM's global command table in the inheritance list for the
new command table.  If the command table already exists and \arg{errorp} is
\term{true}, the \cl{command-table-already-exists} error will be signalled.  If
the command table already exists and \arg{errorp} is \term{false}, then the old
command table will be discarded.  The returned value is the command table.


\Defun {find-command-table} {name \key (errorp t)}

Returns the command table named by \arg{name}.  If \arg{name} is itself a
command table, it is returned.  If the command table is not found and
\arg{errorp} is \term{true}, the \cl{command-table-not-found} error will be
signalled.


\Defcondition {command-table-error}

The class that is the superclass of the following four conditions.  This class
is a subclass of \cl{error}.

\Defcondition {command-table-not-found}

The error that is signalled by such functions as \cl{find-command-table} when a
command table is not found.

\Defcondition {command-table-already-exists}

The error that is signalled when the programmer tries to create a command table
that already exists.

\Defcondition {command-not-present}

The error that is signalled when a command is not present in a command table.

\Defcondition {command-not-accessible}

The error that is signalled when a command is not accessible in a command table.

\Defcondition {command-already-present}

The error that is signalled when a function tries to add a command to a command
table when it is already present in the command table.


\Defun {add-command-to-command-table} {command-name command-table 
                                       \key name menu keystroke (errorp t)}

Adds the command named by \arg{command-name} to the command table specified by
the \term{command table designator} \arg{command-table}.

\arg{name} is the command-line name for the command, and can be \cl{nil},
\cl{t}, or a string.  When it is \cl{nil}, the command will not be available via
command-line interactions.  When it is a string, that string is the command-line
name for the command.  When it is \cl{t}, the command-line name is generated
automatically.  (The automatically generated name consists of the command's name
with the hyphens replaced by spaces, and the words capitalized; furthermore, if
there is a prefix of ``COM-'', the prefix is removed.  For example, if the
command name is \cl{com-show-file}, the command-line name will be ``Show
File''.)  For the purposes of command-line name lookup, the character case and
style of \arg{name} are ignored.

\arg{menu} is a menu item for the command, and can be \cl{nil}, \cl{t}, a
string, or a cons.  When it is \cl{nil}, the command will not be available via
menus.  When it is a string, the string will be used as the menu name.  When it
is \cl{t}, an automatically generate menu name will be used.  When it is a cons
of the form \cl{(\arg{string} . \arg{menu-options})}, \arg{string} is the menu
name and \arg{menu-options} consists of keyword-value pairs.  The valid keywords
are \cl{:after}, \cl{:documentation}, and \cl{:text-style}, which are
interpreted as for \cl{add-menu-item-to-command-table}.

The value for \arg{keystroke} is either keyboard gesture name or \cl{nil}.  When
it is a gesture name, it is the keystroke accelerator for the command; otherwise
the command will not be available via keystroke accelerators.

If the command is already present in the command table and \arg{errorp} is
\term{true}, the \cl{command-already-present} error will be signalled.  When the
command is already present in the command table and \arg{errorp} is
\term{false}, then the old command-line name, menu, and keystroke accelerator
will first be removed from the command table.


\Defun {remove-command-from-command-table} {command-name command-table \key (errorp t)}

Removes the command named by \arg{command-name} from the command table specified
by the \term{command table designator} \arg{command-table}.

If the command is not present in the command table and \arg{errorp} is
\term{true}, the \cl{command-not-present} error will be signalled.


\Defmacro {do-command-table-inheritance}  {(command-table-var command-table) \body body}

Successively executes \arg{body} with \arg{command-table-var} bound first to
the command table specified by the \term{command table designator}
\arg{command-table}, and then (recursively) to all of the command tables from
which \arg{command-table} inherits.

The \arg{command-table-var} argument is not evaluated.  \arg{body} may have zero
or more declarations as its first forms. 

\Defun {map-over-command-table-commands} {function command-table \key (inherited t)}

Applies \arg{function} to all of the commands accessible in the command table
specified by the \term{command table designator} \arg{command-table}.
\arg{function} must be a function that takes a single argument, the command
name; it has dynamic extent.

If \arg{inherited} is \term{false}, this applies \arg{function} only to
those commands present in \arg{command-table}, that is, it does not map over
any inherited command tables.  If \arg{inherited} is \term{true}, then the
inherited command tables are traversed in the same order as for
\cl{do-command-table-inheritance}.

\Defun {map-over-command-table-names} {function command-table \key (inherited t)}

Applies \arg{function} to all of the command-line name accessible in the
command table specified by the \term{command table designator}
\arg{command-table}.  \arg{function} must be a function of two arguments,
the command-line name and the command name; it has dynamic extent.

If \arg{inherited} is \term{false}, this applies \arg{function} only to
those command-line names present in \arg{command-table}, that is, it does
not map over any inherited command tables.  If \arg{inherited} is
\term{true}, then the inherited command tables are traversed in the same
order as for \cl{do-command-table-inheritance}.


\Defun {command-present-in-command-table-p} {command-name command-table}

Returns \term{true} if the command named by \arg{command-name} is present in
the command table specified by the \term{command table designator}
\arg{command-table}, otherwise returns \term{false}.

\Defun {command-accessible-in-command-table-p} {command-name command-table}

If the command named by \arg{command-name} is not accessible in the command
table specified by the \term{command table designator} \arg{command-table}, then
this function returns \cl{nil}.  Otherwise, it returns the command table in
which the command was found.


\Defun {find-command-from-command-line-name} {name command-table \key (errorp t)}

Given a command-line name \arg{name} and a command table, returns two values,
the command name and the command table in which the command was found.  If the
command is not accessible in \arg{command-table} and \arg{errorp} is
\term{true}, the \cl{command-not-accessible} error will be signalled.
\arg{command-table} is a \term{command table designator}.

\cl{find-command-from-command-line-name} ignores character case and style.

\Defun {command-line-name-for-command} {command-name command-table \key (errorp t)}

Returns the command-line name for \arg{command-name} as it is installed in
\arg{command-table}.  \arg{command-table} is a \term{command table designator}.

If the command is not accessible in \arg{command-table} or has no command-line
name, then there are three possible results.  If \arg{errorp} is \cl{nil}, then
the returned value will be \cl{nil}.  If \arg{errorp} is \cl{:create}, then a
command-line name will be generated, as described in
\cl{add-command-to-command-table}.  Otherwise, if \arg{errorp} is \cl{t}, then
the \cl{command-not-accessible} error will be signalled.  The returned
command-line name should not be modified.

This is the inverse of \cl{find-command-from-command-line-name}.  It should be
implemented in such as way that it is fast, since it may be used by presentation
translators to produce pointer documentation.

\Defcommandtable {global-command-table}

The command table from which all other command tables inherit by default.
Programmers should not explicitly add anything to or remove anything from this
command table.The command table used by CLIM to store 

\Defcommandtable {user-command-table}

A command table that can be used by the programmer for any purpose.  CLIM does
not use it for anything, and its contents are completely undefined.


\section {Command Menus}

Each command table may have a menu consisting of an ordered sequence of menu
items.  The menu specifies a mapping from a menu name (the name displayed in the
menu) to a menu item.  The menu of an application frame's top-level command
table may be presented in a window system specific way, for example, as a menu
bar.

Menu items are stored as a list of the form
\cl{(\arg{type} \arg{value} . \arg{options})}, where \arg{type} and \arg{value}
are as in \cl{add-menu-item-to-command-table}, and \arg{options} is a list of
keyword-value pairs.  The allowable keywords are \cl{:documentation}, which is
used to supply optional pointer documention for the menu item, and
\cl{:text-style}, which is used to indicate what text style should be used for
this menu item when it is displayed in a command menu.

\cl{add-menu-item-to-command-table}, \cl{remove-menu-item-from-command-table},
and \cl{find-menu-item} ignore the character case and style of the menu item's
name when searching through the command table's menu.


\Defun {add-menu-item-to-command-table} {command-table string type value 
                                         \key documentation (after ':end) keystroke
                                              text-style (errorp t)}

Adds a menu item to \arg{command-table}'s menu.  \arg{string} is the name of the
menu item; its character case and style are ignored.  \arg{type} is either
\cl{:command}, \cl{:function}, \cl{:menu}, or \cl{:divider}.
\arg{command-table} is a \term{command table designator}.

\issue {SWM} {How do we make iconic command menus?  Probably another keyword...}

When \arg{type} is \cl{:command}, \arg{value} must be a command (a cons of a
command name followed by a list of the command's arguments), or a command name.
(When \arg{value} is a command name, it behaves as though a command with no
arguments was supplied.)  In the case where all of the command's required
arguments are supplied, clicking a a menu item invokes the command immediately.
Otherwise, the user will be prompted for the remaining required arguments.

When \arg{type} is \cl{:function}, \arg{value} must be function having
indefinite extent that, when called, returns a command.  The function is called
with two arguments, the gesture the user used to select the item (either a
keyboard or button press event) and a ``numeric argument''.

When \arg{type} is \cl{:menu}, this item indicates that a sub-menu will be
invoked, and so \arg{value} must be another command table or the name of
another command table.

When \arg{type} is \cl{:divider}, some sort of a dividing line is displayed in
the menu at that point.  If \arg{string} is supplied, it will be drawn as the
divider instead of a line.  If the look and feel provided by the underlying
window system has no corresponding concept, \cl{:divider} items may be ignored.
\arg{value} is ignored.

\arg{documentation} is a documentation string, which can be used as mouse
documentation for the menu item.

\arg{text-style} is either a text style spec or \cl{nil}.  It is used to
indicate that the menu item should be drawn with the supplied text style in
command menus.

\arg{after} must be either \cl{:start} (meaning to add the new item to the
beginning of the menu), \cl{:end} or \cl{nil} (meaning to add the new item to
the end of the menu), or a string naming an existing entry (meaning to add the
new item after that entry).  If \arg{after} is \cl{:sort}, then the item is
inserted in such as way as to maintain the menu in alphabetical order.

If \arg{keystroke} is supplied, the menu item will be added to the command
table's keystroke accelerator table.  The value of \arg{keystroke} must be a
keyboard gesture name.  This is exactly equivalent to calling
\cl{add-keystroke-to-command-table} with the arguments \arg{command-table},
\arg{keystroke}, \arg{type} and \arg{value}.  When \arg{keystroke} is supplied
and \arg{type} is \cl{:command} or \cl{:function}, typing a key on the keyboard
that matches to the keystroke accelerator gesture will invoke the command
specified by \arg{value}.  When \arg{type} is \cl{:menu}, the command will
continue to be read from the sub-menu indicated by \arg{value} in a window
system specific manner.

If the item named by \arg{string} is already present in the command table's menu
and \arg{errorp} is \term{true}, then the \cl{command-already-present} error
will be signalled.  When the item is already present in the command table's menu
and \arg{errorp} is \term{false}, the old item will first be removed from the
menu.  Note that the character case and style of \arg{string} are ignored when
searching the command table's menu.


\Defun {remove-menu-item-from-command-table} {command-table string \key (errorp t)}

Removes the item named by \arg{string} from \arg{command-table}'s menu.
\arg{command-table} is a \term{command table designator}.

If the menu item is not present in the command table's menu and \arg{errorp} is
\term{true}, then the \cl{command-not-present} error will be signalled.  Note
that the character case and style of \arg{string} are ignored when searching the
command table's menu.

\Defun {map-over-command-table-menu-items} {function command-table}

Applies \arg{function} to all of the menu items in \arg{command-table}'s menu.
\arg{function} must be a function of three arguments, the menu name, the
keystroke accelerator gesture (which will be \cl{nil} if there is none), and the
menu item; it has dynamic extent.  The menu items are mapped in the order
specified by \cl{add-menu-item-to-command-table}.  \arg{command-table} is a
\term{command table designator}.

\cl{map-over-command-table-menu-items} does not descend into sub-menus.  If the
programmer requires this behavior, he should examine the type of the menu item
to see if it is \cl{:menu}.


\Defun {find-menu-item} {menu-name command-table \key (errorp t)}

Given a menu name and a command table, returns two values, the menu item and the
command table in which it was found.  (Since menus are not inherited, the second
returned value will always be \arg{command-table}.)  \arg{command-table} is a
\term{command table designator}.
\ReadOnly

If the menu item is not present in \arg{command-table} and \arg{errorp} is
\term{true}, then the \cl{command-not-accessible} error will be signalled.  Note
that the character case and style of \arg{string} are ignored when searching the
command table's menu.


\Defun {command-menu-item-type} {menu-item}

Returns the type of the menu item \arg{menu-item}, for example, \cl{:menu} or
\cl{:command}.  If \arg{menu-item} is not a menu item, the result is
unspecified.

\Defun {command-menu-item-value} {menu-item}

Returns the value of the menu item \arg{menu-item}.  For example, if the type of
\arg{menu-item} is \cl{:command}, this will return a command or a command name.
If \arg{menu-item} is not a menu item, the result is unspecified.

\Defun {command-menu-item-options} {menu-item}

Returns a list of the options for the menu item \arg{menu-item}.  If
\arg{menu-item} is not a menu item, the result is unspecified.


\Defgeneric {display-command-table-menu} {command-table stream
                                          \key max-width max-height n-rows n-columns
                                               x-spacing y-spacing initial-spacing
                                               (cell-align-x \cl{:left}) (cell-align-y \cl{:top})
                                               (move-cursor \cl{t})}

Displays \arg{command-table}'s menu on \arg{stream}.  Implementations may choose
to use \cl{formatting-item-list} or may display the command table's menu in a
platform dependent manner, such as using the menu bar on a Macintosh.
\arg{command-table} is a \term{command table designator}.

\arg{max-width}, \arg{max-height}, \arg{n-rows}, \arg{n-columns},
\arg{x-spacing}, \arg{y-spacing}, \arg{initial-spacing}, \arg{cell-align-x},
\arg{cell-align-y}, and \arg{move-cursor} are as for \cl{formatting-item-list}.

\Defun {menu-choose-command-from-command-table} {command-table 
                                                 \key associated-window default-style label
                                                      cache unique-id id-test
                                                      cache-value cache-test}

Invokes a window system specific routine that displays a menu of commands from
\arg{command-table}'s menu, and allows the user to choose one of the commands.
\arg{command-table} is a \term{command table designator}.  The returned value is
a command object.  This may invoke itself recursively when there are sub-menus.

\arg{associated-window}, \arg{default-style}, \arg{label}, \arg{cache},
\arg{unique-id}, \arg{id-test}, \arg{cache-value}, and \arg{cache-test} are as
for \cl{menu-choose}.

\issue {SWM} {Should this be generic on application frames?}


\section {Keystroke Accelerators}

Each command table may have a mapping from keystroke accelerator gesture names
to menu items.  When a user types a key on the keyboard that corresponds to the
gesture for keystroke accelerator, the menu item will be invoked.  Note that
menu items are shared among the command table's menu and the accelerator table.
There are several reasons for this.  One is that it is common to have menus
display the keystroke associated with a particular item, if there is one.

Note that, despite the fact the keystroke accelerators are specified using
keyboard gesture names rather than characters, the conventions for typed
characters vary widely from one platform to another.  Therefore the programmer
must be careful in choosing keystroke accelerators.  Some sort of per-platform
conditionalization is to be expected.


\Defun {add-keystroke-to-command-table} {command-table gesture type value 
                                         \key documentation (errorp t)} 

Adds a menu item to \arg{command-table}'s keystroke accelerator table.
\arg{gesture} is a keyboard gesture name to be used as the accelerator.
\arg{type} and \arg{value} are as in \cl{add-menu-item-to-command-table}, except
that \arg{type} must be either \cl{:command}, \cl{:function} or \cl{:menu}.
\arg{command-table} is a \term{command table designator}.

\issue {SWM} {Should we allow \arg{gesture} to be a gesture specification as
well as just a gesture name?  It simplifies its use by avoiding a profusion of
defined gesture names, but we may want to encourage the use of gesture names.}

\arg{documentation} is a documentation string, which can be used as
documentation for the keystroke accelerator.

If the menu item associated with \arg{gesture} is already present in the command
table's accelerator table and \arg{errorp} is \term{true}, then the
\cl{command-already-present} error will be signalled.  When the item is already
present in the command table's accelerator table and \arg{errorp} is
\term{false}, the old item will first be removed.


\Defun {remove-keystroke-from-command-table} {command-table gesture \key (errorp t)}  

Removes the item named by keyboard gesture name \arg{gesture} from
\arg{command-table}'s accelerator table.  \arg{command-table} is a \term{command
table designator}.

If the menu item associated with \arg{gesture} is not present in the command
table's menu and \arg{errorp} is \term{true}, then the \cl{command-not-present}
error will be signalled.


\Defun {map-over-command-table-keystrokes} {function command-table}

Applies \arg{function} to all of the keystroke accelerators in
\arg{command-table}'s accelerator table.  \arg{function} must be a function of
three arguments, the menu name (which will be \cl{nil} if there is none), the
keystroke accelerator, and the menu item; it has dynamic extent.
\arg{command-table} is a \term{command table designator}.

\cl{map-over-command-table-keystrokes} does not descend into sub-menus.  If the
programmer requires this behavior, he should examine the type of the menu item
to see if it is \cl{:menu}.


\Defun {find-keystroke-item} {gesture command-table \key (errorp t)}

Given a keyboard gesture \arg{gesture} and a command table, returns two values,
the menu item associated with the gesture and the command table in which it was
found.  (Since keystroke accelerators are not inherited, the second returned
value will always be \arg{command-table}.)

\ReadOnly

Note that \arg{gesture} may be either a keyboard gesture name of a gesture
object.  When it is a gesture name, \cl{eql} will be used to compare the
supplied gesture to the gesture names stored in the command table's menu.  When
it is a gesture object, \cl{event-matches-gesture-name-p} will be used to do the
comparison.

If the keystroke accelerator is not present in \arg{command-table} and
\arg{errorp} is \term{true}, then the \cl{command-not-present} error will be
signalled.  \arg{command-table} is a \term{command table designator}.

\Defun {lookup-keystroke-item} {gesture command-table}

Given a keyboard gesture \arg{gesture} and a command table, returns two values,
the menu item associated with the gesture and the command table in which it was
found.  Note that \arg{gesture} may be either a keyboard gesture name of a
gesture object, and is handled in the same way as in \cl{find-keystroke-item}.
\ReadOnly

Unlike \cl{find-keystroke-item}, this follows the sub-menu chains that can be
created with \cl{add-menu-item-to-command-table}.  If the keystroke accelerator
cannot be found in the command table or any of the command tables from which it
inherits, \cl{lookup-keystroke-item} will return \cl{nil}.  \arg{command-table}
is a \term{command table designator}.

\Defun {lookup-keystroke-command-item} {gesture command-table \key numeric-arg}

Given a keyboard gesture \arg{gesture} and a command table, returns the command
associated with the keystroke, or \arg{gesture} if no command is found.  Note
that \arg{gesture} may be either a keyboard gesture name of a gesture object,
and is handled in the same way as in \cl{find-keystroke-item}.
\ReadOnly

This is like \cl{find-keystroke-item}, except that only keystrokes that map to
an enabled application command will be matched.  \arg{command-table} is a
\term{command table designator}.

\arg{numeric-arg} (which defaults to 1) is substituted into the resulting
command for any occurrence of \cl{*numeric-argument-marker*} in the command.
This is intended to allow programmers to define keystroke accelerators that take
simple numeric arguments, which will be passed on by the input editor.

\issue {SWM} {The above three functions need to have their hands on the port
object since they are might use \cl{event-matches-gesture-name-p}, which also
needs to have a port object.}

\Defun {substitute-numeric-argument-marker} {command numeric-arg}

Given a command object \arg{command}, this substitutes the values of
\arg{numeric-arg} for all occurrences of the value of
\cl{*numeric-argument-marker*} in the command, and returns a command object with
those substitutions.


\section {Presentation Translator Utilities}

These are some utilities for maintain presentation translators in
command tables.  Presentation translators are discussed in more detail
in Chapter~\ref{presentation-types}.


\Defun {add-presentation-translator-to-command-table} {command-table translator-name
                                                       \key (errorp t)}

Adds the translator named by \arg{translator-name} to \arg{command-table}.  The
translator should have been previously defined with
\cl{define-presentation-translator} or
\cl{define-presentation-to-command-translator}.  \arg{command-table} is a
\term{command table designator}.

If \arg{translator-name} is already present in \arg{command-table} and
\arg{errorp} is \term{true}, then the \cl{command-already-present} error will be
signalled.  When the translator is already present and \arg{errorp} is
\term{false}, the old translator will first be removed.


\Defun {remove-presentation-translator-from-command-table} {command-table translator-name
                                                            \key (errorp t)}

Removes the translator named by \arg{translator-name} from \arg{command-table}.
\arg{command-table} is a \term{command table designator}.

If the translator is not present in the command table and \arg{errorp} is
\term{true}, then the \cl{command-not-present} error will be signalled.


\Defun {map-over-command-table-translators} {function command-table \key (inherited t)}

Applies \arg{function} to all of the translators accessible in
\arg{command-table}.  \arg{function} must be a function of one argument, the
translator; it has dynamic extent.  \arg{command-table} is a \term{command table
designator}. 

If \arg{inherited} is \term{false}, this applies \arg{function} only to
those translators present in \arg{command-table}, that is, it does
not map over any inherited command tables.  If \arg{inherited} is
\term{true}, then the inherited command tables are traversed in the same
order as for \cl{do-command-table-inheritance}.


\Defun {find-presentation-translator} {translator-name command-table \key (errorp t)}

Given a translator name and a command table, returns two values, the
presentation translator and the command table in which it was found.  If the
translator is not present in \arg{command-table} and \arg{errorp} is
\term{true}, then the \cl{command-not-accessible} error will be signalled.
\arg{command-table} is a \term{command table designator}.


\section {The Command Processor}

Once a set of commands has been defined, CLIM provides a variety of means to
read a command.  These are all mediated by the Command Processor.


\Defun {read-command} {command-table 
                       \key (stream *query-io*)
                            command-parser command-unparser partial-command-parser
                            use-keystrokes} 

\cl{read-command} is the standard interface used to read a command line.
\arg{stream} is an extended input stream, and \arg{command-table} is a
\term{command table designator}.

\arg{command-parser} must be a function of two arguments, a command table and a
stream.  It reads a command from the user and returns a command object.  The
default value for \arg{command-parser} is \cl{*command-parser*}.

\arg{command-unparser} must be a function of three arguments, a command table, a
stream, and a command to ``unparse''.  It prints a textual description of the
command its supplied arguments onto the stream.  The default value for
\arg{command-unparser} is \cl{*command-unparser*}.

\arg{partial-command-parser} must be a function of four arguments, a command
table, a stream, a partial command, and a start position.  The partial command
is a command object with the value of \cl{*unsupplied-argument-marker*} in place
of any argument that needs to be filled in.  The function reads the remaining,
unsupplied arguments in any way it sees fit (for example, via an
\cl{accepting-values} dialog), and returns a command object.  The start position
is the original input-editor scan position of the stream, when the stream is an
interactive stream.  The default value for \arg{partial-command-parser} is
\cl{*partial-command-parser*}.

\arg{command-parser}, \arg{command-unparser}, and \arg{partial-command-parser}
have dynamic extent.

When \arg{use-keystrokes} is \term{true}, the command reader will also process
keystroke accelerators.  (Implementations will typically use
\cl{with-command-table-keystrokes} and \cl{read-command-using-keystrokes} to
implement the case when \arg{use-keystrokes} is \term{true}.)

Input editing, while conceptually an independent facility, fits into the command
processor via its use of \cl{accept}.  That is, \cl{read-command} must be
implemented by calling \cl{accept} to read command objects, and \cl{accept}
itself makes use of the input editing facilities.


\Defmacro {with-command-table-keystrokes} {(keystroke-var command-table) \body body}

Binds \arg{keystroke-var} to a sequence that contains all of the keystroke
accelerators in \arg{command-table}'s menu, and then executes \arg{body} in that
context.  \arg{command-table} is a \term{command table designator}.  \arg{body}
may have zero or more declarations as its first forms.

\Defun {read-command-using-keystrokes} {command-table keystrokes
                                        \key (stream *query-io*)
                                             command-parser command-unparser
                                             partial-command-parser}

Reads a command from the user via command lines, the pointer, or a single
keystroke, and returns either a command object, or a keyboard gesture object if
the user typed a keystroke that is in \arg{keystrokes} but does not have a
command associated with it in \arg{command-table}.

\arg{keystrokes} is a sequence of keyboard gesture names that are the keystroke
accelerators.

\arg{command-table}, \arg{stream}, \arg{command-parser}, \arg{command-unparser},
and \arg{partial-command-parser} are as for \cl{read-command}.


\Defun {command-line-command-parser} {command-table stream}

The default command-line parser.  It reads a command name and the command's
arguments as a command line from \arg{stream} (with completion as much as is
possible), and returns a command object.  \arg{command-table} is a \term{command
table designator} that specifies the command table to use; the commands are read
via the textual command-line name.

\Defun {command-line-command-unparser} {command-table stream command}

The default command-line unparser.  It prints the command \arg{command} as a
command name and its arguments as a command line on \arg{stream}.
\arg{command-table} is a \term{command table designator} that specifies the
command table to use; the commands are displayed using the textual command-line
name.

\Defun {command-line-read-remaining-arguments-for-partial-command}
       {command-table stream partial-command start-position}

The default partial command-line parser.  If the remaining arguments are at the
end of the command line, it reads them as a command line, otherwise it
constructs a dialog using \cl{accepting-values} and reads the remaining
arguments from the dialog.  \arg{command-table} is a \term{command table
designator}. 

\Defun {menu-command-parser} {command-table stream}

The default menu-driven command parser.  It uses only pointer clicks to
construct a command.  It relies on presentations of all arguments being visible.
\arg{command-table} and \arg{stream} are as for \cl{command-line-parser}.

There is no menu-driven command unparser, since it makes no sense to unparse a
completely menu-driven command.

\Defun {menu-read-remaining-arguments-for-partial-command}
       {command-table stream partial-command start-position}

The default menu-driven partial command parser.  It uses only pointer clicks to
fill in the command.  Again, it relies on presentations of all arguments being
visible.  \arg{command-table} is a \term{command table designator}.


\Defvar {*command-parser*}

Contains the currently active command parsing function.  The default value is
the function \cl{command-line-command-parser}, which is the default command-line
parser.

\Defvar {*command-unparser*}

Contains the currently active command unparsing function.  The default value is
the function \cl{command-line-command-unparser}, which is the default
command-line unparser.

\Defvar {*partial-command-parser*}

Contains the currently active partial command parsing function.  The default value
is the function \cl{command-line-read-remaining-arguments-for-partial-command}.

\Defvar {*unsupplied-argument-marker*}

The value of \cl{*unsupplied-argument-marker*} is an object that can be uniquely
identified as standing for an unsupplied argument in a command object.

\Defvar {*numeric-argument-marker*}

The value of \cl{*numeric-argument-marker*} is an object that can be uniquely
identified as standing for a numeric argument in a command object.

\Defvar {*command-name-delimiters*}

This is a list of the characters that separate the command name from the command
arguments in a command line.  The standard set of command name delimiters must
include \verb+#\Space+.

\Defvar {*command-argument-delimiters*}

This is a list of the characters that separate the command arguments from each
other in a command line.  The standard set of command argument delimiters must
include \verb+#\Space+.


\subsection {Command Presentation Types}

\Defptype {command} {\key command-table}

The presentation type used to represent a command and its arguments; the command
must be accessible in \arg{command-table} and enabled in
\cl{*application-frame*}.  \arg{command-table} is a \term{command table
designator}.  If \arg{command-table} is not supplied, it defaults to the command
table for the current application frame, \cl{(frame-command-table
*application-frame*)}.

The object returned by the \cl{accept} presentation method for \cl{command}
must be a command object, that is, a cons of the command name and the list of
the command's arguments.

The \cl{accept} presentation method for the \cl{command} type must recursively
call \cl{accept} to read a \cl{command-name} and all of the command's arguments.
\cl{read-command} must be implemented by accepting objects whose presentation
type is \cl{command}.

\Defptype {command-name} {\key command-table}

The presentation type used to represent the name of a command that is both
accessible in the command table \arg{command-table} and enabled in
\cl{*application-frame*}.  \arg{command-table} is a \term{command table
designator}.  If \arg{command-table} is not supplied, it defaults to the command
table for the current application frame.

The textual representation of a \cl{command-name} object is the command-line
name of the command, while the internal representation is the command name.

\Defptype {command-or-form} {\key command-table}

The presentation type used to represent an object that is either a Lisp form, or
a command and its arguments.  The command must be accessible in
\arg{command-table} and enabled in \cl{*application-frame*}.
\arg{command-table} is a \term{command table designator}.  If \arg{command-table}
is not supplied, it defaults to the command table for the current application
frame.

The \cl{accept} presentation method for this type reads a Lisp form, except that
if the first character in the user's input is one of the characters in
\cl{*command-dispatchers*} it will read a command.  The two returned values from
the \cl{accept} presentation method will be the command or form object and a
presentation type specifier that is either \cl{command} or \cl{form}.

\Defvar {*command-dispatchers*}

This is a list of the characters that indicates that CLIM reads a command when
it is accepting a \cl{command-or-form}.  The standard set of command argument
delimiters must include the colon character, \verb+#\:+.