wiki:HemlockProgrammer/HemlockVariables

Version 2 (modified by rme, 7 years ago) (diff)

--

6. Hemlock Variables

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

  1. Hemlock has different scoping rules which are useful in an editor. Hemlock variables can be local to a buffer (page 9) or a mode (page 35).
  2. Hemlock variables have hooks (page 25), lists of functions called when someone sets the variable. See variable-value for the arguments Hemlock passes to these hook functions.
  3. 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.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 and referring to a symbol with the same name in the wrong package is an error.

*global-variable-names* [Variable]

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.

current-variable-tables [Function]

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.2. Variable Functions

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

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

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 tonil.
: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-valuefor 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.

variable-value name &optional kind where [Function]

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 anymode or buffer local variables. This is the default.
:global
Return the global value.
:mode
Return the value in the mode namedwhere.

: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.

variable-documentation name &optional kind where [Function]

variable-hooks name &optional kind where [Function]

variable-name name &optional kind where [Function]

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.

string-to-variable string [Function]

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

value name [Macro]

setv name new-value [Macro]

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

hlet ({(var value)}*){form}* [Macro]

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.

hemlock-bound-p name &optional kind where [Function]

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

delete-variable name &optional kind where [Function]

Delete Variable Hook [Hemlock Variable]

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.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.

add-hook place hook-fun [Macro]

remove-hook place hook-fun [Macro]

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)

invoke-hook place &restargs [Macro]

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.