Changes between Version 1 and Version 2 of HemlockProgrammer/HemlockLispEnvironment


Ignore:
Timestamp:
Jan 15, 2008, 10:16:03 PM (12 years ago)
Author:
gz
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • HemlockProgrammer/HemlockLispEnvironment

    v1 v2  
     1[HemlockProgrammer Back to Table of Contents]
    12[[PageOutline]]
    23
     
    67which concern Hemlock's interaction with the outside world.
    78
    8 == 14.1. Entering and Leaving the Editor ==
     9== 14.1. Entering and Leaving the Editor ==#EnteringAndLeavingTheEditor
    910
    1011ed &optional x [Function]
    1112
    12 Entry Hook [Hemlock Variable]
     13This a standard Common Lisp function.  If x is supplied and is a
     14string or pathname, the file specified by x is visited in a hemlock
     15view (opening a new window if necessary, otherwise bringing an
     16existing window with the file to the front), and the hemlock view
     17object is the return value from the function.
    1318
    14 ed enters the editor.  It is basically as specified in Common Lisp.
    15 If x is supplied and is a symbol, the definition of x is put into a
    16 buffer, and that buffer is selected. If x is a pathname, the file
    17 specified by x is visited in a new buffer.  If x is not supplied or
    18 nil, the editor is entered in the same state as when last exited.
     19If x is null, a new empty hemlock view is created and returned.
    1920
    20 The Entry Hook is invoked each time the editor is entered.
     21If x is a symbol or a setf function name, it attempts to
     22edit the definition of the name.  In this last case, the
     23function returns without waiting for the operation to complete
     24(for example, it might put up a non-modal dialog asking the
     25user to select one of multiple definitions) and hence the
     26return value is always NIL.
    2127
    22 exit-hemlock &optional value [Function]
    2328
    24 Exit Hook [Hemlock Variable]
     29== 14.2. Keyboard Input ==#KeyboardInput
    2530
    26 exit-hemlock leaves Hemlock and return to Lisp; value is the value to
    27 return, which defaults to t.  The hook Exit Hook (page 57) is invoked
    28 before this is done.
    29 
    30 pause-hemlock [Function]
    31 
    32 pause-hemlock suspends the editor process and returns control to the
    33 shell.  When the process is resumed, it will still be running Hemlock.
    34 
    35 == 14.2. Keyboard Input==
    36 
    37 Keyboard input interacts with a number of other parts of the editor.
    38 Since the command loop works by reading from the keyboard, keyboard
    39 input is the initial cause of everything that happens.  Also,
    40 Hemlock redisplays in the low-level input loop when there is no
    41 available input from the user.
    42 
    43 *editor-input* [Variable]
    44 
    45 *real-editor-input* [Variable]
    46 
    47 Input Hook [Hemlock Variable]
    48 
    49 Abort Hook [Hemlock Variable]
    50 
    51 *editor-input* is an object on which Hemlock's I/O routines operate.
    52 You can get input, clear input, return input, and listen for input.
    53 Input appears as key-events.
    54 
    55 *real-editor-input* holds the initial value of *editor-input*. This is
    56 useful for reading from the user when *editor-input* is rebound (such as
    57 within a keyboard macro.)
    58 
    59 Hemlock invokes the functions in Input Hook each time someone reads a
    60 key-event from *real-editor-input*. These take no arguments.
    61 
    62 get-key-event editor-input &optional ignore-abort-attempts-p [Function]
    63 
    64 This function returns a key-event as soon as it is available on
    65 editor-input. Editor-input is either *editor-input* or
    66 *real-editor-input*. Ignore-abort-attempts-p indicates whether C-g and
    67 C-G throw to the editor's top-level command loop; when this is
    68 non-nil, this function returns those key-events when the user types
    69 them.  Otherwise, it aborts the editor's current state, returning to
    70 the command loop.
    71 
    72 When the user aborts, Hemlock invokes the functions in Abort
    73 Hook. These functions take no arguments. When aborting, Hemlock
    74 ignores the Input Hook.
    75 
    76 unget-key-event key-event editor-input [Function]
    77 
    78 This function returns key-event to editor-input, so the next
    79 invocation of get-key-event will return key-event. If key-event is
    80 #k"C-g" or #k"C-G", then whether get-key-event returns it depends on
    81 that function's second argument. Editor-input is either *editor-input*
    82 or *real-editor-input*.
    83 
    84 clear-editor-input editor-input [Function]
    85 
    86 This function flushes any pending input on editor-input. Editor-input
    87 is either *editor-input* or *real-editor-input*.
    88 
    89 listen-editor-inputeditor-input [Function]
    90 
    91 This function returns whether there is any input available on editor-input. Editor-input is either *editor-input* or *real-editor-input*.
    92 
    93 editor-sleep time [Function]
    94 
    95 Return either after time seconds have elapsed or when input is available
    96 on *editor-input*.
    97 
    98 *key-event-history* [Variable]
     31`*key-event-history*` [Variable]
    9932
    10033This is a Hemlock ring buffer (see page 70) that holds the last 60
    101 key-events read from the keyboard.
     34key-events received.
    10235
    103 *last-key-event-typed* [Variable]
     36`last-key-event-typed` [Function]
    10437
    105 Commands use this variable to realize the last key-event the user
    106 typed to invoke the commands. Before Hemlock ever reads any input, the
    107 value is nil. This variable usually holds the last key-event read from
    108 the keyboard, but it is also maintained within keyboard macros
    109 allowing commands to behave the same on each repetition as they did in
    110 the recording invocation.
     38This function returns the last key-event the user typed to invoke the current command.
    11139
    112 *input-transcript* [Variable]
     40`last-char-typed` [Function]
    11341
    114 If this is non-nil then it should be an adjustable vector with a
    115 fill-pointer.  When it is non-nil, Hemlock pushes all input read onto
    116 this vector.
     42This function returns the character corresponding to the last key event typed.
    11743
    118 == 14.3. Hemlock Streams ==
     44
     45== 14.3. Hemlock Streams ==#HemlockStreams
    11946
    12047It is possible to create streams which output to or get input from a
     
    12249of Hemlock to Lisp.
    12350
    124 make-hemlock-output-stream mark &optional buffered [Function]
     51Note that operations on these streams operate directly on buffers,
     52therefore they have the same restrictions as described [HemlockProgrammer/Buffers here]
     53for interacting with buffers from outside of the GUI thread.
    12554
    126 hemlock-output-stream-p object [Function]
     55`make-hemlock-output-stream` mark &optional buffered [Function]
    12756
    128 make-hemlock-output-stream returns a stream that inserts at the
    129 permanent mark mark all output directed to it. Buffered controls
    130 whether the stream is buffered or not, and its valid values are the
    131 following keywords:
     57This function returns a stream that inserts at mark all
     58output directed to it.  It works best if mark is a left-inserting mark.
     59Buffered controls whether the stream is buffered or not, and its valid values
     60are the following keywords:
    13261
    13362 :none::
     
    13968
    14069 :full::
    141  The screen is only brought up to date when it is explicitly
     70 The stream is only brought up to date when it is explicitly
    14271 done with force-output
    14372
    144 hemlock-output-stream-p returns t if object is a hemlock-output-stream object.
     73`hemlock-output-stream-p` object [Function]
    14574
    146 make-hemlock-region-stream region [Function]
     75This function returns t if object is a hemlock-output-stream object.
    14776
    148 hemlock-region-stream-p object [Function]
     77`make-hemlock-region-stream` region [Function]
    14978
    150 make-hemlock-region-stream returns a stream from which the text in
     79This function returns a stream from which the text in
    15180region can be read.
    15281
    153 hemlock-region-stream-p returns t if object is a hemlock-region-stream object.
     82`hemlock-region-stream-p` object [Function]
    15483
    155 with-input-from-region (var region) {declaration}* {form}* [Macro]
     84This function returns t if object is a hemlock-region-stream object.
     85
     86`with-input-from-region` (var region) {declaration}* {form}* [Macro]
    15687
    15788While evaluating forms, binds var to a stream which returns input from region.
    15889
    159 with-output-to-mark (var mark [buffered]) {declaration}* {form}* [Macro]
     90`with-output-to-mark` (var mark [buffered]) {declaration}* {form}* [Macro]
    16091
    161 During the evaluation of theforms, bindsvarto a stream which inserts
     92During the evaluation of the forms, binds var to a stream which inserts
    16293output at the permanent mark.  Buffered has the same meaning as for
    16394make-hemlock-output-stream.
    16495
    165 with-pop-up-display (var &keyheight name) {declaration}* {form}* [Macro]
    166 
    167 *random-typeout-buffers* [Variable]
     96`with-pop-up-display` (var &key height name) {declaration}* {form}* [Macro]
    16897
    16998This macro executes forms in a context with var bound to a
     
    171100display of the appropriate height containing all the output.  When
    172101height is supplied, Hemlock creates the pop-up display immediately,
    173 forcing output on line breaks.  The system saves the output in a
    174 buffer named name, which defaults to Random Typeout. When the window
    175 is the incorrect height, the display mechanism will scroll the window
    176 with more-style prompting.  This is useful for displaying information
     102forcing output on line breaks.  This is useful for displaying information
    177103of temporary interest.
    178104
    179 When a buffer with name name already exists and was not previously
    180 created by with-pop-up-display,Hemlock signals an error.
     105== 14.4. Interface to the Error System ==#InterfaceToTheErrorSystem
    181106
    182 *random-typeout-buffers* is an association list mapping random typeout
    183 buffers to the streams that operate on the buffers.
     107Hemlock commands are executed from an event handler in the initial
     108Cocoa thread.  They are executed within a
     109ccl::with-standard-abort-handling form, which means cl:abort,
     110ccl:abort-break, ccl:throw-cancel will abort the current command only
     111and exit the event handler in an orderly fashion.
    184112
    185 == 14.4. Interface to the Error System ==
     113In addition, for now, lisp errors during command execution dump a
     114backtrace in the system console and are otherwise handled as if by
     115`handle-lisp-errors` below, which means it is not possible to debug
     116errors at the point of the error.  Once Clozure CL has better support
     117for debugging errors in the initial Cocoa thread, better Hemlock error
     118handling will be provided that will allow for some way to debug.
    186119
    187 The error system interface is minimal.  There is a simple editor-error
    188 condition which is a subtype of error and a convenient means for
    189 signaling them. Hemlock also provides a standard handler for error
    190 conditions while in the editor.
     120`editor-error` &rest args [Function]
    191121
    192 editor-error-format-string condition [Function]
     122This function is called to report minor errors to the user.  These are
     123errors that a normal user could encounter in the course of editing,
     124such as a search failing or an attempt to delete past the end of the
     125buffer. This function simply aborts the current command.  Any args
     126specified are used to format an error message to be placed in the echo
     127area.  This function never returns.
    193128
    194 editor-error-format-arguments condition [Function]
    195 
    196 Handlers for editor-error conditions can access the condition object with these.
    197 
    198 editor-error &rest args [Function]
    199 
    200 This function is called to signal minor errors within Hemlock; these
    201 are errors that a normal user could encounter in the course of editing
    202 such as a search failing or an attempt to delete past the end of the
    203 buffer. This function signals an editor-error condition formed from
    204 args, which are nil or a format string possibly followed by format
    205 arguments. Hemlock invokes commands in a dynamic context with an
    206 editor-error condition handler bound.  This default handler beeps or
    207 flashes (or both) the display. If the condition passed to the handler
    208 has a non-nil string slot, the handler also invokes message on it.
    209 The command in progress is always aborted, and this function never
    210 returns.
    211 
    212 handle-lisp-errors{form}* [Macro]
     129`handle-lisp-errors` {form}* [Macro]
    213130
    214131Within the body of this macro any Lisp errors that occur are handled
    215 in some fashion more gracefully than simply dumping the user in the
    216 debugger.  This macro should be wrapped around code which may get an
    217 error due to some action of the user---for example, evaluating code
    218 fragments on the behalf of and supplied by the user.  Using this in a
    219 command allows the established handler to shadow the default
    220 editor-error handler, so commands should take care to signal user
    221 errors (calls to editor-errors) outside of this context.
     132by displaying an error message in a dialog and aborting the current
     133command, leaving the error text in the echo area.  This macro should
     134be wrapped around code which may get an error due to some action of
     135the user --- for example, evaluating code fragments on the behalf of
     136and supplied by the user.
    222137
    223 == 14.5. Definition Editing ==
     138== 14.5. Definition Editing ==#DefinitionEditing
    224139
    225 Hemlock provides commands for finding the definition of a function,
    226 macro, or command and placing the user at the definition in a buffer.
    227 This, of course, is implementation dependent, and if an implementation
    228 does not associate a source file with a routine, or if Hemlock cannot
    229 get at the information, then these commands do not work.  If the Lisp
    230 system does not store an absolute pathname, independent of the machine
    231 on which the maintainer built the system, then users need a way of
    232 translating a source pathname to one that will be able to locate the
    233 source.
     140Hemlock provides commands for finding the definition of a function
     141or variable and placing the user at the definition in a buffer. A
     142function is provided to allow invoking this functionality outside
     143of Hemlock.  Note that this function is unusual in that it is
     144it is safe to call outside of the command interpreter, and in fact
     145it can be called from any thread.
    234146
    235 add-definition-dir-translation dir1 dir2 [Function]
     147`edit-definition` name [Function]
    236148
    237 This maps directory pathname dir1 to dir2. Successive invocations
    238 using the same dir1 push into a translation list.  When Hemlock seeks a
    239 definition source file, and it has a translation, then it tries the
    240 translations in order.  This is useful if your sources are on various
    241 machines, some of which may be down. When Hemlock tries to find a
    242 translation, it first looks for translations of longer directory
    243 pathnames, finding more specific translations before shorter, more
    244 general ones.
     149This function tries to find the definition of `name`, create
     150or activate the window containing it, and scroll the view
     151to show the definition.  If there are multiple definitions
     152available, the user is given a choice of which one to
     153use.  This function may return before the operation is complete.
    245154
    246 delete-definition-dir-translation dir [Function]
    247155
    248 This deletes the mapping of dir to all directories to which it has
    249 been mapped.
     156== 14.6. Event Scheduling ==#EventScheduling
    250157
    251 == 14.6. Event Scheduling ==
     158No Event Scheduling functionality is provided at this time.
    252159
    253 The mechanism described in this chapter is only operative when the
    254 Lisp process is actually running inside of Hemlock, within the ed
    255 function. The designers intended its use to be associated with the
    256 editor, such as with auto-saving files, reminding the user, etc.
     160== 14.7. Miscellaneous ==#Miscellaneous
    257161
    258 schedule-event time function &optional repeat [Function]
    259 
    260 This causes Hemlock to call function after time seconds have passed,
    261 optionally repeating every time seconds. Repeat defaults to t. This is
    262 a rough mechanism since commands can take an arbitrary amount of time
    263 to run; Hemlock invokes function at the first possible moment after
    264 time has elapsed. Function takes the time in seconds that has elapsed
    265 since the last time it was called (or since it was scheduled for the
    266 first invocation).
    267 
    268 remove-scheduled-eventfunction [Function]
    269 
    270 This removes function from the scheduling queue. Function does not
    271 have to be in the queue.
    272 
    273 == 14.7. Miscellaneous ==
    274 
    275 in-lisp{form}* [Function]
     162`in-lisp` {form}* [Function]
    276163
    277164This evaluates forms inside handle-lisp-errors. It also binds
     
    279166non-nil. Use this when evaluating Lisp code on behalf of the user.
    280167
    281 do-alpha-chars (var kind [result) {form}*] [Macro]
     168`do-alpha-chars` (var kind [result]) {form}* [Macro]
    282169
    283170This iterates over alphabetic characters in Common Lisp binding var to
     
    286173the user supplies :both, lowercase characters are processed first.
    287174
     175
     176[HemlockProgrammer Back to Table of Contents]