| Previous Section | Next Section | Table of Contents | Glossary | Index |
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.
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.
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))
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.
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 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.
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, a ring of marks, or a ring of command strings which various modes and commands maintain as a history mechanism.
| Previous Section | Next Section | Table of Contents | Glossary | Index |