Changes between Initial Version and Version 1 of HemlockUser/InteractingWithLisp


Ignore:
Timestamp:
11/05/07 17:58:18 (7 years ago)
Author:
rme
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • HemlockUser/InteractingWithLisp

    v1 v1  
     1[[PageOutline]] 
     2 
     3= 9 Interacting With Lisp = 
     4 
     5Lisp encourages highly interactive programming environments by 
     6requiring decisions about object type and function definition to be 
     7postponed until run time. Hemlock supports interactive programming in 
     8Lisp by providing incremental redefinition and environment examination 
     9commands. Hemlock also uses Unix TCP sockets to support multiple Lisp 
     10processes, each of which may be on any machine. 
     11 
     12== 9.1 Eval Servers == 
     13 
     14Hemlock runs in the editor process and interacts with other Lisp 
     15processes called eval servers. A user's Lisp program normally runs in 
     16an eval server process. The separation between editor and eval server 
     17has several advantages: 
     18 
     19 * The editor is protected from any bad things which may happen while 
     20   debugging a Lisp program. 
     21 
     22 * Editing may occur while running a Lisp program. 
     23 
     24 * The eval server may be on a different machine, removing the load 
     25   from the editing machine. 
     26 
     27 * Multiple eval servers allow the use of several distinct Lisp 
     28   environments. 
     29 
     30Instead of providing an interface to a single Lisp environment, 
     31Hemlock coordinates multiple Lisp environments. 
     32 
     33=== 9.1.1 The Current Eval Server === 
     34 
     35Although Hemlock can be connected to several eval servers 
     36simultaneously, one eval server is designated as the current eval 
     37server. This is the eval server used to handle evaluation and 
     38compilation requests. Eval servers are referred to by name so that 
     39there is a convenient way to discriminate between servers when the 
     40editor is connected to more than one. The current eval server is 
     41normally globally specified, but it may also be shadowed locally in 
     42specific buffers. 
     43 
     44Set Eval Server                  [Command] 
     45 
     46Set Buffer Eval Server                   [Command] 
     47 
     48Current Eval Server              [Command] 
     49 
     50Set Eval Server prompts for the name of an eval server and makes it 
     51the the current eval server. Set Buffer Eval Server is the same except 
     52that is sets the eval server for the current buffer only. Current Eval 
     53Server displays the name of the current eval server in the echo area, 
     54taking any buffer eval server into consideration. See also Set Compile 
     55Server. 
     56 
     57 
     58=== 9.1.2 Slaves === 
     59 
     60For now, all eval servers are slaves. A slave is a Lisp process that 
     61uses a typescript (see page 9.2) to run its top-level read-eval-print 
     62loop in a Hemlock buffer. We refer to the buffer that a slave uses for 
     63I/O as its interactive or slave buffer. The name of the interactive 
     64buffer is the same as the eval server's name. 
     65 
     66Hemlock creates a background buffer for each eval server. The 
     67background buffer's name is Background name, where name is the name of 
     68the eval server. Slaves direct compiler warning output to the 
     69background buffer to avoid cluttering up the interactive buffer. 
     70 
     71Hemlock locally sets Current Eval Server in interactive and background 
     72buffers to their associated slave. When in a slave or background 
     73buffer, eval server requests will go to the associated slave, 
     74regardless of the global value of Current Eval Server. 
     75 
     76Select Slave    (bound to C-M-c)         [Command] 
     77 
     78This command changes the current buffer to the current eval server's 
     79interactive buffer. If the current eval server is not a slave, then it 
     80beeps. If there is no current eval server, then this creates a slave 
     81(see section 9.1.3). If a prefix argument is supplied, then this 
     82creates a new slave regardless of whether there is a current eval 
     83server. This command is the standard way to create a slave. 
     84 
     85The slave buffer is a typescript (see page 9.2) the slave uses for its 
     86top-level read-eval-print loop. 
     87 
     88 
     89 
     90Select Background       (bound to C-M-C)         [Command] 
     91 
     92This command changes the current buffer to the current eval server's 
     93background buffer. If there is no current eval server, then it beeps. 
     94 
     95 
     96 
     97=== 9.1.3 Slave Creation and Destruction === 
     98 
     99When Hemlock first starts up, there is no current eval server. If 
     100there is no a current eval server, commands that need to use the 
     101current eval server will create a slave as the current eval server. 
     102 
     103If an eval server's Lisp process terminates, then we say the eval 
     104server is dead. Hemlock displays a message in the echo area, 
     105interactive, and background buffers whenever an eval server dies. If 
     106the user deletes an interactive or background buffer, the associated 
     107eval server effectively becomes impotent, but Hemlock does not try to 
     108kill the process. If a command attempts to use a dead eval server, 
     109then the command will beep and display a message. 
     110 
     111Confirm Slave Creation          (initial value t)        [Variable] 
     112 
     113If this variable is true, then Hemlock always prompts the user for 
     114confirmation before creating a slave. 
     115 
     116 
     117 
     118Ask About Old Servers   (initial value t)        [Variable] 
     119 
     120If this variable is true, and some slave already exists, Hemlock 
     121prompts the user for the name of an existing server when there is no 
     122current server, instead of creating a new one. 
     123 
     124 
     125 
     126Editor Server Name               [Command] 
     127 
     128This command echos the editor server's name, the machine and port of 
     129the editor, which is suitable for use with the Lisp processes -slave 
     130switch. See section 9.10. 
     131 
     132 
     133 
     134Accept Slave Connections                 [Command] 
     135 
     136This command cause Hemlock to accept slave connections, and it 
     137displays the editor server's name, which is suitable for use with the 
     138Lisp processes -slave switch. See section 9.10. Supplying an argument 
     139causes this command to inhibit slave connections. 
     140 
     141 
     142 
     143Slave Utility   (initial value "/usr/misc/.lisp/bin/lisp")       [Variable] 
     144 
     145Slave Utility Switches          (initial value )         [Variable] 
     146 
     147A slave is started by running the program Slave Utility Name with 
     148arguments specified by the list of strings Slave Utility 
     149Switches. This is useful primarily when running customized Lisp 
     150systems. For example, setting Slave Utility Switches to ("-core" 
     151"my.core") will cause "/usr/hqb/my.core" to be used instead of the 
     152default core image. 
     153 
     154The -slave switch and the editor name are always supplied as 
     155arguments, and should remain unspecified in Slave Utility Switches. 
     156 
     157 
     158 
     159Kill Slave               [Command] 
     160 
     161Kill Slave and Buffers                   [Command] 
     162 
     163Kill Slave prompts for a slave name, aborts any operations in the 
     164slave, tells the slave to quit, and shuts down the connection to the 
     165specified eval server. This makes no attempt to assure the eval server 
     166actually dies. 
     167 
     168Kill Slave and Buffers is the same as Kill Slave, but it also deletes 
     169the interactive and background buffers. 
     170 
     171 
     172 
     173=== 9.1.4 Eval Server Operations === 
     174 
     175Hemlock handles requests for compilation or evaluation by queuing an 
     176operation on the current eval server. Any number of operations may be 
     177queued, but each eval server can only service one operation at a 
     178time. Information about the progress of operations is displayed in the 
     179echo area. 
     180 
     181Abort Operations        (bound to C-c a)         [Command] 
     182 
     183This command aborts all operations on the current eval server, either 
     184queued or in progress. Any operations already in the Aborted state 
     185will be flushed. 
     186 
     187 
     188 
     189List Operations         (bound to C-c l)         [Command] 
     190 
     191This command lists all operations which have not yet completed. Along 
     192with a description of the operation, the state and eval server is 
     193displayed. The following states are used: 
     194 
     195 Unsent:: 
     196  The operation is in local queue in the editor, and hasn't been sent yet. 
     197 
     198 Pending:: 
     199  The operation has been sent, but has not yet started execution. 
     200 
     201 Running:: 
     202  The operation is currently being processed. 
     203 
     204 Aborted:: 
     205  The operation has been aborted, but the eval server has not yet 
     206  indicated termination. 
     207 
     208== 9.2 Typescripts == 
     209 
     210Both slave buffers and background buffers are typescripts. The 
     211typescript protocol allows other processes to do stream-oriented 
     212interaction in a Hemlock buffer similar to that of a terminal. When 
     213there is a typescript in a buffer, the Typescript minor mode is 
     214present. Some of the commands described in this section are also used 
     215by Eval mode (page 9.9.2.) 
     216 
     217Typescripts are simple to use. Hemlock inserts output from the process 
     218into the buffer. To give the process input, use normal editing to 
     219insert the input at the end of the buffer, and then type Return to 
     220confirm sending the input to the process. 
     221 
     222Confirm Typescript Input                 [Command] 
     223 
     224Unwedge Interactive Input Confirm       (initial value t)        [Variable] 
     225 
     226This command sends text that has been inserted at the end of the 
     227current buffer to the process reading on the buffer's 
     228typescript. Before sending the text, Hemlock moves the point to the 
     229end of the buffer and inserts a newline. 
     230 
     231Input may be edited as much as is desired before it is confirmed; the 
     232result of editing input after it has been confirmed is 
     233unpredictable. For this reason, it is desirable to postpone confirming 
     234of input until it is actually complete. The Indent New Line command is 
     235often useful for inserting newlines without confirming the input. 
     236 
     237If the process reading on the buffer's typescript is not waiting for 
     238input, then the text is queued instead of being sent immediately. Any 
     239number of inputs may be typed ahead in this fashion. Hemlock makes 
     240sure that the inputs and outputs get interleaved correctly so that 
     241when all input has been read, the buffer looks the same as it would 
     242have if the input had not been typed ahead. 
     243 
     244If the buffer's point is before the start of the input area, then 
     245various actions can occur. When set, Unwedge Interactive Input Confirm 
     246causes Hemlock to ask the user if it should fix the input buffer which 
     247typically results in ignoring any current input and refreshing the 
     248input area at the end of the buffer. This also has the effect of 
     249throwing the slave Lisp to top level, which aborts any pending 
     250operations or queued input. This is the only way to be sure the user 
     251is cleanly set up again after messing up the input region. When this 
     252is nil, Hemlock simply beeps and tells the user in the Echo Area that 
     253the input area is invalid. 
     254 
     255 
     256Kill Interactive Input                   [Command] 
     257 
     258This command kills any input that would have been confirmed by Return. 
     259 
     260 
     261 
     262Next Interactive Input                   [Command] 
     263 
     264Previous Interactive Input               [Command] 
     265 
     266Search Previous Interactive Input                [Command] 
     267 
     268Interactive History Length      (initial value 10)       [Variable] 
     269 
     270Minimum Interactive Input Length        (initial value 2)        [Variable] 
     271 
     272Hemlock maintains a history of interactive inputs. Next Interactive 
     273Input and Previous Interactive Input step forward and backward in the 
     274history, inserting the current entry in the buffer. The prefix 
     275argument is used as a repeat count. 
     276 
     277Search Previous Interactive Input searches backward through the 
     278interactive history using the current input as a search 
     279string. Consecutive invocations repeat the previous search. 
     280 
     281Interactive History Length determines the number of entries with which 
     282Hemlock creates the buffer-specific histories. Hemlock only adds an 
     283input region to the history if its number of characters exceeds 
     284Minimum Interactive Input Length. 
     285 
     286 
     287 
     288Reenter Interactive Input                [Command] 
     289 
     290This copies to the end of the buffer the form to the left of the 
     291buffer's point. When the current region is active, this copies it 
     292instead. This is sometimes easier to use to get a previous input that 
     293is either so far back that it has fallen off the history or is visible 
     294and more readily yanked than gotten with successive invocations of the 
     295history commands. 
     296 
     297 
     298 
     299Interactive Beginning of Line            [Command] 
     300 
     301This command is identical to Beginning of Line unless there is no 
     302prefix argument and the point is on the same line as the start of the 
     303current input; then it moves to the beginning of the input. This is 
     304useful since it skips over any prompt which may be present. 
     305 
     306 
     307 
     308Input Wait Alarm        (initial value :loud-message)    [Variable] 
     309 
     310Slave GC Alarm          (initial value :message)         [Variable] 
     311 
     312Input Wait Alarm determines what action to take when a slave Lisp goes 
     313into an input wait on a typescript that isn't currently displayed in 
     314any window. Slave GC Alarm determines what action to take when a slave 
     315notifies that it is GC'ing. 
     316 
     317The following are legal values: 
     318 
     319 :loud-message:: 
     320  Beep and display a message in the echo area indicating which buffer 
     321  is waiting for input. 
     322 
     323 :message:: 
     324  Display a message, but don't beep. 
     325 
     326 nil:: 
     327  Don't do anything. 
     328 
     329 
     330Typescript Slave BREAK          (bound to Typescript: H-b)       [Command] 
     331 
     332Typescript Slave to Top Level   (bound to Typescript: H-g)       [Command] 
     333 
     334Typescript Slave Status         (bound to Typescript: H-s)       [Command] 
     335 
     336Some typescripts have associated information which these commands 
     337access allowing Hemlock to control the process which uses the 
     338typescript. 
     339 
     340Typescript Slave BREAK puts the current process in a break loop so 
     341that you can be debug it. This is similar in effect to an interrupt 
     342signal (^C or ^\ in the editor process). 
     343 
     344Typescript Slave to Top Level causes the current process to throw to 
     345the top-level read-eval-print loop. This is similar in effect to a 
     346quit signal (^\). 
     347 
     348Typescript Slave Status causes the current process to print status 
     349information on error-output: ; Used 0:06:03, 3851 faults. In: 
     350SYSTEM:SERVE-EVENT The message displays the process run-time, the 
     351total number of page faults and the name of the currently running 
     352function. This command is useful for determining whether the slave is 
     353in an infinite loop, waiting for input, or whatever. 
     354 
     355== 9.3 The Current Package == 
     356 
     357The current package is the package which Lisp interaction commands 
     358use. The current package is specified on a per-buffer basis, and 
     359defaults to "USER". If the current package does not exist in the eval 
     360server, then it is created. If evaluation is being done in the editor 
     361process and the current package doesn't exist, then the value of 
     362*package* is used. The current package is displayed in the modeline 
     363(see section 3.3.) Normally the package for each file is specified 
     364using the Package file option (see page 3.3.3.) 
     365 
     366When in a slave buffer, the current package is controlled by the value 
     367of package in that Lisp process. Modeline display of the current 
     368package is inhibited in this case. 
     369 
     370Set Buffer Package               [Command] 
     371 
     372This command prompts for the name of a package to make the local 
     373package in the current buffer. If the current buffer is a slave, 
     374background, or eval buffer, then this sets the current package in the 
     375associated eval server or editor Lisp. When in an interactive buffer, 
     376do not use in-package; use this command instead. 
     377 
     378== 9.4 Compiling and Evaluating Lisp Code == 
     379 
     380These commands can greatly speed up the edit/debug cycle since they 
     381enable incremental reevaluation or recompilation of changed code, 
     382avoiding the need to compile and load an entire file. 
     383 
     384Evaluate Expression     (bound to M-Escape)      [Command] 
     385 
     386This command prompts for an expression and prints the result of its 
     387evaluation in the echo area. If an error happens during evaluation, 
     388the evaluation is simply aborted, instead of going into the 
     389debugger. This command doesn't return until the evaluation is 
     390complete. 
     391 
     392 
     393 
     394Evaluate Defun          (bound to C-x C-e)       [Command] 
     395 
     396Evaluate Region                  [Command] 
     397 
     398Evaluate Buffer                  [Command] 
     399 
     400These commands evaluate text out of the current buffer, reading the 
     401current defun, the region and the entire buffer, respectively. The 
     402result of the evaluation of each form is displayed in the echo 
     403area. If the region is active, then Evaluate Defun evaluates the 
     404current region, just like Evaluate Region. 
     405 
     406 
     407 
     408Macroexpand Expression          (bound to C-M)   [Command] 
     409 
     410This command shows the macroexpansion of the next expression in the 
     411null environment in a pop-up window. With an argument, it uses 
     412macroexpand instead of macroexpand-1. 
     413 
     414 
     415 
     416Re-evaluate Defvar               [Command] 
     417 
     418This command is similar to Evaluate Defun. It is used for force the re-evaluation of a defvar init form. If the current top-level form is a defvar, then it does a makunbound on the variable, and evaluates the form. 
     419 
     420 
     421 
     422Compile Defun   (bound to C-x C-c)       [Command] 
     423Compile Region                   [Command] 
     424 
     425These commands compile the text in the current defun and the region, respectively. If the region is active, then Compile Defun compiles the current region, just like Compile Region. 
     426 
     427 
     428 
     429Load File                [Command] 
     430Load Pathname Defaults          (initial value nil)      [Variable] 
     431 
     432This command prompts for a file and loads it into the current eval server using load. Load Pathname Defaults contains the default pathname for this command. This variable is set to the file loaded; if it is nil, then there is no default. This command also uses the Remote Compile File variable. 
     433 
     434 
     435 
     436== 9.5 Compiling Files == 
     437 
     438These commands are used to compile source (".lisp") files, producing 
     439binary (".fasl") output files. Note that unlike the other compiling 
     440and evalating commands, this does not have the effect of placing the 
     441definitions in the environment; to do so, the binary file must be 
     442loaded. 
     443 
     444Compile Buffer File     (bound to C-x c)         [Command] 
     445 
     446Compile Buffer File Confirm     (initial value t)        [Variable] 
     447 
     448This command asks for confirmation, then saves the current buffer 
     449(when modified) and compiles the associated file. The confirmation 
     450prompt indicates intent to save and compile or just compile. If the 
     451buffer wasn't modified, and a comparison of the write dates for the 
     452source and corresponding binary (".fasl") file suggests that 
     453recompilation is unnecessary, the confirmation also indicates this. A 
     454prefix argument overrides this test and forces recompilation. Since 
     455there is a complete log of output in the background buffer, the 
     456creation of the normal error output (".err") file is 
     457inhibited. 
     458 
     459Setting Compile Buffer File Confirm to nil inhibits confirmation, 
     460except when the binary is up to date and a prefix argument is not 
     461supplied. 
     462 
     463 
     464Compile File             [Command] 
     465 
     466This command prompts for a file and compiles that file, providing a 
     467convenient way to compile a file that isn't in any buffer. Unlike 
     468Compile Buffer File, this command doesn't do any consistency checks 
     469such as checking whether the source is in a modified buffer or the 
     470binary is up to date. 
     471 
     472 
     473 
     474Compile Group            [Command] 
     475 
     476List Compile Group               [Command] 
     477 
     478Compile Group does a Save All Files and then compiles every ".lisp" 
     479file for which the corresponding ".fasl" file is older or 
     480nonexistent. The files are compiled in the order in which they appear 
     481in the group definition. A prefix argument forces compilation of all 
     482".lisp" files. 
     483 
     484List Compile Group lists any files that would be compiled by Compile 
     485Group. All Modified files are saved before checking to generate a 
     486consistent list. 
     487 
     488Set Compile Server               [Command] 
     489 
     490Set Buffer Compile Server                [Command] 
     491 
     492Current Compile Server                   [Command] 
     493 
     494These commands are analogous to Set Eval Server, Set Buffer Eval 
     495Server and Current Eval Server, but they determine the eval server 
     496used for file compilation requests. If the user specifies a compile 
     497server, then the file compilation commands send compilation requests 
     498to that server instead of the current eval server. 
     499 
     500Having a separate compile server makes it easy to do compilations in 
     501the background while continuing to interact with your eval server and 
     502editor. The compile server can also run on a remote machine relieving 
     503your active development machine of the compilation effort. 
     504 
     505 
     506 
     507Next Compiler Error     (bound to H-n)   [Command] 
     508 
     509Previous Compiler Error         (bound to H-p)   [Command] 
     510 
     511These commands provides a convenient way to inspect compiler 
     512errors. First it splits the current window if there is only one window 
     513present. Hemlock positions the current point in the first window at 
     514the erroneous source code for the next (or previous) error. Then in 
     515the second window, it displays the error beginning at the top of the 
     516window. Given an argument, this command skips that many 
     517errors. 
     518 
     519 
     520 
     521Flush Compiler Error Information                 [Command] 
     522 
     523This command relieves the current eval server of all infomation about 
     524errors encountered while compiling. This is convenient if you have 
     525been compiling a lot, but you were ignoring errors and warnings. You 
     526don't want to step through all the old errors, so you can use this 
     527command immediately before compiling a file whose errors you intend to 
     528edit. 
     529 
     530 
     531 
     532Remote Compile File     (initial value nil)      [Variable] 
     533 
     534When true, this variable causes file compilations to be done using the 
     535RFS remote file system mechanism by prepending "/../host" to the file 
     536being compiled. This allows the compile server to be run on a 
     537different machine, but requires that the source be world readable. If 
     538false, commands use source filenames directly. Do NOT use this to 
     539compile files in AFS. 
     540 
     541== 9.6 Querying the Environment == 
     542 
     543These commands are useful for obtaining various random information 
     544from the Lisp environment. 
     545 
     546Describe Function Call          (bound to C-M-A)         [Command] 
     547 
     548Describe Symbol         (bound to C-M-S)         [Command] 
     549 
     550Describe Function Call uses the current eval server to describe the 
     551symbol found at the head of the currently enclosing list, displaying 
     552the output in a pop-up window. Describe Symbol is the same except that 
     553it describes the symbol at or before the point. These commands are 
     554primarily useful for finding the documentation for functions and 
     555variables. If there is no currently valid eval server, then this 
     556command uses the editor Lisp's environment instead of trying to spawn 
     557a slave. 
     558 
     559== 9.7 Editing Definitions == 
     560 
     561The Lisp compiler annotates each compiled function object with the 
     562source file that the function was originally defined from. The 
     563definition editing commands use this information to locate and edit 
     564the source for functions defined in the environment. 
     565 
     566Edit Definition                  [Command] 
     567 
     568Goto Definition         (bound to C-M-F)         [Command] 
     569 
     570Edit Command Definition                  [Command] 
     571 
     572Edit Definition prompts for the name of a function, and then uses the 
     573current eval server to find out in which file the function is 
     574defined. If something other than defun or defmacro defined the 
     575function, then this simply reads in the file, without trying to find 
     576its definition point within the file. If the function is uncompiled, 
     577then this looks for it in the current buffer. If there is no currently 
     578valid eval server, then this command uses the editor Lisp's 
     579environment instead of trying to spawn a slave. 
     580 
     581Goto Definition edits the definition of the symbol at the beginning of 
     582the current list. 
     583 
     584Edit Command Definition edits the definition of a Hemlock command. By 
     585default, this command does a keyword prompt for the command name (as 
     586in an extended command). If a prefix argument is specified, then 
     587instead prompt for a key and edit the definition of the command bound 
     588to that key. 
     589 
     590 
     591 
     592Add Definition Directory Translation             [Command] 
     593 
     594Delete Definition Directory Translation                  [Command] 
     595 
     596The defining file is recorded as an absolute pathname. The definition 
     597editing commands have a directory translation mechanism that allow the 
     598sources to be found when they are not in the location where 
     599compilation was originally done. Add Definition Directory Translation 
     600prompts for two directory namestrings and causes the first to be 
     601mapped to the second. Longer (more specific) directory specifications 
     602are matched before shorter (more general) ones. 
     603 
     604Delete Definition Directory Translation prompts for a directory 
     605namestring and deletes it from the directory translation 
     606table. 
     607 
     608 
     609 
     610Editor Definition Info          (initial value nil)      [Variable] 
     611 
     612When this variable is true, the editor Lisp is used to determine 
     613definition editing information, otherwise the current eval server is 
     614used. This variable is true in Eval and Editor modes. 
     615 
     616== 9.8 Debugging == 
     617 
     618These commands manipulate the slave when it is in the debugger and 
     619provide source editing based on the debugger's current frame. These 
     620all affect the Current Eval Server. 
     621 
     622=== 9.8.1 Changing Frames === 
     623 
     624Debug Down      (bound to C-M-H-d)       [Command] 
     625 
     626This command moves down one debugger frame. 
     627 
     628 
     629 
     630Debug Up        (bound to C-M-H-u)       [Command] 
     631 
     632This command moves up one debugger frame. 
     633 
     634 
     635 
     636Debug Top       (bound to C-M-H-t)       [Command] 
     637 
     638This command moves to the top of the debugging stack. 
     639 
     640 
     641 
     642Debug Bottom    (bound to C-M-H-b)       [Command] 
     643 
     644This command moves to the bottom of the debugging stack. 
     645 
     646 
     647 
     648Debug Frame     (bound to C-M-H-f)       [Command] 
     649 
     650This command moves to the absolute debugger frame number indicated by 
     651the prefix argument. 
     652 
     653 
     654 
     655=== 9.8.2 Getting out of the Debugger === 
     656 
     657Debug Quit      (bound to C-M-H-q)       [Command] 
     658 
     659This command throws to top level out of the debugger in the Current 
     660Eval Server. 
     661 
     662 
     663 
     664Debug Go        (bound to C-M-H-g)       [Command] 
     665 
     666This command tries the continue restart in the Current Eval Server. 
     667 
     668 
     669 
     670Debug Abort     (bound to C-M-H-a)       [Command] 
     671 
     672This command executes the ABORT restart in the Current Eval 
     673Server. 
     674 
     675 
     676 
     677Debug Restart   (bound to C-M-H-r)       [Command] 
     678 
     679This command executes the restart indicated by the prefix argument in 
     680the Current Eval Server. The debugger enumerates the restart cases 
     681upon entering it. 
     682 
     683 
     684 
     685=== 9.8.3 Getting Information === 
     686 
     687Debug Help      (bound to C-M-H-h)       [Command] 
     688 
     689This command in prints the debugger's help text. 
     690 
     691 
     692 
     693Debug Error     (bound to C-M-H-e)       [Command] 
     694 
     695This command prints the error condition and restart cases displayed 
     696upon entering the debugger. 
     697 
     698 
     699 
     700Debug Backtrace         (bound to C-M-H-B)       [Command] 
     701 
     702This command executes the debugger's backtrace command. 
     703 
     704 
     705 
     706Debug Print     (bound to C-M-H-p)       [Command] 
     707 
     708This command prints the debugger's current frame in the same fashion 
     709as the frame motion commands. 
     710 
     711 
     712 
     713Debug Verbose Print     (bound to C-M-H-P)       [Command] 
     714 
     715This command prints the debugger's current frame without elipsis. 
     716 
     717 
     718 
     719Debug Source    (bound to C-M-H-s)       [Command] 
     720 
     721This command prints the source form for the debugger's current frame. 
     722 
     723 
     724 
     725Debug Verbose Source             [Command] 
     726 
     727This command prints the source form for the debugger's current frame with surrounding forms for context. 
     728 
     729 
     730 
     731Debug List Locals       (bound to C-M-H-l)       [Command] 
     732 
     733This prints the local variables for the debugger's current frame. 
     734 
     735 
     736 
     737=== 9.8.4 Editing Sources === 
     738 
     739Debug Edit Source       (bound to C-M-H-S)       [Command] 
     740 
     741This command attempts to place you at the source location of the 
     742debugger's current frame. Not all debugger frames represent function's 
     743that were compiled with the appropriate debug-info policy. This beeps 
     744with a message if it is unsuccessful. 
     745 
     746 
     747 
     748=== 9.8.5 Miscellaneous === 
     749 
     750Debug Flush Errors      (bound to C-M-H-F)       [Command] 
     751 
     752This command toggles whether the debugger ignores errors or 
     753recursively enters itself. 
     754 
     755 
     756 
     757== 9.9 Manipulating the Editor Process == 
     758 
     759When developing Hemlock customizations, it is useful to be able to 
     760manipulate the editor Lisp environment from Hemlock. 
     761 
     762Editor Describe         (bound to Home t, C-_ t)         [Command] 
     763 
     764This command prompts for an expression, and then evaluates and 
     765describes it in the editor process. 
     766 
     767 
     768 
     769Room             [Command] 
     770 
     771Call the room function in the editor process, displaying information 
     772about allocated storage in a pop-up window. 
     773 
     774 
     775 
     776Editor Load File                 [Command] 
     777 
     778This command is analogous to Load File, but loads the file into the 
     779editor process. 
     780 
     781 
     782 
     783=== 9.9.1 Editor Mode === 
     784 
     785When Editor mode is on, alternate versions of the Lisp interaction 
     786commands are bound in place of the eval server based commands. These 
     787commands manipulate the editor process instead of the current eval 
     788server. Turning on editor mode in a buffer allows incremental 
     789development of code within the running editor. 
     790 
     791Editor Mode              [Command] 
     792 
     793This command turns on Editor minor mode in the current buffer. If it 
     794is already on, it is turned off. Editor mode may also be turned on 
     795using the Mode file option (see page 3.3.3.) 
     796 
     797 
     798Editor Compile Defun             [Command] 
     799 
     800Editor Compile Region            [Command] 
     801 
     802Editor Evaluate Buffer                   [Command] 
     803 
     804Editor Evaluate Defun            [Command] 
     805 
     806Editor Evaluate Region                   [Command] 
     807 
     808Editor Macroexpand Expression   (bound to Editor: C-M)   [Command] 
     809 
     810Editor Re-evaluate Defvar                [Command] 
     811 
     812Editor Describe Function Call            [Command] 
     813 
     814Editor Describe Symbol                   [Command] 
     815 
     816These commands are similar to the standard commands, but modify or 
     817examine the Lisp process that Hemlock is running in. Terminal I/O is 
     818done on the initial window for the editor's Lisp process. Output is 
     819directed to a pop-up window or the editor's window instead of to the 
     820background buffer. 
     821 
     822 
     823 
     824Editor Compile Buffer File               [Command] 
     825 
     826Editor Compile File              [Command] 
     827 
     828Editor Compile Group             [Command] 
     829 
     830In addition to compiling in the editor process, these commands differ 
     831from the eval server versions in that they direct output to the the 
     832Compiler Warnings buffer. 
     833 
     834 
     835 
     836Editor Evaluate Expression               [Command] 
     837 
     838This command prompts for an expression and evaluates it in the editor 
     839process. The results of the evaluation are displayed in the echo area. 
     840 
     841 
     842 
     843=== 9.9.2 Eval Mode === 
     844 
     845Eval mode is a minor mode that simulates a read eval print loop 
     846running within the editor process. Since Lisp program development is 
     847usually done in a separate eval server process (see page 9.1), Eval 
     848mode is used primarily for debugging code that must run in the editor 
     849process. Eval mode shares some commands with Typescript mode: see 
     850section 9.2. 
     851 
     852Eval mode doesn't completely support terminal I/O: it binds 
     853standard-output to a stream that inserts into the buffer and 
     854standard-input to a stream that signals an error for all 
     855operations. Hemlock cannot correctly support the interactive 
     856evaluation of forms that read from the Eval interactive buffer. 
     857 
     858Select Eval Buffer               [Command] 
     859 
     860This command changes to the Eval buffer, creating one if it doesn't 
     861already exist. The Eval buffer is created with Lisp as the major mode 
     862and Eval and Editor as minor modes. 
     863 
     864 
     865 
     866Confirm Eval Input               [Command] 
     867 
     868This command evaluates all the forms between the end of the last 
     869output and the end of the buffer, inserting the results of their 
     870evaluation in the buffer. This beeps if the form is incomplete. Use 
     871Linefeed to insert line breaks in the middle of a form. 
     872 
     873This command uses Unwedge Interactive Input Confirm in the same way 
     874Confirm Interactive Input does. 
     875 
     876 
     877Abort Eval Input                 [Command] 
     878 
     879This command moves the the end of the buffer and prompts, ignoring any 
     880input already typed in. 
     881 
     882 
     883 
     884=== 9.9.3 Error Handling === 
     885 
     886When an error happens inside of Hemlock, Hemlock will trap the error 
     887and display the error message in the echo area, possibly along with 
     888the "Internal error:" prefix. If you want to debug the error, type 
     889?. This causes the prompt "Debug:" to appear in the echo area. The 
     890following commands are recognized: 
     891 
     892 d:: 
     893  Enter a break-loop so that you can use the Lisp debugger. Proceeding 
     894  with "go" will reenter Hemlock and give the "Debug:" prompt again. 
     895 
     896 e:: 
     897  Display the original error message in a pop-up window. 
     898 
     899 b:: 
     900  Show a stack backtrace in a pop-up window. 
     901 
     902 q, Escape:: 
     903  Quit from this error to the nearest command loop. 
     904 
     905 r:: 
     906  Display a list of the restart cases and prompt for the number of a 
     907  restart-case with which to continue. Restarting may result in 
     908  prompting in the window in which Lisp started. 
     909 
     910Only errors within the editor process are handled in this way. Errors 
     911during eval server operations are handled using normal terminal I/O on 
     912a typescript in the eval server's slave buffer or background buffer 
     913(see page 9.1.4). Errors due to interaction in a slave buffer will 
     914cause the debugger to be entered in the slave buffer. 
     915 
     916== 9.10 Command Line Switches == 
     917 
     918Two command line switches control the initialization of editor and 
     919eval servers for a Lisp process: 
     920 
     921 -edit:: 
     922  This switch starts up Hemlock. If there is a non-switch command line 
     923  word immediately following the program name, then the system 
     924  interprets it as a file to edit. For example, given 
     925  `lisp file.txt -edit` 
     926  Lisp will go immediately into Hemlock finding the file file.txt. 
     927 
     928 -slave [name]:: 
     929  This switch causes the Lisp process to become a slave of the editor 
     930  process name. An editor Lisp determines name when it allows 
     931  connections from slaves. Once the editor chooses a name, it keeps 
     932  the same name until the editor's Lisp process terminates. Since the 
     933  editor can automatically create slaves on its own machine, this 
     934  switch is useful primarily for creating slaves that run on a 
     935  different machine. hqb's machine is ME.CS.CMU.EDU, and he wants want 
     936  to run a slave on SLAVE.CS.CMU.EDU, then he should use the Accept 
     937  Slave Connections command, telnet to the machine, and invoke Lisp 
     938  supplying -slave and the editor's name. The command displays the 
     939  editor's name. 
     940