wiki:HemlockProgrammer/Buffers

Version 5 (modified by gz, 4 years ago) (diff)

--

Back to Table of Contents

3. Buffers

A buffer is an object consisting of:

  1. A name.
  2. A piece of text.
  3. The insertion point.
  4. An associated file (optional).
  5. A write protect flag.
  6. Some variables.
  7. Some key bindings.
  8. A collection of modes.
  9. A list of modeline fields (optional).

Because of the way Hemlock is currently integrated in Cocoa, all modifications to buffer contents must take place in the GUI thread. Hemlock commands always run in the GUI thread, so most of the time you do not need to worry about it. If you are running code in another thread that needs to modify a buffer, you should perform that action using gui::execute-in-gui or gui::queue-for-gui.

There are no intrinsic limitations on examining buffers from any thread, however, Hemlock currently does no locking, so you risk seeing the buffer in an inconsistent state if you look at it outside the GUI thread.

3.1. The Current Buffer

Hemlock has the concept of the "current buffer". The current buffer is defined during Hemlock commands as the buffer of the hemlock view that received the key events that invoked the command. Many hemlock function operate on the current buffer rather than taking an explicit buffer argument. In effect, the current buffer is an implicit argument to many text manipulation functions.

current-buffer [Function]

Returns the current buffer, which, during command execution, is the buffer that is the target of the command.

current-point [Function]

This function returns the buffer-point of the current buffer . This is such a common idiom in commands that it is defined despite its trivial implementation.

current-point-collapsing-selection [Function]

This function returns the buffer-point of the current buffer, after first deactivating any active region.

current-point-extending-selection [Function]

This function returns the buffer-point of the current buffer, after first making sure there is an active region - if the region is already active, keeps it active, otherwise it establishes a new (empty) region at point.

current-point-for-insertion [Function]

This function checks to see if the current buffer can be modified at its current point, and errors if not. Otherwise, it deletes the current selection if any, and returns the current point.

current-point-for-deletion [Function]

This function checks to see if the current buffer can be modified at its current point and errors if not. Otherwise, if there is a section in the current buffer, it deletes it and returns NIL. If there is no selection, it returns the current point.

current-point-unless-selection [Function]

This function checks to see if the current buffer can be modified at its current point and errors if not. Otherwise, if there's a selection in the current buffer, returns NIL. If there is no selection, it returns the current point.

current-mark [Function]

This function returns the top of the current buffer's mark stack. There always is at least one mark at the beginning of the buffer's region, and all marks returned are right-inserting.

pop-buffer-mark [Function]

This function pops the current buffer's mark stack, returning the mark. If the stack becomes empty, this pushes a new mark on the stack pointing to the buffer's start. This always deactivates the current region (see Active Regions).

push-buffer-mark mark &optional activate-region [Function]

This function pushes mark into the current buffer's mark stack, ensuring that the mark is right-inserting. If mark does not point into the current buffer, this signals an error. Optionally, the current region is made active, but this never deactivates the current region (see Active Regions). Mark is returned.

push-new-buffer-mark mark &optional activate-region [Function]

This function pushes a new mark onto the mark stack, at the position of mark. It's equivalent to calling push-buffer-mark on (copy-mark mark).

all-buffers [Function]

This function returns a list of all the buffer objects made with make-buffer.

*buffer-names* [Variable]

This variable holds a string-table mapping the name of a buffer to the corresponding buffer object.

3.2. Buffer Functions

make-buffer name &key :modes :modeline-fields :delete-hook [Function]

Default Modeline Fields [Hemlock Variable]
Make Buffer Hook [Hemlock Variable]

make-buffer creates and returns a buffer with the given name. If a buffer named name already exists, nil is returned. Modes is a list of modes which should be in effect in the buffer, major mode first, followed by any minor modes. If this is omitted then the buffer is created with the list of modes contained in Default Modes (page 35). Modeline-fields is a list of modeline-field objects (see section 3.3) which may be nil. delete-hook is a list of delete hooks specific to this buffer, and delete-buffer invokes these along with Delete Buffer Hook.

Buffers created with make-buffer are entered into the list (all-buffers), and their names are inserted into the string-table *buffer-names*. When a buffer is created the hook Make Buffer Hook is invoked with the new buffer.

bufferp buffer [Function]

Returns t if buffer is a buffer object, otherwise nil.

buffer-name buffer [Function]
Buffer Name Hook [Hemlock Variable]

buffer-name returns the name, which is a string, of the given buffer. The corresponding setf method invokes Buffer Name Hook with buffer and the new name and then sets the buffer's name. When the user supplies a name for which a buffer already exists, the setf method signals an error.

buffer-region buffer [Function]

Returns the buffer's region. Note this is the region that contains all the text in a buffer, not the current-region (page 19).

This can be set with setf to replace the buffer's text.

buffer-pathname buffer [Function]
Buffer Pathname Hook [Hemlock Variable]

buffer-pathname returns the pathname of the file associated with the given buffer, or nil if it has no associated file. This is the truename of the file as of the most recent time it was read or written. There is a setf form to change the pathname. When the pathname is changed the hook Buffer Pathname Hook is invoked with the buffer and new value.

buffer-write-date buffer [Function]

Returns the write date for the file associated with the buffer in universal time format. When this the buffer-pathname is set, use setf to set this to the corresponding write date, or to nil if the date is unknown or there is no file.

buffer-point buffer [Function]

Returns the mark which is the current location within buffer. To move the point, use move-mark or move-to-position (page 5).

buffer-mark buffer [Function]

This function returns the top of buffer's mark stack. There always is at least one mark at the beginning of buffer's region, and all marks returned are right-inserting.

buffer-start-mark buffer [Function]

buffer-end-mark buffer [Function]

These functions return the start and end marks of buffer's region:

(buffer-start-mark buffer )  <==>  (region-start (buffer-region buffer))

and

(buffer-end-mark buffer )  <==>  (region-end (buffer-region buffer))

buffer-writable buffer [Function]
Buffer Writable Hook [Hemlock Variable]

This function returns t if you can modify the buffer, nil if you cannot. If a buffer is not writable, then any attempt to alter text in the buffer results in an error. There is a setf method to change this value. The setf method invokes the functions in Buffer Writable Hook on the buffer and new value before storing the new value.

buffer-modified buffer [Function]
Buffer Modified Hook [Hemlock Variable]

buffer-modified returns t if the buffer has been modified, nil if it hasn't. This attribute is set whenever a text-altering operation is performed on a buffer. There is a setf method to change this value. The setf method invokes the functions in Buffer Modified Hook with the buffer whenever the value of the modified flag changes.

with-writable-buffer (buffer) &body body [Macro]

This macro executes forms with buffer's writable status set. After forms execute, this resets the buffer's writable and modified status.

buffer-signature buffer [Function]

This function returns an arbitrary number which reflects the buffer's current signature. The result is eql to a previous result if and only if the buffer has not been modified between the calls.

buffer-variables buffer [Function]

This function returns a string-table (page 69) containing the names of the buffer's local variables. See chapter 6.

buffer-modes buffer [Function]

This function returns the list of the names of the modes active in buffer. The major mode is first, followed by any minor modes. See chapter 8.

buffer-delete-hook buffer [Function]

This function returns the list of buffer specific functions delete-buffer invokes when deleting a buffer . This is setf-able.

delete-buffer buffer [Function]
Delete Buffer Hook [Hemlock Variable]

delete-buffer removes buffer from (all-buffers) (page 10) and its name from *buffer-names* (page 10). Before buffer is deleted, this invokes the functions on buffer returned by buffer-delete-hook and those found in Delete Buffer Hook. If buffer is the current-buffer, or if it is displayed in any view, then this function signals an error.

3.3. Modelines

A Buffer may specify a modeline, a line of text which is displayed across the bottom of a view to indicate status information. Modelines are described by a list of modeline-field objects which have individual update functions and are optionally fixed-width. These have an eql name for convenience in referencing and updating, but the name must be unique for all created modeline-field objects. All modeline-field functions must take a buffer as an argument and return a string. When displaying a modeline-field with a specified width, the result of the update function is either truncated or padded on the right to meet the constraint.

Whenever one of the following changes occurs, all of a buffer's modeline fields are updated:

  • A buffer's major mode is set.
  • One of a buffer's minor modes is turned on or off.
  • A buffer is renamed.
  • A buffer's pathname changes.
  • A buffer's modified status changes.

The policy is that whenever one of these changes occurs, it is guaranteed that the modeline will be updated before the next trip through redisplay. Furthermore, since the system cannot know what modeline-field objects the user has added whose update functions rely on these values, or how he has changed Default Modeline Fields, we must update all the fields.

The user should note that modelines can be updated at any time, so update functions should be careful to avoid needless delays (for example, waiting for a local area network to determine information).

make-modeline-field &key :name :width :function [Function]

This function returns a modeline-field object with name, width, and function. Width defaults to nil meaning that the field is variable width; otherwise, the programmer must supply this as a positive integer. Function must take a buffer as an arguments and return a string. If name already names a modeline-field object, then this signals an error.

modeline-field-name modeline-field [Function]

This function returns the name field of a modeline-field object. If this is set with setf, and the new name already names a modeline-field, then the setf method signals an error.

modeline-field-p modeline-field [Function]

This function returns t if its argument is a modeline-field object, nil otherwise.

modeline-field name [Function]

This returns the modeline-field object named name. If none exists, this returns nil.

modeline-field-function modeline-field [Function]

Returns the function called when updating the modeline-field. When this is set with setf, the setf method updates modeline-field for all views on all buffers that contain the given field, so the next trip through redisplay will reflect the change. All modeline-field functions must take a buffer as an argument and return a string.

modeline-field-width modeline-field [Function]

Returns the width to which modeline-field is constrained, or nil indicating that it is variable width. When this is set with setf, the setf method updates all modeline-fields for all views on all buffers that contain the given field, so the next trip through redisplay will reflect the change.

buffer-modeline-fields buffer [Function]

Returns a copy of the list of buffer's modeline-field objects. This list can be destructively modified without affecting display of buffer's modeline, but modifying any particular field's components (for example, width or function) causes the changes to be reflected the next trip through redisplay in every modeline display that uses the modified modeline-field. When this is set with setf, the setf method method updates all modeline-fields on all views on the buffer, so next trip through the redisplay will reflect the change.

buffer-modeline-field-p buffer field [Function]

If field, a modeline-field or the name of one, is in buffer's list of modeline-field objects, it is returned; otherwise, this returns nil.

update-modeline-fields buffer [Function]

Arranges so that the modeline display is updated with the latest values at the end of current command.

Back to Table of Contents