---

4.4 Active Regions ¶

Every buffer has a mark stack (page mark-stack) 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.

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.

Once a marking command makes the region active, it remains active until:

• a command uses the region,
• a command modifies the buffer,
• a command changes the current window or buffer,
• a command signals an editor-error,
• or the user types C-g.

Hemlock Variable: Active Regions Enabled (initial value t) ¶

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.

Variable: *ephemerally-active-command-types* ¶

This is a list of command types (see section command-types), 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).

Function: activate-region ¶

This makes the current-region active.

Function: deactivate-region ¶

After invoking this the current-region is no longer active.

Function: region-active-p ¶

Returns whether the current-region is active, including ephemerally. This ignores Active Regions Enabled.

Function: check-region-active ¶

This signals an editor-error when active regions are enabled, and the current-region is not active.

Function: current-region &optional error-if-not-active deactivate-region ¶

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.