wiki:HemlockProgrammer/Buffers

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

--

3. Buffers

A buffer is an environment within Hemlock consisting of:

  1. A name.
  2. A piece of text.
  3. A current focus of attention, the point.
  4. An associated file (optional).
  5. A write protect flag.
  6. Some variables (page 23).
  7. Some key bindings (page 29).
  8. Some collection of modes (page 35).
  9. Some windows in which it is displayed (page 41).
  10. A list of modeline fields (optional).

3.1. The Current Buffer

current-buffer [Function]

Set Buffer Hook [Hemlock Variable]

After Set Buffer Hook [Hemlock Variable]

current-buffer returns the current buffer object. Usually this is the buffer that current-window (page 41) is displaying. This value may be changed with setf, and the setf method invokes Set Buffer Hook before the change occurs with the new value. After the change occurs, the method invokes After Set Buffer Hook with the old value.

current-point [Function]

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

current-mark [Function]

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

current-mark 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 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 section 4.4).

push-buffer-mark 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 section 4.4). Mark is returned.

*buffer-list* [Variable]

This variable holds a list of all the buffer objects made withmake-buffer .

*buffer-names* [Variable]

This variable holds a string-table (page 69) of all the names of the buffers in *buffer-list*. The values of the entries are the corresponding buffer objects.

*buffer-history* [Variable]

This is a list of buffer objects ordered from those most recently selected to those selected farthest in the past. When someone makes a buffer, an element of Make Buffer Hook adds this buffer to the end of this list. When someone deletes a buffer, an element of Delete Buffer Hook removes the buffer from this list. Each buffer occurs in this list exactly once, but it never contains the *echo-area-buffer*.

change-to-buffer buffer [Function]

This switches to buffer in the current-window maintaining buffer-history.

previous-buffer [Function]

This returns the first buffer from *buffer-history* that is not the current-buffer. If none can be found, then this returns nil.

3.2. Buffer Functions

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

Make Buffer Hook [Hemlock Variable]

Default Modeline Fields [Hemlock Variable]

make-buffer creates and returns a buffer with the givenname. 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 *buffer-list*, 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. This can be set with setf. Note, this returns the region that contains all the text in a buffer , not the current-region (page 19).

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) rather than setting buffer-point with setf.

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 Hookon the buffer and new value before storing the new value.

buffer-modified buffer [Function]

Buffer Modified Hook [Hemlock Variable]

buffer-modified returns t if thebuffer 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 Hookwith the buffer whenever the value of the modified flag changes.

with-writable-buffer (buffer ) &restforms [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-windows buffer [Function]

This function returns the list of all the windows in which the buffer may be displayed. This list may include windows which are not currently visible. See page 41 for a discussion of windows.

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 *buffer-list* (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 windows, then this function signals an error.

delete-buffer-if-possible buffer [Function] This uses delete-buffer to delete buffer if at all possible. If buffer is the current-buffer, then this sets the current-buffer to the first distinct buffer in buffer-history. If buffer is displayed in any windows, then this makes each window display the same distinct buffer .

3.3. Modelines

A Buffer may specify a modeline, a line of text which is displayed across the bottom of a window to indicate status information. Modelines are described as 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. When creating 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. All modeline-field functions must return simple strings with standard characters, and these take a buffer and a window as arguments. Modeline-field objects are typically shared amongst, or aliased by, different buffers' modeline fields lists. These lists are unique allowing fields to behave the same wherever they occur, but different buffers may display these fields in different arrangements.

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.
  • A window's buffer is changed.

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. When any but the last occurs, the modeline-field update function is invoked once for each window into the buffer . When a window's buffer changes, each modeline-field update function is invoked once; other windows' modeline fields should not be affected due to a given window's buffer changing.

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]

modeline-field-p modeline-field [Function]

modeline-field-name modeline-field [Function]

make-modeline-field 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 and window as arguments and return a simple-string containing only standard characters. If name already names a modeline-field object, then this signals an error.

modeline-field-name 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 returns t or nil, depending on whether its argument is a modeline-field object.

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 windows on all buffers that contain the given field, so the next trip through redisplay will reflect the change. All modeline-field functions must return simple strings with standard characters, and they take a buffer and a window as arguments.

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 windows on all buffers that contain the given field, so the next trip through redisplay will reflect the change. All the fields for any such modeline display must be updated, which is not the case when setting a modeline-field's function.

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, update-modeline-fields is called for each window into buffer .

buffer-modeline-field-pbuffer 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 window [Function]

This invokes each modeline-field object's function from buffer's list, passing buffer and window. The results are collected regarding each modeline-field object's width as appropriate, and the window is marked so the next trip through redisplay will reflect the changes. If window does not display modelines, then no computation occurs.

update-modeline-field buffer window field-or-name [Function]

This invokes the modeline-field object's function for field-or-name, which is a modeline-field object or the name of one for buffer . This passes buffer and window to the update function. The result is applied to the window's modeline display using the modeline-field object's width, and the window is marked so the next trip through redisplay will reflect the changes. If the window does not display modelines, then no computation occurs. If field-or-name is not found in buffer's list of modeline-field objects, then this signals an error. See buffer-modeline-field-p above.