27.1 Commands

A 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 apply 'ed to the rest of the cons, the code representing that interaction is executed.

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

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

command-name command [Function]
Given a command object command , returns the command name.

command-arguments command [Function]
Given a command object command , returns the command's arguments.

partial-command-p command [Function]
Returns true if the command is a partial command, that is, has any occurrences of *unsupplied-argument-marker* in it. Otherwise, partial-command-p returns false .

define-command name-and-options arguments &body body [Macro]
This is the most basic command-defining form. Usually, the programmer will not use define-command directly, but will instead use a define-frame-command form that is automatically generated by define-application-frame . define-frame-command adds the command to the application frame's command table. By default, define-command does not add the command to any command table.

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

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 define-command form, as required and keyword arguments.

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

The keywords from name-and-options can be:

:command-table command-table-name , where command-table-name either names a command table to which the command will be added, or is nil (the default) to indicate that the command should not be added to any command table. If the command table does not exist, the command-table-not-found error will be signalled. This keyword is only accepted by define-command , not by define-frame-command
:name string , where 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 :command-table option. The default is nil , meaning that the command will not be available via command-line interactions. If string is t , then the command-line name will be generated automatically, as described in add-command-to-command-table .
:menu menu-spec , where menu-spec describes an item in the menu of the command table specified by the :command-table option. The default is nil , meaning that the command will not be available via menu interactions. If menu-spec is a string, then that string will be used as the menu name. If menu-spec is t , then if a command-line name was supplied, it will be used as the menu name; otherwise the menu name will be generated automatically, as described in add-command-to-command-table . Otherwise, menu-spec must be a cons of the form (string . menu-options ) , where string is the menu name and menu-options consists of keyword-value pairs. The valid keywords are :after , :documentation , and :text-style , which are interpreted as for add-menu-item-to-command-table .
:keystroke gesture , where gesture is a keyboard gesture name that specifies a keystroke accelerator to use for this command in the command table specified by the :command-table option. The default is nil , meaning that there is no keystroke accelerator.

The :name , :menu , and :keystroke options are only allowed if the :command-table option was supplied explicitly or implicitly, as in define-frame-command

arguments is a list consisting of argument descriptions. A single occurrence of the symbol &key may appear in 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:

:default value , where value is the default that should be used for the argument, as for accept .
:default-type is the same as for accept .
:display-default is the same as for accept .
:mentioned-default value , where 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. :mentioned-default is only allowed on keyword arguments.
:prompt string , where string is a prompt to print out during command-line parsing, as for accept .
:documentation string , where string is a documentation string that describes what the argument is.
:when form . form is evaluated in a scope where the parameter variables for the required parameters are bound, and if the result is nil , the keyword argument is not available. :when is only allowed on keyword arguments, and form cannot use the values of other keyword arguments.
:gesture gesture , where 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 translates from this argument's presentation type to an instance of this command with the selected object as the argument; the other arguments will be filled in with their default values. The keyword-value pairs are used as options for the translator. Valid keywords are :tester , :menu , :priority , :echo , :documentation , and :pointer-documentation . The default for gesture is nil , meaning no translator will be written. :gesture is only allowed when the :command-table option was supplied to the command-defining form.

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 *application-frame* . The returned values of body are ignored. body may have zero or more declarations as its first forms.

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

name-and-options and 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 :when is evaluated when parsing reaches the keyword arguments, and :gesture isn't evaluated at all.

27.2 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 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:

The name of the command table, which is a symbol.
An ordered list of command tables to inherit from.
The set of commands that are present in this command table.
A table that associates command-line names to command names (used to support command-line processor interactions).
A set of presentation translators, defined via define-presentation-translator and define-presentation-to-command-translator .
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.
A menu that associates menu names to command menu items (used to support interaction via command menus). The command menu items can invoke commands or sub-menus. By default, the menu does not contain any command menu items inherited from superior command tables, although this can be overridden by the :inherit-menu option to define-command-table .

We say that a command is present in a command table when it has been added to that command table. We say that a command is 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.

command-table [Protocol Class]
The protocol class that corresponds to command tables. If you want to create a new class that behaves like a command table, it should be a subclass of command-table. Subclasses of command-table must obey the command table protocol.Members of this class are mutable.
command-table-p object [Predicate]
Returns true if object is a command table , otherwise returns false .

standard-command-table [Class]
The instantiable class that implements command tables, a subclass of command-table . 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?

command-table-name

command-table

[Generic function]

Returns the name of the command table command-table .

command-table-inherit-from command-table [Generic function]
Returns a list of the command tables from which the command table command-table inherits. This function returns objects that reveal CLIM's internal state; do not modify those objects.
define-command-table name &key inherit-from menu inherit-menu [Macro]
Defines a command table whose name is the symbol name . The new command table inherits from all of the command tables specified by inherit-from , which is a list of 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.)

If inherit-menu is true , the new command table will inherit the menu items and keystroke accelerators from all of the inherited command tables. If it is false (the default), no menu items or keystroke accelerators will be inherited.

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

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

None of define-command-table 's arguments are evaluated.

make-command-table name &key inherit-from menu inherit-menu (errorp t) [Function]
Creates a command table named name . inherit-from , menu , and inherit-menu are the same as for define-command-table . 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 errorp is true , the command-table-already-exists error will be signalled. If the command table already exists and errorp is false , then the old command table will be discarded. The returned value is the command table.

find-command-table name &key (errorp t) [Function]
Returns the command table named by name . If name is itself a command table, it is returned. If the command table is not found and errorp is true , the command-table-not-found error will be signalled.

command-table-error [Error]
The class that is the superclass of the following four conditions. This class is a subclass of error .

command-table-error and its subclasses must handle the :format-string and :format-arguments initargs, which are used to specify a control string and arguments for a call to format .

command-table-not-found [Error]
The error that is signalled by such functions as find-command-table when a command table is not found.

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

command-not-present [Error]
The error that is signalled when a command is not present in a command table.

command-not-accessible [Error]
The error that is signalled when a command is not accessible in a command table.

command-already-present [Error]
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.

add-command-to-command-table command-name command-table &key name menu keystroke (errorp t) [Function]
Adds the command named by command-name to the command table specified by the command table designator command-table .

name is the command-line name for the command, and can be nil , t , or a string. When it is 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 t , the command-line name is generated automatically by calling command-name-from-symbol on command-name . For the purposes of command-line name lookup, the character case of name is ignored.

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

The value for keystroke is either keyboard gesture name or 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 errorp is true , the command-already-present error will be signalled. When the command is already present in the command table and errorp is false , then the old command-line name, menu, and keystroke accelerator will first be removed from the command table.

remove-command-from-command-table command-name command-table &key (errorp t) [Function]
Removes the command named by command-name from the command table specified by the command table designator command-table .

If the command is not present in the command table and errorp is true , the command-not-present error will be signalled.

command-name-from-symbol symbol [Function]
Generates a string suitable for use as a command-line name from the symbol symbol . The string consists the symbol name with the hyphens replaced by spaces, and the words capitalized. If the symbol name is prefixed by ``COM-'', the prefix is removed. For example, if the symbol is com-show-file , the result string will be ``Show File''.

do-command-table-inheritance (command-table-var command-table) &body body [Macro]
Successively executes body with command-table-var bound first to the command table specified by the command table designator command-table , and then (recursively) to all of the command tables from which command-table inherits.

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

map-over-command-table-commands function command-table &key (inherited t) [Function]
Applies function to all of the commands accessible in the command table specified by the command table designator command-table . function must be a function that takes a single argument, the command name; it has dynamic extent.

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

map-over-command-table-names function command-table &key (inherited t) [Function]
Applies function to all of the command-line name accessible in the command table specified by the command table designator command-table . function must be a function of two arguments, the command-line name and the command name; it has dynamic extent.

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

command-present-in-command-table-p command-name command-table [Function]
Returns true if the command named by command-name is present in the command table specified by the command table designator command-table , otherwise returns false .

command-accessible-in-command-table-p command-name command-table [Function]
If the command named by command-name is not accessible in the command table specified by the command table designator command-table , then this function returns nil . Otherwise, it returns the command table in which the command was found.

find-command-from-command-line-name name command-table &key (errorp t) [Function]
Given a command-line name 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 command-table and errorp is true , the command-not-accessible error will be signalled. command-table is a command table designator .

find-command-from-command-line-name ignores character case.

command-line-name-for-command command-name command-table &key (errorp t) [Function]
Returns the command-line name for command-name as it is installed in command-table . command-table is a command table designator .

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

This is the inverse of 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.

command-table-complete-input command-table string action &key frame [Function]
A function that can be used as in conjunction with complete-input in order to complete over all of the command lines names accessible in the command table command-table . string is the input string to complete over, and action is as for complete-from-possibilities .

frame is either an application frame, or nil . If frame is supplied, no disabled commands should be offered as valid completions.

command-table-complete-input could be implemented by collecting all of the command line names accessible in the command table and then calling complete-from-possibilities , or it could be implemented more efficiently than that (such as by caching a sorted list of command line names and using a binary search).

global-command-table [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. CLIM can use this command to store internals or system-wide commands and translators (for example, the translator that implements the ``identity'' translation from a type to itself). Programmers should not casually install any commands or translators into this command table.

user-command-table [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.

27.3 Command Menus

Each command table may have a menu consisting of an ordered sequence of command menu items. The menu specifies a mapping from a menu name (the name displayed in the menu) to a command 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.

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

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

add-menu-item-to-command-table command-table string type value &key documentation (after ':end) keystroke text-style (errorp t) [Function]
Adds a command menu item to command-table 's menu. string is the name of the command menu item; its character case is ignored. type is either :command , :function , :menu , or :divider . command-table is a command table designator .

Issue: SWM
How do we make iconic command menus? Probably another keyword...

When type is :command , 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 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 on an item in the menu invokes the command immediately. Otherwise, the user will be prompted for the remaining required arguments.

When type is :function , 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 type is :menu , this item indicates that a sub-menu will be invoked, and so value must be another command table or the name of another command table.

When type is :divider , some sort of a dividing line is displayed in the menu at that point. If 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, :divider items may be ignored. value is ignored.

documentation is a documentation string, which can be used as mouse documentation for the command menu item.

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

after must be either :start (meaning to add the new item to the beginning of the menu), :end or 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 after is :sort , then the item is inserted in such as way as to maintain the menu in alphabetical order.

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

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

remove-menu-item-from-command-table command-table string &key (errorp t) [Function]
Removes the item named by string from command-table 's menu. command-table is a command table designator .

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

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

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 command menu item to see if it is :menu .

find-menu-item menu-name command-table &key (errorp t) [Function]
Given a menu name and a command table, returns two values, the command menu item and the command table in which it was found. (Since menus are not inherited, the second returned value will always be command-table .) command-table is a command table designator . This function returns objects that reveal CLIM's internal state; do not modify those objects. If there is no command menu item corresponding to menu-name present in command-table and errorp is true , then the command-not-accessible error will be signalled. Note that the character case of string is ignored when searching the command table's menu.

command-menu-item-type menu-item [Function]
Returns the type of the command menu item menu-item , for example, :menu or :command . If menu-item is not a command menu item, the result is unspecified.

command-menu-item-value menu-item [Function]
Returns the value of the command menu item menu-item . For example, if the type of menu-item is :command , this will return a command or a command name. If menu-item is not a command menu item, the result is unspecified.

command-menu-item-options menu-item [Function]
Returns a list of the options for the command menu item menu-item . If menu-item is not a command menu item, the result is unspecified.

display-command-table-menu command-table stream &key max-width max-height n-rows n-columns x-spacing y-spacing initial-spacing row-wise (cell-align-x :left ) (cell-align-y :top ) (move-cursor t ) [Generic function]
Displays command-table 's menu on stream . Implementations may choose to use 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. command-table is a command table designator .

max-width , max-height , n-rows , n-columns , x-spacing , y-spacing , row-wise , initial-spacing , cell-align-x , cell-align-y , and move-cursor are as for formatting-item-list .

menu-choose-command-from-command-table command-table &key associated-window default-style label cache unique-id id-test cache-value cache-test [Function]
Invokes a window system specific routine that displays a menu of commands from command-table 's menu, and allows the user to choose one of the commands. command-table is a command table designator . The returned value is a command object. This may invoke itself recursively when there are sub-menus.

associated-window , default-style , label , cache , unique-id , id-test , cache-value , and cache-test are as for menu-choose .

Issue: SWM
Should this be generic on application frames?

27.4 Keystroke Accelerators

Each command table may have a mapping from keystroke accelerator gesture names to command menu items. When a user types a key on the keyboard that corresponds to the gesture for keystroke accelerator, the corresponding command menu item will be invoked. Note that command 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.

add-keystroke-to-command-table command-table gesture type value &key documentation (errorp t) [Function]
Adds a command menu item to command-table 's keystroke accelerator table. gesture is a keyboard gesture name to be used as the accelerator. type and value are as in add-menu-item-to-command-table , except that type must be either :command , :function or :menu . command-table is a command table designator .

Issue: SWM
Should we allow 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.

documentation is a documentation string, which can be used as documentation for the keystroke accelerator.

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

remove-keystroke-from-command-table command-table gesture &key (errorp t) [Function]
Removes the command menu item named by keyboard gesture name gesture from command-table 's accelerator table. command-table is a command table designator .

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

map-over-command-table-keystrokes function command-table [Function]
Applies function to all of the keystroke accelerators in command-table 's accelerator table. function must be a function of three arguments, the menu name (which will be nil if there is none), the keystroke accelerator, and the command menu item; it has dynamic extent. command-table is a command table designator .

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

find-keystroke-item gesture command-table &key test (errorp t) [Function]
Given a keyboard gesture gesture and a command table, returns two values, the command 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 command-table .)

This function returns objects that reveal CLIM's internal state; do not modify those objects. test is the test used to compare the supplied gesture to the gesture name in the command table. The supplied gesture will generally be an event object, so the default for test is event-matches-gesture-name-p .

If the keystroke accelerator is not present in command-table and errorp is true , then the command-not-present error will be signalled. command-table is a command table designator .

lookup-keystroke-item gesture command-table &key test [Function]
Given a keyboard gesture gesture and a command table, returns two values, the command menu item associated with the gesture and the command table in which it was found. Note that gesture may be either a keyboard gesture name of a gesture object, and is handled in the same way as in find-keystroke-item . This function returns objects that reveal CLIM's internal state; do not modify those objects. Unlike find-keystroke-item , this follows the sub-menu chains that can be created with 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, lookup-keystroke-item will return nil . command-table is a command table designator .

test is the test used to compare the supplied gesture to the gesture name in the command table. The supplied gesture will generally be an event object, so the default for test is event-matches-gesture-name-p .

lookup-keystroke-command-item gesture command-table &key test numeric-arg [Function]
Given a keyboard gesture gesture and a command table, returns the command associated with the keystroke, or gesture if no command is found. Note that gesture may be either a keyboard gesture name of a gesture object, and is handled in the same way as in find-keystroke-item . This function returns objects that reveal CLIM's internal state; do not modify those objects. This is like find-keystroke-item , except that only keystrokes that map to an enabled application command will be matched. command-table is a command table designator .

numeric-arg (which defaults to 1) is substituted into the resulting command for any occurrence of *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
Do the above three functions need to have their hands on the port? If event-matches-gesture-name-p needs the port, then the answer is yes. Otherwise, if gesture names are ``global'' across all ports, then these don't need the port.

substitute-numeric-argument-marker

command numeric-arg

[Function]

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

27.5 Presentation Translator Utilities

These are some utilities for maintain presentation translators in command tables. Presentation translators are discussed in more detail in Chapter Presentation Types .

add-presentation-translator-to-command-table command-table translator-name &key (errorp t) [Function]
Adds the translator named by translator-name to command-table . The translator must have been previously defined with define-presentation-translator or define-presentation-to-command-translator . command-table is a command table designator .

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

remove-presentation-translator-from-command-table command-table translator-name &key (errorp t) [Function]
Removes the translator named by translator-name from command-table . command-table is a command table designator .

If the translator is not present in the command table and errorp is true , then the command-not-present error will be signalled.

map-over-command-table-translators function command-table &key (inherited t) [Function]
Applies function to all of the translators accessible in command-table . function must be a function of one argument, the translator; it has dynamic extent. command-table is a command table designator .

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

find-presentation-translator translator-name command-table &key (errorp t) [Function]
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 command-table and errorp is true , then the command-not-accessible error will be signalled. command-table is a command table designator .

27.6 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.

read-command command-table &key (stream *standard-input*) command-parser command-unparser partial-command-parser use-keystrokes [Function]
read-command is the standard interface used to read a command line. stream is an extended input stream, and command-table is a command table designator .

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, or nil if an empty command line was read. The default value for command-parser is the value of *command-parser* .

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 command-unparser is the value of *command-unparser* .

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 *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 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 partial-command-parser is the value of *partial-command-parser* .

command-parser , command-unparser , and partial-command-parser have dynamic extent.

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

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

with-command-table-keystrokes (keystroke-var command-table) &body body [Macro]
Binds keystroke-var to a sequence that contains all of the keystroke accelerators in command-table 's menu, and then executes body in that context. command-table is a command table designator . body may have zero or more declarations as its first forms.

read-command-using-keystrokes command-table keystrokes &key (stream *standard-input*) command-parser command-unparser partial-command-parser [Function]
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 keystrokes but does not have a command associated with it in command-table .

keystrokes is a sequence of keyboard gesture names that are the keystroke accelerators.

command-table , stream , command-parser , command-unparser , and partial-command-parser are as for read-command .

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

command-line-command-unparser command-table stream command [Function]
The default command-line unparser. It prints the command command as a command name and its arguments as a command line on stream . command-table is a command table designator that specifies the command table to use; the commands are displayed using the textual command-line name.

command-line-read-remaining-arguments-for-partial-command command-table stream partial-command start-position [Function]
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 accepting-values and reads the remaining arguments from the dialog. command-table is a command table designator .

menu-command-parser command-table stream [Function]
The default menu-driven command parser. It uses only pointer clicks to construct a command. It relies on presentations of all arguments being visible. command-table and stream are as for command-line-parser .

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

menu-read-remaining-arguments-for-partial-command command-table stream partial-command start-position [Function]
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. command-table is a command table designator .

*command-parser* [Variable]
Contains the currently active command parsing function. The default value is the function command-line-command-parser , which is the default command-line parser.

*command-unparser* [Variable]
Contains the currently active command unparsing function. The default value is the function command-line-command-unparser , which is the default command-line unparser.

*partial-command-parser* [Variable]
Contains the currently active partial command parsing function. The default value is the function command-line-read-remaining-arguments-for-partial-command .

*unsupplied-argument-marker* [Variable]
The value of *unsupplied-argument-marker* is an object that can be uniquely identified as standing for an unsupplied argument in a command object.

*numeric-argument-marker* [Variable]
The value of *numeric-argument-marker* is an object that can be uniquely identified as standing for a numeric argument in a command object.

*command-name-delimiters* [Variable]
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 #\Space.

*command-argument-delimiters* [Variable]
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 #\Space.

27.6.1 Command Presentation Types

command &key command-table [Presentation Type]

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

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

The accept presentation method for the command type must call the command parser stored in *command-parser* to read the command. The parser will recursively call accept to read a command-name and all of the command's arguments. The parsers themselves must be implemented by accepting objects whose presentation type is command .

If the command parser returns a partial command, the accept presentation method for the command type must call the partial command prser stored in *partial-command-parser* .

The present presentation method for the command type must call the command unparser stored in *command-unparser* .

If a presentation history is maintained for the command presentation type, it should be maintained separately for each instance of an application frame.

command-name &key command-table [Presentation Type]
The presentation type used to represent the name of a command that is both accessible in the command table command-table and enabled in *application-frame* . command-table is a command table designator . If command-table is not supplied, it defaults to the command table for the current application frame, (frame-command-table *application-frame*) .

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

command-or-form &key command-table [Presentation Type]
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 command-table and enabled in *application-frame* . command-table is a command table designator . If command-table is not supplied, it defaults to the command table for the current application frame, (frame-command-table *application-frame*) .

The 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 *command-dispatchers* it will read a command. The two returned values from the accept presentation method will be the command or form object and a presentation type specifier that is either command or form .

If a presentation history is maintained for the command-or-form presentation type, it should be maintained separately for each instance of an application frame.

*command-dispatchers* [Variable]
This is a list of the characters that indicates that CLIM reads a command when it is accepting a command-or-form . The standard set of command argument delimiters must include the colon character, #\:.