Changes between Version 1 and Version 2 of HemlockProgrammer/Commands


Ignore:
Timestamp:
Jan 15, 2008, 12:59:41 AM (12 years ago)
Author:
gz
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • HemlockProgrammer/Commands

    v1 v2  
     1[HemlockProgrammer Back to Table of Contents]
    12[[PageOutline]]
    23
    34= 7. Commands =
    45
    5 == 7.1. Introduction ==
     6== 7.1. Introduction ==#Introduction
    67
    78The way that the user tells Hemlock to do something is by invoking a
     
    1819 A command is implemented by a Lisp function, which is callable from Lisp.
    1920
    20 *command-names* [Variable]
     21`*command-names*` [Variable]
    2122
    2223Holds a string-table (page 69) associating command names to command
     
    2425table.
    2526
    26 === 7.1.1. Defining Commands ===
    27 defcommand{command-name | (command-name function-name)} lambda-list
    28 command-doc function-doc {form}* [Macro]
     27=== 7.1.1. Defining Commands ===#DefiningCommands
     28
     29`defcommand` {command-name | (command-name function-name &key)} lambda-list command-doc {function-doc} {form}* [Macro]
    2930
    3031Defines a command named name. defcommand creates a function to
    31 implement the command from the lambda-list and forms supplied.  The
    32 lambda-list must specify one required argument, see section 7.4, which
    33 by convention is typically named p. If the caller does not specify
     32implement the command from the lambda-list and forms supplied.  The
     33lambda-list must specify one required argument, see [HemlockProgrammer/Commands#CommandArguments below],
     34which by convention is typically named `p`. If the caller does not specify
    3435function-name, defcommand creates the command name by replacing all
    35 spaces with hyphens and appending "-command".  Function-doc becomes
    36 the documentation for the function and should primarily describe
     36spaces with hyphens and appending "-command".  Any keyword arguments
     37are as for `make-command`.  Command-doc becomes the command
     38documentation for the command.  Function-doc, if present, becomes the
     39documentation for the function and should primarily describe
    3740issues involved in calling the command as a function, such as what any
    38 additional arguments are. Command-doc becomes the command
    39 documentation for the command.
    40 
    41 make-command name documentation function [Function]
     41additional arguments are.
     42
     43`make-command` name documentation function &key :transparent-p [Function]
    4244
    4345Defines a new command named name, with command documentation
    44 documentation and function function. The command in entered in the
     46documentation and function function.  If :transparent-p is true,
     47the command becomes [HemlockProgrammer/Commands#TransparentKeyBindings transparent].
     48The command in entered in the
    4549string-table *command-names* (page 27), with the command object as its
    46 value.  Normally command implementors will use the defcommandmacro,
     50value.  Normally command implementors will use the defcommand macro,
    4751but this permits access to the command definition mechanism at a lower
    4852level, which is occasionally useful.
    4953
    50 commandp command [Function]
     54`commandp` command [Function]
    5155
    5256Returns t if command is a command object, otherwise nil.
    5357
    54 command-documentation command [Function]
    55 
    56 command-function command [Function]
    57 
    58 command-name command [Function]
     58`command-documentation` command [Function][[BR]]
     59`command-function` command [Function][[BR]]
     60`command-name` command [Function][[BR]]
    5961
    6062Returns the documentation, function, or name for command. These may be
    6163set with setf.
    6264
    63 === 7.1.2. Command Documentation ===
     65=== 7.1.2. Command Documentation ===#CommandDocumentation
    6466
    6567Command documentation is a description of what the command does when
     
    7476   With prefix argument move that many characters, with negative
    7577   argument go backwards."
    76   "Move the point of the current buffer forward p characters."
    7778. . .)
    7879}}}
     
    8384to document the command fully.
    8485
    85 == 7.2. The Command Interpreter ==
    86 
    87 The command interpreter is a function which reads key-events (see
    88 section 7.2.1) from the keyboard and dispatches to different commands
    89 on the basis of what the user types.  When the command interpreter
    90 executes a command, we say it invokes the command.  The command
    91 interpreter also provides facilities for communication between
    92 commands contiguously running commands, such as a last command type
    93 register.  It also takes care of resetting communication mechanisms,
    94 clearing the echo area, displaying partial keys typed slowly by the
    95 user, etc.
    96 
    97 *invoke-hook* [Variable]
    98 
    99 This variable contains a function the command interpreter calls when
    100 it wants to invoke a command.  The function receives the command and
    101 the prefix argument as arguments.  The initial value is a function
    102 which simply funcalls the command-function of the command with the
    103 supplied prefix argument.  This is useful for implementing keyboard
    104 macros and similar things.
    105 
    106 Command Abort Hook [Hemlock Variable]
     86== 7.2. The Command Interpreter ==#CommandInterpreter
     87
     88The command interpreter is the functionality invoked by the event
     89handler to process key-events from the keyboard and dispatch to
     90different commands on the basis of what the user types.  When the
     91command interpreter executes a command, we say it invokes the command.  The
     92command interpreter also provides facilities for communication between
     93contiguously running commands, such as a last command type register.
     94It also takes care of resetting communication mechanisms, clearing the
     95echo area, displaying partial keys typed slowly by the user, etc.
     96
     97`Command Abort Hook` [Hemlock Variable]
    10798
    10899The command interpreter invokes the function in this variable whenever
     
    110101editor-error).
    111102
    112 When Hemlock initially starts the command interpreter is in control,
    113 but commands may read from the keyboard themselves and assign whatever
    114 interpretation they will to the key-events read.  Commands may call
    115 the command interpreter recursively using the function recursive-edit
    116 (page 32).
    117 
    118 === 7.2.1. Editor Input ===
     103=== 7.2.1. Editor Input ===#EditorInput
    119104
    120105The canonical representation of editor input is a key-event structure.
    121106Users can bind commands to keys (see section 7.2.2), which are
    122 non-zero length sequences of key-events. A key-event consists of an
    123 identifying token known as akeysymand a field of bits representing
    124 modifiers.  Users define keysyms, integers between 0 and 65535
    125 inclusively, by supplying names that reflect the legends on their
    126 keyboard’s keys. Users define modifier names similarly, but the system
    127 chooses the bit and mask for recognizing the modifier.  You can use
    128 keysym and modifier names to textually specify key-events and Hemlock
    129 keys in a#ksyntax. The following are some examples:
     107non-empty sequences of key-events. A key-event consists of an
     108identifying token known as a keysym and a field of bits representing
     109modifiers.  Users define keysym names by supplying names that reflect
     110the legends on their keyboard's keys. Users define modifier names
     111similarly, but the system chooses the bit and mask for recognizing the
     112modifier.  You can use keysym and modifier names to textually specify
     113key-events and Hemlock keys in a #k syntax. The following are some
     114examples:
    130115
    131116{{{
     
    140125
    141126This is convenient for use within code and in init files
    142 containingbind-keycalls.
    143 
    144 The #k syntax is delimited by double quotes, but the system parses the
    145 contents rather than reading it as a Common Lisp string.  Within the
     127containing `bind-key` calls.
     128
     129The #k syntax is delimited by double quotes.  Within the
    146130double quotes, spaces separate multiple key-events.  A single
    147131key-event optionally starts with modifier names terminated by hyphens.
     
    160144For more information on key-events see section 18.1.
    161145
    162 === 7.2.2. Binding Commands to Keys ===
     146=== 7.2.2. Binding Commands to Keys ===#BindingCommandsToKeys
    163147
    164148The command interpreter determines which command to invoke on the
    165 basis ofkey bindings. A key binding is an association between a
     149basis of ''key bindings''. A key binding is an association between a
    166150command and a sequence of key-events (see section 7.2.1).  A sequence
    167151of key-events is called a key and is represented by a single key-event
     
    172156any given time.  When the command interpreter tries to find the
    173157binding for a key, it first checks if there is a local binding in
    174 thecurrent-buffer (page 9), then if there is a binding in each of the
     158the current buffer (page 9), then if there is a binding in each of the
    175159minor modes and the major mode for the current buffer (page 35), and
    176160finally checks to see if there is a global binding.  If no binding is
     
    178162indicate this.
    179163
    180 bind-keyname key &optional kind where [Function]
    181 
    182 This function associates command name and keyin some environment. Key
     164`bind-key` name key &optional kind where [Function]
     165
     166This function associates command name and key in some environment. Key
    183167is either a key-event or a sequence of key-events.  There are three
    184168possible values of kind:
     
    200184effectively deleting it.
    201185
    202 ext:do-alpha-key-events is useful for setting up bindings in certain new modes.
    203 
    204 command-bindings command [Function]
     186`do-alpha-key-events` is useful for setting up bindings in certain new modes.
     187
     188`command-bindings` command [Function]
    205189
    206190This function returns a list of the places where command is bound.  A
     
    209193local, or nil if it is a global).
    210194
    211 delete-key-bindingkey &optional kind where [Function]
     195`delete-key-binding` key &optional kind where [Function]
    212196
    213197This function removes the binding of key in some place. Key is either
     
    222206See section 7.2.3.
    223207
    224 get-command key &optional kind where [Function]
     208`get-command` key &optional kind where [Function]
    225209
    226210This function returns the command bound to key, returning nil if it is
     
    230214
    231215 :current::
    232   Return the current binding of key using the current buffers search
    233   list.  If there are any transparent key bindings forkey, then they
     216  Return the current binding of key using the current buffer's search
     217  list.  If there are any transparent key bindings for key, then they
    234218  are returned in a list as a second value.
    235219
     
    246230binding.  See section 7.2.3.
    247231
    248 map-bindings function kind &optional where [Function]
     232`map-bindings` function kind &optional where [Function]
    249233
    250234This function maps over the key bindings in some place.  For each
    251235binding, this passes function the key and the command bound to
    252 it. Kind and wher eare the same as in bind-key. The key is not
     236it. Kind and where are the same as in bind-key. The key is not
    253237guaranteed to remain valid after a given iteration.
    254238
    255 === 7.2.3. Key Translation ===
     239=== 7.2.3. Key Translation ===#KeyTranslation
    256240
    257241Key translation is a process that the command interpreter applies to
     
    278262command; otherwise, it will wait for the user to type more key-events.
    279263
    280 key-translation key [Function]
     264`key-translation` key [Function]
    281265
    282266This form is setf-able and allows users to register key translations
    283267that the command interpreter will use as users type key-events.
    284268
    285 This function returns the key translation for key, returning ni lif
     269This function returns the key translation for key, returning nil if
    286270there is none. Key is either a key-event or a sequence of key-events.
    287271If key is a prefix of a translation, then this returns :prefix.
     
    294278translation.
    295279
    296 === 7.2.4. Transparent Key Bindings ===
    297 
    298 Key bindings local to a mode may betransparent. A transparent key
     280=== 7.2.4. Transparent Key Bindings ===#TransparentKeyBindings
     281
     282Key bindings local to a mode may be transparent. A transparent key
    299283binding does not shadow less local key bindings, but rather indicates
    300284that the bound command should be invoked before the first normal key
     
    302286implementing minor modes such as auto fill and word
    303287abbreviation. There may be several transparent key bindings for a
    304 given key, in which case all of the commands bound are invoked in the
     288given key, in which case all of the transparent commands are invoked in the
    305289order they were found. If there no normal key binding for a key typed,
    306290then the command interpreter acts as though the key is unbound even if
     
    308292
    309293The :transparent-p argument to defmode (page 36) determines whether
    310 the key bindings in a mode are transparent or not.
    311 
    312 === 7.2.5. Interactive ===
    313 
    314 Hemlock supports keyboard macros.  A user may enter a mode where the
    315 editor records his actions, and when the user exits this mode, the
    316 command Last Keyboard Macro plays back the actions.  Some commands
    317 behave differently when invoked as part of the definition of a
    318 keyboard macro.  For example, when used in a keyboard macro, a command
    319 that message’s useless user confirmation will slow down the repeated
    320 invocations of Last Keyboard Macro because the command will pause on
    321 each execution to make sure the user sees the message.  This can be
    322 eliminated with the use of interactive. As another example, some
    323 commands conditionally signal an editor-error versus simply beeping
    324 the device depending on whether it executes on behalf of the user or a
    325 keyboard macro.
    326 
    327 interactive [Function]
    328 
    329 This returns t when the user invoked the command directly.
    330 
    331 == 7.3. Command Types ==
     294all the key bindings in a mode are transparent or not.  In addition
     295a particular command may be declared to be transparent by the
     296:transparent-p argument to defcommand and make-command.
     297
     298== 7.3. Command Types ==#CommandTypes
    332299
    333300In many editors the behavior of a command depends on the kind of
    334301command invoked before it. Hemlock provides a mechanism to support
    335 this known as command type.
    336 
    337 last-command-type [Function]
     302this known as `command type`.
     303
     304`last-command-type` [Function]
    338305
    339306This returns the command type of the last command invoked. If this is
     
    344311command is invoked due to a transparent key binding.
    345312
    346 == 7.4. Command Arguments ==
     313== 7.4. Command Arguments ==#CommandArguments
    347314
    348315There are three ways in which a command may be invoked: It may be
     
    354321command is to function properly.
    355322
    356 === 7.4.1. The Prefix Argument ===
     323=== 7.4.1. The Prefix Argument ===#PrefixArgument
    357324
    358325Whenever a command is invoked it is passed as its first argument what
     
    361328repeat count, or some conceptually similar function.
    362329
    363 prefix-argument [Function]
     330`prefix-argument` [Function]
    364331
    365332This function returns the current value of the prefix argument.  When
     
    370337binding.
    371338
    372 === 7.4.2. Lisp Arguments ===
     339=== 7.4.2. Lisp Arguments ===#LispArguments
    373340
    374341It is often desirable to call commands from Lisp code, in which case
     
    377344any arguments not supplied.
    378345
    379 == 7.5. Recursive Edits ==
    380 
    381 use-buffer buffer {form}* [Macro]
    382 
    383 The effect of this is similar to setting the current-buffer
    384 to buffer during the evaluation of forms. There are restrictions placed
    385 on what the code can expect about its environment. In particular, the
    386 value of any global binding of a Hemlock variable which is also a mode
    387 local variable of some mode is ill-defined; if the variable has a
    388 global binding it will be bound, but the value may not be the global
    389 value.  It is also impossible to nest use-buffer’s in different
    390 buffers. The reason for using use-buffer is that it may be significantly
    391 faster than changing current-buffer to buffer and back.
    392 
    393 recursive-edit &optional handle-abort [Function]
    394 
    395 Enter Recursive Edit Hook [Hemlock Variable]
    396 
    397 recursive-edit invokes the command interpreter.  The command
    398 interpreter will read from the keyboard and invoke commands until it
    399 is terminated with either exit-recursive-edit or abort-recursive-edit.
    400 
    401 Normally, an editor-error or C-g aborts the command in progress and
    402 returns control to the top-level command loop. If recursive-edit is
    403 used with handle-abort true, then editor-error or C-g will only abort
    404 back to the recursive command loop.  Before the command interpreter is
    405 entered the hook Enter Recursive Edit Hook is invoked.
    406 
    407 in-recursive-edit [Function]
    408 
    409 This returns whether the calling point is dynamically within a
    410 recursive edit context.
    411 
    412 exit-recursive-edit &optional values-list [Function]
    413 
    414 Exit Recursive Edit Hook [Hemlock Variable]
    415 
    416 exit-recursive-edit exits a recursive edit returning as multiple
    417 values each element of values-list, which defaults to nil. This
    418 invokes Exit Recursive Edit Hook after exiting the command interpreter.
    419 If no recursive edit is in progress, then this signals an error.
    420 
    421 abort-recursive-edit &restargs [Function]
    422 
    423 Abort Recursive Edit Hook [Hemlock Variable]
    424 
    425 abort-recursive-edit terminates a recursive edit by applying
    426 editor-error (page 60) to args after exiting the command
    427 interpreter. This invokes Abort Recursive Edit Hook with args before
    428 aborting the recursive edit.  If no recursive edit is in progress,
    429 then this signals an error.
    430 
     346
     347[HemlockProgrammer Back to Table of Contents]