27.6 The Command Processor

  • 27.6.1 Command Presentation Types
  • 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. [annotate]

    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. [annotate]

    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*. [annotate]

    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*. [annotate]

    Note: This is most likely an omission. CLIM-TOS (and soon enough McCLIM) passes keywords acceptably and for-context-type from the pmethod `present`. [edit]-- DK 2021-11-07 11:50Z
     

    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*. [annotate]

    command-parser, command-unparser, and partial-command-parser have dynamic extent. [annotate]

    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.) [annotate]

    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. [annotate]

    [annotate]

    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. [annotate]

    Note: This should descend into submenus until a keystroke is encountered (unlike map-over-command-table-keystrokes which does not descend). [edit]-- DK 2020-10-18 08:08Z
     

    [annotate]

    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. [annotate]

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

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

    [annotate]

    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. [annotate]

    [annotate]

    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. [annotate]

    [annotate]

    Note:

    This function should also have at least

    &key acceptably for-context-type

    in order to be able to accept these arguments from the presentation method present specialized on the command.

    [edit]-- Daniel Kochmanski 2021-10-27 19:10Z
     

    command-line-read-remaining-arguments-for-partial-command   [Function]
              

    command-table stream partial-command start-position [annotate]

    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. [annotate]

    [annotate]

    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. [annotate]

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

    [annotate]

    menu-read-remaining-arguments-for-partial-command   [Function]
              

    command-table stream partial-command start-position [annotate]

    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. [annotate]

    [annotate]

    *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. [annotate]

    [annotate]

    *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. [annotate]

    [annotate]

    *partial-command-parser*   [Variable]
    *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. [annotate]

    [annotate]

    *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. [annotate]

    [annotate]

    *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. [annotate]

    [annotate]

    *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. [annotate]

    [annotate]

    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*). [annotate]

    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. [annotate]

    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. [annotate]

    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*. [annotate]

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

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

    [annotate]

    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*). [annotate]

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

    [annotate]

    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*). [annotate]

    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. [annotate]

    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. [annotate]

    [annotate]

    *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, #\:. [annotate]

    [annotate]