wiki:HemlockProgrammer/Utilities

Version 3 (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

No API to the undo facility is provided at this time.

Back to Table of Contents