Clozure CL Documentation

6.6. Hemlock Variables

Hemlock implements a system of variables separate from normal Lisp variables for the following reasons:

Hemlock has different scoping rules which are useful in an editor. Hemlock variables can be local to a buffer or a mode.
Hemlock variables have hooks, lists of functions called when someone sets the variable. See variable-value for the arguments Hemlock passes to these hook functions.
There is a database of variable names and documentation which makes it easier to find out what variables exist and what their values mean.

6.6.1. Variable Names

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.

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.

[Variable]


                        *global-variable-names*

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.

[Function]


                        current-variable-tables

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.

6.6.2. Variable Functions

In the following descriptions name is the symbol name of the variable.

[Function]


                        defhvar string-name documentation &key :mode :buffer :hooks :value

This function defines a Hemlock variable. Functions that take a variable name signal an error when the variable is undefined.

string-name--- The string name of the variable to define.

documentation--- The documentation string for the variable.

:mode, :buffer--- If buffer is supplied, the variable is local to that buffer. If mode is supplied, it is local to that mode. If neither is supplied, it is global.

:value--- This is the initial value for the variable, which defaults to nil.

:hooks--- This is the initial list of functions to call when someone sets the variable's value. These functions execute before Hemlock establishes the new value. See variable-value for the arguments passed to the hook functions.

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.

[Function]


                        variable-value name &optional kind where

This function returns the value of a Hemlock variable in some place. The following values for kind are defined:

:current--- Return the value present in the current environment, taking into consideration any mode or buffer local variables. This is the default.

:global--- Return the global value.

:mode--- Return the value in the mode named where.

:buffer--- Return the value in the buffer where.

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.

[Function]


                        variable-documentation name &optional kind where

[Function]


                        variable-hooks name &optional kind where

[Function]


                        variable-name name &optional kind where

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.

[Function]


                        string-to-variable string

This function converts a string into the corresponding variable symbol name. String need not be the name of an actual Hemlock variable.

[Macro]


                        value name

[Macro]


                        setv name new-value

These macros get and set the current value of the Hemlock variable name. Name is not evaluated. There is a setf form for value.

[Macro]


                        hlet ({(var value)}*){form}*

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.

[Function]


                        hemlock-bound-p name &optional kind where

Returns t if name is defined as a Hemlock variable in the place specified by kind and where, or nil otherwise.

[Function]


                        delete-variable name &optional kind where

[Hemlock Variable]


                        Delete Variable Hook

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

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.

6.6.3. Hooks

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.

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.

[Macro]


                        add-hook place hook-fun

[Macro]


                        remove-hook place hook-fun

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:


(add-hook delete-buffer-hook 'remove-buffer-from-menu)
(add-hook (variable-hooks 'check-mail-interval)
          'reschedule-mail-check)

[Macro]


                        invoke-hook place &rest args

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.