Emacs Library Reference

ABBREV, Extended Abbreviation Support

The ABBREV library provides useful functions that allow you to manipulate abbreviations. To access these functions, you must load ABBREV using ESC-x execute-mlisp-file.

The functions defined in the ABBREV library and their key bindings are as follows:

^X-G (define-global-abbrev-in-buffer)

Takes the word to the left of dot and defines it as a global abbreviation. You are prompted for the expansion in the Mini-buffer.

^X-L (define-local-abbrev-in-buffer)

Takes the word to the left of dot and defines it as an abbreviation in the current buffer's local abbreviation table. You are prompted for the abbreviation's expansion in the Mini-buffer.

(list-local-abbrevs)

Displays a buffer called Abbrev list and fills it with the abbreviations and their expansions in effect for the current buffer.

^X-W (edit-local-abbrevs)

Displays a buffer called Abbrev list, fills it with the abbreviations and their expansions in effect for the current buffer and then enters a recursive edit so that you can edit these definitions. When the recursive edit is exited, the buffer is used to define the new abbreviations.

(list-all-abbrevs)

Displays a buffer called Abbrev list and fills it with the abbreviations and expansions currently defined in Emacs.

(edit-all-abbrevs)

Displays a buffer called Abbrev list, fills it with all the abbreviations defined in the current Emacs, and then enters a recursive edit to let you alter these abbreviations. When you exit the recursive edit, the modified buffer contents are used to define the abbreviations.

^X-R (define-global-abbrev-for-region)

Uses the region as an expansion and prompts you for an abbreviation. The abbreviation is defined in the global abbreviation table.

^X-S (define-local-abbrev-for-region)

Uses the region as an expansion and prompts you for an abbreviation. The abbreviation is defined in the current buffer's local abbreviation table.

The AREA package defines two functions that allow you to define a box and then remove the text from that box leaving the text not included in the box undisturbed. The removed text is stored in a buffer called Area. This text may be inserted later at some other location.

The AREA functions and key bindings are:

ESC-w (delete-area)

Deletes a vertically-bounded area, storing the deleted area in a buffer named Area.

ESC-y (insert-area)

Inserts the contents of the Area buffer into the current buffer at dot.

The AREA library has been superceded by the RECTANGULAR library, but it is still supplied with Emacs for compatibility with existing MLisp code. For details on the RECTANGULAR library, see RECTANGULAR, Rectangular Cut and Paste

BUFF, One Line Buffer Listing

This library defines the single function one-line-buffer-list. This function displays the names of all of the buffers in Emacs in the mode line. If more that one line's worth of buffers exist, each line of names is displayed and a character input to display the next line. The default binding for the one-line-buffer-list function is ^X-^B.

Some buffers in the list may be preceded by a single character. The various characters and their meanings are:

* Indicates that the buffer has been modified since it was last written to disk
# Indicates that the buffer is a scratch buffer.
@ Indicates that the buffer is empty.

CENTERLIN, Line Centering

The CENTERLIN library package defines the single function center-line which can be used to centre the current line between the margins as defined by left-margin and right-margin.

There is no default binding for the center-line function.

DABBREV, Dynamic Abbreviation Expansion

The DABBREV library defines the dabbrev function. The dabbrev function takes the word that the cursor is positioned in and looks through the buffer for a word for which the current word is a prefix. If a match is found, the current word is expanded into the full word.

For example, if you have already typed the word FOOBAR into the buffer, you can then type the subword FOO, then execute the dabbrev function and FOO will be expanded to FOOBAR.

dabbrev-expand-whole-word 0

This variable changes the way dabbrev works when you start dabbrev in the middle of a word. Either dabbrev uses the whole of the word as the prefix to expand or dabbrev uses the beginning of the word and deletes the end of the word.

^W (dabbrev)

dabbrev.

DENT, Region Indentation

The DENT library defines the functions indent-region and undent-region. indent-region indents the currently selected region by logical-tab-size characters. If provided with a prefix argument, it performs the indentation the specified numbers of times. undent-region undents the current region.

EDTSIM, EDT Simulation

The EDTSIM package defines functions which emulate the EDT text editor found on the OpenVMS operating system from Digital Equipment Corporation.

When you load the EDTSIM library (using ESC-x execute-mlisp-file edtsim), the numeric keypad keys are re-bound to perform the same actions as they would in the real EDT editor. The major mode string in the mode line is modified to indicate that EDT simulation is loaded.

The following list contains all of the implemented EDT commands with a simple description of what each command does.

Introduce a command repetition count. GOLD-digits
The GOLD key. PF1
Give help and also, when a command is requested, cause Emacs name completion. The help text is obtained from the EDT help library, and re-formatted so that it can be displayed from within Emacs. PF2 (HELP)
Find the next occurrence of the current search string. PF3 (FNDNXT)
Delete to the end of the current line and delete the line terminator. PF4 (DEL-L)
Move to the next line in the current direction. KP0 (LINE)
Move to the next word in the current direction. KP1 (WORD)
Move to the end of the current line. KP2 (EOL)
Moves to the next character in the current direction. KP3 (CHAR)
Change the current direction to forwards. This key may also to used to terminate a search string. KP4 (ADVANCE)
Change the current direction to backwards. This key may also be used to terminate a search string. KP5 (BACKUP)
Cut the select region and put it in the paste buffer. KP6 (CUT)
Move to the next page in the current direction. KP7 (PAGE)
Scroll the window by two thirds and moves dot to the selected line. KP8 (SECT)
Set the start of the select region to the current cursor position. KP. (SELECT)
Delete the character following the current cursor position. KP, (DEL-C)
Delete the word following the current cursor position. KP-- (DEL-W)
Insert a line terminator after the current cursor position. GOLD-KP0 (OPEN LINE)
Invert the case of the current character or select region. GOLD-KP1 (CHGCASE)
Delete the text from dot to the end of the current line. GOLD-KP2 (DEL-EOL)
Insert a character into the buffer. The character inserted has the numeric value specified by the command's prefix argument. GOLD-KP3 (SPECINS)
Move the current cursor position to the bottom of the current buffer. GOLD-KP4 (BOTTOM)
Move the current cursor position to the top of the current buffer. GOLD-KP5 (TOP)
Insert the contents of the paste buffer at the current cursor position. GOLD-KP6 (PASTE)
Go to the Emacs command line. GOLD-KP7 (CMD)
Replace a string throughout the rest of the buffer. GOLD-KP9 (REPLACE)
Unset the start of the select region. GOLD-KP. (RESET)
Paste in the last character deleted. GOLD-KP, (UND-C)
Paste in the last word deleted. GOLD-KP- (UND-W)
Search for an occurrence of a string. GOLD-PF3 (FIND)
Paste in the last line deleted. GOLD-PF4 (UND-L)
Move the cursor up one line. Up-arrow (UP)
Move the cursor down one line. Down-arrow (DOWN)
Move the cursor left one character. left-arrow (left)
Move the cursor right one character. Right-arrow (RIGHT)

ELECTRICC, A Mode for Writing C Programs

The ELECTRICC library defines functions for Electric C Mode, a major mode for writing C programs. Electric C Mode is an alternative library to the C Mode library described in the Barry's Emacs Programmer's Guide.

Electric C Mode performs a number of useful functions for the C programmer, including:

FLASHER, Parenthesis Balancing

The FLASHER library defines the single function paren-flashwhich can be used to cause parenthesis balancing The function paren-flash should be bound to the closing version of the brackets that are to be balanced.

Two buffer-specific variables are used to provide input parameters to the functions:

paren-flash-wait

A numeric variable used to control the maximum length of time the cursor stays over a matching parenthesis. The value is specified in tenths of a second. The default value is 10 (1 second).

paren-flash-message

A boolean variable used to control the displaying of the error message when no matching bracket is found. If true, an error message is displayed; otherwise, the fact that the bracket is non-matching is ignored.

GLOBDEL, Global Deletion Of Lines

The GLOBDEL library provides the facility to nominate a set of lines by a search string, and then delete all the nominated lines. The library defines two functions:

(global-delete-lines)

Prompts for an ordinary search string, and deletes all lines containing that string.

(re-global-delete-lines)

Prompts for a regular expression search string, and deletes all lines containing the regular expression.

Both functions indicate the total number of lines deleted.

GOTO, Goto Line/Page/Percent

The GOTO library defines functions that move dot directly to a specified line, page, or percentage of the current buffer. The functions defined are:

(goto-line)

Moves dot to the beginning of the specified line. If a prefix argument is provided, use that as the line number to find. The first line in the buffer is line number 1.

(adjust-line-number)

Makes the current line line number 1 so that goto-line starts counting from the current line rather than the beginning of the file.

(goto-page)

Moves dot to the beginning of the specified page. If a prefix argument is provided, use that as the page number to find.

(goto-percent)

Moves dot to the percentage position of the file indicated. If a prefix argument is provided, use that as the percentage position to find. The beginning of the file is percentage position 0. The end of the file is percentage position 100.

HTMLMODE, HTML mode

The HTMLMODE library defines the HTML editing mode, HTML-mode.

HTML-mode provides syntax colouring for HTML code. HTML version 3.2 is fully supported, however not all of HTML 4.0 is syntax coloured.

ESC-c (HTML-view-buffer)

Save the HTML document and then view the HTML document using the default Web browser.

(HTML-mode)

Start HTML-mode for the current buffer.

INCSEARCH, Incremental Searching

When you execute the normal Emacs search commands, you are prompted for the search string in the Mini-buffer. You type in the entire search string, press Return, and Emacs searches for the specified string. The INCSEARCH library defines functions which implement a different style of searching called incremental searching.

Incremental searches begin searching before you have finished typing the search string. As you type in the search string, Emacs moves the cursor to where the string would be found. When you have typed enough characters to identify the place you want, you can stop. Depending on what you will do next, you may or may not need to terminate the search explicitly with an RETURN.

Incremental searching is enabled by loading the INCSEARCH package. This package replaces the existing search commands with the following commands:

^F (incremental-search)

Performs a forwards incremental search.

^R (reverse-incremental-search)

Performs a reverse incremental search.

inc-search-use-region 0

Set variable inc-search-use-region to 1 to prevent incremental search from using the hilighted text as the default search string.

The ^F command initiates a forwards incremental search. It reads in characters and positions the cursor at the first occurrence of the characters that you have typed. If you type ^F-F, the cursor moves right after the first F. Type an O, and the cursor moves to the first FO. After another O, the cursor is moved to the first occurrence of FOO. At the same time, the text FOO is echoed at the bottom of the screen.

If you type a incorrect character, you can rub it out. After the FOO, typing a Delete makes the last O disappear from the bottom of the screen, leaving only FO. The cursor moves back to the first occurrence of FO. If you delete the next O and the F, the cursor moves back to where you started the search.

When you are satisfied with the place you have reached, you can type a RETURN, which stops the search, leaving the cursor where the search brought it. Also, any command not meaningful in incremental searches stops the searching and is then executed. Thus, typing HOME would exit the search and then move to the beginning of the line. RETURN is necessary only if the next command you want to type is a printing character, Delete, RETURN, ^Q, or another search command, since those are the characters that have special meanings inside the search.

Sometimes you may search for FOO and find it, but not the one you expected to find. Type another ^F and the cursor will find the next FOO. This can be done any number of times. If you overshoot, you can rub out the unwanted ^F commands and the cursor will move back to the previous occurrences of the string.

If your string is not found at all, the message Failing I-Search is displayed in the Mini-buffer. The cursor is placed where Emacs found as much of your string as was possible. For example, if you search for FOOT, and there is no FOOT, you might see the cursor after the FOO (if the text FOO exists). At this point there are several things you can do. If your string was mis-typed, you can rub some of it out and correct it. If you like the place you have found, you can type a RETURN or some other Emacs command to accept what the search found.

The ^R command starts a reverse incremental search. This works in exactly the same way as the forward incremental search command, but in the opposite direction.

If you highlighted some text in the buffer and then start incremental search the text is used as the default string to search for.

For example hightlight FOO in the buffer, type ^F to start incremental search. Notice that the prompt is now "forward I-search [FOO]: " showing that FOO is the default string to search for. Type ^F again to find the next FOO.

While incremental search is active the default key bindings are:

Incremental search key bindings
Binding Function Binding Function
^F Search forward ^R search reverse
^G Abort search and go back to where we started Return Exits incremental search here
^P prompt you for a string to replace what the search has matched so far ^Q Quote next character, allows you to search for special characters.
^V Paste the clipboard contents into the search string. ^L enter a recursive edit level. Continue searching on exiting the recursive edit
F1 Display incremental search help. ^_ Display incremental search help.

KILLER, A Kill Ring System

The KILLER library provides the ability to keep a history of killed objects, and to define a killed object as any combination of successive kill commands. The killed objects are stored in a kill ring and can be retrieved at any time.

The KILLER text deletion functions replace the normal Emacs text deletion commands with versions that delete text and store it in the appropiate place in the kill ring. The kill ring functions and default key bindings are:

ESC-. (kr-set-mark)

Sets the mark with reverse-video highlighting enabled.

^X-. (kr-toggle-highlight)

Toggles the highlight setting.

ESC-d (kr-kill-forward-word)

Deletes the next word and inserts it into the kill ring.

ESC-Delete (kr-kill-bacward-word)

Deletes the previous word and inserts it in the kill ring.

^W (kr-kill-region)

Deletes the region and inserts it into the kill ring.

^K (kr-kill-forward-line)

Deletes the current line from dot to the end-of-line and inserts the deleted text into the kill ring.

ESC-k (kr-kill-backward-line)

Deletes the current line from dot to the beginning of the line and inserts the deleted text into the kill ring.

^Y (kr-yank)

Yanks the text from the current buffer in the kill ring, placing the yanked text into the current buffer at dot and leaving the region around the yanked text.

ESC-y (kr-more-yank)

If the text yanked by ^Y. is not the text you want, use ESC-y to yank text from other buffers in the kill ring. Successive ESC-ys will yank text from successive buffers in the kill ring. ESC-y only works after ^Y.

You can change these bindings by making a copy of the KILLER.KEY file, modifying it with your own bindings, and saving the modified file in your EMACS_PATH. kr-max-buf

The default size of the kill ring is 10 buffers. The size of the kill ring is controlled by the kr-max-buf variable which is defined in KILLER.KEY. If you want to change the size of the kill ring, make a private copy of the KILLER.KEY file as described above and change the setting of the kr-max-buf variable.

LATEXMODE, A Major Mode for writing LaTeX Documents

The LATEXMODE library implements the LaTeX Mode major mode which can be used to help write documents with the LaTeX document preparation system.

LaTeX Mode works in the same way as the standard Emacs language modes C Mode and Bliss Mode by providing expansion of templates for LaTeXreserved words. LaTeX Mode also defines comment handling and parenthesis balancing.

See the Barry's Emacs Programmer's Guide for details of how to use the Emacs language modes.

MAKEBOX, Drawing Boxes Around Text

The MAKEBOX library can be used to draw rectangular boxes around text. It relies on functions defined in the RECTANGULAR library, so you must first load the RECTANGULAR library before loading MAKEBOX. See RECTANGULAR, Rectangular Cut and Paste for a description of the RECTANGULAR library.

The library defines the make-box function. To draw a box around text with make-box:

· Select one corner of the box using rectangular-select (which is bound to GOLD-Select by default).

· Move to the diagonally opposite corner of the box.

· Execute the make-box function.

By default, make-box will use the +, -- and | characters to draw boxes. You can override these default values by setting the following variables:

makebox-h-symbol

Contains the character that make-box uses to draw horizontal lines.

makebox-v-symbol

Contains the character that make-box uses to draw vertical lines.

makebox-corners

Contains the character that make-box uses to draw corners.

The following example shows how to define your own drawing variables. Note that the MAKEBOX library must be loaded before setting the values of the drawing variables.

(execute-mlisp-file "makebox")

(setq makebox-h-symbol "=")

(setq makebox-v-symbol "!")

(setq makebox-corners "#")

The following convenience functions are defined to set the drawing variables:

makebox-use-lines

Sets the make-box drawing variables to the default line-drawing set.

makebox-use-stars

Sets all the make-box drawing variables to *.

MINIBUF, Writing and Executing Small MLisp Programs

The MINIBUF library provides a better interface for the execution simple MLisp programs than the execute-mlisp-line function. When loaded, MINIBUF rebinds ESC-ESC so that instead of collecting its arguments in the Mini-buffer at the bottom of the screen, it pops up a small buffer called minibuffer to collect the MLisp code. Lisp Mode is in effect in this buffer so that MLisp name expansion can be used.

When you are satisfied that the MLisp in the minibuffer is correct, you can execute it with the command ESC-ESC. Subsequent uses of ESC-ESC will re-display the minibuffer containing the last program executed; you can re-execute the same code with ESC-ESC, or you can edit the code first before executing it with ESC-ESC.

MINIBUF-RECALL, Command Recall in the Mini-buffer

The MINIBUF-RECALL library provides the ability to recall and edit commands in the Mini-buffer. The library remembers the last 60 commands executed. The following keys can be used to edit and recall commands when MINIBUF-RECALL has been loaded:

up-arrow or esc-r

Recalls the previous command in the command history.

down-arrow or esc-v

Recalls the next command in the command history.

left-arrow

Moves the cursor one character left in the Mini-buffer.

right-arrow

Moves the cursor one character right in the Mini-buffer.

pgup and pgdn

Pop up a buffer that allows you to select a line to recall from a list

f1

Pops up a Help window and lists the available options.

f11

Executes a command with completion.

^g

Aborts the Mini-buffer command.

MOUSE, Mouse Support

The MOUSE library defines functions that support the use of a mouse with Barry's Emacs.

You can use the MOUSE library to:

· Select windows

· Position the cursor

· Cut and paste regions of text

· Change window sizes

· Scroll a window up or down

· Scroll a window left or right

· Execute the keyboard macro at a specific position

In addition, you can customise the MOUSE library to perform specialised mouse actions for buffers, and you can build mouse support into your own MLisp code.

Using the MOUSE Library

Enabling and Disabling Mouse Support

To use the MOUSE library functions, add the following MLisp code to your EMACSINIT.ML:

(load "mouse")

(mouse-mode) mouse-on

With the MOUSE library loaded, you can turn on mouse support with the mouse-on function. mouse-on takes one argument which is a number describing the required mouse cursor. A value of 0 (the default) specifies the default mouse cursor. A value of 1 specifies a cross-hair cursor (the cross-hair cursor is supported only on VWS workstations).

When Emacs mouse handling is enabled, you do not have access to the workstation cut and paste features. To use workstation cut and paste with Emacs, you must disable Emacs mouse handling using the mouse-off function. When you want to use Emacs mouse handling again, re-execute the mouse-on function.

The easiest way to have mouse support enabled whenever you enter Emacs is to execute mouse-on from the enter-emacs-hook and return-to-emacs-hook functions. You should always disable Emacs mouse support when you leave Emacs and return to DCL. The easiest way to do this is to execute mouse-off from the leave-emacs-hook and exit-emacs-hook functions. The example shows how you can define the hook functions in your EMACSINIT.ML to enable and disable mouse support:

Example: Enabling and Disabling Emacs Mouse Support

;
; Set up Emacs hook functions to enable/disable
; mouse support.
;
(defun
    (my-return-to-emacs-actions
  (mouse-on 0) ; Turn on Emacs mouse support
  ;
  ; Other code to be executed on returning
  ; to Emacs
  ;
    )
)       ; defun - my-return-to-emacs-actions

(defun
    (my-leave-emacs-actions
  (mouse-off) ; Turn off Emacs mouse support
  ;
  ; Other code to be executed on leaving Emacs
  ;
    )
)       ; defun - my-leave-emacs-actions

(setq enter-emacs-hook "my-enter-emacs-actions")
(setq return-to-emacs-hook "my-enter-emacs-actions")
(setq exit-emacs-hook "my-leave-emacs-actions")
(setq leave-emacs-hook "my-leave-emacs-actions")

The MLisp code in the example shows how to toggle the Emacs mouse on and off simply by pressing the F14 key. This provides easy access to the workstation cut and paste facilities from within Emacs.

Example: TOGGLEMOUSE --- Toggling the Emacs Mouse

(declare-global ~togglemouse)
(setq ~togglemouse 0)
(defun
    (togglemouse
  (setq ~togglemouse
      (if ~togglemouse
    (progn
        ;
        ; Mouse was off, turn it on
        ;
        (mouse-on 0)
        (message "Emacs mouse enabled")
      (! ~togglemouse)
        )
        ; else
        (progn
      ;
      ; Mouse was on, turn it off
      ;
      (mouse-off)
      (message "Emacs mouse disabled")
          (! ~togglemouse)
      )
        )
    )
      )     ; if
  )
    )
)       ; defun - togglemouse
(bind-to-key "togglemouse" "f14)")

Using Mouse Features

The following list describes how to use the various features provided by the Emacs mouse support. In the descriptions of each feature, MB1refers to mouse button 1, MB2 refers to mouse button 2, and MB3 refers to mouse button 3.

position cursor

Move the pointer to the position you wish to locate the cursor and click MB1. In overstrike mode, spaces (but not newlines) are inserted when needed to reach the selected position. In insert mode, no spaces are inserted, the cursor is placed at the end of the selected line.

select window

Move the pointer to the mode line of the window you wish to select, and click MB1.

scroll window, vertical

Grab part of the text by pointing to it with the pointer and pressing MB1. Move the mouse up or down to the position you would like the grabbed line to appear, then release MB1. The text is scrolled by a corresponding distance.

scroll window, horizontal

Grab part of the mode line with MB1 and move the mouse left or right. Release with the pointer still on the mode line. The window will be panned to the left or right a corresponding distance.

change window size

To make a window taller, shorter, narrower, or wider, grab the window's mode line, a vertical window border, or their intersection point, with MB1. Move the pointer to the new location of the mode line or border, and release MB1. Windows are deleted, if needed, to make room for the new window size.

execute keyboard macro

A double-click of MB1 positions the cursor at the selected location, and then executes the current keyboard macro at that location.

copy region to kill buffer

A click of MB2 copies the text from the current location of dot to the selected position into the Kill buffer. The cursor position remains as selected with the mouse. Moving the mouse between the press and release of MB2 will perform the same scroll/pan/resize functions as with MB1.

kill region to kill buffer

A double-click of MB2 kills the text from the current location of dot to the selected position into the Kill buffer.

yank region from kill buffer

A double-click of MB3 yanks the Kill buffer into the selected position. If you click on the mode line, the yank is performed at the current location of dot in the selected window. A single click of MB3 performs the same functions as MB1. Moving the mouse between the press and release of MB3 performs the same scroll/pan/resize functions as MB1.

NOTE: The following features work only with the VWS terminal emulator, not with the DECwindows DECterm emulator.

copy region to local paste buffer

The keystroke ^X-c copies the current select region into the terminal-wide cross-session paste buffer. The sequence ^X-MB2 copies the text from the current location of dot to the position selected into the cross-session paste buffer.

yank from local paste buffer

The keystroke ^X-^C yanks the current contents of the terminal-wide cross-session paste buffer into the current buffer. The sequence ^X-MB3 pastes the paste buffer into the selected position.

Customising the MOUSE Library

Customising Mouse Cut and Paste

By default, MOUSE uses the standard Kill buffer handling routines for performing cut and paste operations. If you are using a modified version of cut and paste, or some kind of kill ring library, you can communicate this to the mouse library by setting the favorite-... series of global variables defined by the MOUSE library. These are:

favorite-set-mark

A string variable containing the name of the function the MOUSE library should use to set the mark. This is set-mark by default.

favorite-kill-region

A string variable containing the name of the function the MOUSE library should use to kill the region to the Kill buffer. This is delete-to-killbuffer by default.

favorite-copy-region

A string variable containing the name of the function the MOUSE library should use to copy the region to the Kill buffer. This is copy-to-killbuffer by default (a function defined by the MOUSE library).

favorite-yank

A string variable containing the name of the function the MOUSE library should use to yank the contents of the Kill buffer into the current buffer. This is yank-from-killbuffer by default. KILLER, With the MOUSE library

The example shows how to set these variables so that the KILLER cut and paste routines can be used with the MOUSE library. KILLER is described in KILLER, A Kill Ring System.

Example: Using KILLER with the MOUSE Package

;
; Use the KILLER cut and paste functions
; with the MOUSE library.
;
(setq favorite-set-mark "kr-set-mark")
(setq favorite-copy-region "kr-copy-region")
(setq favorite-kill-region "kr-kill-region")
(setq favorite-yank "kr-yank")

When you use the mouse to scroll or pan windows, the default behaviour is for the scroll or pan to occur when the mouse button is released. If you set the variable mouse-continuous to 1, the scroll and pan functions will continuously update the display to reflect the position of the mouse pointer. Add the following MLisp line to your EMACSINIT.ML to use continuous scrolling:

(setq mouse-continuous 1)

Note that you need a fast communications line or a fast Xwindows environment to use continuous scrolling.

Mlisp Programming with the Mouse

To write MLisp code with a mouse interface, you must write a mouse action function in MLisp, then bind the function to a mouse button sequence. Pressing that mouse button sequence will then invoke the mouse action function.

The general scheme for a mouse action function is as follows:

See the template mouse action function that illustrates how to program both for single and double mouse clicks. When written in this way, your local mouse action functions retain the pan and scroll features of the default mouse actions.

Example: Template Mouse Action Function

(defun
    (my-local-mouse-action
  mousex
  mousey
  mouseevent
  mouse-second-click
  ;
  ; Fetch the mouse parameters and position the cursor.
  ;
  (mouse-parameters)
  (mouse-reposition mousex mousey mouseevent)
  ;
  ; At this point, the cursor has been positioned at a
  ; location specified by the mouse cursor.
  ;
  (if mouse-second-click _ ; Check for double-click
      (progn
    ;
    ; If action is desired only on the second click,
    ; place it here.
    ; Note that the action of the double click must be a
    ; logical superset of the action of the single click
    ; (the single click code is always executed if it
    ; exists).
    ;
      )
      (progn ; else
    ;
    ; If action is desired on the first click, place it
    ; here, otherwise leave out the else clause.
    ;
      )
  )     ; if
    )
)       ; defun - my-local-mouse-action

(local-bind-to-key "my-local-mouse-action" "mouse-1-down)")

You can bind your own local mouse action functions to any of the mouse button escapes listed in the table.

mouse-1-down mouse-1-up
mouse-2-down mouse-2-up
mouse-3-down mouse-3-up

Note that it is possible to include Escape or function key prefixes in mouse button bindings. For example, the following bindings are all legal:

(local-bind-to-key "my-local-mouse-action" "\[mouse-1-down])")
(local-bind-to-key "my-local-mouse-action" "\^c\[mouse-1-down])")

The example contains a complete mouse programming example. The example is intended for use with the Emacs Notes package, and binds several useful actions to MB3. For example, clicking MB3 on a conference name in a conference directory will open the conference, and clicking MB3 on a note in a note directory will read the selected note.

Example: Example Mouse Bindings for the Notes Package

;
; Mouse bindings for the Notes package.
;
; When pressing MB3, do the most appropriate thing
; depending on which buffer is selected.
;
(defun
    (my-notes-action
        mousex
        mousey
        mouseevent
        mouse-second-click
        ;
        ; Get the mouse parameters and position the cursor at the
        ; selected position.
        ;
        (mouse-parameters)
        (mouse-reposition mousex mousey mouseevent)
        ;
        ; Depending on which buffer was selected with the mouse,
        ; perform the most appropriate action.
        ;
        (if
            (= current-buffer-name notes-notebook-entry-directory)
            (notes-c-open)
            (= current-buffer-name notes-notebook-class-directory)
            (notes-c-set-class)
            (= current-buffer-name notes-notefile-directory)
            (notes-c-read-note)
            (= current-buffer-name notes-notefile-header)
            (notes-c-close)
            (= current-buffer-name notes-notebook-header)
            (notes-c-exit)
            (notes-c-enter-key)
        )
    )
)

(local-bind-to-key "my-notes-action" "mouse-3-up)")
(local-bind-to-key "novalue" "mouse-3-down)")

MOUSE-RECTANGULAR, Mouse Interface to the RECTANGULAR Library

The MOUSE-RECTANGULAR library provides a workstation mouse interface to the rectangular cut and paste routines defined in the RECTANGULAR library. You must load the RECTANGULAR library before loading the MOUSE-RECTANGULAR library. The RECTANGULAR library is described in RECTANGULAR, Rectangular Cut and Paste.

The MOUSE-RECTANGULAR mouse button bindings are:

esc-mouse button 1

Rectangular copy between text cursor and mouse pointer position.

esc-mouse button 2

Rectangular cut between text cursor and mouse pointer position.

esc-mouse button 3

Rectangular paste at mouse pointer location.

If Replace Mode is active, the Replace Mode versions of the rectangular cut and paste routines are used.

NEWCOMPIL, Compiling Programs

The NEWCOMPIL library provides a more convenient program compilation interface than the compile-it and next-errorfunctions built in to Emacs. After loading the NEWCOMPIL library, compile-it and next-error are modified so that while compilation is in progress, other work in Emacs can continue. The standard functions do not provide this capability. kill-compilation

An extra command is provided to cater for this extra flexibility: ^X-^K (kill-compilation), which aborts the currently active compilation.

NUMBER, Number Base Conversion

The NUMBER library defines functions to convert a number into hexadecimal, octal and decimal notation and display the result in the Mini-buffer.

The interface to the base conversion functions is the numberfunction. When executed, number prompts for a number to convert. The number can be one of the following forms:

dddddd Decimal
0ooooooo Octal
0xhhhhh Hexadecimal

The number function then returns the specified value in hexadecimal, octal and decimal formats in the Mini-buffer. For example, if the value 55 is entered, number returns:

Converted 55 to: 0x37 067 55

PYTHONMODE, Python mode

An editing mode for Python code. Python mode provide syntax colouring for Python code.

Python is a well designed, object oriented, simple to learn, scripting language. Python is available for Windows, Unix and Mac systems. The home of Python is www.python.org

(Python-mode)

Start Python mode on the current buffer

RECTANGULAR, Rectangular Cut and Paste

The RECTANGULAR library provides the ability to cut and paste rectangular areas of text bounded by any two opposite corners. The corners can be in the same row or column. RECTANGULAR handles Tab characters correctly and fixes problems in the AREA package. RECTANGULAR functions correctly in insert or replace mode.

To handle all possible options, there are two modes for cut and two modes for paste which are controlled by the following variables:

replace-with-white-space

Controls the action of the rectangular cut function. When this variable is set to 1, deleted text is replaced with white-space. When the variable is set to 0, text is deleted and is not replaced with white-space.

overstrike-mode

Controls the action of the rectangular paste function. When this variable is set to 1, text is pasted in overstrike (replace) mode. When the variable is set to 0, text is pasted in insert mode.

The rectangular cut and paste key bindings and commands are:

GOLD-Select (rectangular-select)

Selects one corner of the area to be cut.

Remove (rectangular-cut)

Cuts the selected area from the buffer with replace-with-white-space set to 0.

GOLD-Remove (rectangular-cut)

Cuts the selected area from the buffer with replace-with-white-space set to 1.

Insert Here (rectangular-paste)

Pastes the previously-cut text into the buffer at dot in insert mode (overstrike-mode set to 0).

GOLD-Insert Here (rectangular-paste)

Pastes the previously-cut text into the buffer at dot in replace mode (overstrike-mode set to 1).

The following convenience functions are also defined:

rect-cut-space

Performs a rectangular cut with replace-with-white-space set to 1.

rect-cut

Performs a rectangular cut with replace-with-white-space set to 0.

rect-paste

Performs a rectangular paste with overstrike-mode set to 0.

rect-paste-overstrike

Performs a rectangular paste with overstrike-mode set to 1.

To cut a rectangular area from the buffer, move the cursor to one corner of the area to be cut and press GOLD-Select. Then move to the opposite corner and press either Remove or GOLD-Remove. Tabs replaced by spaces in the cut area.

When you cut a rectangular area where one of the corners is a space character, the highlighted space may remain highlighted after the cut operation is completed. To remove the highlighting, type ^L(redraw-display) and Emacs will redraw the display with the highlighting removed.

To paste a previously cut area back into the buffer, move the cursor to the desired location and type either Insert Here or GOLD-Insert Here. White-space at the ends of lines affected by the rectangular paste will first be removed.

Here are some examples:

Remove --- removes the area and the text moves to to fill the hole:

aaaaaaaaabb aaaaaaaaabb

aaaaaaaaabb -------> aabb

aaaaaaaaabb aabb

aaaaaaaaabb aaaaaaaaabb

GOLD-Remove --- removes the area and leaves a hole:

aaaaaaaaabb aaaaaaaaabb

aaaaaaaaabb ------> aa bb

aaaaaaaaabb aa bb

aaaaaaaaabb aaaaaaaaabb

Insert Here --- inserts the area into the text in insert mode:

oooo aa$$$*** aaoooo$$$***

oooo aa$$$*** aaoooo$$$***

oooo + aa$$$*** -------> aaoooo$$$***

oooo oooo

oooo oooo

Text to Original

be inserted text

GOLD-Insert --- inserts the area in the text in replace mode:

oooo aa$$$*** aaoooo**

oooo aa$$$*** aaoooo**

oooo + aa$$$*** -------> aaoooo**

oooo oooo

oooo oooo

Text to Original

be inserted text

TAGS, An Indexing System

The TAGS library defines functions which remember the locations of function definitions in a file, and enable you to go directly to the definition of any function without having to search the whole file.

The TAGS package can be used to tag a set of files used to build a program as well as an individual file.

Any text file or set of files may be tagged, not just computer programs. All that is required is that some entity be used to initially create the tags.

The functions provided by the TAGS library are summarised here and are described in detail in the following sections.

(make-tag-table)

Makes a tag table for a specified set of files.

(set-tag-language)

Sets the tag language to a user-specified language. This is used when files being tagged are not known to the TAGS library.

(recompute-all-tags)

Updates all the tags in the tag table.

(visit-tag-table)

Tells Emacs which tag table file to use.

^X-^L (goto-tag)

Moves dot to the specified tag, visiting the appropriate file if necessary.

^X-^A (add-tag)

Adds a new tag to the current tag table.

(list-tags)

Lists all tags in the current tag table.

(tag-replace-string)

Replace a string in all files in the current tag table.

(tag-query-replace-string)

Perform a query-replace operation on all files in the tag table.

(tag-execute-mlisp)

Execute an MLisp expression over all files in the tag table.

How to Make a Tag Table for a Program

To use the TAGS package, you must create a tag table from the source file or files in your program. Normally, the tag table does not reside in any of these files, but in a separate tag table file which contains the names of the text files which it describes. Tag table files are generated using the ESC-x make-tag-table command. make-tag-table asks you to specify the names of the files you wish to tag (which may contain wildcards), then proceeds to read all the files matching that file specification into Emacs. It then uses a set of built-in rules to tag the lines according to the source language. TAGS selects the language based on the file's extension. TAGS has built-in rules for building tag tables for the following languages:

· MLisp

· C, C++

· Python

· BLISS, BLISS-16, BLISS-32

· RUNOFF

· MACRO-32

· FORTRAN. set-tag-language

If the language you wish to tag does not have built-in rules, you will have to teach TAGS how to recognise the lines to be tagged by using the ESC-x set-tag-language command. This command asks for a file type for the language and a regular expression search string to use to select lines to be tagged. Only one extra language can be specified; multiple calls of set-tag-language overwrite previous language specifications. recompute-all-tags

Once a tag table file exists, you must update it if you add new tags to the source files, or change the files extensively. You can do this by using the command ESC-x recompute-all-tags. TAGS finds the names and languages of the source files by reading the old tag table.

How to Tell Emacs You Want to Use TAGS

Before you can use the TAGS package, you have to load the library using the ESC-x execute-mlisp-file command. visit-tag-table

Before you can access a particular tag, you have to tell TAGS the name of the tag table file you want to use. This is done with the command ESC-x visit-tag-table. TAGS can only know about one tag table file at a time; executing a second ESC-x visit-tag-table command will overwrite any existing tag table (including any changes you may have made to it).

If no tag table has been specified and you attempt to find a tag, Emacs will read in the default tag table called SYS$DISK:[]TAGS.TAG.

visit-tag-table is essentially equivalent to selecting the buffer *TAGS* (which is where the tags live) and visiting the tag table file in that buffer, then returning to the previously selected buffer. After execution of visit-tag-table, ESC-x list-buffers will show the buffer *TAGS* visiting the tag table file.

Jumping to a Tag

To jump to the definition of a tagged item, use the command ^X-^L (goto-tag). You will go straight to the definition of the tag you want. If the definition is in a different file, TAGS will visit that file and locate the tag. If it is in the same file, TAGS moves dot to the appropriate place.

You do not need to type the complete name of the tag to be found; any substring will do. If you use this feature, you may not always find the tag you expected; when this happens, ^U-^X-^L will find the next definition matching the tag substring. For example, if you want to find the definition of X-SET-TYPE-1 and you specify just TYPE-1, you might find X-READ-TYPE-1 instead. You could then type ^U-^X-^L until you reach X-SET-TYPE-1.

Other Operations on Tag Tables

When you define a new function, its location does not go in the tag table automatically. This is because Emacs cannot tell that you have defined a function unless you tell it by invoking the command ^X-^A (add-tag).

When you type the command ^X-^A, dot should be on the line that introduces the function definition. Thus, in a Lisp program, you might type (defun (foo) and then type ^X-^A to define a tag for the foo function.

add-tag modifies only the copy of the tag table loaded into Emacs. To modify the tag table file itself, you must save the tag table to disk. ^X-^M (write-modified-files) is the easiest way to do this.

Although local modifications to a file do not degrade the efficiency of the TAGS package or require that the tag table be rebuilt, moving a function a great distance makes finding that function much slower. In this case, you can add the function to the tag table with ^X-^A to give the table its new location. Alternatively, you can run recompute-all-tags to update everything, as is usually done.

Visiting a Function

The command ESC-x visit-function can be used to temporarily view a function in another window. Type the function's name in the buffer, then execute visit-function. The function's name is extracted from the buffer and used as a tag to find. Before the tag is located, TAGS enters a recursive edit, so that when you have finished viewing the function, your original windows and buffers are re-displayed.

finding out what has been tagged

The function list-tags can be used to list the files and functions that have been tagged for any tag table. Just load the tag table and call the function. When you use make-tag-table, the list-tags function is automatically called so that you can see exactly what TAGS has tagged.

replacing strings in a tagged program

Two functions can be used to change all occurrences of a string in a set of files that have been tagged: tag-replace-string and tag-query-replace-string. Both of these functions require a regular expression search string and a replacement string as arguments, and apply the appropriate replace commands to all of the files tagged in the tag table.

applying mlisp to lines in a tagged program

A more flexible approach to multiple file editing is provided by the function tag-execute-mlisp. This function requires a regular expression search string which is used to find lines in all the files specified in the tag table. For all of the lines that match the pattern, the function sets dot to the found line, and executes a specified MLisp expression at that location.

What Constitutes a Tag?

The following list describes what defines an item to be tagged using the built-in tagging rules for the supported languages. Any of these definitions may be overriden using the set-tag-language command.

C matches file type .c, .cpp and .cxx and tags lines that start a C or C++ routine or #define symbol. C++, ANSI C and K&R C are correctly tagged.
MLisp matches file type .ml and tags lines that start with (defun where all white space is optional.
Python matches file type .py and .pyw and tags lines that start with def or class.
BLISS matches file type .BLI and tags all lines that start with optional white space and contain either ROUTINE or GLOBAL ROUTINE.
BLISS-16 matches file type .B16 and tags lines as BLISS does.
BLISS-32 matches file type .B32 and tags lines as BLISS does.
RUNOFF matches file type .RNO and tags lines that start with .CH, .HL or .AX.
FORTRAN matches file type .FOR and tags lines containing SUBROUTINE or FUNCTION.

Adding or Removing Source Files

A tag table file is a sequence of entries, one per file. Each entry looks like:

^-filename
^Adata line^Bchar pos

where:
filename is the file name and file type of the file for which the following lines are tag information.
data line contains the tag's line
char pos is the position of the start of the tagged line.

If you are changing a source file's name, you should simply change the name where it is presently described in the tag table.

To add a new source file, simply insert a dummy entry containing the filename and update the tag table. The dummy will then be turned into a real entry.

You can delete a source file from a tag table by deleting its entire entry. Since the counts of the remaining entries are still valid, you need not run recompute-all-tags over the file again. You can also change the order of the entries without doing any harm. The order of the entries matters if there are tags which appear in more than one source file.

TABS, Intelligent Tab Handling

The TABS library defines functions that insert and delete Tab characters in an intelligent way. The functions use the buffer-specific variable logical-tab-size to compute how much whitespace to insert or delete. The two functions defined are:

(tab-key)

Inserts enough tabs and spaces to move to the next tab stop as indicated by logical-tab-size.

(tab-delete)

Deletes enough tabs and spaces to move back to the previous tab stop as indicated by logical-tab-size.

TIME, A Running Time Display

The TIME library defines the time function. When executed, the time function puts a running digital time display of the form HH:MM:SS in the mode line of the current window.

When you move the cursor to a new window or visit a new file, the time display is added to the new mode line and is made active.

The time display is only active in the current window's mode line. If the time display is enabled in any other window, the time shown is the time that the cursor was moved out of that window.

WHEREIS, Where Is That Command?

The WHEREIS library defines the where-is function, which prompts for a function name and displays in the Mini-buffer the key binding (if any) to which the function is bound.

where-is cannot be called from an MLisp program.

WHITE-SPACE-MINI-MODE, check for white space problems

The WHITE-SPACE-MINI-MODE library adds the ability to highlight white spaces problems.

This library should be loaded before other language modes.

Which problems are checked for is controlled by the following variables:

Typically add the following to emacsinit.ml:

(load "white-space-mini-mode")
(setq check-for-white-space-problems 1)
(setq check-for-use-of-tabs-problems 1)

WRITEREG, Write Region to File

The WRITEREG library defines the single function write-region-to-file which prompts for a file name and writes the region to the specified file.