wiki:HemlockProgrammer/HemlockLispEnvironment

Version 2 (modified by gz, 7 years ago) (diff)

--

Back to Table of Contents

14. Hemlock's Lisp Environment

This chapter is sort of a catch all for any functions and variables which concern Hemlock's interaction with the outside world.

14.1. Entering and Leaving the Editor

ed &optional x [Function]

This a standard Common Lisp function. If x is supplied and is a string or pathname, the file specified by x is visited in a hemlock view (opening a new window if necessary, otherwise bringing an existing window with the file to the front), and the hemlock view object is the return value from the function.

If x is null, a new empty hemlock view is created and returned.

If x is a symbol or a setf function name, it attempts to edit the definition of the name. In this last case, the function returns without waiting for the operation to complete (for example, it might put up a non-modal dialog asking the user to select one of multiple definitions) and hence the return value is always NIL.

14.2. Keyboard Input

*key-event-history* [Variable]

This is a Hemlock ring buffer (see page 70) that holds the last 60 key-events received.

last-key-event-typed [Function]

This function returns the last key-event the user typed to invoke the current command.

last-char-typed [Function]

This function returns the character corresponding to the last key event typed.

14.3. Hemlock Streams

It is possible to create streams which output to or get input from a buffer. This mechanism is quite powerful and permits easy interfacing of Hemlock to Lisp.

Note that operations on these streams operate directly on buffers, therefore they have the same restrictions as described here for interacting with buffers from outside of the GUI thread.

make-hemlock-output-stream mark &optional buffered [Function]

This function returns a stream that inserts at mark all output directed to it. It works best if mark is a left-inserting mark. Buffered controls whether the stream is buffered or not, and its valid values are the following keywords:

:none
No buffering is done. This is the default.
:line
The buffer is flushed whenever a newline is written or when it is explicitly done with force-output.
:full
The stream is only brought up to date when it is explicitly done with force-output

hemlock-output-stream-p object [Function]

This function returns t if object is a hemlock-output-stream object.

make-hemlock-region-stream region [Function]

This function returns a stream from which the text in region can be read.

hemlock-region-stream-p object [Function]

This function returns t if object is a hemlock-region-stream object.

with-input-from-region (var region) {declaration}* {form}* [Macro]

While evaluating forms, binds var to a stream which returns input from region.

with-output-to-mark (var mark [buffered]) {declaration}* {form}* [Macro]

During the evaluation of the forms, binds var to a stream which inserts output at the permanent mark. Buffered has the same meaning as for make-hemlock-output-stream.

with-pop-up-display (var &key height name) {declaration}* {form}* [Macro]

This macro executes forms in a context with var bound to a stream. Hemlock collects output to this stream and tries to pop up a display of the appropriate height containing all the output. When height is supplied, Hemlock creates the pop-up display immediately, forcing output on line breaks. This is useful for displaying information of temporary interest.

14.4. Interface to the Error System

Hemlock commands are executed from an event handler in the initial Cocoa thread. They are executed within a ccl::with-standard-abort-handling form, which means cl:abort, ccl:abort-break, ccl:throw-cancel will abort the current command only and exit the event handler in an orderly fashion.

In addition, for now, lisp errors during command execution dump a backtrace in the system console and are otherwise handled as if by handle-lisp-errors below, which means it is not possible to debug errors at the point of the error. Once Clozure CL has better support for debugging errors in the initial Cocoa thread, better Hemlock error handling will be provided that will allow for some way to debug.

editor-error &rest args [Function]

This function is called to report minor errors to the user. These are errors that a normal user could encounter in the course of editing, such as a search failing or an attempt to delete past the end of the buffer. This function simply aborts the current command. Any args specified are used to format an error message to be placed in the echo area. This function never returns.

handle-lisp-errors {form}* [Macro]

Within the body of this macro any Lisp errors that occur are handled by displaying an error message in a dialog and aborting the current command, leaving the error text in the echo area. This macro should be wrapped around code which may get an error due to some action of the user --- for example, evaluating code fragments on the behalf of and supplied by the user.

14.5. Definition Editing

Hemlock provides commands for finding the definition of a function or variable and placing the user at the definition in a buffer. A function is provided to allow invoking this functionality outside of Hemlock. Note that this function is unusual in that it is it is safe to call outside of the command interpreter, and in fact it can be called from any thread.

edit-definition name [Function]

This function tries to find the definition of name, create or activate the window containing it, and scroll the view to show the definition. If there are multiple definitions available, the user is given a choice of which one to use. This function may return before the operation is complete.

14.6. Event Scheduling

No Event Scheduling functionality is provided at this time.

14.7. Miscellaneous

in-lisp {form}* [Function]

This evaluates forms inside handle-lisp-errors. It also binds *package* to the package named by Current Package if it is non-nil. Use this when evaluating Lisp code on behalf of the user.

do-alpha-chars (var kind [result]) {form}* [Macro]

This iterates over alphabetic characters in Common Lisp binding var to each character in order as specified under character relations in Common Lisp the Language. Kind is one of:lower, :upper, or :both. When the user supplies :both, lowercase characters are processed first.

Back to Table of Contents