wiki:HemlockProgrammer/Utilities

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

--

Back to Table of Contents

16. Utilities

This chapter describes a number of utilities for manipulating some types of objects Hemlock uses to record information. String-tables are used to store names of variables, commands, modes, and buffers. Ring lists can be used to provide a kill ring, recent command history, or other user-visible features.

16.1. String-table Functions

String tables are similar to Common Lisp hash tables in that they associate a value with an object. There are a few useful differences: in a string table the key is always a case insensitive string, and primitives are provided to facilitate keyword completion and recognition. Any type of string may be added to a string table, but the string table functions always return simple-string's.

A string entry in one of these tables may be thought of as being separated into fields or keywords. The interface provides keyword completion and recognition which is primarily used to implement some Echo Area commands. These routines perform a prefix match on a field-by-field basis allowing the ambiguous specification of earlier fields while going on to enter later fields. While string tables may use any string-char as a separator, the use of characters other than space may make the Echo Area commands fail or work unexpectedly.

make-string-table [Function]

This function creates an empty string table that uses separator as the character, which must be a string-char, that distinguishes fields. Initial-contents specifies an initial set of strings and their values in the form of a dotted a-list, for example:

'(("Global" . t) ("Mode" . t) ("Buffer" . t))

string-table-p string-table [Function]

This function returns t if string-table is a string-table object, otherwise nil.

string-table-separator string-table [Function]

This function returns the separator character given to make-string-table.

delete-string string table [Function]

clrstring table [Function]

delete-string removes any entry for string from the string-table table, returning t if there was an entry. clrstring removes all entries from table.

getstring string table [Function]

This function returns as multiple values, first the value corresponding to the string if it is found and nil if it isn't, and second t if it is found and nil if it isn't.

This may be set with setf to add a new entry or to store a new value for a string. It is an error to try to insert a string with more than one field separator character occurring contiguously.

complete-string string tables [Function]

This function completes string as far as possible over the list of tables, returning five values. It is an error for tables to have different separator characters. The five return values are as follows:

  • The maximal completion of the string or nil if there is none.
  • An indication of the usefulness of the returned string:
:none
There is no completion of string.
:complete
The completion is a valid entry, but other valid completions exist too. This occurs when the supplied string is an entry as well as initial substring of another entry.
:unique
The completion is a valid entry and unique.
:ambiguous
The completion is invalid; get-string would return nil and nil if given the returned string.
  • The value of the string when the completion is :unique or :complete, otherwise nil.
  • An index, or nil, into the completion returned, indicating where the addition of a single field to string ends. The command Complete Field uses this when the completion contains the addition to string of more than one field.
  • An index to the separator following the first ambiguous field when the completion is :ambiguous or :complete, otherwise nil.

find-ambiguous string table [Function]

find-containing string table [Function]

find-ambiguous returns a list in alphabetical order of all the strings in table matching string. This considers an entry as matching if each field in string, taken in order, is an initial substring of the entry's fields; entry may have fields remaining.

find-containing is similar, but it ignores the order of the fields in string, returning all strings in table matching any permutation of the fields in string.

do-strings (string-var value-var table result) declaration tag statement [Macro]

This macro iterates over the strings in table in alphabetical order. On each iteration, it binds string-var to an entry's string and value-var to an entry's value.

16.2. Ring Functions

There are various purposes in an editor for which a ring of values can be used, so Hemlock provides a general ring buffer type. It is used for maintaining a ring of killed regions (see section 4.3), a ring of marks (see section 3.1), or a ring of command strings which various modes and commands maintain as a history mechanism.

make-ring length &optional delete-function [Function]

Makes an empty ring object capable of holding up to length Lisp objects. Delete-function is a function that each object is passed to before it falls off the end. Length must be greater than zero.

ringp ring [Function]

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

ring-length ring [Function]

Returns as multiple-values the number of elements which ring currently holds and the maximum number of elements which it may hold.

ring-ref ring index [Function]

Returns the index'th item in the ring, where zero is the index of the most recently pushed. This may be set with setf.

ring-push object ring [Function]

Pushes object into ring, possibly causing the oldest item to go away.

ring-pop ring [Function]

Removes the most recently pushed object from ring and returns it. If the ring contains no elements then an error is signalled.

rotate-ring ring offset [Function]

With a positive offset, rotates ring forward that many times. In a forward rotation the index of each element is reduced by one, except the one which initially had a zero index, which is made the last element. A negative offset rotates the ring the other way.

16.3 Undoing commands

save-for-undo name method &optional cleanup method-undo buffer [Function] This saves information to undo a command. Name is a string to display when prompting the user for confirmation when he invokes the Undo command (for example, "kill" or "Fill Paragraph"). Method is the function to invoke to undo the effect of the command. Method-undo is a function that undoes the undo function, or effectively re-establishes the state immediately after invoking the command. If there is any existing undo information, this invokes the cleanup function; typically method closes over or uses permanent marks into a buffer, and the cleanup function should delete such references. Buffer defaults to the current-buffer, and the Undo command only invokes undo methods when they were saved for the buffer that is current when the user invokes Undo.

make-region-undo kind name region &optional mark-or-region [Function] This handles three common cases that commands fall into when setting up undo methods, including cleanup and method-undo functions (see save-for-undo). These cases are indicated by the kind argument:

:twiddle
Use this kind when a command modifies a region, and the undo information indicates how to swap between two regions -- the one before any modification occurs and the resulting region. Region is the resulting region, and it has permanent marks into the buffer. Mark-or-region is a region without marks into the buffer (for example, the result of copy-region). As a result of calling this, a first invocation of Undo deletes region, saving it, and inserts mark-or-region where region used to be. The undo method sets up for a second invocation of Undo that will undo the effect of the undo; that is, after two calls, the buffer is exactly as it was after invoking the command. This activity is repeatable any number of times. This establishes a cleanup method that deletes the two permanent marks into the buffer used to locate the modified region.
:insert
Use this kind when a command has deleted a region, and the undo information indicates how to re-insert the region. Region is the deleted and saved region, and it does not contain marks into any buffer. Mark-or-region is a permanent mark into the buffer where the undo method should insert region. As a result of calling this, a first invocation of Undo inserts region at mark-or-region and forms a region around the inserted text with permanent marks into the buffer. This allows a second invocation of Undo to undo the effect of the undo; that is, after two calls, the buffer is exactly as it was after invoking the command. This activity is repeatable any number of times. This establishes a cleanup method that deletes either the permanent mark into the buffer or the two permanent marks of the region, depending on how many times the user used Undo.
:delete
Use this kind when a command has inserted a block of text, and the undo information indicates how to delete the region. Region has permanent marks into the buffer and surrounds the inserted text. Leave Mark-or-region unspecified. As a result of calling this, a first invocation of Undo deletes region, saving it, and establishes a permanent mark into the buffer to remember where the region was. This allows a second invocation of Undo to undo the effect of the undo; that is, after two calls, the buffer is exactly as it was after invoking the command. This activity is repeatable any number of times. This establishes a cleanup method that deletes either the permanent mark into the buffer or the two permanent marks of the region, depending on how many times the user used Undo.

Name in all cases is an appropriate string indicating what the command did. This is used by Undo when prompting the user for confirmation before calling the undo method. The string used by Undo alternates between this argument and something to indicate that the user is undoing an undo.

Back to Table of Contents