[Openmcl-cvs-notifications] r14797 - in /trunk/source/doc/src: ccl-documentation.xml hemlock.xml
gz at clozure.com
gz at clozure.com
Sat May 14 10:33:46 CDT 2011
Author: gz
Date: Sat May 14 10:33:46 2011
New Revision: 14797
Log:
Add hemlock programming documentation
Added:
trunk/source/doc/src/hemlock.xml
Modified:
trunk/source/doc/src/ccl-documentation.xml
Modified: trunk/source/doc/src/ccl-documentation.xml
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D
--- trunk/source/doc/src/ccl-documentation.xml (original)
+++ trunk/source/doc/src/ccl-documentation.xml Sat May 14 10:33:46 2011
@@ -25,6 +25,8 @@
href=3D"using.xml"/>
<xi:include xmlns:xi=3D"http://www.w3.org/2001/XInclude"
href=3D"ide.xml"/>
+<xi:include xmlns:xi=3D"http://www.w3.org/2001/XInclude"
+ href=3D"hemlock.xml"/>
<xi:include xmlns:xi=3D"http://www.w3.org/2001/XInclude"
href=3D"threads.xml"/>
<xi:include xmlns:xi=3D"http://www.w3.org/2001/XInclude"
Added: trunk/source/doc/src/hemlock.xml
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D
--- trunk/source/doc/src/hemlock.xml (added)
+++ trunk/source/doc/src/hemlock.xml Sat May 14 10:33:46 2011
@@ -1,0 +1,9877 @@
+<?xml version=3D"1.0" encoding=3D"utf-8"?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.=
oasis-open.org/docbook/xml/4.5/docbookx.dtd"[
+ <!ENTITY rest "<varname>&rest</varname>">
+ <!ENTITY key "<varname>&key</varname>">
+ <!ENTITY optional "<varname>&optional</varname>">
+ <!ENTITY body "<varname>&body</varname>">
+ <!ENTITY aux "<varname>&aux</varname>">
+ <!ENTITY allow-other-keys "<varname>&allow-other-keys</varna=
me>">
+ <!ENTITY CCL "Clozure CL">
+ ]>
+<chapter id=3D"HemlockProgramming">
+ <title>Hemlock Programming</title>
+ <sect1 id=3D"HemlockProgrammingIntroduction">
+ <title>Introduction</title>
+ <para>
+Hemlock is the text editor used in &CCL;. It was originally based on the =
<ulink url=3D"http://www.cons.org/cmucl/hemlock/index.html">CMU Hemlock edi=
tor</ulink>, but has since diverged from it in various ways. We continue t=
o call the editor part of our IDE <code>Hemlock</code> to give credit where=
credit is due, but we make no attempt at source or API compatibility with =
the original Hemlock.
+ </para>
+ <para>
+Like the code, this documentation is based on the original Hemlock documen=
tation, modified as necessary.
+ </para>
+ <para>
+Hemlock follows in the tradition of Emacs-compatible editors, with a rich =
set of extensible commands. This document describes the API for implementi=
ng new commands. The basic editor consists of a set of Lisp utility functi=
ons for manipulating buffers and the other data structures of the editor. =
All user level commands are written in terms of these =
+functions. To find out how to define commands see <ulink url=3D"HemlockPro=
grammer/Commands">Commands</ulink>.
+ </para>
+ </sect1>
+ <sect1 id=3D"HemlockProgrammingRepresentationOfText">
+ <title>Representation of Text</title>
+ <para>
+In Hemlock, text is represented as a sequence of lines. Newline characters
+are never stored but are implicit between lines. The
+implicit newline character is treated as the single character <code>#\Newl=
ine</code> by the
+text primitives.
+ </para>
+ <para>
+Text is broken into lines when it is first introduced into Hemlock. Text =
enters
+Hemlock from the outside world in two ways: reading a file, or pasting text
+from the system clipboard. Hemlock uses heuristics <emphasis role=3D'bold=
'>(which should be documented here!)</emphasis>
+to decide what newline convention to use to convert the incoming text into=
its internal
+representation as a sequence of lines. Similarly it uses heuristics
+<emphasis role=3D'bold'>(which should be documented here!)</emphasis> to c=
onvert the internal representation into
+a string with embedded newlines in order to write a file or paste a region=
into
+the clipboard.
+ </para>
+ <sect2 id=3D"Lines">
+ <title>Lines</title>
+ <para>
+A <code>line</code> is an object representing a sequence of characters wit=
h no line breaks.
+ </para>
+ <refentry id=3D"f_linep">
+ <indexterm zone=3D"f_linep">
+ <primary>linep</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>linep</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ linep line =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+This function returns t if line is a line object, otherwise nil.
+ </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_line-string">
+ <indexterm zone=3D"f_line-string">
+ <primary>line-string</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>line-string</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ line-string line =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+Given a line, this function returns as a simple string the characters
+in the line. This is setf'able to set the line-string to any string
+that does not contain newline characters. It is an error to
+destructively modify the result of line-string or to destructively
+modify any string after the line-string of some line has been set to
+that string.
+ </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_line-previous">
+ <indexterm zone=3D"f_line-previous">
+ <primary>line-previous</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>line-previous</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ line-previous line =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para> </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_line-next">
+ <indexterm zone=3D"f_line-next">
+ <primary>line-next</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>line-next</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ line-next line =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+Given a line, line-previous returns the previous line or nil if there
+is no previous line. Similarly, line-next returns the line following
+line or nil.
+ </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_line-buffer">
+ <indexterm zone=3D"f_line-buffer">
+ <primary>line-buffer</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>line-buffer</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ line-buffer line =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+This function returns the buffer which contains this line. Since a
+line may not be associated with any buffer, in which case line-buffer
+returns nil.
+ </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_line-length">
+ <indexterm zone=3D"f_line-length">
+ <primary>line-length</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>line-length</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ line-length line =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+This function returns the number of characters in the line. This
+excludes the newline character at the end.
+ </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_line-character">
+ <indexterm zone=3D"f_line-character">
+ <primary>line-character</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>line-character</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ line-character line index =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+This function returns the character at position index within line. It
+is an error for index to be greater than the length of the line or
+less than zero. If index is equal to the length of the line, this
+returns a #\newline character.
+ </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_line-plist">
+ <indexterm zone=3D"f_line-plist">
+ <primary>line-plist</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>line-plist</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ line-plist line =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+This function returns the property-list for line. setf, getf, putf and
+remf can be used to change properties. This is typically used in
+conjunction with line-signature to cache information about the line's
+contents.
+ </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_line-signature">
+ <indexterm zone=3D"f_line-signature">
+ <primary>line-signature</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>line-signature</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ line-signature line =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+This function returns an object that serves as a signature for a
+line's contents. It is guaranteed that any modification of text on the
+line will result in the signature changing so that it is not eql to
+any previous value. The signature may change even when the text
+remains unmodified, but this does not happen often.
+ </para>
+ </refsect1>
+ </refentry>
+ </sect2>
+ <sect2 id=3D"Marks">
+ <title>Marks</title>
+ <para>
+A <code>mark</code> indicates a specific position within the text represen=
ted by a
+line and a character position within that line. Although a mark is
+sometimes loosely referred to as pointing to some character, it in
+fact points between characters. If the charpos is zero, the previous
+character is the newline character separating the previous line from
+the mark's line. If the charpos is equal to the number of characters
+in the line, the next character is the newline character separating
+the current line from the next. If the mark's line has no previous
+line, a mark with charpos of zero has no previous character; if the
+mark's line has no next line, a mark with charpos equal to the length of
+the line has no next character.
+ </para>
+ <para>
+This section discusses the very basic operations involving marks, but
+a lot of Hemlock programming is built on altering some text at a mark.
+For more extended uses of marks see <ulink url=3D"HemlockProgrammer/Alteri=
ngAndSearchingText">Altering And Searching Text</ulink>.
+ </para>
+ <sect3 id=3D"MarksKindsOfMarks">
+ <title>Kinds of Marks</title>
+ <para>
+A mark may have one of two lifetimes: temporary or permanent. Permanent
+marks remain valid after arbitrary operations on the text; temporary
+marks do not. Temporary marks are used because less bookkeeping
+overhead is involved in their creation and use. If a temporary mark
+is used after the text it points to has been modified results will be
+unpredictable. Permanent marks continue to point between the same two
+characters regardless of insertions and deletions made before or after
+them.
+ </para>
+ <para>
+There are two different kinds of permanent marks which differ only in
+their behavior when text is inserted at the position of the mark; text
+is inserted to the left of a left-inserting mark and to the right of
+right-inserting mark.
+ </para>
+ </sect3>
+ <sect3 id=3D"MarksMarkFunctions">
+ <title>Mark Functions</title>
+ <refentry id=3D"f_markp">
+ <indexterm zone=3D"f_markp">
+ <primary>markp</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>markp</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ markp mark =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+This function returns t if mark is a mark object, otherwise nil.
+ </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_mark-line">
+ <indexterm zone=3D"f_mark-line">
+ <primary>mark-line</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>mark-line</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ mark-line mark =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+This function returns the line to which mark points.
+ </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_mark-charpos">
+ <indexterm zone=3D"f_mark-charpos">
+ <primary>mark-charpos</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>mark-charpos</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ mark-charpos mark =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+This function returns the character position <emphasis>in the line</emphas=
is> of the character
+after mark, i.e. the number of characters before the mark in the mark's li=
ne.
+ </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_mark-buffer">
+ <indexterm zone=3D"f_mark-buffer">
+ <primary>mark-buffer</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>mark-buffer</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ mark-buffer mark =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+Returns the buffer containing this mark.
+ </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_mark-absolute-position">
+ <indexterm zone=3D"f_mark-absolute-position">
+ <primary>mark-absolute-position</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>mark-absolute-position</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ mark-absolute-position mark =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+This function returns the character position <emphasis>in the buffer</emph=
asis> of the character
+after the mark, i.e. the number of characters before the mark in the mark's
+buffer.
+ </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_mark-kind">
+ <indexterm zone=3D"f_mark-kind">
+ <primary>mark-kind</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>mark-kind</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ mark-kind mark =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+This function returns one of <code>:right-inserting</code>, <code>:left-in=
serting</code> or
+ <code>:temporary</code> depending on the mark'=
s kind. A corresponding setf form
+changes the mark's kind.
+ </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_previous-character">
+ <indexterm zone=3D"f_previous-character">
+ <primary>previous-character</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>previous-character</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ previous-character mark =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para> </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_next-character">
+ <indexterm zone=3D"f_next-character">
+ <primary>next-character</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>next-character</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ next-character mark =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+This function returns the character immediately before (after) the
+position of the mark, or nil if there is no previous (next) character.
+These characters may be set with setf when they exist; the setf
+methods for these forms signal errors when there is no previous or
+next character.
+ </para>
+ </refsect1>
+ </refentry>
+ </sect3>
+ <sect3 id=3D"MarksMakingMarks">
+ <title>Making Marks</title>
+ <refentry id=3D"f_mark">
+ <indexterm zone=3D"f_mark">
+ <primary>mark</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>mark</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ mark line charpos &optional; kind =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+This function returns a mark object that points to the charpos'th
+character of the line. Kind is the kind of mark to create, one
+of <code>:temporary</code>, <code>:left-inserting</code>, or <code>:right-=
inserting</code>. The default is
+:temporary.
+ </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_copy-mark">
+ <indexterm zone=3D"f_copy-mark">
+ <primary>copy-mark</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>copy-mark</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ copy-mark mark &optional; kind =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+This function returns a new mark pointing to the same position and of
+the same kind, or of kind kind if it is supplied.
+ </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_delete-mark">
+ <indexterm zone=3D"f_delete-mark">
+ <primary>delete-mark</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>delete-mark</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ delete-mark mark =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+This function deletes mark. Delete any permanent marks when you are
+finished using it.
+ </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"m_with-mark">
+ <indexterm zone=3D"m_with-mark">
+ <primary>with-mark</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>with-mark</refname>
+ <refpurpose></refpurpose>
+ <refclass>Macro</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ with-mark ({(mark pos [kind])}*) {form}* =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+This macro binds to each variable mark a mark of kind kind, which
+defaults to <code>:temporary</code>, pointing to the same position as the
+markpos. On exit from the scope the mark is deleted. The value of the
+last form is the value returned.
+ </para>
+ </refsect1>
+ </refentry>
+ </sect3>
+ <sect3 id=3D"MarksMovingMarks">
+ <title>Moving Marks</title>
+ <para>
+These functions destructively modify marks to point to new positions.
+Other sections of this document describe mark moving routines specific
+to higher level text forms than characters and lines, such as words,
+sentences, paragraphs, Lisp forms, etc.
+ </para>
+ <refentry id=3D"f_move-to-position">
+ <indexterm zone=3D"f_move-to-position">
+ <primary>move-to-position</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>move-to-position</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ move-to-position mark charpos &optional; line =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+This function changes the mark to point to the given character
+position on the line line. Line defaults to mark's line.
+ </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_move-to-absolute-position">
+ <indexterm zone=3D"f_move-to-absolute-position">
+ <primary>move-to-absolute-position</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>move-to-absolute-position</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ move-to-absolute-position mark position =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+This function changes the mark to point to the given character
+position in the buffer.
+ </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_move-mark">
+ <indexterm zone=3D"f_move-mark">
+ <primary>move-mark</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>move-mark</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ move-mark mark new-position =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+This function moves mark to the same position as the
+mark new-position and returns it.
+ </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_line-start">
+ <indexterm zone=3D"f_line-start">
+ <primary>line-start</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>line-start</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ line-start mark &optional; line =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para> </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_line-end">
+ <indexterm zone=3D"f_line-end">
+ <primary>line-end</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>line-end</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ line-end mark &optional; line =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+This function changes mark to point to the beginning or the end of
+line and returns it. Line defaults to mark's line.
+ </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_buffer-start">
+ <indexterm zone=3D"f_buffer-start">
+ <primary>buffer-start</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>buffer-start</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ buffer-start mark &optional; buffer =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para> </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_buffer-end">
+ <indexterm zone=3D"f_buffer-end">
+ <primary>buffer-end</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>buffer-end</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ buffer-end mark &optional; buffer =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+These functions change mark to point to the beginning or end of
+buffer, which defaults to the buffer mark currently points into. If
+buffer is unsupplied, then it is an error for mark to be disassociated
+from any buffer.
+ </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_mark-before">
+ <indexterm zone=3D"f_mark-before">
+ <primary>mark-before</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>mark-before</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ mark-before mark =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para> </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_mark-after">
+ <indexterm zone=3D"f_mark-after">
+ <primary>mark-after</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>mark-after</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ mark-after mark =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+These functions change mark to point one character before or after the
+current position. If there is no character before/after the current
+position, then they return nil and leave mark unmodified.
+ </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_character-offset">
+ <indexterm zone=3D"f_character-offset">
+ <primary>character-offset</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>character-offset</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ character-offset mark n =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+This function changes mark to point n characters after (n before if n
+is negative) the current position. If there are less than n
+characters after (before) the mark, then this returns nil and mark is
+unmodified.
+ </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_line-offset">
+ <indexterm zone=3D"f_line-offset">
+ <primary>line-offset</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>line-offset</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ line-offset mark n &optional; charpos =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+This function changes mark to point n lines after (n before if n is
+negative) the current position. The character position of the
+resulting mark is (min (line-length resulting-line) (mark-charpos
+mark)) if charpos is unspecified, or (min (line-length resulting-line)
+charpos) if it is. As with character-offset, if there are not n lines
+then nil is returned and mark is not modified.
+ </para>
+ </refsect1>
+ </refentry>
+ </sect3>
+ </sect2>
+ <sect2 id=3D"Regions">
+ <title>Regions</title>
+ <para>
+A <code>region</code> is simply a pair of marks: a starting mark and an en=
ding
+mark. The text in a region consists of the characters following the
+starting mark and preceding the ending mark (keep in mind that a mark
+points between characters on a line, not at them). By modifying the
+starting or ending mark in a region it is possible to produce regions
+with a start and end which are out of order or even in different
+buffers. The use of such regions is undefined and may result in
+arbitrarily bad behavior.
+ </para>
+ <sect3 id=3D"RegionsRegionFunctions">
+ <title>Region Functions</title>
+ <refentry id=3D"f_region">
+ <indexterm zone=3D"f_region">
+ <primary>region</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>region</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ region start end =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+This function returns a region constructed from the marks start and
+end. It is an error for the marks to point to non-contiguous lines or
+for start to come after end.
+ </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_regionp">
+ <indexterm zone=3D"f_regionp">
+ <primary>regionp</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>regionp</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ regionp region =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+This function returns t if region is a region object, otherwise nil.
+ </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_make-empty-region">
+ <indexterm zone=3D"f_make-empty-region">
+ <primary>make-empty-region</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>make-empty-region</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ make-empty-region =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+This function returns a region with start and end marks pointing to
+the start of one empty line. The start mark is a <code>:right-inserting</=
code>
+mark, and the end is a <code>:left-inserting</code> mark.
+ </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_copy-region">
+ <indexterm zone=3D"f_copy-region">
+ <primary>copy-region</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>copy-region</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ copy-region region =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+This function returns a region containing a copy of the text in the
+specified region. The resulting region is completely disjoint
+from region with respect to data references --- marks, lines, text, etc.
+ </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_region-to-string">
+ <indexterm zone=3D"f_region-to-string">
+ <primary>region-to-string</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>region-to-string</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ region-to-string region =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para> </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_string-to-region">
+ <indexterm zone=3D"f_string-to-region">
+ <primary>string-to-region</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>string-to-region</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ string-to-region string =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+These functions coerce regions to Lisp strings and vice versa. Within
+the string, lines are delimited by newline characters.
+ </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_line-to-region">
+ <indexterm zone=3D"f_line-to-region">
+ <primary>line-to-region</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>line-to-region</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ line-to-region line =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+This function returns a region containing all the characters on
+line. The first mark is <code>:right-inserting</code> and the last is
+ <code>:left-inserting</code>.
+ </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_region-start">
+ <indexterm zone=3D"f_region-start">
+ <primary>region-start</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>region-start</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ region-start region =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para> </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_region-end">
+ <indexterm zone=3D"f_region-end">
+ <primary>region-end</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>region-end</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ region-end region =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+This function returns the start or end mark of region.
+ </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_region-bounds">
+ <indexterm zone=3D"f_region-bounds">
+ <primary>region-bounds</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>region-bounds</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ region-bounds region =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+This function returns as multiple-values the starting and ending marks
+of region.
+ </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_set-region-bounds">
+ <indexterm zone=3D"f_set-region-bounds">
+ <primary>set-region-bounds</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>set-region-bounds</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ set-region-bounds region start end =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+This function sets the start and end of region to start and end. It is
+an error for start to be after or in a different buffer from end.
+ </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_count-lines">
+ <indexterm zone=3D"f_count-lines">
+ <primary>count-lines</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>count-lines</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ count-lines region =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+This function returns the number of lines in the region, first and
+last lines inclusive. A newline is associated with the line it
+follows, thus a region containing some number of non-newline
+characters followed by one newline is one line, but if a newline were
+added at the beginning, it would be two lines.
+ </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_count-characters">
+ <indexterm zone=3D"f_count-characters">
+ <primary>count-characters</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>count-characters</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ count-characters region =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+This function returns the number of characters in a given region. This
+counts line breaks as one character.
+ </para>
+ </refsect1>
+ </refentry>
+ </sect3>
+ </sect2>
+ </sect1>
+ <sect1 id=3D"HemlockProgrammingBuffers">
+ <title>Buffers</title>
+ <para>
+A buffer is an object consisting of:
+ <orderedlist>
+ <listitem>
+ <para>
+A name.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+A piece of text.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+The insertion point.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+An associated file (optional).
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+A write protect flag.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Some <ulink url=3D"HemlockProgrammer/HemlockVariables">variables</ulink>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Some <ulink url=3D"HemlockProgrammer/Commands">key bindings</ulink>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+A collection of <ulink url=3D"HemlockProgrammer/Modes">modes</ulink>.
+10. A list of modeline fields (optional).
+ </para>
+ </listitem>
+ </orderedlist>Because of the way Hemlock is currently integrat=
ed in Cocoa, all modifications
+to buffer contents must take place in the GUI thread. Hemlock commands al=
ways
+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, y=
ou
+should perform that action using <code>gui::execute-in-gui</code> or <code=
>gui::queue-for-gui</code>.
+ </para>
+ <para>
+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.
+ </para>
+ <sect2 id=3D"CurrentBuffer">
+ <title>The Current Buffer</title>
+ <para>
+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.
+ </para>
+ <refentry id=3D"f_current-buffer">
+ <indexterm zone=3D"f_current-buffer">
+ <primary>current-buffer</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>current-buffer</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ current-buffer =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+Returns the current buffer, which, during command execution, is the
+buffer that is the target of the command.
+ </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_current-point">
+ <indexterm zone=3D"f_current-point">
+ <primary>current-point</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>current-point</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ current-point =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+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.
+ </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_current-point-collapsing-selection">
+ <indexterm zone=3D"f_current-point-collapsing-selection">
+ <primary>current-point-collapsing-selection</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>current-point-collapsing-selection</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ current-point-collapsing-selection =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+This function returns the buffer-point of the current buffer, after first
+deactivating any active region.
+ </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_current-point-extending-selection">
+ <indexterm zone=3D"f_current-point-extending-selection">
+ <primary>current-point-extending-selection</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>current-point-extending-selection</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ current-point-extending-selection =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+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.
+ </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_current-point-for-insertion">
+ <indexterm zone=3D"f_current-point-for-insertion">
+ <primary>current-point-for-insertion</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>current-point-for-insertion</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ current-point-for-insertion =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+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.
+ </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_current-point-for-deletion">
+ <indexterm zone=3D"f_current-point-for-deletion">
+ <primary>current-point-for-deletion</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>current-point-for-deletion</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ current-point-for-deletion =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+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.
+ </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_current-point-unless-selection">
+ <indexterm zone=3D"f_current-point-unless-selection">
+ <primary>current-point-unless-selection</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>current-point-unless-selection</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ current-point-unless-selection =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+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.
+ </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_current-mark">
+ <indexterm zone=3D"f_current-mark">
+ <primary>current-mark</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>current-mark</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ current-mark =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+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.
+ </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_pop-buffer-mark">
+ <indexterm zone=3D"f_pop-buffer-mark">
+ <primary>pop-buffer-mark</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>pop-buffer-mark</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ pop-buffer-mark =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+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 <ulink url=3D"HemlockProgrammer/AlteringAndSearchingText#Activ=
eRegions">Active Regions</ulink>).
+ </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_push-buffer-mark">
+ <indexterm zone=3D"f_push-buffer-mark">
+ <primary>push-buffer-mark</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>push-buffer-mark</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ push-buffer-mark mark &optional; activate-region =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+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 <ulink url=3D"HemlockProgrammer/AlteringAndSearchingText#ActiveRegion=
s">Active Regions</ulink>).
+Mark is returned.
+ </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_push-new-buffer-mark">
+ <indexterm zone=3D"f_push-new-buffer-mark">
+ <primary>push-new-buffer-mark</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>push-new-buffer-mark</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ push-new-buffer-mark mark &optional; activate-regi=
on =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+This function pushes a new mark onto the mark stack, at the position of <c=
ode>mark</code>.
+It's equivalent to calling <code>push-buffer-mark</code> on <code>(copy-ma=
rk mark)</code>.
+ </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_all-buffers">
+ <indexterm zone=3D"f_all-buffers">
+ <primary>all-buffers</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>all-buffers</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ all-buffers =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+This function returns a list of all the buffer objects made with make-buff=
er.
+ </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"v_buffer-names">
+ <indexterm zone=3D"v_buffer-names">
+ <primary>*buffer-names*</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>*buffer-names*</refname>
+ <refpurpose></refpurpose>
+ <refclass>Variable</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ *buffer-names* =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+This variable holds a <ulink url=3D"HemlockProgrammer/Utilities#StringTabl=
es">string-table</ulink>
+mapping the name of a buffer to the corresponding buffer object.
+ </para>
+ </refsect1>
+ </refentry>
+ </sect2>
+ <sect2 id=3D"BufferFunctions">
+ <title>Buffer Functions</title>
+ <refentry id=3D"f_make-buffer">
+ <indexterm zone=3D"f_make-buffer">
+ <primary>make-buffer</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>make-buffer</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ make-buffer name &key; :modes :modeline-fields :d=
elete-hook =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para> </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"hv_default_modeline_fields">
+ <indexterm zone=3D"hv_default_modeline_fields">
+ <primary>Default Modeline Fields</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>Default Modeline Fields</refname>
+ <refpurpose></refpurpose>
+ <refclass>Hemlock Variable</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ Default Modeline Fields =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para> </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"hv_make_buffer_hook">
+ <indexterm zone=3D"hv_make_buffer_hook">
+ <primary>Make Buffer Hook</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>Make Buffer Hook</refname>
+ <refpurpose></refpurpose>
+ <refclass>Hemlock Variable</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ Make Buffer Hook =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+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.
+ </para>
+ <para>
+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.
+ </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_bufferp">
+ <indexterm zone=3D"f_bufferp">
+ <primary>bufferp</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>bufferp</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ bufferp buffer =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+Returns t if buffer is a buffer object, otherwise nil.
+ </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_buffer-name">
+ <indexterm zone=3D"f_buffer-name">
+ <primary>buffer-name</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>buffer-name</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ buffer-name buffer =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para> </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"hv_buffer_name_hook">
+ <indexterm zone=3D"hv_buffer_name_hook">
+ <primary>Buffer Name Hook</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>Buffer Name Hook</refname>
+ <refpurpose></refpurpose>
+ <refclass>Hemlock Variable</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ Buffer Name Hook =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+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.
+ </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_buffer-region">
+ <indexterm zone=3D"f_buffer-region">
+ <primary>buffer-region</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>buffer-region</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ buffer-region buffer =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+Returns the buffer's region. Note this is the region that contains all
+the text in a buffer, not the current-region (page 19).
+ </para>
+ <para>
+This can be set with setf to replace the buffer's text.
+ </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_buffer-pathname">
+ <indexterm zone=3D"f_buffer-pathname">
+ <primary>buffer-pathname</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>buffer-pathname</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ buffer-pathname buffer =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para> </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"hv_buffer_pathname_hook">
+ <indexterm zone=3D"hv_buffer_pathname_hook">
+ <primary>Buffer Pathname Hook</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>Buffer Pathname Hook</refname>
+ <refpurpose></refpurpose>
+ <refclass>Hemlock Variable</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ Buffer Pathname Hook =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+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.
+ </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_buffer-write-date">
+ <indexterm zone=3D"f_buffer-write-date">
+ <primary>buffer-write-date</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>buffer-write-date</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ buffer-write-date buffer =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+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.
+ </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_buffer-point">
+ <indexterm zone=3D"f_buffer-point">
+ <primary>buffer-point</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>buffer-point</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ buffer-point buffer =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+Returns the mark which is the current location within buffer. To move
+the point, use move-mark or move-to-position (page 5).
+ </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_buffer-mark">
+ <indexterm zone=3D"f_buffer-mark">
+ <primary>buffer-mark</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>buffer-mark</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ buffer-mark buffer =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+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.
+ </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_buffer-start-mark">
+ <indexterm zone=3D"f_buffer-start-mark">
+ <primary>buffer-start-mark</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>buffer-start-mark</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ buffer-start-mark buffer =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para> </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_buffer-end-mark">
+ <indexterm zone=3D"f_buffer-end-mark">
+ <primary>buffer-end-mark</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>buffer-end-mark</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ buffer-end-mark buffer =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+These functions return the start and end marks of buffer's region:
+<programlisting>
+<![CDATA[
+(buffer-start-mark buffer ) <=3D=3D> (region-start (buffer-region =
buffer))
+]]>
+</programlisting>and
+<programlisting>
+<![CDATA[
+(buffer-end-mark buffer ) <=3D=3D> (region-end (buffer-region buff=
er))
+]]>
+</programlisting>
+ </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_buffer-writable">
+ <indexterm zone=3D"f_buffer-writable">
+ <primary>buffer-writable</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>buffer-writable</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ buffer-writable buffer =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para> </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"hv_buffer_writable_hook">
+ <indexterm zone=3D"hv_buffer_writable_hook">
+ <primary>Buffer Writable Hook</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>Buffer Writable Hook</refname>
+ <refpurpose></refpurpose>
+ <refclass>Hemlock Variable</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ Buffer Writable Hook =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+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.
+ </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_buffer-modified">
+ <indexterm zone=3D"f_buffer-modified">
+ <primary>buffer-modified</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>buffer-modified</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ buffer-modified buffer =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para> </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"hv_buffer_modified_hook">
+ <indexterm zone=3D"hv_buffer_modified_hook">
+ <primary>Buffer Modified Hook</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>Buffer Modified Hook</refname>
+ <refpurpose></refpurpose>
+ <refclass>Hemlock Variable</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ Buffer Modified Hook =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+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.
+ </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"m_with-writable-buffer">
+ <indexterm zone=3D"m_with-writable-buffer">
+ <primary>with-writable-buffer</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>with-writable-buffer</refname>
+ <refpurpose></refpurpose>
+ <refclass>Macro</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ with-writable-buffer (buffer) &body; body =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+This macro executes forms with buffer's writable status set. After
+forms execute, this resets the buffer's writable and modified status.
+ </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_buffer-signature">
+ <indexterm zone=3D"f_buffer-signature">
+ <primary>buffer-signature</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>buffer-signature</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ buffer-signature buffer =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+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.
+ </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_buffer-variables">
+ <indexterm zone=3D"f_buffer-variables">
+ <primary>buffer-variables</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>buffer-variables</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ buffer-variables buffer =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+This function returns a string-table (page 69) containing the names of
+the buffer's local variables. See chapter 6.
+ </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_buffer-modes">
+ <indexterm zone=3D"f_buffer-modes">
+ <primary>buffer-modes</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>buffer-modes</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ buffer-modes buffer =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+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.
+ </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_buffer-delete-hook">
+ <indexterm zone=3D"f_buffer-delete-hook">
+ <primary>buffer-delete-hook</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>buffer-delete-hook</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ buffer-delete-hook buffer =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+This function returns the list of buffer specific functions
+delete-buffer invokes when deleting a buffer . This is setf-able.
+ </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_delete-buffer">
+ <indexterm zone=3D"f_delete-buffer">
+ <primary>delete-buffer</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>delete-buffer</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ delete-buffer buffer =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para> </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"hv_delete_buffer_hook">
+ <indexterm zone=3D"hv_delete_buffer_hook">
+ <primary>Delete Buffer Hook</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>Delete Buffer Hook</refname>
+ <refpurpose></refpurpose>
+ <refclass>Hemlock Variable</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ Delete Buffer Hook =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+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.
+ </para>
+ </refsect1>
+ </refentry>
+ </sect2>
+ <sect2 id=3D"Modelines">
+ <title>Modelines</title>
+ <para>
+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.
+ </para>
+ <para>
+Whenever one of the following changes occurs, all of a buffer's
+modeline fields are updated:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+A buffer's major mode is set.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+One of a buffer's minor modes is turned on or off.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+A buffer is renamed.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+A buffer's pathname changes.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+A buffer's modified status changes.
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>
+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. =
+ </para>
+ <para>
+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).
+ </para>
+ <refentry id=3D"f_make-modeline-field">
+ <indexterm zone=3D"f_make-modeline-field">
+ <primary>make-modeline-field</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>make-modeline-field</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ make-modeline-field &key; :name :width :function =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+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.
+ </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_modeline-field-name">
+ <indexterm zone=3D"f_modeline-field-name">
+ <primary>modeline-field-name</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>modeline-field-name</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ modeline-field-name modeline-field =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+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.
+ </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_modeline-field-p">
+ <indexterm zone=3D"f_modeline-field-p">
+ <primary>modeline-field-p</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>modeline-field-p</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ modeline-field-p modeline-field =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+This function returns t if its argument is a modeline-field object, nil
+otherwise.
+ </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_modeline-field">
+ <indexterm zone=3D"f_modeline-field">
+ <primary>modeline-field</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>modeline-field</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ modeline-field name =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+This returns the modeline-field object named name. If none exists, this
+returns nil.
+ </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_modeline-field-function">
+ <indexterm zone=3D"f_modeline-field-function">
+ <primary>modeline-field-function</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>modeline-field-function</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ modeline-field-function modeline-field =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+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.
+ </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_modeline-field-width">
+ <indexterm zone=3D"f_modeline-field-width">
+ <primary>modeline-field-width</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>modeline-field-width</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ modeline-field-width modeline-field =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+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.
+ </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_buffer-modeline-fields">
+ <indexterm zone=3D"f_buffer-modeline-fields">
+ <primary>buffer-modeline-fields</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>buffer-modeline-fields</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ buffer-modeline-fields buffer =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+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.
+ </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_buffer-modeline-field-p">
+ <indexterm zone=3D"f_buffer-modeline-field-p">
+ <primary>buffer-modeline-field-p</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>buffer-modeline-field-p</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ buffer-modeline-field-p buffer field =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+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.
+ </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_update-modeline-fields">
+ <indexterm zone=3D"f_update-modeline-fields">
+ <primary>update-modeline-fields</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>update-modeline-fields</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ update-modeline-fields buffer =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+Arranges so that the modeline display is updated with the latest values
+at the end of current command.
+ </para>
+ </refsect1>
+ </refentry>
+ </sect2>
+ </sect1>
+ <sect1 id=3D"HemlockProgrammingAlteringAndSearchingText">
+ <title>Altering and Searching Text</title>
+ <para>
+A note on marks and text alteration: :temporary marks are invalid
+after any change has been made to the buffer the mark points to; it is
+an error to use a temporary mark after such a change has been made.
+ </para>
+ <para>
+If text is deleted which has permanent marks pointing into it then
+they are left pointing to the position where the text was.
+ </para>
+ <sect2 id=3D"AlteringText">
+ <title>Altering Text</title>
+ <refentry id=3D"f_insert-character">
+ <indexterm zone=3D"f_insert-character">
+ <primary>insert-character</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>insert-character</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ insert-character mark character =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para> </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_insert-string">
+ <indexterm zone=3D"f_insert-string">
+ <primary>insert-string</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>insert-string</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ insert-string mark string =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para> </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_insert-region">
+ <indexterm zone=3D"f_insert-region">
+ <primary>insert-region</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>insert-region</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ insert-region mark region =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+Inserts character, string or region at mark. <code>insert-character</code>=
signals
+an error if character is not <code>string-char-p</code>. If string or regi=
on is
+empty, and mark is in some buffer, then Hemlock leaves buffer-modified of
+mark's buffer unaffected.
+ </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_ninsert-region">
+ <indexterm zone=3D"f_ninsert-region">
+ <primary>ninsert-region</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>ninsert-region</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ ninsert-region mark region =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+Like <code>insert-region</code>, inserts the region at the mark's position,
+destroying the source region. This must be used with caution, since
+if anyone else can refer to the source region bad things will
+happen. In particular, one should make sure the region is not linked
+into any existing buffer. If region is empty, and mark is in some
+buffer, then Hemlock leaves buffer-modified of mark's buffer unaffected.
+ </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_delete-characters">
+ <indexterm zone=3D"f_delete-characters">
+ <primary>delete-characters</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>delete-characters</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ delete-characters mark n =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+This deletes n characters after the mark (or -n before if n is
+negative). If n characters after (or -n before) the mark do not
+exist, then this returns nil; otherwise, it returns t. If n is zero,
+and mark is in some buffer, then Hemlock leaves buffer-modified of
+mark's buffer unaffected.
+ </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_delete-region">
+ <indexterm zone=3D"f_delete-region">
+ <primary>delete-region</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>delete-region</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ delete-region region =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+This deletes region. This is faster than delete-and-save-region
+(below) because no lines are copied. If region is empty and contained
+in some buffer's buffer-region, then Hemlock leaves buffer-modified of
+the buffer unaffected.
+ </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_delete-and-save-region">
+ <indexterm zone=3D"f_delete-and-save-region">
+ <primary>delete-and-save-region</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>delete-and-save-region</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ delete-and-save-region region =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+This deletes region and returns a region containing the original
+region's text. If region is empty and contained in some buffer's
+buffer-region, then Hemlock leaves buffer-modified of the buffer
+unaffected. In this case, this returns a distinct empty region.
+ </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_filter-region">
+ <indexterm zone=3D"f_filter-region">
+ <primary>filter-region</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>filter-region</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ filter-region function region =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+Destructively modifies region by replacing the text of each line with
+the result of the application of function to a string containing that
+text. Function must obey the following restrictions:
+ </para>
+ <orderedlist>
+ <listitem>
+ <para>
+The argument may not be destructively modified.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+The return value may not contain newline characters.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+The return value may not be destructively modified after it is returned fr=
om function.
+ </para>
+ </listitem>
+ </orderedlist>
+ <para>
+The strings are passed in order.
+ </para>
+ <para>
+Using this function, a region could be uppercased by doing:
+ <code>(filter-region #'string-upcase region)</code>
+ </para>
+ </refsect1>
+ </refentry>
+ </sect2>
+ <sect2 id=3D"TextPredicates">
+ <title>Text Predicates</title>
+ <refentry id=3D"f_start-line-p">
+ <indexterm zone=3D"f_start-line-p">
+ <primary>start-line-p</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>start-line-p</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ start-line-p mark =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+Returns t if the mark points before the first character in a line, nil
+otherwise.
+ </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_end-line-p">
+ <indexterm zone=3D"f_end-line-p">
+ <primary>end-line-p</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>end-line-p</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ end-line-p mark =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+Returns t if the mark points after the last character in a line and
+before the newline, nil otherwise.
+ </para>
+ <para>
+ <code>empty-line-p</code> mark [Function]
+Return t if the line which mark points to contains no characters.
+ </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_blank-line-p">
+ <indexterm zone=3D"f_blank-line-p">
+ <primary>blank-line-p</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>blank-line-p</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ blank-line-p line =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+Returns t if line contains only characters with a Whitespace attribute
+of 1. See chapter 9 for discussion of character attributes.
+ </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_blank-before-p">
+ <indexterm zone=3D"f_blank-before-p">
+ <primary>blank-before-p</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>blank-before-p</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ blank-before-p mark =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para> </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_blank-after-p">
+ <indexterm zone=3D"f_blank-after-p">
+ <primary>blank-after-p</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>blank-after-p</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ blank-after-p mark =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+These functions test if all the characters preceding or following mark
+on the line it is on have a Whitespace attribute of 1.
+ </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_same-line-p">
+ <indexterm zone=3D"f_same-line-p">
+ <primary>same-line-p</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>same-line-p</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ same-line-p mark1 mark2 =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+Returns t if mark1 and mark2 point to the same line, or nil otherwise; Tha=
t is,
+<programlisting>
+<![CDATA[
+(same-line-p a b) <=3D=3D> (eq (mark-line a) (mark-line b))
+]]>
+</programlisting>
+ </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_mark_lt">
+ <indexterm zone=3D"f_mark_lt">
+ <primary>mark<</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>mark<</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ mark< mark1 mark2 =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para> </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_mark_lt__eq">
+ <indexterm zone=3D"f_mark_lt__eq">
+ <primary>mark<=3D</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>mark<=3D</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ mark<=3D mark1 mark2 =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para> </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_mark_eq">
+ <indexterm zone=3D"f_mark_eq">
+ <primary>mark=3D</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>mark=3D</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ mark=3D mark1 mark2 =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para> </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_mark__eq">
+ <indexterm zone=3D"f_mark__eq">
+ <primary>mark/=3D</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>mark/=3D</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ mark/=3D mark1 mark2 =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para> </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_mark_gt__eq">
+ <indexterm zone=3D"f_mark_gt__eq">
+ <primary>mark>=3D</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>mark>=3D</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ mark>=3D mark1 mark2 =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para> </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_mark_gt">
+ <indexterm zone=3D"f_mark_gt">
+ <primary>mark></primary>
+ </indexterm>
+ <refnamediv>
+ <refname>mark></refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ mark> mark1 mark2 =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+These predicates test the relative ordering of two marks in a piece of
+text, that is a mark is mark> another if it points to a position after
+it. An error is signalled if the marks do not point into the same buffer,
+except that for such marks mark=3D is always false and mark/=3D is always =
true.
+ </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_line_lt">
+ <indexterm zone=3D"f_line_lt">
+ <primary>line<</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>line<</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ line< line1 line2 =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para> </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_line_lt__eq">
+ <indexterm zone=3D"f_line_lt__eq">
+ <primary>line<=3D</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>line<=3D</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ line<=3D line1 line2 =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para> </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_line_gt__eq">
+ <indexterm zone=3D"f_line_gt__eq">
+ <primary>line>=3D</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>line>=3D</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ line>=3D line1 line2 =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para> </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_line_gt">
+ <indexterm zone=3D"f_line_gt">
+ <primary>line></primary>
+ </indexterm>
+ <refnamediv>
+ <refname>line></refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ line> line1 line2 =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+These predicates test the ordering of line1 and line2. An error is signall=
ed
+if the lines are not in the same buffer.
+ </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_lines-related">
+ <indexterm zone=3D"f_lines-related">
+ <primary>lines-related</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>lines-related</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ lines-related line1 line2 =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+This function returns t if line1 and line2 are in the same buffer, nil
+nil otherwise.
+ </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_first-line-p">
+ <indexterm zone=3D"f_first-line-p">
+ <primary>first-line-p</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>first-line-p</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ first-line-p mark =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para> </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_last-line-p">
+ <indexterm zone=3D"f_last-line-p">
+ <primary>last-line-p</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>last-line-p</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ last-line-p mark =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+ <code>first-line-p</code> returns t if there is no=
line before the line mark is on,
+and nil otherwise. <code>Last-line-p</code> similarly tests tests whether =
there is
+no line after mark.
+ </para>
+ </refsect1>
+ </refentry>
+ </sect2>
+ <sect2 id=3D"KillRing">
+ <title>Kill Ring</title>
+ <para>
+There is a global ring (see section 16.2) of regions deleted from buffers.
+Some commands save affected regions on the kill ring before performing
+modifications. You should consider making the command undoable (see
+section 16.3), but this is a simple way of achieving a less
+satisfactory means for the user to recover.
+ </para>
+ <refentry id=3D"f_kill-region">
+ <indexterm zone=3D"f_kill-region">
+ <primary>kill-region</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>kill-region</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ kill-region region current-type =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+This kills region saving it in the kill ring. Current-type is either
+:kill-forward or :kill-backward. When the last-command-type (page 31)
+is one of these, this adds region to the beginning or end,
+respectively, of the top of the kill ring. The result of calling this is
+undoable using the command Undo (see the Hemlock User's Manual). This
+sets last-command-type to current-type, and it interacts with
+kill-characters.
+ </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_kill-characters">
+ <indexterm zone=3D"f_kill-characters">
+ <primary>kill-characters</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>kill-characters</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ kill-characters mark count =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para> </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"hv_character_deletion_threshold">
+ <indexterm zone=3D"hv_character_deletion_threshold">
+ <primary>Character Deletion Threshold</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>Character Deletion Threshold</refname>
+ <refpurpose></refpurpose>
+ <refclass>Hemlock Variable</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ Character Deletion Threshold (initial value 5) =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+kill-characters kills count characters after mark if count is
+positive, otherwise before mark if count is negative. When count is
+greater than or equal to Character Deletion Threshold, the killed
+characters are saved on the kill ring. This may be called multiple times
+contiguously (that is, without last-command-type (page 31) being set)
+to accumulate an effective count for purposes of comparison with the
+threshold.
+ </para>
+ <para>
+This sets last-command-type, and it interacts with kill-region. When
+this adds a new region to the kill ring, it sets last-command-type to
+:kill-forward (if count is positive) or :kill-backward (if count is
+negative). When last-command-type is :kill-forward or :kill-backward,
+this adds the killed characters to the beginning (if count is
+negative) or the end (if count is positive) of the top of the kill ring,
+and it sets last-command-type as if it added a new region to the
+kill ring. When the kill ring is unaffected, this sets
+last-command-type to :char-kill-forward or :char-kill-backward
+depending on whether count is positive or negative, respectively.
+ </para>
+ <para>
+This returns mark if it deletes characters. If there are not count
+characters in the appropriate direction, this returns nil.
+ </para>
+ </refsect1>
+ </refentry>
+ </sect2>
+ <sect2 id=3D"ActiveRegions">
+ <title>Active Regions</title>
+ <para>
+Every buffer has a mark stack (page 9) and a mark known as the point
+where most text altering nominally occurs. Between the top of the
+mark stack, the current-mark, and the current-buffer's point, the
+current-point, is what is known as the current-region . Certain
+commands signal errors when the user tries to operate on the
+current-region without its having been activated. If the user turns
+off this feature, then the current-region is effectively always
+active.
+ </para>
+ <para>
+When writing a command that marks a region of text, the programmer
+should make sure to activate the region. This typically occurs
+naturally from the primitives that you use to mark regions, but
+sometimes you must explicitly activate the region. These commands
+should be written this way, so they do not require the user to
+separately mark an area and then activate it. Commands that modify
+regions do not have to worry about deactivating the region since
+modifying a buffer automatically deactivates the region. Commands
+that insert text often activate the region ephemerally; that is, the
+region is active for the immediately following command, allowing the
+user wants to delete the region inserted, fill it, or whatever.
+ </para>
+ <para>
+Once a marking command makes the region active, it remains active until:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+a command uses the region,
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+a command modifies the buffer,
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+a command changes the current window or buffer,
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+a command signals an editor-error,
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+or the user types C-g.
+ </para>
+ </listitem>
+ </itemizedlist>
+ <refentry id=3D"hv_active_regions_enabled">
+ <indexterm zone=3D"hv_active_regions_enabled">
+ <primary>Active Regions Enabled</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>Active Regions Enabled</refname>
+ <refpurpose></refpurpose>
+ <refclass>Hemlock Variable</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ Active Regions Enabled (initial value t) =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+When this variable is non-nil, some primitives signal an editor-error
+if the region is not active. This may be set to nil for more
+traditional Emacs region semantics.
+ </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"v_ephemerally-active-command-types">
+ <indexterm zone=3D"v_ephemerally-active-command-types">
+ <primary>*ephemerally-active-command-types*</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>*ephemerally-active-command-types*</refname>
+ <refpurpose></refpurpose>
+ <refclass>Variable</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ *ephemerally-active-command-types* =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+This is a list of command types (see section 7.3), and its initial
+value is the list of :ephemerally-active and :unkill. When the
+previous command's type is one of these, the current-region is active
+for the currently executing command only, regardless of whether it
+does something to deactivate the region. However, the current command
+may activate the region for future commands. :ephemerally-active is a
+default command type that may be used to ephemerally activate the
+region, and:unkill is the type used by two commands, Un-kill and
+Rotate Kill Ring (what users typically think of as C-y and M-y).
+ </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_activate-region">
+ <indexterm zone=3D"f_activate-region">
+ <primary>activate-region</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>activate-region</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ activate-region =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+This makes the current-region active.
+ </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_deactivate-region">
+ <indexterm zone=3D"f_deactivate-region">
+ <primary>deactivate-region</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>deactivate-region</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ deactivate-region =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+After invoking this the current-region is no longer active.
+ </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_region-active-p">
+ <indexterm zone=3D"f_region-active-p">
+ <primary>region-active-p</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>region-active-p</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ region-active-p =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+Returns whether the current-region is active, including
+ephemerally. This ignores Active Regions Enabled.
+ </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_check-region-active">
+ <indexterm zone=3D"f_check-region-active">
+ <primary>check-region-active</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>check-region-active</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ check-region-active =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+This signals an editor-error when active regions are enabled, and the
+current-region is not active.
+ </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_current-region">
+ <indexterm zone=3D"f_current-region">
+ <primary>current-region</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>current-region</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ current-region &optional; error-if-not-active deac=
tivate-region =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+This returns a region formed with current-mark and current-point,
+optionally signaling an editor-error if the current region is not
+active. Error-if-not-active defaults to t. Each call returns a
+distinct region object. Depending on deactivate-region (defaults to
+t), fetching the current region deactivates it. Hemlock primitives
+are free to modify text regardless of whether the region is active, so
+a command that checks for this can deactivate the region whenever it
+is convenient.
+ </para>
+ </refsect1>
+ </refentry>
+ </sect2>
+ <sect2 id=3D"SearchingAndReplacing">
+ <title>Searching and Replacing</title>
+ <para>
+Before using any of these functions to do a character search, look at
+character attributes (page 37). They provide a facility similar to
+the syntax table in real Emacs. Syntax tables are a powerful,
+general, and efficient mechanism for assigning meanings to characters
+in various modes.
+ </para>
+ <refentry id=3D"f_new-search-pattern">
+ <indexterm zone=3D"f_new-search-pattern">
+ <primary>new-search-pattern</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>new-search-pattern</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ new-search-pattern kind direction pattern &optiona=
l; result-search-pattern =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+Returns a search-pattern object which can be given to the find-pattern
+and replace-pattern functions. A search-pattern is a specification of
+a particular sort of search to do. direction is either :forward or
+:backward, indicating the direction to search in. kind specifies the
+kind of search pattern to make, and pattern is a thing which specifies
+what to search for. The interpretation of pattern depends on the kind
+of pattern being made. Currently defined kinds of search pattern are:
+ </para>
+ <variablelist>
+ <varlistentry>
+ <term>:string-insensitive</term>
+ <listitem>
+ <para>
+Does a case-insensitive string search for pattern
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>:string-sensitive</term>
+ <listitem>
+ <para>
+Does a case-sensitive string search for pattern.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>:character</term>
+ <listitem>
+ <para>
+Finds an occurrence of the character pattern. This is case sensitive.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>:not-character</term>
+ <listitem>
+ <para>
+Find a character which is not the character pattern.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>:test</term>
+ <listitem>
+ <para>
+Finds a character which satisfies the function pattern. This function may =
not be applied an any particular fashion, so it should depend only on what =
its argument is, and should have no side-effects.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>:test-not</term>
+ <listitem>
+ <para>
+Similar to :test, except it finds a character that fails the test.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>:any</term>
+ <listitem>
+ <para>
+Finds a character that is in the string pattern.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>:not-any</term>
+ <listitem>
+ <para>
+Finds a character that is not in the string pattern.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ <para>
+result-search-pattern, if supplied, is a search-pattern to
+destructively modify to produce the new pattern. Where reasonable
+this should be supplied, since some kinds of search patterns may
+involve large data structures.
+ </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_search-pattern-p">
+ <indexterm zone=3D"f_search-pattern-p">
+ <primary>search-pattern-p</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>search-pattern-p</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ search-pattern-p search-pattern =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+Returns t if search-pattern is a search-pattern object, otherwise nil.
+ </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_get-search-pattern">
+ <indexterm zone=3D"f_get-search-pattern">
+ <primary>get-search-pattern</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>get-search-pattern</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ get-search-pattern string direction =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+get-search-pattern interfaces to a default search string and pattern
+that search and replacing commands can use. These commands then share
+a default when prompting for what to search or replace, and save on
+consing a search pattern each time they execute. This uses Default
+Search Kind (see the Hemlock User's Manual) when updating the pattern
+object.
+ </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"v_last-search-string">
+ <indexterm zone=3D"v_last-search-string">
+ <primary>*last-search-string*</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>*last-search-string*</refname>
+ <refpurpose></refpurpose>
+ <refclass>Variable</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ *last-search-string* =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+Returns the last string searched for, useful when prompting.
+ </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_find-pattern">
+ <indexterm zone=3D"f_find-pattern">
+ <primary>find-pattern</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>find-pattern</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ find-pattern mark search-pattern =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+Find the next match of search-pattern starting at mark. If a match is
+found then mark is altered to point before the matched text and the
+number of characters matched is returned. If no match is found then
+nil is returned and mark is not modified.
+ </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_replace-pattern">
+ <indexterm zone=3D"f_replace-pattern">
+ <primary>replace-pattern</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>replace-pattern</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ replace-pattern mark search-pattern replacement &o=
ptional; n =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+Replace n matches of search-pattern with the string replacement
+starting at mark. If n is nil (the default) then replace all matches.
+A mark pointing before the last replacement done is returned.
+ </para>
+ </refsect1>
+ </refentry>
+ </sect2>
+ </sect1>
+ <sect1 id=3D"HemlockProgrammingTheCurrentEnvironment">
+ <title>The Current Environment</title>
+ <sect2 id=3D"DifferentScopes">
+ <title>Different Scopes</title>
+ <para>
+In Hemlock the "current" values of <ulink url=3D"HemlockProgrammer/Hemlock=
Variables">variables</ulink>,
+<ulink url=3D"HemlockProgrammer/Commands">key bindings</ulink> and
+<ulink url=3D"HemlockProgrammer/CharacterAttributes">character-attributes<=
/ulink>
+depend on the <ulink url=3D"HemlockProgrammer/Buffers#CurrentBuffer">curre=
nt buffer</ulink>
+and the modes active in it. There are three possible scopes for
+Hemlock values:
+ </para>
+ <variablelist>
+ <varlistentry>
+ <term>buffer local</term>
+ <listitem>
+ <para>
+The value is present only if the buffer it is local to is the current buff=
er.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>mode local</term>
+ <listitem>
+ <para>
+The value is present only when the mode it is local to is active in the cu=
rrent buffer.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>global</term>
+ <listitem>
+ <para>
+The value is always present unless shadowed by a buffer or mode local valu=
e.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </sect2>
+ <sect2 id=3D"Shadowing">
+ <title>Shadowing</title>
+ <para>
+It is possible that there are different values for the same thing in =
+in different scopes. For example, there be might a global binding for a g=
iven
+variable and also a local binding in the current buffer. Whenever there i=
s a
+conflict, shadowing occurs, permitting only one of the values to be visibl=
e in
+the current environment.
+ </para>
+ <para>
+The process of resolving such a conflict can be described as a search
+down a list of places where the value might be defined, returning the
+first value found. The order for the search is as follows:
+ </para>
+ <orderedlist>
+ <listitem>
+ <para>
+Local values in the current buffer.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Mode local values in the minor modes of the current buffer, in order from =
the highest precedence mode to the lowest precedence mode. The order of mi=
nor modes with equal precedences is undefined.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Mode local values in the current buffer's major mode.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Global values.
+ </para>
+ </listitem>
+ </orderedlist>
+ </sect2>
+ </sect1>
+ <sect1 id=3D"HemlockProgrammingHemlockVariables">
+ <title>Hemlock Variables</title>
+ <para>
+Hemlock implements a system of variables separate from normal Lisp
+variables for the following reasons:
+ </para>
+ <orderedlist>
+ <listitem>
+ <para>
+Hemlock has different scoping rules which are useful in an editor. Hemloc=
k variables can be local to a buffer (page 9) or a mode (page 35).
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Hemlock variables have hooks (page 25), lists of functions called when som=
eone sets the variable. See variable-value for the arguments Hemlock passes=
to these hook functions.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+There is a database of variable names and documentation which makes it eas=
ier to find out what variables exist and what their values mean.
+ </para>
+ </listitem>
+ </orderedlist>
+ <sect2 id=3D"VariableNames">
+ <title>Variable Names</title>
+ <para>
+To the user, a variable name is a case insensitive string. This
+string is referred to as the string name of the variable. A string
+name is conventionally composed of words separated by spaces.
+ </para>
+ <para>
+In Lisp code a variable name is a symbol. The name of this symbol is
+created by replacing any spaces in the string name with hyphens. This
+symbol name is always interned in the Hemlock package.
+ </para>
+ <refentry id=3D"v_global-variable-names">
+ <indexterm zone=3D"v_global-variable-names">
+ <primary>*global-variable-names*</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>*global-variable-names*</refname>
+ <refpurpose></refpurpose>
+ <refclass>Variable</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ *global-variable-names* =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+This variable holds a string-table of the names of all the global
+Hemlock variables. The value of each entry is the symbol name of the
+variable.
+ </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_current-variable-tables">
+ <indexterm zone=3D"f_current-variable-tables">
+ <primary>current-variable-tables</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>current-variable-tables</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ current-variable-tables =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+This function returns a list of variable tables currently established,
+globally, in the current buffer, and by the modes of the
+current-buffer. This list is suitable for use with
+prompt-for-variable.
+ </para>
+ </refsect1>
+ </refentry>
+ </sect2>
+ <sect2 id=3D"VariableFunctions">
+ <title>Variable Functions</title>
+ <para>
+In the following descriptions name is the symbol name of the variable.
+ </para>
+ <refentry id=3D"f_defhvar">
+ <indexterm zone=3D"f_defhvar">
+ <primary>defhvar</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>defhvar</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ defhvar string-name documentation &key; :mode :buf=
fer :hooks :value =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+This function defines a Hemlock variable. Functions that take a
+variable name signal an error when the variable is undefined.
+ </para>
+ <variablelist>
+ <varlistentry>
+ <term>string-name</term>
+ <listitem>
+ <para>
+The string name of the variable to define.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>documentation</term>
+ <listitem>
+ <para>
+The documentation string for the variable.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>:mode, :buffer</term>
+ <listitem>
+ <para>
+If buffer is supplied, the variable is local to that buffer. If mode is s=
upplied, it is local to that mode. If neither is supplied, it is global.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>:value</term>
+ <listitem>
+ <para>
+This is the initial value for the variable, which defaults to nil.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>:hooks</term>
+ <listitem>
+ <para>
+This is the initial list of functions to call when someone sets the variab=
le's value. These functions execute before Hemlock establishes the new valu=
e. See variable-value for the arguments passed to the hook functions.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ <para>
+If a variable with the same name already exists in the same place,
+then defhvar sets its hooks and value from hooks and value if the user
+supplies these keywords.
+ </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_variable-value">
+ <indexterm zone=3D"f_variable-value">
+ <primary>variable-value</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>variable-value</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ variable-value name &optional; kind where =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+This function returns the value of a Hemlock variable in some place. The f=
ollowing values for kind are defined:
+ </para>
+ <variablelist>
+ <varlistentry>
+ <term>:current</term>
+ <listitem>
+ <para>
+Return the value present in the current environment, taking into considera=
tion any mode or buffer local variables. This is the default.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>:global</term>
+ <listitem>
+ <para>
+Return the global value.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>:mode</term>
+ <listitem>
+ <para>
+Return the value in the mode named where.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>:buffer</term>
+ <listitem>
+ <para>
+Return the value in the buffer where.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ <para>
+When set with setf, Hemlock sets the value of the specified variable
+and invokes the functions in its hook list with name, kind, where, and
+the new value.
+ </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_variable-documentation">
+ <indexterm zone=3D"f_variable-documentation">
+ <primary>variable-documentation</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>variable-documentation</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ variable-documentation name &optional; kind where =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para> </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_variable-hooks">
+ <indexterm zone=3D"f_variable-hooks">
+ <primary>variable-hooks</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>variable-hooks</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ variable-hooks name &optional; kind where =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para> </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_variable-name">
+ <indexterm zone=3D"f_variable-name">
+ <primary>variable-name</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>variable-name</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ variable-name name &optional; kind where =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+These function return the documentation, hooks and string name of a
+Hemlock variable. The kind and where arguments are the same as for
+variable-value. The documentation and hook list may be set using setf.
+ </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_string-to-variable">
+ <indexterm zone=3D"f_string-to-variable">
+ <primary>string-to-variable</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>string-to-variable</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ string-to-variable string =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+This function converts a string into the corresponding variable symbol
+name. String need not be the name of an actual Hemlock variable.
+ </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"m_value">
+ <indexterm zone=3D"m_value">
+ <primary>value</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>value</refname>
+ <refpurpose></refpurpose>
+ <refclass>Macro</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ value name =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para> </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"m_setv">
+ <indexterm zone=3D"m_setv">
+ <primary>setv</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>setv</refname>
+ <refpurpose></refpurpose>
+ <refclass>Macro</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ setv name new-value =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+These macros get and set the current value of the Hemlock variable
+name. Name is not evaluated. There is a setf form for <code>value</code>.
+ </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"m_hlet">
+ <indexterm zone=3D"m_hlet">
+ <primary>hlet</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>hlet</refname>
+ <refpurpose></refpurpose>
+ <refclass>Macro</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ hlet ({(var value)}*){form}* =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+This macro is very similar to let in effect; within its scope each of
+the Hemlock variables var have the respective values, but after the
+scope is exited by any means the binding is removed. This does not
+cause any hooks to be invoked. The value of the last form is
+returned.
+ </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_hemlock-bound-p">
+ <indexterm zone=3D"f_hemlock-bound-p">
+ <primary>hemlock-bound-p</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>hemlock-bound-p</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ hemlock-bound-p name &optional; kind where =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+Returns t if name is defined as a Hemlock variable in the place
+specified by kind and where, or nil otherwise.
+ </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_delete-variable">
+ <indexterm zone=3D"f_delete-variable">
+ <primary>delete-variable</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>delete-variable</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ delete-variable name &optional; kind where =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para> </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"hv_delete_variable_hook">
+ <indexterm zone=3D"hv_delete_variable_hook">
+ <primary>Delete Variable Hook</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>Delete Variable Hook</refname>
+ <refpurpose></refpurpose>
+ <refclass>Hemlock Variable</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ Delete Variable Hook =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+delete-variable makes the Hemlock variable name no longer defined in
+the specified place. Kind and where have the same meanings as they do
+for variable-value, except that :current is not available, and the
+default for kind is :global
+ </para>
+ <para>
+An error will be signaled if no such variable exists. The hook,
+Delete Variable Hook is invoked with the same arguments before the
+variable is deleted.
+ </para>
+ </refsect1>
+ </refentry>
+ </sect2>
+ <sect2 id=3D"Hooks">
+ <title>Hooks</title>
+ <para>
+Hemlock actions such as setting variables, changing buffers, changing
+windows, turning modes on and off, etc., often have hooks associated
+with them. A hook is a list of functions called before the system
+performs the action. The manual describes the object specific hooks
+with the rest of the operations defined on these objects.
+ </para>
+ <para>
+Often hooks are stored in Hemlock variables, Delete Buffer Hook and
+Set Window Hook for example. This leads to a minor point of confusion
+because these variables have hooks that the system executes when
+someone changes their values. These hook functions Hemlock invokes
+when someone sets a variable are an example of a hook stored in an
+object instead of a Hemlock variable. These are all hooks for editor
+activity, but Hemlock keeps them in different kinds of locations.
+This is why some of the routines in this section have a special
+interpretation of the hook place argument.
+ </para>
+ <refentry id=3D"m_add-hook">
+ <indexterm zone=3D"m_add-hook">
+ <primary>add-hook</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>add-hook</refname>
+ <refpurpose></refpurpose>
+ <refclass>Macro</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ add-hook place hook-fun =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para> </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"m_remove-hook">
+ <indexterm zone=3D"m_remove-hook">
+ <primary>remove-hook</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>remove-hook</refname>
+ <refpurpose></refpurpose>
+ <refclass>Macro</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ remove-hook place hook-fun =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+These macros add or remove a hook function in some place. If hook-fun
+already exists in place, this call has no effect. If place is a
+symbol, then it is a Hemlock variable; otherwise, it is a generalized
+variable or storage location. Here are two examples:
+ </para><programlisting>
+<![CDATA[
+(add-hook delete-buffer-hook 'remove-buffer-from-menu)
+(add-hook (variable-hooks 'check-mail-interval)
+ 'reschedule-mail-check)
+]]>
+</programlisting>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"m_invoke-hook">
+ <indexterm zone=3D"m_invoke-hook">
+ <primary>invoke-hook</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>invoke-hook</refname>
+ <refpurpose></refpurpose>
+ <refclass>Macro</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ invoke-hook place &rest; args =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+This macro calls all the functions in place. If place is a symbol,
+then it is a Hemlock variable; otherwise, it is a generalized
+variable.
+ </para>
+ </refsect1>
+ </refentry>
+ </sect2>
+ </sect1>
+ <sect1 id=3D"HemlockProgrammingCommands">
+ <title>Commands</title>
+ <sect2 id=3D"HemlockProgrammingCommandsIntroduction">
+ <title>Introduction</title>
+ <para>
+The way that the user tells Hemlock to do something is by invoking a
+command. Commands have three attributes:
+ </para>
+ <variablelist>
+ <varlistentry>
+ <term>name</term>
+ <listitem>
+ <para>
+A command's name provides a way to refer to it. Command names are
+usually capitalized words separated by spaces, such as Forward Word.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>documentation</term>
+ <listitem>
+ <para>
+The documentation for a command is used by on-line help facilities.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>function</term>
+ <listitem>
+ <para>
+A command is implemented by a Lisp function, which is callable from Lisp.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ <refentry id=3D"v_command-names">
+ <indexterm zone=3D"v_command-names">
+ <primary>*command-names*</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>*command-names*</refname>
+ <refpurpose></refpurpose>
+ <refclass>Variable</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ *command-names* =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+Holds a string-table (page 69) associating command names to command
+objects. Whenever a new command is defined it is entered in this
+table.
+ </para>
+ </refsect1>
+ <refsect3>
+ <title>Defining Commands</title>
+ <refentry id=3D"m_defcommand">
+ <indexterm zone=3D"m_defcommand">
+ <primary>defcommand</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>defcommand</refname>
+ <refpurpose></refpurpose>
+ <refclass>Macro</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ defcommand {command-name | (command-name f=
unction-name &key;)} lambda-list command-doc {function-doc} {form}* =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+Defines a command named name. defcommand creates a function to
+implement the command from the lambda-list and forms supplied. The
+lambda-list must specify one required argument, see <ulink url=3D"HemlockP=
rogrammer/Commands#CommandArguments">below</ulink>,
+which by convention is typically named <code>p</code>. If the caller does =
not specify
+function-name, defcommand creates the command name by replacing all
+spaces with hyphens and appending "-command". Any keyword arguments
+are as for <code>make-command</code>. Command-doc becomes the command
+documentation for the command. Function-doc, if present, becomes the
+documentation for the function and should primarily describe
+issues involved in calling the command as a function, such as what any
+additional arguments are. =
+ </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_make-command">
+ <indexterm zone=3D"f_make-command">
+ <primary>make-command</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>make-command</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ make-command name documentation function &=
key; :transparent-p =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+Defines a new command named name, with command documentation
+documentation and function function. If :transparent-p is true,
+the command becomes <ulink url=3D"HemlockProgrammer/Commands#TransparentKe=
yBindings">transparent</ulink>.
+The command in entered in the
+string-table *command-names* (page 27), with the command object as its
+value. Normally command implementors will use the defcommand macro,
+but this permits access to the command definition mechanism at a lower
+level, which is occasionally useful.
+ </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_commandp">
+ <indexterm zone=3D"f_commandp">
+ <primary>commandp</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>commandp</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ commandp command =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+Returns t if command is a command object, otherwise nil.
+ </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_command-documentation">
+ <indexterm zone=3D"f_command-documentation">
+ <primary>command-documentation</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>command-documentation</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ command-documentation command =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para> </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_command-function">
+ <indexterm zone=3D"f_command-function">
+ <primary>command-function</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>command-function</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ command-function command =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para> </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_command-name">
+ <indexterm zone=3D"f_command-name">
+ <primary>command-name</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>command-name</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ command-name command =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+Returns the documentation, function, or name for command. These may be
+set with setf.
+ </para>
+ </refsect1>
+ </refentry>
+ </refsect3>
+ <refsect3>
+ <title>Command Documentation</title>
+ <para>
+Command documentation is a description of what the command does when
+it is invoked as an extended command or from a key. Command
+documentation may be either a string or a function. If the
+documentation is a string then the first line should briefly summarize
+the command, with remaining lines filling the details. Example:
+ </para><programlisting>
+<![CDATA[
+(defcommand "Forward Character" (p)
+ "Move the point forward one character.
+ With prefix argument move that many characters, with negative
+ argument go backwards."
+. . .)
+]]>
+</programlisting>
+ <para>
+Command documentation may also be a function of one argument. The
+function is called with either :short or :full, indicating that the
+function should return a short documentation string or do something
+to document the command fully.
+ </para>
+ </refsect3>
+ </refentry>
+ </sect2>
+ <sect2 id=3D"CommandInterpreter">
+ <title>The Command Interpreter</title>
+ <para>
+The command interpreter is the functionality invoked by the event
+handler to process key-events from the keyboard and dispatch to
+different commands on the basis of what the user types. When the
+command interpreter executes a command, we say it invokes the command. The
+command interpreter also provides facilities for communication between
+contiguously running commands, such as a last command type register.
+It also takes care of resetting communication mechanisms, clearing the
+echo area, displaying partial keys typed slowly by the user, etc.
+ </para>
+ <refentry id=3D"hv_command_abort_hook">
+ <indexterm zone=3D"hv_command_abort_hook">
+ <primary>Command Abort Hook</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>Command Abort Hook</refname>
+ <refpurpose></refpurpose>
+ <refclass>Hemlock Variable</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ Command Abort Hook =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+The command interpreter invokes the function in this variable whenever
+someone aborts a command (for example, if someone called
+editor-error).
+ </para>
+ </refsect1>
+ <refsect3>
+ <title>Editor Input</title>
+ <para>
+The canonical representation of editor input is a key-event structure.
+Users can bind commands to keys (see section 7.2.2), which are
+non-empty sequences of key-events. A key-event consists of an
+identifying token known as a keysym and a field of bits representing
+modifiers. Users define keysym names by supplying names that reflect
+the legends on their keyboard's keys. Users define modifier names
+similarly, but the system chooses the bit and mask for recognizing the
+modifier. You can use keysym and modifier names to textually specify
+key-events and Hemlock keys in a #k syntax. The following are some
+examples:
+ </para><programlisting>
+<![CDATA[
+#k"C-u"
+#k"Control-u"
+#k"c-m-z"
+#k"control-x meta-d"
+#k"a"
+#k"A"
+#k"Linefeed"
+]]>
+</programlisting>
+ <para>
+This is convenient for use within code and in init files
+containing <code>bind-key</code> calls.
+ </para>
+ <para>
+The #k syntax is delimited by double quotes. Within the
+double quotes, spaces separate multiple key-events. A single
+key-event optionally starts with modifier names terminated by hyphens.
+Modifier names are alphabetic sequences of characters which the system
+uses case-insensitively. Following modifiers is a keysym name, which
+is case-insensitive if it consists of multiple characters, but if the
+name consists of only a single character, then it is case-sensitive.
+ </para>
+ <para>
+You can escape special characters---hyphen, double quote, open angle
+bracket, close angle bracket, and space---with a backslash, and you
+can specify a backslash by using two contiguously. You can use angle
+brackets to enclose a keysym name with many special characters in it.
+Between angle brackets appearing in a keysym name position, there are
+only two special characters, the closing angle bracket and backslash.
+ </para>
+ <para>
+For more information on key-events see section 18.1.
+ </para>
+ </refsect3>
+ <refsect3>
+ <title>Binding Commands to Keys</title>
+ <para>
+The command interpreter determines which command to invoke on the
+basis of <emphasis>key bindings</emphasis>. A key binding is an associatio=
n between a
+command and a sequence of key-events (see section 7.2.1). A sequence
+of key-events is called a key and is represented by a single key-event
+or a sequence (list or vector) of key-events.
+ </para>
+ <para>
+Since key bindings may be local to a mode or buffer, the current
+environment (page 21) determines the set of key bindings in effect at
+any given time. When the command interpreter tries to find the
+binding for a key, it first checks if there is a local binding in
+the current buffer (page 9), then if there is a binding in each of the
+minor modes and the major mode for the current buffer (page 35), and
+finally checks to see if there is a global binding. If no binding is
+found, then the command interpreter beeps or flashes the screen to
+indicate this.
+ </para>
+ <refentry id=3D"f_bind-key">
+ <indexterm zone=3D"f_bind-key">
+ <primary>bind-key</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>bind-key</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ bind-key name key &optional; kind where =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+This function associates command name and key in some environment. Key
+is either a key-event or a sequence of key-events. There are three
+possible values of kind:
+ </para>
+ <variablelist>
+ <varlistentry>
+ <term>:global</term>
+ <listitem>
+ <para>
+The default, make a global key binding.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>:mode</term>
+ <listitem>
+ <para>
+Make a mode specific key binding in the mode whose name is where.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>:buffer</term>
+ <listitem>
+ <para>
+Make a binding which is local to buffer where.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ <para>
+This processes key for key translations before establishing the
+binding. See section 7.2.3.
+ </para>
+ <para>
+If the key is some prefix of a key binding which already exists in the
+specified place, then the new one will override the old one,
+effectively deleting it.
+ </para>
+ <para>
+ <code>do-alpha-key-events</code> is useful=
for setting up bindings in certain new modes.
+ </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_command-bindings">
+ <indexterm zone=3D"f_command-bindings">
+ <primary>command-bindings</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>command-bindings</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ command-bindings command =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+This function returns a list of the places where command is bound. A
+place is specified as a list of the key (always a vector), the kind of
+binding, and where (either the mode or buffer to which the binding is
+local, or nil if it is a global).
+ </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_delete-key-binding">
+ <indexterm zone=3D"f_delete-key-binding">
+ <primary>delete-key-binding</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>delete-key-binding</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ delete-key-binding key &optional; kind whe=
re =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+This function removes the binding of key in some place. Key is either
+a key-event or a sequence of key-events. kind is the kind of binding
+to delete, one of :global(the default), :mode or :buffer. If kind is
+:mode, where is the mode name, and if kind is :buffer, then where is
+the buffer.
+ </para>
+ <para>
+This function signals an error if key is unbound.
+ </para>
+ <para>
+This processes key for key translations before deleting the binding.
+See section 7.2.3.
+ </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_get-command">
+ <indexterm zone=3D"f_get-command">
+ <primary>get-command</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>get-command</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ get-command key &optional; kind where =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+This function returns the command bound to key, returning nil if it is
+unbound. Key is either a key-event or a sequence of key-events. If
+key is an initial subsequence of some keys, then this returns the
+keyword :prefix. There are four cases of kind:
+ </para>
+ <variablelist>
+ <varlistentry>
+ <term>:current</term>
+ <listitem>
+ <para>
+Return the current binding of key using the current buffer's search
+list. If there are any transparent key bindings for key, then they
+are returned in a list as a second value.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>:global</term>
+ <listitem>
+ <para>
+Return the global binding of key. This is the default.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>:mode</term>
+ <listitem>
+ <para>
+Return the binding of key in the mode named where.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>:buffer</term>
+ <listitem>
+ <para>
+Return the binding of key local to the buffer where.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ <para>
+This processes key for key translations before looking for any
+binding. See section 7.2.3.
+ </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_map-bindings">
+ <indexterm zone=3D"f_map-bindings">
+ <primary>map-bindings</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>map-bindings</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ map-bindings function kind &optional; wher=
e =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+This function maps over the key bindings in some place. For each
+binding, this passes function the key and the command bound to
+it. Kind and where are the same as in bind-key. The key is not
+guaranteed to remain valid after a given iteration.
+ </para>
+ </refsect1>
+ </refentry>
+ </refsect3>
+ <refsect3>
+ <title>Key Translation</title>
+ <para>
+Key translation is a process that the command interpreter applies to
+keys before doing anything else. There are two kinds of key
+translations: substitution and bit-prefix. In either case, the command
+interpreter translates a key when a specified key-event sequence
+appears in a key.
+ </para>
+ <para>
+In a substitution translation, the system replaces the matched
+subsequence with another key-event sequence. Key translation is not
+recursively applied to the substituted key-events.
+ </para>
+ <para>
+In a bit-prefix translation, the system removes the matched
+subsequence and effectively sets the specified bits in the next
+key-event in the key.
+ </para>
+ <para>
+While translating a key, if the system encounters an incomplete final
+subsequence of key-events, it aborts the translation process. This
+happens when those last key-events form a prefix of some
+translation. It also happens when they translate to a bit-prefix, but
+there is no following key-event to which the system can apply the
+indicated modifier. If there is a binding for this partially
+untranslated key, then the command interpreter will invoke that
+command; otherwise, it will wait for the user to type more key-events.
+ </para>
+ <refentry id=3D"f_key-translation">
+ <indexterm zone=3D"f_key-translation">
+ <primary>key-translation</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>key-translation</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ key-translation key =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+This form is setf-able and allows users to register key translations
+that the command interpreter will use as users type key-events.
+ </para>
+ <para>
+This function returns the key translation for key, returning nil if
+there is none. Key is either a key-event or a sequence of key-events.
+If key is a prefix of a translation, then this returns :prefix.
+ </para>
+ <para>
+A key translation is either a key or modifier specification. The bits
+translations have a list form: (:bits {bit-name}*).
+ </para>
+ <para>
+Whenever key appears as a subsequence of a key argument to the binding
+manipulation functions, that portion will be replaced with the
+translation.
+ </para>
+ </refsect1>
+ </refentry>
+ </refsect3>
+ <refsect3>
+ <title>Transparent Key Bindings</title>
+ <para>
+Key bindings local to a mode may be transparent. A transparent key
+binding does not shadow less local key bindings, but rather indicates
+that the bound command should be invoked before the first normal key
+binding. Transparent key bindings are primarily useful for
+implementing minor modes such as auto fill and word
+abbreviation. There may be several transparent key bindings for a
+given key, in which case all of the transparent commands are invoked in the
+order they were found. If there no normal key binding for a key typed,
+then the command interpreter acts as though the key is unbound even if
+there are transparent key bindings.
+ </para>
+ <para>
+The :transparent-p argument to defmode (page 36) determines whether
+all the key bindings in a mode are transparent or not. In addition
+a particular command may be declared to be transparent by the
+:transparent-p argument to defcommand and make-command.
+ </para>
+ </refsect3>
+ </refentry>
+ </sect2>
+ <sect2 id=3D"CommandTypes">
+ <title>Command Types</title>
+ <para>
+In many editors the behavior of a command depends on the kind of
+command invoked before it. Hemlock provides a mechanism to support
+this known as <code>command type</code>.
+ </para>
+ <refentry id=3D"f_last-command-type">
+ <indexterm zone=3D"f_last-command-type">
+ <primary>last-command-type</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>last-command-type</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ last-command-type =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+This returns the command type of the last command invoked. If this is
+set with setf, the supplied value becomes the value of
+last-command-type until the next command completes. If the previous
+command did not set last-command-type, then its value is nil. Normally
+a command type is a keyword. The command type is not cleared after a
+command is invoked due to a transparent key binding.
+ </para>
+ </refsect1>
+ </refentry>
+ </sect2>
+ <sect2 id=3D"CommandArguments">
+ <title>Command Arguments</title>
+ <para>
+There are three ways in which a command may be invoked: It may be
+bound to a key which has been typed, it may be invoked as an extended
+command, or it may be called as a Lisp function. Ideally commands
+should be written in such a way that they will behave sensibly no
+matter which way they are invoked. The functions which implement
+commands must obey certain conventions about argument passing if the
+command is to function properly.
+ </para>
+ <sect3 id=3D"PrefixArgument">
+ <title>The Prefix Argument</title>
+ <para>
+Whenever a command is invoked it is passed as its first argument what
+is known as the prefix argument. The prefix argument is always either
+an integer or nil. When a command uses this value it is usually as a
+repeat count, or some conceptually similar function.
+ </para>
+ <refentry id=3D"f_prefix-argument">
+ <indexterm zone=3D"f_prefix-argument">
+ <primary>prefix-argument</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>prefix-argument</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ prefix-argument =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+This function returns the current value of the prefix argument. When
+set with setf, the new value becomes the prefix argument for the next
+command. If the prefix argument is not set by the previous command
+then the prefix argument for a command is nil. The prefix argument is
+not cleared after a command is invoked due to a transparent key
+binding.
+ </para>
+ </refsect1>
+ </refentry>
+ </sect3>
+ <sect3 id=3D"LispArguments">
+ <title>Lisp Arguments</title>
+ <para>
+It is often desirable to call commands from Lisp code, in which case
+arguments which would otherwise be prompted for are passed as optional
+arguments following the prefix argument. A command should prompt for
+any arguments not supplied.
+ </para>
+ </sect3>
+ </sect2>
+ </sect1>
+ <sect1 id=3D"HemlockProgrammingModes">
+ <title>Modes</title>
+ <para>
+A mode is a collection of Hemlock values which may be present in the
+current environment (page 21) depending on the editing task at hand.
+An example of a typical mode is Lisp, for editing Lisp code.
+ </para>
+ <sect2 id=3D"ModeHooks">
+ <title>Mode Hooks</title>
+ <para>
+When a mode is added to or removed from a buffer, its mode hook is
+invoked. The hook functions take two arguments, the buffer involved
+and t if the mode is being added or nil if it is being removed. Mode
+hooks are typically used to make a mode do something additional to
+what it usually does. One might, for example, make a Text mode hook
+that turned on auto-fill mode when you entered.
+ </para>
+ </sect2>
+ <sect2 id=3D"MajorAndMinorModes">
+ <title>Major and Minor Modes</title>
+ <para>
+There are two kinds of modes, major modes and minor modes. A buffer
+always has exactly one major mode, but it may have any number of minor
+modes. Major modes may have mode character attributes while minor
+modes may not.
+ </para>
+ <para>
+A major mode is usually used to change the environment in some major
+way, such as to install special commands for editing some language.
+Minor modes generally change some small attribute of the environment,
+such as whether lines are automatically broken when they get too long.
+A minor mode should work regardless of what major mode and minor modes
+are in effect.
+ </para>
+ <refentry id=3D"hv_default_modes">
+ <indexterm zone=3D"hv_default_modes">
+ <primary>Default Modes</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>Default Modes</refname>
+ <refpurpose></refpurpose>
+ <refclass>Hemlock Variable</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ Default Modes (initial value '("Fundamental" "Save=
")) =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+This variable contains a list of mode names which are instantiated in
+a buffer when no other information is available.
+ </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"v_mode-names">
+ <indexterm zone=3D"v_mode-names">
+ <primary>*mode-names*</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>*mode-names*</refname>
+ <refpurpose></refpurpose>
+ <refclass>Variable</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ *mode-names* =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+Holds a string-table of the names of all the modes.
+ </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"c_illegal">
+ <indexterm zone=3D"c_illegal">
+ <primary>Illegal</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>Illegal</refname>
+ <refpurpose></refpurpose>
+ <refclass>Command</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ Illegal =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+This is a useful command to bind in modes that wish to shadow global
+bindings by making them effectively illegal. Also, although less
+likely, minor modes may shadow major mode bindings with this. This
+command calls editor-error.
+ </para>
+ </refsect1>
+ </refentry>
+ </sect2>
+ <sect2 id=3D"ModeFunctions">
+ <title>Mode Functions</title>
+ <refentry id=3D"f_defmode">
+ <indexterm zone=3D"f_defmode">
+ <primary>defmode</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>defmode</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ defmode name &key; :setup-function :cleanup-functi=
on :major-p :precedence :transparent-p :documentation =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+This function defines a new mode named name, and enters it in
+*mode-names* (page 35). If major-p is supplied and is not nil then
+the mode is a major mode; otherwise it is a minor mode.
+ </para>
+ <para>
+Setup-function and cleanup-function are functions which are invoked
+with the buffer affected, after the mode is turned on, and before it
+is turned off, respectively. These functions typically are used to
+make buffer-local key or variable bindings and to remove them when the
+mode is turned off.
+ </para>
+ <para>
+Precedence is only meaningful for a minor mode. The precedence of a
+minor mode determines the order in which it in a buffer's list of
+modes. When searching for values in the current environment, minor
+modes are searched in order, so the precedence of a minor mode
+determines which value is found when there are several definitions.
+ </para>
+ <para>
+Transparent-p determines whether key bindings local to the defined mode
+are transparent. Transparent key bindings are invoked in addition to
+the first normal key binding found rather than shadowing less local
+key bindings.
+ </para>
+ <para>
+Documentation is some introductory text about the mode. Commands such
+as Describe Mode use this.
+ </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_mode-documentation">
+ <indexterm zone=3D"f_mode-documentation">
+ <primary>mode-documentation</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>mode-documentation</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ mode-documentation name =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+This function returns the documentation for the mode named name.
+ </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_buffer-major-mode">
+ <indexterm zone=3D"f_buffer-major-mode">
+ <primary>buffer-major-mode</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>buffer-major-mode</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ buffer-major-mode buffer =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para> </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"hv_buffer_major_mode_hook">
+ <indexterm zone=3D"hv_buffer_major_mode_hook">
+ <primary>Buffer Major Mode Hook</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>Buffer Major Mode Hook</refname>
+ <refpurpose></refpurpose>
+ <refclass>Hemlock Variable</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ Buffer Major Mode Hook =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+buffer-major-mode returns the name of buffer's major mode. The major
+mode may be changed with setf; then Buffer Major Mode Hook is invoked
+with buffer and the new mode.
+ </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_buffer-minor-mode">
+ <indexterm zone=3D"f_buffer-minor-mode">
+ <primary>buffer-minor-mode</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>buffer-minor-mode</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ buffer-minor-mode buffer name =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para> </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"hv_buffer_minor_mode_hook">
+ <indexterm zone=3D"hv_buffer_minor_mode_hook">
+ <primary>Buffer Minor Mode Hook</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>Buffer Minor Mode Hook</refname>
+ <refpurpose></refpurpose>
+ <refclass>Hemlock Variable</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ Buffer Minor Mode Hook =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+buffer-minor-mode returns t if the minor mode name is active in
+buffer, nil otherwise. A minor mode may be turned on or off by using
+setf; then Buffer Minor Mode Hook is invoked with buffer, name and the
+new value.
+ </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_mode-variables">
+ <indexterm zone=3D"f_mode-variables">
+ <primary>mode-variables</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>mode-variables</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ mode-variables name =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+Returns the string-table of mode local variables.
+ </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_mode-major-p">
+ <indexterm zone=3D"f_mode-major-p">
+ <primary>mode-major-p</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>mode-major-p</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ mode-major-p name =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+Returns t if name is the name of a major mode, or nil if it is the
+name of a minor mode. It is an error for name not to be the name of a
+mode.
+ </para>
+ </refsect1>
+ </refentry>
+ </sect2>
+ </sect1>
+ <sect1 id=3D"HemlockProgrammingCharacterAttributes">
+ <title>Character Attributes</title>
+ <sect2 id=3D"HemlockProgrammingCharacterAttributesIntroduction">
+ <title>Introduction</title>
+ <para>
+Character attributes provide a global database of information about
+characters. This facility is similar to, but more general than, the
+syntax tables of other editors such as Emacs. For example, you should
+use character attributes for commands that need information regarding
+whether a character is whitespace or not. Use character attributes
+for these reasons:
+ </para>
+ <orderedlist>
+ <listitem>
+ <para>
+If this information is all in one place, then it is easy the
+change the behavior of the editor by changing the syntax table,
+much easier than it would be if character constants were wired
+into commands.
+ </para>
+ </listitem>
+ </orderedlist>
+ <orderedlist>
+ <listitem>
+ <para>
+This centralization of information avoids needless duplication of effort.
+ </para>
+ </listitem>
+ </orderedlist>
+ <orderedlist>
+ <listitem>
+ <para>
+The syntax table primitives are probably faster than anything that
+can be written above the primitive level.
+ </para>
+ </listitem>
+ </orderedlist>
+ <para>
+Note that an essential part of the character attribute scheme is that
+character attributes are global and are there for the user to
+change. Information about characters which is internal to some set of
+commands (and which the user should not know about) should not be
+maintained as a character attribute. For such uses various character
+searching abilities are provided by the function find-pattern (page
+20).
+ </para>
+ </sect2>
+ <sect2 id=3D"CharacterAttributeNames">
+ <title>Character Attribute Names</title>
+ <para>
+As for Hemlock variables, character attributes have a user visible
+string name, but are referred to in Lisp code as a symbol. The string
+name, which is typically composed of capitalized words separated by
+spaces, is translated into a keyword by replacing all spaces with
+hyphens and interning this string in the keyword package. The
+attribute named "Ada Syntax" would thus become :ada-syntax.
+ </para>
+ <refentry id=3D"v_character-attribute-names">
+ <indexterm zone=3D"v_character-attribute-names">
+ <primary>*character-attribute-names*</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>*character-attribute-names*</refname>
+ <refpurpose></refpurpose>
+ <refclass>Variable</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ *character-attribute-names* =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+Whenever a character attribute is defined, its name is entered in this
+string table (page 69), with the corresponding keyword as the value.
+ </para>
+ </refsect1>
+ </refentry>
+ </sect2>
+ <sect2 id=3D"CharacterAttributeFunctions">
+ <title>Character Attribute Functions</title>
+ <refentry id=3D"f_defattribute">
+ <indexterm zone=3D"f_defattribute">
+ <primary>defattribute</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>defattribute</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ defattribute name documentation &optional; type in=
itial-value =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+This function defines a new character attribute with name, a
+string. Character attribute operations take attribute
+arguments as a keyword whose name is name uppercased with spaces
+replaced by hyphens.
+ </para>
+ <para>
+Documentation describes the uses of the character attribute.
+ </para>
+ <para>
+Type, which defaults to (mod 2), specifies what type the values of the
+character attribute are. Values of a character attribute may be of
+any type which may be specified to make-array. Initial-value (default
+0) is the value which all characters will initially have for this
+attribute.
+ </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_character-attribute-name">
+ <indexterm zone=3D"f_character-attribute-name">
+ <primary>character-attribute-name</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>character-attribute-name</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ character-attribute-name attribute =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para> </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_character-attribute-documentation">
+ <indexterm zone=3D"f_character-attribute-documentation">
+ <primary>character-attribute-documentation</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>character-attribute-documentation</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ character-attribute-documentation attribute =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+These functions return the name or documentation for attribute.
+ </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_character-attribute">
+ <indexterm zone=3D"f_character-attribute">
+ <primary>character-attribute</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>character-attribute</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ character-attribute attribute character =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para> </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"hv_character_attribute_hook">
+ <indexterm zone=3D"hv_character_attribute_hook">
+ <primary>Character Attribute Hook</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>Character Attribute Hook</refname>
+ <refpurpose></refpurpose>
+ <refclass>Hemlock Variable</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ Character Attribute Hook =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+character-attribute returns the value of attribute for character. This
+signals an error if attribute is undefined.
+ </para>
+ <para>
+setf will set a character's attributes. This setf method invokes the
+functions in Character Attribute Hook on the attribute and character
+before it makes the change.
+ </para>
+ <para>
+If character is nil, then the value of the attribute for the beginning
+or end of the buffer can be accessed or set. The buffer beginning and
+end thus become a sort of fictitious character, which simplifies the
+use of character attributes in many cases.
+ </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_character-attribute-p">
+ <indexterm zone=3D"f_character-attribute-p">
+ <primary>character-attribute-p</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>character-attribute-p</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ character-attribute-p symbol =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+This function returns t if symbolis the name of a character attribute,
+nil otherwise.
+ </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_shadow-attribute">
+ <indexterm zone=3D"f_shadow-attribute">
+ <primary>shadow-attribute</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>shadow-attribute</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ shadow-attribute attribute character value mode =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para> </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"hv_shadow_attribute_hook">
+ <indexterm zone=3D"hv_shadow_attribute_hook">
+ <primary>Shadow Attribute Hook</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>Shadow Attribute Hook</refname>
+ <refpurpose></refpurpose>
+ <refclass>Hemlock Variable</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ Shadow Attribute Hook =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+This function establishes value as the value of character's attribute
+attribute when in the mode mode. Mode must be the name of a major
+mode. Shadow Attribute Hook is invoked with the same arguments when
+this function is called. If the value for an attribute is set while
+the value is shadowed, then only the shadowed value is affected, not
+the global one.
+ </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_unshadow-attribute">
+ <indexterm zone=3D"f_unshadow-attribute">
+ <primary>unshadow-attribute</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>unshadow-attribute</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ unshadow-attribute attribute character mode =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para> </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"hv_unshadow_attribute_hook">
+ <indexterm zone=3D"hv_unshadow_attribute_hook">
+ <primary>Unshadow Attribute Hook</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>Unshadow Attribute Hook</refname>
+ <refpurpose></refpurpose>
+ <refclass>Hemlock Variable</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ Unshadow Attribute Hook =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+Make the value of attribute for character no longer be shadowed in
+mode. Unshadow Attribute Hook is invoked with the same arguments when
+this function is called.
+ </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_find-attribute">
+ <indexterm zone=3D"f_find-attribute">
+ <primary>find-attribute</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>find-attribute</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ find-attribute mark attribute &optional; test =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para> </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_reverse-find-attribute">
+ <indexterm zone=3D"f_reverse-find-attribute">
+ <primary>reverse-find-attribute</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>reverse-find-attribute</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ reverse-find-attribute mark attribute &optional; t=
est =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+These functions find the next (or previous) character with some value
+for the character attribute attribute starting at mark. They pass test
+one argument, the value of attribute for the character tested. If the
+test succeeds, then these routines modify mark to point before (after
+for reverse-find-attribute) the character which satisfied the test.
+If no characters satisfy the test, then these return nil, and mark
+remains unmodified. Test defaults to <code>#'not-zerop</code>. There is no=
guarantee
+that the test is applied in any particular fashion, so it should have
+no side effects and depend only on its argument.
+ </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_find-not-attribute">
+ <indexterm zone=3D"f_find-not-attribute">
+ <primary>find-not-attribute</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>find-not-attribute</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ find-not-attribute mark attribute =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para> </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_reverse-find-not-attribute">
+ <indexterm zone=3D"f_reverse-find-not-attribute">
+ <primary>reverse-find-not-attribute</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>reverse-find-not-attribute</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ reverse-find-not-attribute mark attribute =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+These are equivalent to (find-attribute mark attribute #'zerop) and
+(reverse-find-attribute mark attribute #'zerop), respectively.
+ </para>
+ </refsect1>
+ </refentry>
+ </sect2>
+ <sect2 id=3D"CharacterAttributeHooks">
+ <title>Character Attribute Hooks</title>
+ <para>
+It is often useful to use the character attribute mechanism as an
+abstract interface to other information about characters which in fact
+is stored elsewhere. For example, some implementation of Hemlock
+might decide to define a Print Representation attribute which controls
+how a character is displayed on an output device.
+ </para>
+ <para>
+To make this easy to do, each attribute has a list of hook functions
+which are invoked with the attribute, character and new value whenever
+the current value changes for any reason.
+ </para>
+ <refentry id=3D"f_character-attribute-hooks">
+ <indexterm zone=3D"f_character-attribute-hooks">
+ <primary>character-attribute-hooks</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>character-attribute-hooks</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ character-attribute-hooks attribute =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+Return the current hook list for attribute. This may be set with
+setf. The add-hook and remove-hook (page 25) macros should be used to
+manipulate these lists.
+ </para>
+ </refsect1>
+ </refentry>
+ </sect2>
+ <sect2 id=3D"SystemDefinedCharacterAttributes">
+ <title>System Defined Character Attributes</title>
+ <para>
+These are predefined in Hemlock:
+ </para>
+ <variablelist>
+ <varlistentry>
+ <term>"Whitespace"</term>
+ <listitem>
+ <para>
+A value of 1 indicates the character is whitespace.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>"Word Delimiter"</term>
+ <listitem>
+ <para>
+A value of 1 indicates the character separates words (see section 15.3).
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>"Space"</term>
+ <listitem>
+ <para>
+This is like Whitespace, but it should not include Newline. Hemlock
+uses this primarily for handling indentation on a line.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>"Sentence Terminator"</term>
+ <listitem>
+ <para>
+A value of 1 indicates these characters terminate sentences (see section 1=
5.3).
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>"Sentence Closing Char"</term>
+ <listitem>
+ <para>
+A value of 1 indicates these delimiting characters, such as " or ),
+may follow a Sentence Terminator (see section 15.3).
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>"Paragraph Delimiter"</term>
+ <listitem>
+ <para>
+A value of 1 indicates these characters delimit paragraphs when they
+begin a line (see section 15.3).
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>"Page Delimiter"</term>
+ <listitem>
+ <para>
+A value of 1 indicates this character separates logical pages (see
+section 15.4) when it begins a line.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>"Lisp Syntax"</term>
+ <listitem>
+ <para>
+This uses symbol values from the following:
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ <itemizedlist>
+ <listitem>
+ <para>
+nil These characters have no interesting properties.
+ </para>
+ </listitem>
+ </itemizedlist>
+ <itemizedlist>
+ <listitem>
+ <para>
+:space These characters act like whitespace and should not include Newlin=
e.
+ </para>
+ </listitem>
+ </itemizedlist>
+ <itemizedlist>
+ <listitem>
+ <para>
+:newline This is the Newline character.
+ </para>
+ </listitem>
+ </itemizedlist>
+ <itemizedlist>
+ <listitem>
+ <para>
+:open-paren This is ( character.
+ </para>
+ </listitem>
+ </itemizedlist>
+ <itemizedlist>
+ <listitem>
+ <para>
+:close-paren This is ) character.
+ </para>
+ </listitem>
+ </itemizedlist>
+ <itemizedlist>
+ <listitem>
+ <para>
+:prefix This is a character that is a part of any form it precedes for ex=
ample, the single quote, '.
+ </para>
+ </listitem>
+ </itemizedlist>
+ <itemizedlist>
+ <listitem>
+ <para>
+:string-quote This is the character that quotes a string literal, ".
+ </para>
+ </listitem>
+ </itemizedlist>
+ <itemizedlist>
+ <listitem>
+ <para>
+:char-quote This is the character that escapes a single character, \.
+ </para>
+ </listitem>
+ </itemizedlist>
+ <itemizedlist>
+ <listitem>
+ <para>
+:comment This is the character that makes a comment with the rest of the =
line,;.
+ </para>
+ </listitem>
+ </itemizedlist>
+ <itemizedlist>
+ <listitem>
+ <para>
+:constituent These characters are constitute symbol names.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </sect2>
+ </sect1>
+ <sect1 id=3D"HemlockProgrammingControllingTheDisplay">
+ <title>Controlling the Display</title>
+ <sect2 id=3D"Views">
+ <title>Views</title>
+ <para>
+A <code>hemlock-view</code> represents the GUI object(s) used to display t=
he contents
+of a buffer. Conceptually it consists of a text buffer, a
+modeline for semi-permanent status info, an echo area for transient
+status info, and a text input area for reading prompted
+input. (Currently the last two are conflated, i.e. text input happens
+in the echo area).
+ </para>
+ <para>
+The API for working with hemlock-views is not fully
+defined yet. If you need to work with views beyond what's listed
+here, you will probably need to get in the sources and find some
+internal functions to call.
+ </para>
+ </sect2>
+ <sect2 id=3D"CurrentView">
+ <title>The Current View</title>
+ <refentry id=3D"f_current-view">
+ <indexterm zone=3D"f_current-view">
+ <primary>current-view</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>current-view</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ current-view =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+current-view returns the hemlock view which is the target of the
+currently executing command. This is usually the frontmost hemlock
+window in the current application.
+ </para>
+ </refsect1>
+ </refentry>
+ </sect2>
+ <sect2 id=3D"ViewFunctions">
+ <title>View Functions</title>
+ <refentry id=3D"f_hemlock-view-p">
+ <indexterm zone=3D"f_hemlock-view-p">
+ <primary>hemlock-view-p</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>hemlock-view-p</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ hemlock-view-p object =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+This function returns t if object is a hemlock view, otherwise nil.
+ </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_hemlock-view-buffer">
+ <indexterm zone=3D"f_hemlock-view-buffer">
+ <primary>hemlock-view-buffer</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>hemlock-view-buffer</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ hemlock-view-buffer view =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+This function returns the buffer which is displayed in the view.
+ </para>
+ </refsect1>
+ </refentry>
+ </sect2>
+ <sect2 id=3D"CursorPositions">
+ <title>Cursor Positions</title>
+ <refentry id=3D"f_mark-column">
+ <indexterm zone=3D"f_mark-column">
+ <primary>mark-column</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>mark-column</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ mark-column mark =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+This function returns the X position at which mark would be displayed,
+supposing its line was displayed on an infinitely wide screen. This
+takes into consideration strange characters such as tabs.
+ </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_move-to-column">
+ <indexterm zone=3D"f_move-to-column">
+ <primary>move-to-column</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>move-to-column</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ move-to-column mark column &optional; line =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+This function is analogous to move-to-position (page 5), except that
+it moves mark to the position on line which corresponds to the
+specified column. If the line would not reach to the specified column, th=
en nil is
+returned and mark is not modified. Note that since a character may be
+displayed on more than one column on the screen, several different
+values of column may cause mark to be moved to the same position.
+ </para>
+ </refsect1>
+ </refentry>
+ </sect2>
+ <sect2 id=3D"Redisplay">
+ <title>Redisplay</title>
+ <para>
+The display of the buffer contents on the screen is updated at the
+end of each command. The following function can be used to control
+the scroll position of the buffer in the view.
+ </para>
+ <refentry id=3D"f_set-scroll-position">
+ <indexterm zone=3D"f_set-scroll-position">
+ <primary>set-scroll-position</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>set-scroll-position</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ set-scroll-position how &optional; what =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+Normally, after a command that changes the contents of the buffer
+or the selection (i.e. the active region), the event handler repositions
+the view so that the selection is visible, scrolling the buffer as
+necessary. Calling this function tells the system to not do that,
+and instead to position the buffer in a particular way. <code>how</code> =
can
+be one of the following:
+ </para>
+ <variablelist>
+ <varlistentry>
+ <term>:center-selection</term>
+ <listitem>
+ <para>
+This causes the selection (or the point) to be centered in the visible are=
a. <code>what</code> is ignored.
+
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>:page-up</term>
+ <listitem>
+ <para>
+This causes the previous page of the buffer to be shown <code>what</code> =
is ignored.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>:page-down</term>
+ <listitem>
+ <para>
+This causes the next page of the buffer to be shown. <code>what</code> is =
ignored.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>:lines-up</term>
+ <listitem>
+ <para>
+ This causes <code>what</code> previous lines to be scrolled in at the top=
. <code>what</code> must be an integer. =
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>:lines-down</term>
+ <listitem>
+ <para>
+This causes <code>what</code> next lines to be scrolled in at the bottom. =
<code>what</code> must be an integer.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>:line</term>
+ <listitem>
+ <para>
+ This causes the line containing <code>what</code> to be scrolled to the t=
op of the view. <code>what</code> must be a mark.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect1>
+ </refentry>
+ </sect2>
+ </sect1>
+ <sect1 id=3D"HemlockProgrammingLogicalKeyEvents">
+ <title>Logical Key-Events</title>
+ <sect2 id=3D"HemlockProgrammingLogicalKeyEventsIntroduction">
+ <title>Introduction</title>
+ <para>
+Some primitives such as prompt-for-key (page 50) and commands such as
+Emacs query replace read key-events directly from the keyboard instead
+of using the command interpreter. To encourage consistency between
+these commands and to make them portable and easy to customize, there
+is a mechanism for defininglogical key-events. A logical key-event is
+a keyword which stands for some set of key-events. The system
+globally interprets these key-events as indicators a particular
+action. For example, the :help logical key-event represents the set of
+key-events that request help in a given Hemlock implementation. This
+mapping is a many-to-many mapping, not one-to-one, so a given logical
+key-event may have multiple corresponding actual key-events. Also,
+any key-event may represent different logical key-events.
+ </para>
+ </sect2>
+ <sect2 id=3D"LogicalKeyEventFunctions">
+ <title>Logical Key-Event Functions</title>
+ <refentry id=3D"v_logical-key-event-names">
+ <indexterm zone=3D"v_logical-key-event-names">
+ <primary>*logical-key-event-names*</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>*logical-key-event-names*</refname>
+ <refpurpose></refpurpose>
+ <refclass>Variable</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ *logical-key-event-names* =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+This variable holds a string-table mapping all logical key-event names
+to the keyword identifying the logical key-event.
+ </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_define-logical-key-event">
+ <indexterm zone=3D"f_define-logical-key-event">
+ <primary>define-logical-key-event</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>define-logical-key-event</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ define-logical-key-event string-name documentation =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+This function defines a new logical key-event with name string-name.
+Logical key-event operations take logical key-events
+arguments as a keyword whose name is string-name uppercased with
+spaces replaced by hyphens.
+ </para>
+ <para>
+Documentation describes the action indicated by the logical key-event.
+ </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_logical-key-event-key-events">
+ <indexterm zone=3D"f_logical-key-event-key-events">
+ <primary>logical-key-event-key-events</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>logical-key-event-key-events</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ logical-key-event-key-events keyword =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+This function returns the list of key-events representing the logical
+key-event keyword.
+ </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_logical-key-event-name">
+ <indexterm zone=3D"f_logical-key-event-name">
+ <primary>logical-key-event-name</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>logical-key-event-name</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ logical-key-event-name keyword =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para> </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_logical-key-event-documentation">
+ <indexterm zone=3D"f_logical-key-event-documentation">
+ <primary>logical-key-event-documentation</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>logical-key-event-documentation</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ logical-key-event-documentation keyword =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+These functions return the string name and documentation given
+to define-logical-key-event for logical key-event keyword.
+ </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_logical-key-event-p">
+ <indexterm zone=3D"f_logical-key-event-p">
+ <primary>logical-key-event-p</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>logical-key-event-p</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ logical-key-event-p key-event keyword =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+This function returns t if key-event is the logical key-event
+keyword. This is setf-able establishing or disestablishing key-events
+as particular logical key-events. It is a error for keyword to be an
+undefined logical key-event.
+ </para>
+ </refsect1>
+ </refentry>
+ </sect2>
+ <sect2 id=3D"SystemDefinedLogicalKeyEvents">
+ <title>System Defined Logical Key-Events</title>
+ <para>
+There are many default logical key-events, some of which are used by
+functions documented in this manual. If a command wants to read a
+single key-event command that fits one of these descriptions then the
+key-event read should be compared to the corresponding logical
+key-event instead of explicitly mentioning the particular key-event in
+the code. In many cases you can use the command-case (page 48) macro.
+It makes logical key-events easy to use and takes care of prompting
+and displaying help messages.
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+:abort Indicates the prompter should terminate its activity without perfor=
ming any closing actions of convenience, for example.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+:yes Indicates the prompter should take the action under consideration.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+:no Indicates the prompter should NOT take the action under consideration.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+:do-all Indicates the prompter should repeat the action under consideratio=
n as many times as possible.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+:do-once Indicates the prompter should execute the action under considerat=
ion once and then exit.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+:help Indicates the prompter should display some help information.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+:confirm Indicates the prompter should take any input provided or use the =
default if the user entered nothing.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+:quote Indicates the prompter should take the following key-event as itsel=
f without any sort of command interpretation.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+:keep Indicates the prompter should preserve something.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+:y Indicates a short positive response
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+:n Indicates a short negative response
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>
+Define a new logical key-event whenever:
+ </para>
+ <orderedlist>
+ <listitem>
+ <para>
+The key-event concerned represents a general class of actions, and
+several commands may want to take a similar action of this type.
+ </para>
+ </listitem>
+ </orderedlist>
+ <orderedlist>
+ <listitem>
+ <para>
+The exact key-event a command implementor chooses may generate
+violent taste disputes among users, and then the users can trivially
+change the command in their init files.
+ </para>
+ </listitem>
+ </orderedlist>
+ <orderedlist>
+ <listitem>
+ <para>
+You are using <code>command-case</code> which prevents implementors from
+specifying non-standard characters for dispatching in otherwise
+possibly portable code, and you can define and set the logical
+key-event in a site dependent file where you can mention
+implementation dependent characters.
+ </para>
+ </listitem>
+ </orderedlist>
+ </sect2>
+ </sect1>
+ <sect1 id=3D"EchoArea">
+ <title>The Echo Area</title>
+ <para>
+Hemlock provides a number of facilities for displaying information and
+prompting the user for it. Most of these work through a small area
+displayed at the bottom of the screen, called the Echo Area.
+ </para>
+ <sect2 id=3D"EchoAreaFunctions">
+ <title>Echo Area Functions</title>
+ <refentry id=3D"f_clear-echo-area">
+ <indexterm zone=3D"f_clear-echo-area">
+ <primary>clear-echo-area</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>clear-echo-area</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ clear-echo-area =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+Clears the echo area.
+ </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_message">
+ <indexterm zone=3D"f_message">
+ <primary>message</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>message</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ message control-string &rest; format-arguments =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para> </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_loud-message">
+ <indexterm zone=3D"f_loud-message">
+ <primary>loud-message</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>loud-message</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ loud-message control-string &rest; format-argument=
s =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+Displays a message in the echo area, replacing previous contents if any.
+loud-message is like message, but it also beeps.
+ </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_beep">
+ <indexterm zone=3D"f_beep">
+ <primary>beep</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>beep</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ beep =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+Gets the user's attention, typically by making a sound.
+ </para>
+ </refsect1>
+ </refentry>
+ </sect2>
+ <sect2 id=3D"PromptingFunctions">
+ <title>Prompting Functions</title>
+ <para>
+Prompting functions can be used to obtain short one-line input from the us=
er.
+ </para>
+ <para>
+Cocoa note: Because of implementation restrictions, only one buffer at
+a time is allowed to read prompted input. If a prompting function is
+invoked while a prompting operation is already in effect in another
+buffer, the attempt fails, telling the user "Buffer xxx is already
+waiting for input".
+ </para>
+ <para>
+Most of the prompting functions accept the following keyword arguments:
+ </para>
+ <variablelist>
+ <varlistentry>
+ <term>:must-exist</term>
+ <listitem>
+ <para>
+If :must-exist has a non-nil value then the user is
+prompted until a valid response is obtained. If :must-exist is nil
+then return as a string whatever is input. The default is t.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>:default</term>
+ <listitem>
+ <para>
+If null input is given when the user is prompted then this
+value is returned. If no default is given then some input must be
+given before anything interesting will happen.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>:default-string</term>
+ <listitem>
+ <para>
+If a :default is given then this is a string to be
+printed to indicate what the default is. The default is some
+representation of the value for :default, for example for a buffer it
+is the name of the buffer.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>:prompt</term>
+ <listitem>
+ <para>
+This is the prompt string to display.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>:help</term>
+ <listitem>
+ <para>
+This is similar to :prompt, except that it is displayed when the help
+command is typed during input.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ <blockquote><para>This may also be a function. When called wi=
th no arguments, it
+should either return a string which is the help text or perform some
+action to help the user, returning nil.
+ </para></blockquote>
+ <refentry id=3D"f_prompt-for-buffer">
+ <indexterm zone=3D"f_prompt-for-buffer">
+ <primary>prompt-for-buffer</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>prompt-for-buffer</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ prompt-for-buffer &key; :prompt :help :must-exist =
:default :default-string =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+Prompts with completion for a buffer name and returns the
+corresponding buffer. If must-exist is nil, then it returns the input
+string if it is not a buffer name. This refuses to accept the empty
+string as input when :default and :default-string are
+nil. :default-string may be used to supply a default buffer name
+when:default is nil, but when :must-exist is non-nil, it must name an
+already existing buffer.
+ </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_prompt-for-key-event">
+ <indexterm zone=3D"f_prompt-for-key-event">
+ <primary>prompt-for-key-event</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>prompt-for-key-event</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ prompt-for-key-event &key; :prompt :help =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+This function prompts for a key-event returning immediately when the
+user types the next key-event. command-case (page 48) is more useful
+for most purposes. When appropriate, use logical key-events (page 45).
+ </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_prompt-for-key">
+ <indexterm zone=3D"f_prompt-for-key">
+ <primary>prompt-for-key</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>prompt-for-key</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ prompt-for-key &key; :prompt :help :must-exist :de=
fault :default-string =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+This function prompts for a key, a vector of key-events, suitable for
+passing to any of the functions that manipulate key bindings (page
+29). If must-exist is true, then the key must be bound in the current
+environment, and the command currently bound is returned as the second
+value.
+ </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_prompt-for-file">
+ <indexterm zone=3D"f_prompt-for-file">
+ <primary>prompt-for-file</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>prompt-for-file</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ prompt-for-file &key; :prompt :help :must-exist :d=
efault :default-string =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+This function prompts for an acceptable filename. "Acceptable" means
+that it is a legal filename, and it exists if must-exist is
+non-nil. prompt-for-file returns a Common Lisp pathname. If the file
+exists as entered, then this returns it, otherwise it is merged with
+default as by merge-pathnames.
+ </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_prompt-for-integer">
+ <indexterm zone=3D"f_prompt-for-integer">
+ <primary>prompt-for-integer</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>prompt-for-integer</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ prompt-for-integer &key; :prompt :help :must-exist=
:default :default-string =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+This function prompts for a possibly signed integer. If must-exist is
+nil, then prompt-for-integer returns the input as a string if it is
+not a valid integer.
+ </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_prompt-for-keyword">
+ <indexterm zone=3D"f_prompt-for-keyword">
+ <primary>prompt-for-keyword</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>prompt-for-keyword</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ prompt-for-keyword string-tables &key; :prompt :he=
lp :must-exist :default :default-string =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+This function prompts for a keyword with completion, using the string
+tables in the list string-tables. If must-exist is non-nil, then the
+result must be an unambiguous prefix of a string in one of the
+string-tables, and the returns the complete string even if only a
+prefix of the full string was typed. In addition, this returns the
+value of the corresponding entry in the string table as the second
+value.
+ </para>
+ <para>
+If must-exist is nil, then this function returns the string exactly as
+entered. The difference between prompt-for-keyword with must-exist
+nil, and prompt-for-string, is the user may complete the input using
+the Complete Parse and Complete Field commands.
+ </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_prompt-for-expression">
+ <indexterm zone=3D"f_prompt-for-expression">
+ <primary>prompt-for-expression</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>prompt-for-expression</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ prompt-for-expression &key; :prompt :help :must-ex=
ist :default :default-string =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+This function reads a Lisp expression. If must-exist is nil, and a
+read error occurs, then this returns the string typed.
+ </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_prompt-for-string">
+ <indexterm zone=3D"f_prompt-for-string">
+ <primary>prompt-for-string</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>prompt-for-string</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ prompt-for-string &key; :prompt :help :default :de=
fault-string =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+This function prompts for a string; this cannot fail.
+ </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_prompt-for-variable">
+ <indexterm zone=3D"f_prompt-for-variable">
+ <primary>prompt-for-variable</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>prompt-for-variable</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ prompt-for-variable &key; :prompt :help :must-exis=
t :default :default-string =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+This function prompts for a variable name. If must-exist is non-nil,
+then the string must be a variable defined in the current environment,
+in which case the symbol name of the variable found is returned as the
+second value.
+ </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_prompt-for-y-or-n">
+ <indexterm zone=3D"f_prompt-for-y-or-n">
+ <primary>prompt-for-y-or-n</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>prompt-for-y-or-n</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ prompt-for-y-or-n &key; :prompt :help :must-exist =
:default :default-string =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+This prompts for logical key events :Y or :N, returning t or nil without w=
aiting for
+confirmation. When the user types a confirmation key, this returns
+default if it is supplied. If must-exist is nil, this returns
+whatever key-event the user first types; however, if the user types
+one of the above key-events, this returns t or nil. This is analogous to
+the Common Lisp function y-or-n-p.
+ </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_prompt-for-yes-or-no">
+ <indexterm zone=3D"f_prompt-for-yes-or-no">
+ <primary>prompt-for-yes-or-no</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>prompt-for-yes-or-no</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ prompt-for-yes-or-no &key; :prompt :help :must-exi=
st :default :default-string =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+This function is to prompt-for-y-or-n as yes-or-no-p is to
+y-or-n-p. "Yes" or "No" must be typed out in full and confirmation
+must be given.
+ </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"m_command-case">
+ <indexterm zone=3D"m_command-case">
+ <primary>command-case</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>command-case</refname>
+ <refpurpose></refpurpose>
+ <refclass>Macro</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ command-case ({key value}*){({({tag}*) | tag} help=
{form}*)}* =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+This macro is analogous to the Common Lisp case macro. Commands such
+as Help use this to get a key-event, translate it to a
+character, and then to dispatch on the character to some case. In
+addition to character dispatching, this supports logical key-events
+(page 45) by using the input key-event directly without translating it
+to a character. Since the description of this macro is rather
+complex, first consider the following example:
+<programlisting>
+<![CDATA[
+(defcommand "Save All Buffers" (p)
+ "Give the User a chance to save each modified buffer."
+ (dolist (b *buffer-list*)
+ (select-buffer-command () b)
+ (when (buffer-modified b)
+ (command-case (:prompt "Save this buffer: [Y] "
+ :help "Save buffer, or do something else:")
+ ((:yes :confirm)
+ "Save this buffer and go on to the next."
+ (save-file-command () b))
+ (:no "Skip saving this buffer, and go on to the next.")
+ ((:exit #\p) "Punt this silly loop."
+ (return nil))))))
+]]>
+</programlisting>
+ </para>
+ <para>
+command-case prompts for a key-event and then executes the code in the
+first branch with a logical key-event or a character (called tags)
+matching the input. Each character must be a standard-character, one
+that satisfies the Common Lisp standard-char-p predicate, and the
+dispatching mechanism compares the input key-event to any character
+tags by mapping the key-event to a character with
+ext:key-event-char. If the tag is a logical key-event, then the search
+for an appropriate case compares the key-event read with the tag
+using logical-key-event-p.
+ </para>
+ <para>
+All uses of command-case have two default cases, :help and :abort. You
+can override these easily by specifying your own branches that include
+these logical key-event tags. The :help branch displays in a pop-up
+window the a description of the valid responses using the variously
+specified help strings. The :abort branch signals an editor-error.
+ </para>
+ <para>
+The key/value arguments control the prompting. The following are valid va=
lues:
+ </para>
+ <variablelist>
+ <varlistentry>
+ <term>:help</term>
+ <listitem>
+ <para>
+The default :help case displays this string in a pop-up window. In
+addition it formats a description of the valid input including each
+case's help string.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>:prompt</term>
+ <listitem>
+ <para>
+This is the prompt used when reading the key-event.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>:bind</term>
+ <listitem>
+ <para>
+This specifies a variable to which the prompting mechanism binds the
+input key-event. Any case may reference this variable. If you wish
+to know what character corresponds to the key-event, use
+key-event-char.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ <para>
+Instead of specifying a tag or list of tags, you may use t. This
+becomes the default branch, and its forms execute if no other branch
+is taken, including the default :help and :abort cases. This option has
+no helpstring, and the default :help case does not describe the default
+branch. Every command-case has a default branch; if none is specified,
+the macro includes one that beep's and reprompt's (see below).
+ </para>
+ <para>
+Within the body of command-case, there is a defined reprompt macro. It
+causes the prompting mechanism and dispatching mechanism to
+immediately repeat without further execution in the current branch.
+ </para>
+ </refsect1>
+ </refentry>
+ </sect2>
+ <sect2 id=3D"ControlOfParsingBehavior">
+ <title>Control of Parsing Behavior</title>
+ <refentry id=3D"hv_beep_on_ambiguity">
+ <indexterm zone=3D"hv_beep_on_ambiguity">
+ <primary>Beep On Ambiguity</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>Beep On Ambiguity</refname>
+ <refpurpose></refpurpose>
+ <refclass>Hemlock Variable</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ Beep On Ambiguity (initial value t) =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+If this variable is true, then an attempt to complete a parse which is
+ambiguous will result in a "beep".
+ </para>
+ </refsect1>
+ </refentry>
+ </sect2>
+ <sect2 id=3D"DefiningNewPromptingFunctions">
+ <title>Defining New Prompting Functions</title>
+ <para>
+Prompting functionality is implemented by the function parse-for-something
+in cooperation with commands defined in "Echo Area" mode on the buffer ass=
ociated
+with the echo area. You can implement new prompting functions by invoking
+parse-for-something with appropriate arguments.
+ </para>
+ <refentry id=3D"f_parse-for-something">
+ <indexterm zone=3D"f_parse-for-something">
+ <primary>parse-for-something</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>parse-for-something</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ parse-for-something &key; =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+This function enters a mode reading input from the user and echoing it in =
the echo area, and
+returns a value when done. The input is managed by commands bound in "Ech=
o Area" mode on the
+buffer associated with the echo area. The following keyword arguments ar=
e accepted:
+ </para>
+ <variablelist>
+ <varlistentry>
+ <term><code>:verification-function</code></ter=
m>
+ <listitem>
+ <para>
+This is invoked by the Confirm Parse command (page 52). It does most of
+the work when parsing prompted input. Confirm Parse (page 52) calls it
+with one argument, which is the string that the user typed so far.
+The function should return a list of values which are to be the result
+of the recursive edit, or nil indicating that the parse failed. In order
+to return zero values, a non-nil second value may be returned along with
+a nil first value.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><code>:string-tables</code></term>
+ <listitem>
+ <para>
+This is the list of string-tables, if any, that pertain to this parse.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><code>:value-must-exist</code></term>
+ <listitem>
+ <para>
+This is referred to by the verification function, and possibly some of the
+commands.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><code>:default</code></term>
+ <listitem>
+ <para>
+The string representing the default object when prompting the user.
+Confirm Parse supplies this to the parse verification function when the
+user input is empty.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><code>:default-string</code></term>
+ <listitem>
+ <para>
+When prompting the user, if :default is not specified, Hemlock displays
+this string as a representation of the default object; for example,
+when prompting for a buffer, this argument would be a default buffer name.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><code>:type</code></term>
+ <listitem>
+ <para>
+The kind of parse, e.g. :file, :keyword, :string. This tells the completion
+commands how to do completion, with :string disabling completion.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><code>:prompt</code></term>
+ <listitem>
+ <para>
+The prompt to display to the user.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><code>:help</code></term>
+ <listitem>
+ <para>
+The help string or function being used for the current parse.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect1>
+ </refentry>
+ </sect2>
+ <sect2 id=3D"SomeEchoAreaCommands">
+ <title>Some Echo Area Commands</title>
+ <para>
+These are some of the Echo Area commands that coordinate with the
+prompting routines. Hemlock binds other commands specific to the Echo
+Area, but they are uninteresting to mention here, such as deleting to
+the beginning of the line or deleting backwards a word.
+ </para>
+ <refentry id=3D"c_help_on_parse">
+ <indexterm zone=3D"c_help_on_parse">
+ <primary>Help On Parse</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>Help On Parse</refname>
+ <refpurpose></refpurpose>
+ <refclass>Command</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ Help On Parse (bound to Home, C-_ in Echo Area mod=
e) =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+Display the help text for the parse currently in progress.
+ </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"c_complete_keyword">
+ <indexterm zone=3D"c_complete_keyword">
+ <primary>Complete Keyword</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>Complete Keyword</refname>
+ <refpurpose></refpurpose>
+ <refclass>Command</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ Complete Keyword (bound to Escape in Echo Area mod=
e) =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+This attempts to complete the current region.
+It signals an editor-error if the input is ambiguous or incorrect.
+ </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"c_complete_field">
+ <indexterm zone=3D"c_complete_field">
+ <primary>Complete Field</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>Complete Field</refname>
+ <refpurpose></refpurpose>
+ <refclass>Command</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ Complete Field (bound to Space in Echo Area mode) =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+Similar to <code>Complete Keyword</code>, but only attempts to complete up=
to and
+including the first character in the keyword with a non-zero
+:parse-field-separator attribute. If there is no field separator then
+attempt to complete the entire keyword. If it is not a keyword parse
+then just self-insert.
+ </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"c_confirm_parse">
+ <indexterm zone=3D"c_confirm_parse">
+ <primary>Confirm Parse</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>Confirm Parse</refname>
+ <refpurpose></refpurpose>
+ <refclass>Command</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ Confirm Parse (bound to Return in Echo Area mode) =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+Call the verification function with the current input. If it
+returns a non-nil value then that is returned as the value of the
+parse. A parse may return a nil value if the verification function
+returns a non-nil second value.
+ </para>
+ </refsect1>
+ </refentry>
+ </sect2>
+ </sect1>
+ <sect1 id=3D"Files">
+ <title>Files</title>
+ <para>
+This chapter discusses ways to read and write files at various
+levels---at marks, into regions, and into buffers. This also treats
+automatic mechanisms that affect the state of buffers in which files
+are read.
+ </para>
+ <sect2 id=3D"FileOptionsAndTypeHooks">
+ <title>File Options and Type Hooks</title>
+ <para>
+The user specifies file options with a special syntax on the first
+line of a file. If the first line contains the string "-*-",
+then Hemlock interprets the text between the first such occurrence and
+the second, which must be contained in one line , as a list of
+"option: value" pairs separated by semicolons. The following is a
+typical example:
+<programlisting>
+<![CDATA[
+;;; -*- Mode: Lisp, Editor; Package: Hemlock -*-
+]]>
+</programlisting>See the Hemlock User's Manual for more details and predef=
ined options.
+ </para>
+ <para>
+File type hooks are executed when Hemlock reads a file into a buffer
+based on the type of the pathname. When the user specifies a Mode
+file option that turns on a major mode, Hemlock ignores type hooks.
+This mechanism is mostly used as a simple means for turning on some
+appropriate default major mode.
+ </para>
+ <refentry id=3D"m_define-file-option">
+ <indexterm zone=3D"m_define-file-option">
+ <primary>define-file-option</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>define-file-option</refname>
+ <refpurpose></refpurpose>
+ <refclass>Macro</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ define-file-option name (buffer value) {declaratio=
n}* {form}* =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+This defines a new file option with the string
+name name. Buffer and value specify variable names for the buffer and the
+option value string, and forms are evaluated with these bound.
+ </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"m_define-file-type-hook">
+ <indexterm zone=3D"m_define-file-type-hook">
+ <primary>define-file-type-hook</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>define-file-type-hook</refname>
+ <refpurpose></refpurpose>
+ <refclass>Macro</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ define-file-type-hook type-list (buffer type) {dec=
laration}* {form}* =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+This defines some code that process-file-options(below) executes when
+the file options fail to set a major mode. This associates each type,
+a string, in type-list with a routine that binds buffer to the
+buffer the file is in and type to the type of the pathname.
+ </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_process-file-options">
+ <indexterm zone=3D"f_process-file-options">
+ <primary>process-file-options</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>process-file-options</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ process-file-options buffer &optional; pathname =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+This checks for file options in buffer and invokes handlers if there
+are any. Pathname defaults to buffer's pathname but may be nil. If
+there is no Mode file option that specifies a major mode, and pathname
+has a type, then this tries to invoke the appropriate file type
+hook. read-buffer-file calls this.
+ </para>
+ </refsect1>
+ </refentry>
+ </sect2>
+ <sect2 id=3D"PathnamesAndBuffers">
+ <title>Pathnames and Buffers</title>
+ <para>
+There is no good way to uniquely identify buffer names and pathnames.
+However, Hemlock has one way of mapping pathnames to buffer names that
+should be used for consistency among customizations and primitives.
+Independent of this, Hemlock provides a means for consistently
+generating prompting defaults when asking the user for pathnames.
+ </para>
+ <refentry id=3D"f_pathname-to-buffer-name">
+ <indexterm zone=3D"f_pathname-to-buffer-name">
+ <primary>pathname-to-buffer-name</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>pathname-to-buffer-name</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ pathname-to-buffer-name pathname =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+This function returns a string of the form "file-namestring directory-name=
string".
+ </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"hv_pathname_defaults">
+ <indexterm zone=3D"hv_pathname_defaults">
+ <primary>Pathname Defaults</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>Pathname Defaults</refname>
+ <refpurpose></refpurpose>
+ <refclass>Hemlock Variable</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ Pathname Defaults (initial value (pathname "gazonk=
.del")) =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para> </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"hv_last_resort_pathname_defaults_function">
+ <indexterm zone=3D"hv_last_resort_pathname_defaults_functi=
on">
+ <primary>Last Resort Pathname Defaults Function</prima=
ry>
+ </indexterm>
+ <refnamediv>
+ <refname>Last Resort Pathname Defaults Function</refna=
me>
+ <refpurpose></refpurpose>
+ <refclass>Hemlock Variable</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ Last Resort Pathname Defaults Function =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para> </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"hv_last_resort_pathname_defaults">
+ <indexterm zone=3D"hv_last_resort_pathname_defaults">
+ <primary>Last Resort Pathname Defaults</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>Last Resort Pathname Defaults</refname>
+ <refpurpose></refpurpose>
+ <refclass>Hemlock Variable</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ Last Resort Pathname Defaults (initial value (path=
name "gazonk")) =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+These variables control the computation of default pathnames when
+needed for promting the user. Pathname Defaults is a sticky
+default. See the Hemlock User's Manual for more details.
+ </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_buffer-default-pathname">
+ <indexterm zone=3D"f_buffer-default-pathname">
+ <primary>buffer-default-pathname</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>buffer-default-pathname</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ buffer-default-pathname buffer =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+This returns Buffer Pathname if it is bound. If it is not bound, and
+buffer's name is composed solely of alphnumeric characters, then
+return a pathname formed from buffer's name. If buffer's name has
+other characters in it, then return the value of Last Resort Pathname
+Defaults Function called on buffer.
+ </para>
+ </refsect1>
+ </refentry>
+ </sect2>
+ <sect2 id=3D"FileGroups">
+ <title>File Groups</title>
+ <para>
+Currently Hemlock doesn't have support for file groups.
+ </para>
+ </sect2>
+ <sect2 id=3D"FileReadingAndWriting">
+ <title>File Reading and Writing</title>
+ <para>
+Common Lisp pathnames are used by the file primitives. For probing,
+checking write dates, and so forth, all of the Common Lisp file
+functions are available.
+ </para>
+ <refentry id=3D"f_read-file">
+ <indexterm zone=3D"f_read-file">
+ <primary>read-file</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>read-file</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ read-file pathname mark =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+This inserts the file named by pathname at mark.
+ </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_write-file">
+ <indexterm zone=3D"f_write-file">
+ <primary>write-file</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>write-file</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ write-file region pathname &key; :keep-backup :app=
end =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para> </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"hv_keep_backup_files">
+ <indexterm zone=3D"hv_keep_backup_files">
+ <primary>Keep Backup Files</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>Keep Backup Files</refname>
+ <refpurpose></refpurpose>
+ <refclass>Hemlock Variable</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ Keep Backup Files (initial value nil) =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+This function writes the contents of region to the file named by
+pathname. This writes region using a stream as if it were opened with
+:if-exists supplied as :rename-and-delete.
+ </para>
+ <para>
+When keep-backup, which defaults to the value of Keep Backup Files, is
+non-nil, this opens the stream as if :if-exists were :rename. If
+append is non-nil, this writes the file as if it were opened
+with:if-exists supplied as :append.
+ </para>
+ <para>
+This signals an error if both append and keep-backup are supplied as non-n=
il.
+ </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_write-buffer-file">
+ <indexterm zone=3D"f_write-buffer-file">
+ <primary>write-buffer-file</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>write-buffer-file</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ write-buffer-file buffer pathname =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para> </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"hv_write_file_hook">
+ <indexterm zone=3D"hv_write_file_hook">
+ <primary>Write File Hook</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>Write File Hook</refname>
+ <refpurpose></refpurpose>
+ <refclass>Hemlock Variable</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ Write File Hook =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para> </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"hv_add_newline_at_eof_on_writing_file">
+ <indexterm zone=3D"hv_add_newline_at_eof_on_writing_file">
+ <primary>Add Newline at EOF on Writing File</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>Add Newline at EOF on Writing File</refname>
+ <refpurpose></refpurpose>
+ <refclass>Hemlock Variable</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ Add Newline at EOF on Writing File (initial value =
:ask-user) =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+write-buffer-file writes buffer to the file named by pathname
+including the following:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+It assumes pathname is somehow related to buffer's pathname: if
+the buffer's write date is not the same as pathname's, then this
+prompts the user for confirmation before overwriting the file.
+ </para>
+ </listitem>
+ </itemizedlist>
+ <itemizedlist>
+ <listitem>
+ <para>
+It consults Add Newline at EOF on Writing File (see Hemlock User's
+Manual for possible values) and interacts with the user if
+necessary.
+ </para>
+ </listitem>
+ </itemizedlist>
+ <itemizedlist>
+ <listitem>
+ <para>
+It sets Pathname Defaults, and after using write-file,
+marks buffer unmodified.
+ </para>
+ </listitem>
+ </itemizedlist>
+ <itemizedlist>
+ <listitem>
+ <para>
+It updates Buffer's pathname and write date.
+ </para>
+ </listitem>
+ </itemizedlist>
+ <itemizedlist>
+ <listitem>
+ <para>
+It renames the buffer according to the new pathname if possible.
+ </para>
+ </listitem>
+ </itemizedlist>
+ <itemizedlist>
+ <listitem>
+ <para>
+It invokes Write File Hook.
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>
+Write File Hook is a list of functions that take the newly written buffer =
as an argument.
+ </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_read-buffer-file">
+ <indexterm zone=3D"f_read-buffer-file">
+ <primary>read-buffer-file</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>read-buffer-file</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ read-buffer-file pathname buffer =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para> </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"hv_read_file_hook">
+ <indexterm zone=3D"hv_read_file_hook">
+ <primary>Read File Hook</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>Read File Hook</refname>
+ <refpurpose></refpurpose>
+ <refclass>Hemlock Variable</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ Read File Hook =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+read-buffer-file deletes buffer's region and uses read-file to read
+pathname into it, including the following:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+It sets buffer's write date to the file's write date if the file
+exists; otherwise, it messages that this is a new file and sets
+buffer's write date to nil.
+ </para>
+ </listitem>
+ </itemizedlist>
+ <itemizedlist>
+ <listitem>
+ <para>
+It moves buffer's point to the beginning.
+ </para>
+ </listitem>
+ </itemizedlist>
+ <itemizedlist>
+ <listitem>
+ <para>
+It sets buffer's unmodified status.
+ </para>
+ </listitem>
+ </itemizedlist>
+ <itemizedlist>
+ <listitem>
+ <para>
+It sets buffer's pathname to the result of probing pathname if the
+file exists; otherwise, this function sets buffer's pathname to the
+result of merging pathname with default-directory.
+ </para>
+ </listitem>
+ </itemizedlist>
+ <itemizedlist>
+ <listitem>
+ <para>
+It sets Pathname Defaults to the result of the previous item.
+ </para>
+ </listitem>
+ </itemizedlist>
+ <itemizedlist>
+ <listitem>
+ <para>
+It processes the file options.
+ </para>
+ </listitem>
+ </itemizedlist>
+ <itemizedlist>
+ <listitem>
+ <para>
+It invokes Read File Hook.
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>
+Read File Hook is a list functions that take two arguments---the
+buffer read into and whether the file existed, t if so.
+ </para>
+ </refsect1>
+ </refentry>
+ </sect2>
+ </sect1>
+ <sect1 id=3D"HemlockProgrammingHemlockSLispEnvironment">
+ <title>Hemlock's Lisp Environment</title>
+ <para>
+This chapter is sort of a catch all for any functions and variables
+which concern Hemlock's interaction with the outside world.
+ </para>
+ <sect2 id=3D"EnteringAndLeavingTheEditor">
+ <title>Entering and Leaving the Editor</title>
+ <refentry id=3D"f_ed">
+ <indexterm zone=3D"f_ed">
+ <primary>ed</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>ed</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ ed &optional; x =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+This a standard Common Lisp function. If x is supplied and is a
+string or pathname, the file specified by x is visited in a hemlock
+view (opening a new window if necessary, otherwise bringing an
+existing window with the file to the front), and the hemlock view
+object is the return value from the function.
+ </para>
+ <para>
+If x is null, a new empty hemlock view is created and returned.
+ </para>
+ <para>
+If x is a symbol or a setf function name, it attempts to
+edit the definition of the name. In this last case, the
+function returns without waiting for the operation to complete
+(for example, it might put up a non-modal dialog asking the
+user to select one of multiple definitions) and hence the
+return value is always NIL.
+ </para>
+ </refsect1>
+ </refentry>
+ </sect2>
+ <sect2 id=3D"KeyboardInput">
+ <title>Keyboard Input</title>
+ <refentry id=3D"v_key-event-history">
+ <indexterm zone=3D"v_key-event-history">
+ <primary>*key-event-history*</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>*key-event-history*</refname>
+ <refpurpose></refpurpose>
+ <refclass>Variable</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ *key-event-history* =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+This is a Hemlock ring buffer (see page 70) that holds the last 60
+key-events received.
+ </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_last-key-event-typed">
+ <indexterm zone=3D"f_last-key-event-typed">
+ <primary>last-key-event-typed</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>last-key-event-typed</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ last-key-event-typed =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+This function returns the last key-event the user typed to invoke the curr=
ent command.
+ </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_last-char-typed">
+ <indexterm zone=3D"f_last-char-typed">
+ <primary>last-char-typed</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>last-char-typed</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ last-char-typed =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+This function returns the character corresponding to the last key event ty=
ped.
+ </para>
+ </refsect1>
+ </refentry>
+ </sect2>
+ <sect2 id=3D"HemlockStreams">
+ <title>Hemlock Streams</title>
+ <para>
+It is possible to create streams which output to or get input from a
+buffer. This mechanism is quite powerful and permits easy interfacing
+of Hemlock to Lisp.
+ </para>
+ <para>
+Note that operations on these streams operate directly on buffers,
+therefore they have the same restrictions as described <ulink url=3D"Hemlo=
ckProgrammer/Buffers">here</ulink>
+for interacting with buffers from outside of the GUI thread.
+ </para>
+ <refentry id=3D"f_make-hemlock-output-stream">
+ <indexterm zone=3D"f_make-hemlock-output-stream">
+ <primary>make-hemlock-output-stream</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>make-hemlock-output-stream</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ make-hemlock-output-stream mark &optional; buffere=
d =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+This function returns a stream that inserts at mark all
+output directed to it. It works best if mark is a left-inserting mark.
+Buffered controls whether the stream is buffered or not, and its valid val=
ues
+are the following keywords:
+ </para>
+ <variablelist>
+ <varlistentry>
+ <term>:none</term>
+ <listitem>
+ <para>
+No buffering is done. This is the default.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>:line</term>
+ <listitem>
+ <para>
+The buffer is flushed whenever a newline is written or when it is
+explicitly done with force-output.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>:full</term>
+ <listitem>
+ <para>
+The stream is only brought up to date when it is explicitly
+done with force-output
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_hemlock-output-stream-p">
+ <indexterm zone=3D"f_hemlock-output-stream-p">
+ <primary>hemlock-output-stream-p</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>hemlock-output-stream-p</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ hemlock-output-stream-p object =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+This function returns t if object is a hemlock-output-stream object.
+ </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_make-hemlock-region-stream">
+ <indexterm zone=3D"f_make-hemlock-region-stream">
+ <primary>make-hemlock-region-stream</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>make-hemlock-region-stream</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ make-hemlock-region-stream region =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+This function returns a stream from which the text in
+region can be read.
+ </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_hemlock-region-stream-p">
+ <indexterm zone=3D"f_hemlock-region-stream-p">
+ <primary>hemlock-region-stream-p</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>hemlock-region-stream-p</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ hemlock-region-stream-p object =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+This function returns t if object is a hemlock-region-stream object.
+ </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"m_with-input-from-region">
+ <indexterm zone=3D"m_with-input-from-region">
+ <primary>with-input-from-region</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>with-input-from-region</refname>
+ <refpurpose></refpurpose>
+ <refclass>Macro</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ with-input-from-region (var region) {declaration}*=
{form}* =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+While evaluating forms, binds var to a stream which returns input from reg=
ion.
+ </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"m_with-output-to-mark">
+ <indexterm zone=3D"m_with-output-to-mark">
+ <primary>with-output-to-mark</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>with-output-to-mark</refname>
+ <refpurpose></refpurpose>
+ <refclass>Macro</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ with-output-to-mark (var mark [buffered]) {declara=
tion}* {form}* =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+During the evaluation of the forms, binds var to a stream which inserts
+output at the permanent mark. Buffered has the same meaning as for
+make-hemlock-output-stream.
+ </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"m_with-pop-up-display">
+ <indexterm zone=3D"m_with-pop-up-display">
+ <primary>with-pop-up-display</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>with-pop-up-display</refname>
+ <refpurpose></refpurpose>
+ <refclass>Macro</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ with-pop-up-display (var &key; height name) {decla=
ration}* {form}* =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+This macro executes forms in a context with var bound to a
+stream. Hemlock collects output to this stream and tries to pop up a
+display of the appropriate height containing all the output. When
+height is supplied, Hemlock creates the pop-up display immediately,
+forcing output on line breaks. This is useful for displaying information
+of temporary interest.
+ </para>
+ </refsect1>
+ </refentry>
+ </sect2>
+ <sect2 id=3D"InterfaceToTheErrorSystem">
+ <title>Interface to the Error System</title>
+ <para>
+Hemlock commands are executed from an event handler in the initial
+Cocoa thread. They are executed within a
+ccl::with-standard-abort-handling form, which means cl:abort,
+ccl:abort-break, ccl:throw-cancel will abort the current command only
+and exit the event handler in an orderly fashion.
+ </para>
+ <para>
+In addition, for now, lisp errors during command execution dump a
+backtrace in the system console and are otherwise handled as if by
+ <code>handle-lisp-errors</code> below, which means it is n=
ot possible to debug
+errors at the point of the error. Once &CCL; has better support
+for debugging errors in the initial Cocoa thread, better Hemlock error
+handling will be provided that will allow for some way to debug.
+ </para>
+ <refentry id=3D"f_editor-error">
+ <indexterm zone=3D"f_editor-error">
+ <primary>editor-error</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>editor-error</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ editor-error &rest; args =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+This function is called to report minor errors to the user. These are
+errors that a normal user could encounter in the course of editing,
+such as a search failing or an attempt to delete past the end of the
+buffer. This function simply aborts the current command. Any args
+specified are used to format an error message to be placed in the echo
+area. This function never returns.
+ </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"m_handle-lisp-errors">
+ <indexterm zone=3D"m_handle-lisp-errors">
+ <primary>handle-lisp-errors</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>handle-lisp-errors</refname>
+ <refpurpose></refpurpose>
+ <refclass>Macro</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ handle-lisp-errors {form}* =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+Within the body of this macro any Lisp errors that occur are handled
+by displaying an error message in a dialog and aborting the current
+command, leaving the error text in the echo area. This macro should
+be wrapped around code which may get an error due to some action of
+the user --- for example, evaluating code fragments on the behalf of
+and supplied by the user.
+ </para>
+ </refsect1>
+ </refentry>
+ </sect2>
+ <sect2 id=3D"DefinitionEditing">
+ <title>Definition Editing</title>
+ <para>
+Hemlock provides commands for finding the definition of a function
+or variable and placing the user at the definition in a buffer. A
+function is provided to allow invoking this functionality outside
+of Hemlock. Note that this function is unusual in that it is
+it is safe to call outside of the command interpreter, and in fact
+it can be called from any thread.
+ </para>
+ <refentry id=3D"f_edit-definition">
+ <indexterm zone=3D"f_edit-definition">
+ <primary>edit-definition</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>edit-definition</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ edit-definition name =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+This function tries to find the definition of <code>name</code>, create
+or activate the window containing it, and scroll the view
+to show the definition. If there are multiple definitions
+available, the user is given a choice of which one to
+use. This function may return before the operation is complete.
+ </para>
+ </refsect1>
+ </refentry>
+ </sect2>
+ <sect2 id=3D"EventScheduling">
+ <title>Event Scheduling</title>
+ <para>
+No Event Scheduling functionality is provided at this time.
+ </para>
+ </sect2>
+ <sect2 id=3D"Miscellaneous">
+ <title>Miscellaneous</title>
+ <refentry id=3D"f_in-lisp">
+ <indexterm zone=3D"f_in-lisp">
+ <primary>in-lisp</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>in-lisp</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ in-lisp {form}* =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+This evaluates forms inside handle-lisp-errors. It also binds
+*package* to the package named by Current Package if it is
+non-nil. Use this when evaluating Lisp code on behalf of the user.
+ </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"m_do-alpha-chars">
+ <indexterm zone=3D"m_do-alpha-chars">
+ <primary>do-alpha-chars</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>do-alpha-chars</refname>
+ <refpurpose></refpurpose>
+ <refclass>Macro</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ do-alpha-chars (var kind [result]) {form}* =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+This iterates over alphabetic characters in Common Lisp binding var to
+each character in order as specified under character relations in
+Common Lisp the Language. Kind is one of:lower, :upper, or :both. When
+the user supplies :both, lowercase characters are processed first.
+ </para>
+ </refsect1>
+ </refentry>
+ </sect2>
+ </sect1>
+ <sect1 id=3D"HemlockProgrammingHighLevelTextPrimitives">
+ <title>High-Level Text Primitives</title>
+ <para>
+This chapter discusses primitives that operate on higher level text
+forms than characters and words. For English text, there are functions
+that know about sentence and paragraph structures, and for Lisp
+sources, there are functions that understand this language. This
+chapter also describes mechanisms for organizing file sections into
+logical pages and for formatting text forms.
+ </para>
+ <sect2 id=3D"IndentingText">
+ <title>Indenting Text</title>
+ <refentry id=3D"hv_indent_function">
+ <indexterm zone=3D"hv_indent_function">
+ <primary>Indent Function</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>Indent Function</refname>
+ <refpurpose></refpurpose>
+ <refclass>Hemlock Variable</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ Indent Function (initial value tab-to-tab-st=
op) =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+The value of this variable determines how indentation is done, and it
+is a function which is passed a mark as its argument. The function
+should indent the line that the mark points to. The function may move
+the mark around on the line. The mark will be :left-inserting. The
+default simply inserts a tab character at the mark. A function for
+Lisp mode probably moves the mark to the beginning of the line,
+deletes horizontal whitespace, and computes some appropriate
+indentation for Lisp code.
+ </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"hv_indent_with_tabs">
+ <indexterm zone=3D"hv_indent_with_tabs">
+ <primary>Indent with Tabs</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>Indent with Tabs</refname>
+ <refpurpose></refpurpose>
+ <refclass>Hemlock Variable</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ Indent with Tabs (initial value nil) =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para> </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"hv_spaces_per_tab">
+ <indexterm zone=3D"hv_spaces_per_tab">
+ <primary>Spaces per Tab</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>Spaces per Tab</refname>
+ <refpurpose></refpurpose>
+ <refclass>Hemlock Variable</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ Spaces per Tab (initial value 8) =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+Indent with Tabs should be true if indenting should use tabs
+whenever possible. If nil, the default, it only uses spaces.
+Spaces per Tab defines the size of a tab.
+ </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_indent-region">
+ <indexterm zone=3D"f_indent-region">
+ <primary>indent-region</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>indent-region</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ indent-region region =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para> </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_indent-region-for-commands">
+ <indexterm zone=3D"f_indent-region-for-commands">
+ <primary>indent-region-for-commands</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>indent-region-for-commands</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ indent-region-for-commands region =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+indent-region invokes the value of Indent Function on every line of
+region. indent-region-for-commands uses indent-region but first saves
+the region for the Undo command.
+ </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_delete-horizontal-space">
+ <indexterm zone=3D"f_delete-horizontal-space">
+ <primary>delete-horizontal-space</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>delete-horizontal-space</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ delete-horizontal-space mark =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+This deletes all characters on either side of mark with a Space attribute =
(see section 9.5)
+of 1.
+ </para>
+ </refsect1>
+ </refentry>
+ </sect2>
+ <sect2 id=3D"LispTextBuffers">
+ <title>Lisp Text Buffers</title>
+ <para>
+Hemlock bases its Lisp primitives on parsing a block of the buffer and
+annotating lines as to what kind of Lisp syntax occurs on the line or
+what kind of form a mark might be in (for example, string, comment,
+list, etc.). These do not work well if the block of parsed forms is
+exceeded when moving marks around these forms, but the block that gets
+parsed is somewhat programmable.
+ </para>
+ <para>
+There is also a notion of a top level form which this documentation
+often uses synonymously with defun, meaning a Lisp form occurring in a
+source file delimited by parentheses with the opening parenthesis at
+the beginning of some line. The names of the functions include this
+inconsistency.
+ </para>
+ <refentry id=3D"f_pre-command-parse-check">
+ <indexterm zone=3D"f_pre-command-parse-check">
+ <primary>pre-command-parse-check</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>pre-command-parse-check</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ pre-command-parse-check mark for-sure =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para> </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"hv_parse_start_function">
+ <indexterm zone=3D"hv_parse_start_function">
+ <primary>Parse Start Function</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>Parse Start Function</refname>
+ <refpurpose></refpurpose>
+ <refclass>Hemlock Variable</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ Parse Start Function (initial value start-of-pars=
e-block) =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para> </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"hv_parse_end_function">
+ <indexterm zone=3D"hv_parse_end_function">
+ <primary>Parse End Function</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>Parse End Function</refname>
+ <refpurpose></refpurpose>
+ <refclass>Hemlock Variable</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ Parse End Function (initial value end-of-parse-=
block) =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para> </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"hv_minimum_lines_parsed">
+ <indexterm zone=3D"hv_minimum_lines_parsed">
+ <primary>Minimum Lines Parsed</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>Minimum Lines Parsed</refname>
+ <refpurpose></refpurpose>
+ <refclass>Hemlock Variable</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ Minimum Lines Parsed (initial value 50) =
=
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para> </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"hv_maximum_lines_parsed">
+ <indexterm zone=3D"hv_maximum_lines_parsed">
+ <primary>Maximum Lines Parsed</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>Maximum Lines Parsed</refname>
+ <refpurpose></refpurpose>
+ <refclass>Hemlock Variable</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ Maximum Lines Parsed (initial value 500) =
=
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para> </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"hv_defun_parse_goal">
+ <indexterm zone=3D"hv_defun_parse_goal">
+ <primary>Defun Parse Goal</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>Defun Parse Goal</refname>
+ <refpurpose></refpurpose>
+ <refclass>Hemlock Variable</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ Defun Parse Goal (initial value 2) =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+pre-command-parse-check calls Parse Start Function and Parse End
+Function on mark to get two marks. It then parses all the lines
+between the marks including the complete lines they point into. When
+for-sure is non-nil, this parses the area regardless of any cached
+information about the lines. Every command that uses the following
+routines calls this before doing so.
+ </para>
+ <para>
+The default values of the start and end variables use Minimum Lines
+Parsed, Maximum Lines Parsed, and Defun Parse Goal to determine how
+big a region to parse. These two functions always include at least the
+minimum number of lines before and after the mark passed to them. They
+try to include Defun Parse Goal number of top level forms before and
+after the mark passed them, but these functions never return marks
+that include more than the maximum number of lines before or after the
+mark passed to them.
+ </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_form-offset">
+ <indexterm zone=3D"f_form-offset">
+ <primary>form-offset</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>form-offset</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ form-offset mark count =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+This tries to move mark count forms forward if positive or -count
+forms backwards if negative. Mark is always moved. If there were
+enough forms in the appropriate direction, this returns mark,
+otherwise nil.
+ </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_top-level-offset">
+ <indexterm zone=3D"f_top-level-offset">
+ <primary>top-level-offset</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>top-level-offset</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ top-level-offset mark count =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+This tries to move mark count top level forms forward if positive or
+-count top level forms backwards if negative. If there were enough top
+level forms in the appropriate direction, this returns mark, otherwise
+nil. Mark is moved only if this is successful.
+ </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_mark-top-level-form">
+ <indexterm zone=3D"f_mark-top-level-form">
+ <primary>mark-top-level-form</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>mark-top-level-form</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ mark-top-level-form mark1 mark2 =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+This moves mark1 and mark2 to the beginning and end, respectively, of
+the current or next top level form. Mark1 is used as a reference to
+start looking. The marks may be altered even if unsuccessful. If
+successful, return mark2, else nil. Mark2 is left at the beginning of
+the line following the top level form if possible, but if the last
+line has text after the closing parenthesis, this leaves the mark
+immediately after the form.
+ </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_defun-region">
+ <indexterm zone=3D"f_defun-region">
+ <primary>defun-region</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>defun-region</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ defun-region mark =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+This returns a region around the current or next defun with respect to
+mark. Mark is not used to form the region. If there is no appropriate
+top level form, this signals an editor-error. This calls
+pre-command-parse-check first.
+ </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_inside-defun-p">
+ <indexterm zone=3D"f_inside-defun-p">
+ <primary>inside-defun-p</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>inside-defun-p</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ inside-defun-p mark =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para> </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_start-defun-p">
+ <indexterm zone=3D"f_start-defun-p">
+ <primary>start-defun-p</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>start-defun-p</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ start-defun-p mark =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+These return, respectively, whether mark is inside a top level form or
+at the beginning of a line immediately before a character whose Lisp
+Syntax (see section 9.5) value is :opening-paren.
+ </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_forward-up-list">
+ <indexterm zone=3D"f_forward-up-list">
+ <primary>forward-up-list</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>forward-up-list</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ forward-up-list mark =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para> </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_backward-up-list">
+ <indexterm zone=3D"f_backward-up-list">
+ <primary>backward-up-list</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>backward-up-list</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ backward-up-list mark =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+Respectively, these move mark immediately past a character whose Lisp
+Syntax (see section 9.5) value is :closing-paren or immediately before
+a character whose Lisp Syntax value is :opening-paren.
+ </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_valid-spot">
+ <indexterm zone=3D"f_valid-spot">
+ <primary>valid-spot</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>valid-spot</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ valid-spot mark forwardp =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+This returns t or nil depending on whether the character indicated by
+mark is a valid spot. When forwardp is set, use the character after
+mark and vice versa. Valid spots exclude commented text, inside
+strings, and character quoting.
+ </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_defindent">
+ <indexterm zone=3D"f_defindent">
+ <primary>defindent</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>defindent</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ defindent name count =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+This defines the function with name to have count special
+arguments. indent-for-lisp, the value of Indent Function (see section
+15.1) in Lisp mode, uses this to specially indent these arguments. For
+example, do has two, with-open-file has one, etc. There are many of
+these defined by the system including definitions for special Hemlock
+forms. Name is a simple-string, case insensitive and purely textual
+(that is, not read by the Lisp reader); therefore, "with-a-mumble" is
+distinct from "mumble:with-a-mumble".
+ </para>
+ </refsect1>
+ </refentry>
+ </sect2>
+ <sect2 id=3D"EnglishTextBuffers">
+ <title>English Text Buffers</title>
+ <para>
+This section describes some routines that understand basic English
+language forms.
+ </para>
+ <refentry id=3D"f_word-offset">
+ <indexterm zone=3D"f_word-offset">
+ <primary>word-offset</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>word-offset</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ word-offset mark count =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+This moves mark count words forward (if positive) or backwards (if
+negative). If mark is in the middle of a word, that counts as one. If
+there were count (-count if negative) words in the appropriate
+direction, this returns mark, otherwise nil. This always moves mark. A
+word lies between two characters whose Word Delimiter attribute value
+is 1 (see section 9.5).
+ </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_sentence-offset">
+ <indexterm zone=3D"f_sentence-offset">
+ <primary>sentence-offset</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>sentence-offset</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ sentence-offset mark count =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+This moves mark count sentences forward (if positive) or backwards (if neg=
ative). If mark is in the middle of a sentence, that counts as one. If ther=
e were count (-count if negative) sentences in the appropriate direction, t=
his returns mark, otherwise nil. This always moves mark. =
+ </para>
+ <para>
+A sentence ends with a character whose Sentence Terminator attribute
+is 1 followed by two spaces, a newline, or the end of the buffer. The
+terminating character is optionally followed by any number of
+characters whose Sentence Closing Char attribute is 1. A sentence
+begins after a previous sentence ends, at the beginning of a
+paragraph, or at the beginning of the buffer.
+ </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_paragraph-offset">
+ <indexterm zone=3D"f_paragraph-offset">
+ <primary>paragraph-offset</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>paragraph-offset</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ paragraph-offset mark count &optional; prefix=
=
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para> </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"hv_paragraph_delimiter_function">
+ <indexterm zone=3D"hv_paragraph_delimiter_function">
+ <primary>Paragraph Delimiter Function</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>Paragraph Delimiter Function</refname>
+ <refpurpose></refpurpose>
+ <refclass>Hemlock Variable</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ Paragraph Delimiter Function (initial val=
ue ) =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+This moves mark count paragraphs forward (if positive) or backwards
+(if negative). If mark is in the middle of a paragraph, that counts as
+one. If there were count (-count if negative) paragraphs in the
+appropriate direction, this returns mark, otherwise nil. This only
+moves mark if there were enough paragraphs.
+ </para>
+ <para>
+Paragraph Delimiter Function holds a function that takes a mark,
+typically at the beginning of a line, and returns whether or not the
+current line should break the paragraph. default-para-delim-function
+returns t if the next character, the first on the line, has a
+Paragraph Delimiter attribute value of 1. This is typically a space,
+for an indented paragraph, or a newline, for a block style. Some modes
+require a more complicated determinant; for example, Scribe modes adds
+some characters to the set and special cases certain formatting
+commands.
+ </para>
+ <para>
+Prefix defaults to Fill Prefix (see section 15.5), and the right
+prefix is necessary to correctly skip paragraphs. If prefix is
+non-nil, and a line begins with prefix, then the scanning process
+skips the prefix before invoking the Paragraph Delimiter
+Function. Note, when scanning for paragraph bounds, and prefix is
+non-nil, lines are potentially part of the paragraph regardless of
+whether they contain the prefix; only the result of invoking the
+delimiter function matters.
+ </para>
+ <para>
+The programmer should be aware of an idiom for finding the end of the
+current paragraph. Assume paragraphp is the result of moving mark one
+paragraph, then the following correctly determines whether there
+actually is a current paragraph:
+<programlisting>
+<![CDATA[
+(or paragraphp
+ (and (last-line-p mark)
+ (end-line-p mark)
+ (not (blank-line-p (mark-line mark))))) =
+]]>
+</programlisting>
+ </para>
+ <para>
+In this example mark is at the end of the last paragraph in the
+buffer, and there is no last newline character in the
+buffer. paragraph-offset would have returned nil since it could not
+skip any paragraphs since mark was at the end of the current and last
+paragraph. However, you still have found a current paragraph on which
+to operate. mark-paragraph understands this problem.
+ </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_mark-paragraph">
+ <indexterm zone=3D"f_mark-paragraph">
+ <primary>mark-paragraph</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>mark-paragraph</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ mark-paragraph mark1 mark2 =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+This marks the next or current paragraph, setting mark1 to the
+beginning and mark2 to the end. This uses Fill Prefix (see section
+15.5). Mark1 is always on the first line of the paragraph, regardless
+of whether the previous line is blank. Mark2 is typically at the
+beginning of the line after the line the paragraph ends on, this
+returns mark2 on success. If this cannot find a paragraph, then the
+marks are left unmoved, and nil is returned.
+ </para>
+ </refsect1>
+ </refentry>
+ </sect2>
+ <sect2 id=3D"LogicalPages">
+ <title>Logical Pages</title>
+ <para>
+Logical pages are not supported at this time.
+ </para>
+ </sect2>
+ <sect2 id=3D"Filling">
+ <title>Filling</title>
+ <para>
+Filling is an operation on text that breaks long lines at word
+boundaries before a given column and merges shorter lines together in
+an attempt to make each line roughly the specified length. This is
+different from justification which tries to add whitespace in awkward
+places to make each line exactly the same length. Hemlock's filling
+optionally inserts a specified string at the beginning of each
+line. Also, it eliminates extra whitespace between lines and words,
+but it knows two spaces follow sentences (see section 15.3).
+ </para>
+ <refentry id=3D"hv_fill_column">
+ <indexterm zone=3D"hv_fill_column">
+ <primary>Fill Column</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>Fill Column</refname>
+ <refpurpose></refpurpose>
+ <refclass>Hemlock Variable</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ Fill Column (initial value 75) =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para> </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"hv_fill_prefix">
+ <indexterm zone=3D"hv_fill_prefix">
+ <primary>Fill Prefix</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>Fill Prefix</refname>
+ <refpurpose></refpurpose>
+ <refclass>Hemlock Variable</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ Fill Prefix (initial value nil) =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+These variables hold the default values of the prefix and column
+arguments to Hemlock's filling primitives. If Fill Prefix is nil, then
+there is no fill prefix.
+ </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_fill-region">
+ <indexterm zone=3D"f_fill-region">
+ <primary>fill-region</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>fill-region</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ fill-region region &optional; prefix column =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+This deletes any blank lines in region and fills it according to
+prefix and column. Prefix and column default to Fill Prefix and Fill
+Column.
+ </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_fill-region-by-paragraphs">
+ <indexterm zone=3D"f_fill-region-by-paragraphs">
+ <primary>fill-region-by-paragraphs</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>fill-region-by-paragraphs</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ fill-region-by-paragraphs region &optional; pr=
efix column =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+This finds paragraphs (see section 15.3) within region and fills them
+with fill-region. This ignores blank lines between paragraphs. Prefix
+and column default to Fill Prefix and Fill Column.
+ </para>
+ </refsect1>
+ </refentry>
+ </sect2>
+ </sect1>
+ <sect1 id=3D"HemlockProgrammingUtilities">
+ <title>Utilities</title>
+ <para>
+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.
+ </para>
+ <sect2 id=3D"StringTableFunctions">
+ <title>String-table Functions</title>
+ <para>
+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.
+ </para>
+ <para>
+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.
+ </para>
+ <refentry id=3D"f_make-string-table">
+ <indexterm zone=3D"f_make-string-table">
+ <primary>make-string-table</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>make-string-table</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ make-string-table =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+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:
+<programlisting>
+<![CDATA[
+'(("Global" . t) ("Mode" . t) ("Buffer" . t))
+]]>
+</programlisting>
+ </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_string-table-p">
+ <indexterm zone=3D"f_string-table-p">
+ <primary>string-table-p</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>string-table-p</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ string-table-p string-table =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+This function returns t if string-table is a string-table object,
+otherwise nil.
+ </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_string-table-separator">
+ <indexterm zone=3D"f_string-table-separator">
+ <primary>string-table-separator</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>string-table-separator</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ string-table-separator string-table =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+This function returns the separator character given to
+make-string-table.
+ </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_delete-string">
+ <indexterm zone=3D"f_delete-string">
+ <primary>delete-string</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>delete-string</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ delete-string string table =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para> </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_clrstring">
+ <indexterm zone=3D"f_clrstring">
+ <primary>clrstring</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>clrstring</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ clrstring table =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+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.
+ </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_getstring">
+ <indexterm zone=3D"f_getstring">
+ <primary>getstring</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>getstring</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ getstring string table =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+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.
+ </para>
+ <para>
+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.
+ </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_complete-string">
+ <indexterm zone=3D"f_complete-string">
+ <primary>complete-string</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>complete-string</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ complete-string string tables =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+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:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+The maximal completion of the string or nil if there is none.
+ </para>
+ </listitem>
+ </itemizedlist>
+ <itemizedlist>
+ <listitem>
+ <para>
+An indication of the usefulness of the returned string:
+ </para>
+ </listitem>
+ </itemizedlist>
+ <variablelist>
+ <varlistentry>
+ <term>:none</term>
+ <listitem>
+ <para>
+There is no completion of string.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>:complete</term>
+ <listitem>
+ <para>
+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.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>:unique</term>
+ <listitem>
+ <para>
+The completion is a valid entry and unique.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>:ambiguous</term>
+ <listitem>
+ <para>
+The completion is invalid; get-string would return nil
+and nil if given the returned string.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ <itemizedlist>
+ <listitem>
+ <para>
+The value of the string when the completion is :unique or
+:complete, otherwise nil.
+ </para>
+ </listitem>
+ </itemizedlist>
+ <itemizedlist>
+ <listitem>
+ <para>
+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.
+ </para>
+ </listitem>
+ </itemizedlist>
+ <itemizedlist>
+ <listitem>
+ <para>
+An index to the separator following the first ambiguous field when
+the completion is :ambiguous or :complete, otherwise nil.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_find-ambiguous">
+ <indexterm zone=3D"f_find-ambiguous">
+ <primary>find-ambiguous</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>find-ambiguous</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ find-ambiguous string table =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para> </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_find-containing">
+ <indexterm zone=3D"f_find-containing">
+ <primary>find-containing</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>find-containing</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ find-containing string table =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+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.
+ </para>
+ <para>
+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.
+ </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"m_do-strings">
+ <indexterm zone=3D"m_do-strings">
+ <primary>do-strings</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>do-strings</refname>
+ <refpurpose></refpurpose>
+ <refclass>Macro</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ do-strings (string-var value-var table result) d=
eclaration tag statement =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+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.
+ </para>
+ </refsect1>
+ </refentry>
+ </sect2>
+ <sect2 id=3D"RingFunctions">
+ <title>Ring Functions</title>
+ <para>
+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.
+ </para>
+ <refentry id=3D"f_make-ring">
+ <indexterm zone=3D"f_make-ring">
+ <primary>make-ring</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>make-ring</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ make-ring length &optional; delete-function =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+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.
+ </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_ringp">
+ <indexterm zone=3D"f_ringp">
+ <primary>ringp</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>ringp</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ ringp ring =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+Returns t if ring is a ring object, otherwise nil.
+ </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_ring-length">
+ <indexterm zone=3D"f_ring-length">
+ <primary>ring-length</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>ring-length</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ ring-length ring =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+Returns as multiple-values the number of elements which ring currently
+holds and the maximum number of elements which it may hold.
+ </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_ring-ref">
+ <indexterm zone=3D"f_ring-ref">
+ <primary>ring-ref</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>ring-ref</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ ring-ref ring index =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+Returns the index'th item in the ring, where zero is the index of the
+most recently pushed. This may be set with setf.
+ </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_ring-push">
+ <indexterm zone=3D"f_ring-push">
+ <primary>ring-push</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>ring-push</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ ring-push object ring =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+Pushes object into ring, possibly causing the oldest item to go away.
+ </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_ring-pop">
+ <indexterm zone=3D"f_ring-pop">
+ <primary>ring-pop</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>ring-pop</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ ring-pop ring =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+Removes the most recently pushed object from ring and returns it. If
+the ring contains no elements then an error is signalled.
+ </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_rotate-ring">
+ <indexterm zone=3D"f_rotate-ring">
+ <primary>rotate-ring</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>rotate-ring</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ rotate-ring ring offset =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+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.
+ </para>
+ </refsect1>
+ </refentry>
+ </sect2>
+ <sect2 id=3D"UndoingCommands">
+ <title>Undoing commands</title>
+ <para>
+No API to the undo facility is provided at this time.
+ </para>
+ </sect2>
+ </sect1>
+ <sect1 id=3D"HemlockProgrammingMiscellaneous">
+ <title>Miscellaneous</title>
+ <para>
+This chapter is somewhat of a catch-all for comments and features that
+don't fit well anywhere else.
+ </para>
+ <sect2 id=3D"KeyEvents">
+ <title>Key-events</title>
+ <sect3 id=3D"KeyEventsIntroduction">
+ <title>Introduction</title>
+ <para>
+The canonical representation of editor input is a key-event
+structure. Users can bind commands to keys (see section 1.3.1), which
+are non-empty sequences of key-events. A key-event consists of
+an identifying token known as a keysym and a field of bits
+representing modifiers. Users define keysyms by supplying names
+that reflect the legends on their keyboard's keys.
+Users define modifier names similarly, but the system chooses the
+bit and mask for recognizing the modifier. You can
+use keysym and modifier names to textually specify key-events and
+Hemlock keys in a #k syntax. The following are some examples:
+<programlisting>
+<![CDATA[
+#k"C-u"
+#k"Control-u"
+#k"c-m-z"
+#k"control-x meta-d"
+#k"a"
+#k"A"
+#k"Linefeed"
+]]>
+</programlisting>
+ </para>
+ <para>
+This is convenient for use within code and in init files containing
+bind-key calls.
+ </para>
+ <para>
+The #k syntax is delimited by double quotes, but the system parses the
+contents rather than reading it as a Common Lisp string. Within the
+double quotes, spaces separate multiple key-events. A single key-event
+optionally starts with modifier names terminated by hyphens. Modifier
+names are alphabetic sequences of characters which the system uses
+case-insensitively. Following modifiers is a keysym name, which is
+case-insensitive if it consists of multiple characters, but if the
+name consists of only a single character, then it is case-sensitive.
+ </para>
+ <para>
+You can escape special characters --- hyphen, double quote, open angle
+bracket, close angle bracket, and space --- with a backslash, and you
+can specify a backslash by using two contiguously. You can use angle
+brackets to enclose a keysym name with many special characters in
+it. Between angle brackets appearing in a keysym name position, there
+are only two special characters, the closing angle bracket and
+backslash.
+ </para>
+ </sect3>
+ <sect3 id=3D"KeyEventsInterface">
+ <title>Interface</title>
+ <refentry id=3D"f_define-keysym">
+ <indexterm zone=3D"f_define-keysym">
+ <primary>define-keysym</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>define-keysym</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ define-keysym keysym preferred-name &rest; o=
ther-names =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+This function establishes a mapping from preferred-name to keysym for
+purposes of #k syntax. Other-names also map to keysym, but the system
+uses preferred-name when printing key-events. The names are
+case-insensitive simple-strings; however, if the string contains a
+single character, then it is used case-sensitively. Redefining a
+keysym or re-using names has undefined effects.
+ </para>
+ <para>
+Keysym can be any object, but generally it is either an integer
+representing the window-system code for the event, or a keyword
+which allows the mapping of the keysym to its code to be defined
+separately.
+ </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_define-keysym-code">
+ <indexterm zone=3D"f_define-keysym-code">
+ <primary>define-keysym-code</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>define-keysym-code</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ define-keysym-code keysym code =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+Defines the window-system code for the key event which in Hemlock is
+represented by keysym.
+ </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_define-mouse-keysym">
+ <indexterm zone=3D"f_define-mouse-keysym">
+ <primary>define-mouse-keysym</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>define-mouse-keysym</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ define-mouse-keysym button keysym name shift=
ed-bit event-key =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+This function defines keysym named name for key-events representing
+mouse click events. Shifted-bit is a defined modifier name that
+translate-mouse-key-event sets in the key-event it returns whenever
+the shift bit is set in an incoming event.
+ </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_name-keysym">
+ <indexterm zone=3D"f_name-keysym">
+ <primary>name-keysym</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>name-keysym</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ name-keysym name =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+This function returns the keysym named name. If name is unknown, this
+returns nil.
+ </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_keysym-names">
+ <indexterm zone=3D"f_keysym-names">
+ <primary>keysym-names</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>keysym-names</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ keysym-names keysym =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+This function returns the list of all names for keysym. If keysym is
+undefined, this returns nil.
+ </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_keysym-preferred-name">
+ <indexterm zone=3D"f_keysym-preferred-name">
+ <primary>keysym-preferred-name</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>keysym-preferred-name</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ keysym-preferred-name keysym =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+This returns the preferred name for keysym, how it is typically
+printed. If keysym is undefined, this returns nil.
+ </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_define-key-event-modifier">
+ <indexterm zone=3D"f_define-key-event-modifier">
+ <primary>define-key-event-modifier</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>define-key-event-modifier</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ define-key-event-modifier long-name short-na=
me =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+This establishes long-name and short-name as modifier names for
+purposes of specifying key-events in #k syntax. The names are
+case-insensitive strings. If either name is already defined,
+this signals an error.
+ </para>
+ <para>
+The system defines the following default modifiers (first the long
+name, then the short name):
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+"Hyper", "H"
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+"Super", "S"
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+"Meta", "M"
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+"Control", "C"
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+"Shift", "Shift"
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+"Lock", "Lock"
+ </para>
+ </listitem>
+ </itemizedlist>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"v_all-modifier-names">
+ <indexterm zone=3D"v_all-modifier-names">
+ <primary>*all-modifier-names*</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>*all-modifier-names*</refname>
+ <refpurpose></refpurpose>
+ <refclass>Variable</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ *all-modifier-names* =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+This variable holds all the defined modifier names.
+ </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_make-key-event-bits">
+ <indexterm zone=3D"f_make-key-event-bits">
+ <primary>make-key-event-bits</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>make-key-event-bits</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ make-key-event-bits &rest; modifier-names =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+This function returns bits suitable for make-key-event from the
+supplied modifier-names. If any name is undefined, this signals an
+error.
+ </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_key-event-modifier-mask">
+ <indexterm zone=3D"f_key-event-modifier-mask">
+ <primary>key-event-modifier-mask</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>key-event-modifier-mask</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ key-event-modifier-mask modifier-name =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+This function returns a mask for modifier-name. This mask is suitable
+for use with key-event-bits. If modifier-name is undefined, this
+signals an error.
+ </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_key-event-bits-modifiers">
+ <indexterm zone=3D"f_key-event-bits-modifiers">
+ <primary>key-event-bits-modifiers</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>key-event-bits-modifiers</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ key-event-bits-modifiers bits =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+This returns a list of key-event modifier names, one for each modifier
+set in bits.
+ </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_make-key-event">
+ <indexterm zone=3D"f_make-key-event">
+ <primary>make-key-event</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>make-key-event</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ make-key-event object bits =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+This function returns a key-event described by object with
+bits. Object is one of keysym, string, or key-event. When object is a
+key-event, this uses key-event-keysym. You can form bits with
+make-key-event-bits or key-event-modifier-mask.
+ </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_key-event-p">
+ <indexterm zone=3D"f_key-event-p">
+ <primary>key-event-p</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>key-event-p</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ key-event-p object =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+This function returns whether object is a key-event.
+ </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_key-event-bits">
+ <indexterm zone=3D"f_key-event-bits">
+ <primary>key-event-bits</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>key-event-bits</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ key-event-bits key-event =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+This function returns the bits field of a key-event.
+ </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_key-event-keysym">
+ <indexterm zone=3D"f_key-event-keysym">
+ <primary>key-event-keysym</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>key-event-keysym</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ key-event-keysym key-event =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+This function returns the keysym field of a key-event.
+ </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_char-key-event">
+ <indexterm zone=3D"f_char-key-event">
+ <primary>char-key-event</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>char-key-event</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ char-key-event character =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+This function returns the key-event associated with character. You can
+associate a key-event with a character by setf-ing this form.
+ </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_key-event-char">
+ <indexterm zone=3D"f_key-event-char">
+ <primary>key-event-char</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>key-event-char</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ key-event-char key-event =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+This function returns the character associated with key-event. You can
+associate a character with a key-event by setf'ing this form. The
+system defaultly translates key-events in some implementation
+dependent way for text insertion; for example, under an ASCII system,
+the key-event #k"C-h", as well as #k"backspace" would map to the
+Common Lisp character that causes a backspace.
+ </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_key-event-bit-p">
+ <indexterm zone=3D"f_key-event-bit-p">
+ <primary>key-event-bit-p</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>key-event-bit-p</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ key-event-bit-p key-event bit-name =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+This function returns whether key-event has the bit set named by
+bit-name. This signals an error if bit-name is undefined.
+ </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"m_do-alpha-key-events">
+ <indexterm zone=3D"m_do-alpha-key-events">
+ <primary>do-alpha-key-events</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>do-alpha-key-events</refname>
+ <refpurpose></refpurpose>
+ <refclass>Macro</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ do-alpha-key-events (var kind &optional; res=
ult) form =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+This macro evaluates each form with var bound to a key-event
+representing an alphabetic character. Kind is one of :lower, :upper,
+or :both, and this binds var to each key-event in order a-z A-Z.
+When :both is specified, this processes lowercase letters
+first.
+ </para>
+ </refsect1>
+ </refentry>
+ <refentry id=3D"f_pretty-key-string">
+ <indexterm zone=3D"f_pretty-key-string">
+ <primary>pretty-key-string</primary>
+ </indexterm>
+ <refnamediv>
+ <refname>pretty-key-string</refname>
+ <refpurpose></refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+ pretty-key-string key &optional; stream long=
-names-p =
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+This returns a string representing key, a key-event or vector of key-event=
s, in a
+user-expected fashion. Long-names-p indicates whether
+modifiers should be described by their long or short name.
+ </para>
+ </refsect1>
+ </refentry>
+ </sect3>
+ </sect2>
+ </sect1>
+</chapter>
More information about the Openmcl-cvs-notifications
mailing list