6.3.1 Calling editor functions

All editor commands and some other editor functions expect to be called within a dynamic context that includes settings for the current buffer and current window. This happens automatically when using the editor interactively.

You can set up the context in a CAPI application by using the function capi:call-editor (see the CAPI User Guide and Reference Manual ).

You can also use the following function to call editor commands and functions.

editor:process-character

Function

Processes char in a dynamic context where the current window is window and the current buffer is the buffer currently displayed in window.

The char can be one of the following:

A string, naming an editor command to invoke.

A list of the form (function . args), which causes function to be called with args. The items in args are not evaluated.

A function or symbol, which is called with nil as its argument (like a command function would be if there is no prefix argument).

A character or system:gesture-spec object, which is treated as if it has been typed on the keyboard.

There is no return value. The processing may happen in another thread, so may not have competed before this function returns.

6.3.2 Defining commands

editor:defcommand

Macro

Defines a new editor command. name is a usually string naming the new editor command which can invoked in the editor via Extended Command, and command-function is a symbol naming the new command function which can be called programmatically. The command-function symbol is interned in the current package.

lambda-list is the lambda list of the new command, which must have at least one argument which is usually denoted p, the prefix argument.

command-doc and function-doc should be strings giving detailed and brief descriptions of the new command respectively.

forms is the Lisp code for the command.

The name of the command must be a string, while the name of the associated command function must be a symbol. There are two ways in which name can be supplied. Most simply, name is given as a string, and the string is taken to be the name of the editor command. The symbol naming the command function is computed from that string: spaces are replaced with hyphens and alphabetic characters are uppercased, but otherwise the symbol name contains the same characters as the string with -COMMAND appended.

If a specific function name, different to the one defcommand derives itself, is required, then this can be supplied explicitly. To do this, name should be a list: its first element is the string used as the name of the command, while its second and last element is the symbol used to name the Lisp command function.

For example the following code defines an editor command, Move Five, which moves the cursor forward in an editor buffer by five characters.

(editor:defcommand "Move Five" (p)

   "Moves the current point forward five characters.

    Any prefix argument is ignored."      

   "Moves five characters forward."

   (editor:forward-character-command 5))

=>

MOVE-FIVE-COMMAND

The prefix argument p is not used, and is there simply because the lambda-list must have at least one element.

Use Meta+X Move Five to invoke the command.

As another example this command changes all the text in a writable buffer to be uppercase:

(editor:defcommand "Uppercase Buffer" (p) 

     "Uppercase the buffer contents" ""

  (declare (ignore p))

  (let* ((buffer (editor:current-buffer))

         (point (editor:buffer-point buffer))

         (start (editor:buffers-start buffer))

         (end (editor:buffers-end buffer)))

    (editor:set-current-mark start)

    (editor:move-point point end)

    (editor:uppercase-region-command nil)))

Having defined your new command, you can invoke it immediately by Meta+X Uppercase Buffer.

You could also call it programmatically:

If you anticipate frequent interactive use of Uppercase Buffer you will want to bind it to a key. You can do this interactively for the current session using Bind Key. Also you can put something like this in your initialization file to establish the key binding for each new session:

Then, entering Ctrl+X Meta+U will invoke the command.

Define Command Synonym

Editor Command

Arguments: new-name, command-name
Key sequence: None

The command Define Command Synonym prompts for a string and an existing command name, and makes the string be a synonym for the existing command name.

6.3.3 Buffers

Each buffer that you manipulate interactively using editor commands is an object of type editor:buffer that can be used directly when programming the editor. Buffers contain an arbitrary number of editor:point objects, which are used when examining or modifying the text in a buffer (see Points).

(editor:with-buffer-locked ((editor:current-buffer))

  (editor:delete-next-character-command nil)

  (editor:insert-character (editor:current-point)

                           #\Space))

editor:with-buffer-locked (buffer
 &key for-modification
 check-file-modification
 block-interrupts
) &body body
 => values

editor:with-point-locked (point
 &key for-modification
 check-file-modification
 block-interrupts
 errorp
) &body body
  =>  values

6.3.4 Points

Locations within a buffer are recorded as editor:point objects. Each point remembers a character position within the buffer and all of the editor functions that manipulate the text of a buffer locate the text using one or more point objects (sometimes the current point).

A point's kind controls what happens to the point when text in the buffer is inserted or deleted.

:temporary points are for cases where you need read-only access to the buffer. They are like GNU Emacs "points". They have a lower overhead than the other kinds of point and do not need to be explicitly deleted, but do not use them in cases where you make a point, insert or delete text and then use the point again, since they do not move when the text is changed. Also, do not use them in cases where more than one thread can modify their buffer without locking the buffer first (see Buffer locking)

:before-insert and :after-insert points are for cases where you need to make a point, insert or delete text and still use the point afterwards. They are like GNU Emacs "markers". The difference between these two kinds is what happens when text is inserted. For a point at position n from the start of the buffer, inserting len characters will leave the point at either position n or n+len according to the following table.

When text is deleted, :before-insert and :after-insert points are treated the same: points <= the start of the deletion remain unchanged, points >= the end of the deletion are moved with the text and points within the deleted region are automatically deleted and cannot be used again.

All points with kind other than :temporary are stored within the data structures of the editor buffer so they can be updated when the text changes. A point can be removed from the buffer by editor:delete-point, and point objects are also destroyed if their buffer is killed.

editor:point-kind

Function

Returns the kind of the point, which is :temporary, :before-insert or :after-insert.

editor:current-point

Function

Returns the current point. See also editor:buffer-point.

editor:current-mark

Function

Returns the current mark. If pop-p is t, the mark ring is rotated so that the previous mark becomes the current mark. If no mark is set and no-error-p is t, nil is returned; otherwise an error is signalled. The default for both of these optional arguments is nil.

editor:set-current-mark

Function

Sets the current mark to be point.

editor:point<

Function

Returns non-nil if point1 is before point2 in the buffer.

editor:point<=

Function

Returns non-nil if point1 is before or at the same offset as point2 in the buffer.

editor:point>

Function

Returns non-nil if point1 is after point2 in the buffer.

editor:point>=

Function

Returns non-nil if point1 is after or at the same offset as point2 in the buffer.

editor:copy-point

Function

Makes and returns a copy of point. The argument kind can take the value :before, :after, or :temporary. If new-point is supplied, the copied point is bound to that as well as being returned.

editor:delete-point

Function

Deletes the point point.

This should be done to any non-temporary point which is no longer needed.

editor:move-point

Function

Moves point to new-position, which should itself be a point.

editor:start-line-p

Function

Returns t if point is immediately before the first character in a line, and nil otherwise.

editor:end-line-p

Function

Returns t if point is immediately after the last character in a line, and nil otherwise.

editor:same-line-p

Function

Returns t if point1 and point2 are on the same line, and nil otherwise.

editor:save-excursion

Macro

Saves the location of the point and the mark and restores them after completion of body. This restoration is accomplished even when there is an abnormal exit from body.

editor:with-point

Macro

point-bindings is a list of bindings, each of the form (var point [kind]). Each variable var is bound to a new point which is a copy of the point point though possibly with a different kind, if kind is supplied. If kind is not supplied, then the new point has kind :temporary.

The forms of body are evaluated within the scope of the point bindings, and then the points in each variable var are deleted, as if by editor:delete-point. Each point var is deleted even if there was an error when evaluating body.

The main reason for using with-point to create non-temporary points is to allow body to modify the buffer while keeping these points up to date for later use within body.

6.3.5 Regular expression searching

editor:regular-expression-search

Search for pattern starting from point.

point must be an editor:point object or nil, meaning the result of calling editor:current-point.

pattern can be a string, a "precompiled" pattern (result of lw:precompile-regexp), or nil.

forwardp is a boolean (default value t) specifying the direction to search.

prompt is a string used to prompt for a pattern when pattern is nil.

limit should be nil or an editor:point specifying a limit for the search.

to-end is a boolean (default value t), specifying whether to move the point to the end of the match when searching forward.

brackets-limits is a boolean specifying whether regular-expression-search should return a vector of brackets-limits.

regular-expression-search performs a search starting from point for the pattern, in the direction specified by forwardp, up to to limit if specified, or the buffer's end (when forwardp is non-nil) or the buffer's start (when forwardp is nil). If it succeeds, it then moves the point, either to the end of that match when both forwardp and to-end are non-nil (the default), or to the beginning of the match.

When pattern is non-nil it must be either a string or a precompiled pattern created with lw:precompile-regexp. If pattern is a string, regular-expression-search "precompiles" it before searching, so using a precompiled pattern is more efficient when using the same pattern repeatedly.

If pattern is nil, regular-expression-search first prompts for a pattern in the echo area, using the prompt. If pattern is non-nil, prompt is ignored.

Return values: If regular-expression-search is successful, it returns the length of the string that it matched, and if brackets-limits is non-nil, a second value which is a vector of the limits of the matches of each \( and \) pair in the pattern. The meaning of the vector is described in the manual entry for lw:find-regexp-in-string in the LispWorks User Guide and Reference Manual .

Compatibility note: regular-expression-search was exported but not documented in LispWorks 6.1 and earlier versions. brackets-limits was introduced in LispWorks 7.0.

See also:
lw:find-regexp-in-string , lw:regexp-find-symbols and lw:precompile-regexp in the LispWorks User Guide and Reference Manual
Regular expression syntax

6.3.6 The echo area

editor:message

Function

A message is printed in the Echo Area. The argument string must be a string, which may contain formatting characters to be interpreted by format. The argument args consists of arguments to be printed within the string.

editor:clear-echo-area

Function

Clears the Echo Area. The argument string is then printed in the Echo Area. If force is non-nil, the Echo Area is cleared immediately, with no delay. Otherwise, there may be a delay for the user to read any existing message.

6.3.7 Editor errors

Many editor commands and functions signal an error on failure (using editor:editor-error as described below). This causes the current operation to be aborted.

In many cases, the user will not want the operation to abort completely if one of the editor commands it uses is not successful. For example, the operation may involve a search, but some aspects of the operation should continue even if the search is not successful. To achieve this, the user can catch the editor:editor-error using a macro such as handler-case.

For example, one part of an application might involve moving forward 5 forms. If the current point cannot be moved forward five forms, generally the Editor would signal an error. However, this error can be caught. The following trivial example shows how a new message could be printed in this situation, replacing the system message.

(editor:defcommand "Five Forms" (p)  

   "Tries to move the current point forward five forms,
    printing out an appropriate message on failure."  

   "Tries to move the current point forward five forms."

   (handler-case

      (editor:forward-form-command 5)

      (editor:editor-error (condition)

         (editor:message "could not move forward five"))))

editor:editor-error

Function

By default this prints a message in the Echo Area, sounds a beep, and exits to the top level of LispWorks, aborting the current operation. The argument string must be a string, which is interpreted as a control string by format. As with editor:message, args can consist of arguments to be processed within the control string.

The behavior is affected by break-on-editor-error.

6.3.8 Files

editor:find-file-buffer

Function

Returns a buffer associated with the file pathname, reading the file into a new buffer if necessary. The second value returned is T if a new buffer is created, and nil otherwise. If the file already exists in a buffer, its consistency is first checked by means of check-function. If no value is supplied for check-function, editor:check-disk-version-consistent is used.

editor:fast-save-all-buffers

Function

Saves all modified buffers which are associated with a file. If ask is non-nil then confirmation is asked for before saving each buffer. If ask is not set, all buffers are saved without further prompting.

Unlike the editor command Save All Files this function can be run without any window interaction. It is thus suitable for use in code which does not intend to allow the user to leave any buffers unsaved, and from the console if it is necessary to save buffers without re-entering the full window system.

editor:check-disk-version-consistent

Function

Checks that the date of the file pathname is not more recent than the last time buffer was saved. If pathname is more recent, the user is prompted on how to proceed. Returns t if there is no need to read the file from disk and nil if it should be read from disk.

editor:buffer-pathname

Function

Returns the pathname of the file associated with buffer. If no file is associated with buffer, nil is returned.

(setf (editor:variable-value 'editor:output-format-default

                             :global)

      ef-spec
)

6.3.9 Inserting text

editor:insert-string

Function

Inserts string at point in the current buffer. The arguments start and end specify the indices within string of the substring to be inserted. The default values for start and end are 0 and (length string) respectively.

editor:kill-ring-string

Function

Returns either the topmost string on the kill ring, or the string at index places below the top when index is supplied.

The editor kill ring stores the strings copied by the editor, in order to allow using them later.

editor:points-to-string

Function

Returns the string between the points start and end.

6.3.10 Indentation

editor:*indent-with-tabs*

Variable

Controls whether indentation commands such as Indent and Indent Form insert whitespace using #\Space or #\Tab characters when changing the indentation of a line.

The initial value is nil, meaning that only the #\Space character is inserted.

A true value for editor:*indent-with-tabs* causes the indentation commands to insert #\Tab characters according to the value of spaces-for-tab and then pad with #\Space characters as needed.

6.3.11 Lisp

editor:*find-likely-function-ignores*

Variable

Contains a list of symbols likely to be found at the beginning of a form (such as apply, funcall, defun, defmethod, defgeneric).

editor:*source-found-action*

Variable

This variable determines how definitions found by the commands Find Source, Find Source for Dspec and Find Tag are shown. The value should be a list of length 2.

The first element controls the positioning of the definition: when t, show it at the top of the editor window; when a non-negative fixnum, position it that many lines from the top; and when nil, position it at the center of the window.

The second element can be :highlight, meaning highlight the definition, or nil, meaning do not highlight it.

The initial value of *source-found-action* is (nil :highlight).

6.3.12 Movement

editor:line-end

Function

Moves point to be located immediately before the next newline character, or the end of the buffer if there are no following newline characters.

editor:line-start

Function

Moves point to be located immediately after the previous newline character, or the start of the buffer if there are no previous newline characters.

editor:character-offset

Function

Moves point forward n characters. If n is negative, point moves back n characters.

editor:word-offset

Function

Moves point forward n words. If n is negative, point moves back n words.

editor:line-offset

Function

Moves point n lines forward, to a location to-offset characters into the line. If n is negative, point moves back n lines. If to-offset is nil (its default value), an attempt is made to retain the current offset. An error is signalled if there are not n further lines in the buffer.

editor:form-offset

Function

Moves point forward n Lisp forms. If n is negative, point moves back n forms. If form is t (its default value) then atoms are counted as forms, otherwise they are ignored. Before point is moved forward n forms, it first jumps out depth levels. The default value for depth is 0.

6.3.13 Prompting the user

The following functions can be used to prompt for some kind of input, which is generally typed into the Echo Area.

The following keyword arguments are common to a number of prompting functions.

:must-exist

Specifies whether the value that is input by the user must be an existing value or not. If :must-exist is non-nil, the user is prompted again if a non-existent value is input.

:default

Defines the default value that is selected if an empty string is input.

:default-string

Specifies the string that may be edited by the user (with Insert Parse Default).

:prompt

Defines the prompt that is written in the Echo Area. Most prompting functions have a default prompt that is used if no value is supplied for :prompt.

:help

Provides a help message that is printed if the user types "?".

editor:prompt-for-file

Function

Prompts for a file name, and returns a pathname.

:direction

You can specify direction :input (when expecting to read the file) or direction :output (when expecting to write the file). This controls the default value of must-exist, which is false for direction :output and true otherwise.

:create-directories

If create-directories is true, then the user is prompted to create any missing directories in the path she enters. The default is false for direction :output and true otherwise.

See above for an explanation of the other arguments.

editor:prompt-for-buffer

Function

Prompts for a buffer name, and returns the buffer. See above for an explanation of the keywords.

The default value of must-exist is t. If must-exist is nil and the buffer does not exist, it is created.

editor:prompt-for-integer

Function

Prompts for an integer. See above for an explanation of the keywords.

editor:prompt-for-string

Function

Prompts for a string. No checking is done on the input. The keyword clear-echo-area controls whether or not the echo area is cleared (that is, whether the text being replaced is visible or not). The default for this keyword is t. See above for an explanation of the remaining keywords.

editor:prompt-for-variable

Function

Prompts for an editor variable. See above for an explanation of the keywords. The default value of must-exist is t.

6.3.14 In-place completion

editor:complete-in-place

Function

Performs a non-focus completion at the editor current point.

complete-func should be a function designator with signature:

string should be a string to complete. user-arg is the second return value of extract-func, if this is not nil. result should be a list of items to be displayed in the list panel of the non-focus window.

extract-func must be a function designator with signature

point should be a Point object

extract-func needs to move point to the beginning of the text that will be replaced if the user confirms. It should return two values: string is the string to complete, and user-arg can be any Lisp object. string is passed to the function complete-func, and if user-arg is non-nil it is also passed.

The default value of extract-func is a function which searches backwards until it finds a non-alphanumeric character, or the beginning of the buffer. It then moves its point argument forward to the next character. The function returns its first value string the string between this and the original location of the point, and it returns nil as the second value user-arg.

skip-func, if supplied, must be a function designator with signature

point should be a Point object

point will be used as the end of the region to replace by the completion. At the call to skip-func, the point is located at the same place as the point that was passed to extract-func (after it moved). skip-func needs to move point forward to the end of the text that should be replaced when the user wants to do the completion. If skip-func is not supplied, the end point is set to the current point.

insert-func, if supplied, must be a function designator with signature

result is the item selected by the user, string is the original string that was returned by extract-func, and user-arg is the second value returned by extract-func (regardless of whether this value is nil). It must return a string, string-to-use, which is inserted as the the completion.

If insert-func is not supplied, the completion item is inserted. If it is not a string it is first converted by prin1-to-string.

When editor:complete-in-place is called, it makes a copy of the current point and passes it to extract-func. It then copies this point and positions it either using skip-func or the current point. These two points define the text to be replaced. editor:complete-in-place then calls complete-func, and use the result to raise a non-focus window next to the current point. The interaction of this window is as described in CAPI User Guide and Reference Manual .

Note: editor:complete-with-non-focus is a deprecated synonym for editor:complete-in-place.

6.3.15 Variables

editor:define-editor-variable

Function

Defines an editor variable.

name

Symbol naming the variable.

value

The value to assign to the variable.

mode

A string naming a mode.

documentation

A documentation string.

The macro editor:define-editor-variable defines a global editor variable. There is only one global value, so repeated uses of editor:define-editor-variable overwrite each other.

editor:define-editor-variable gives a readable value of defining a variable, and is recognized by the LispWorks source code location system. However variables can also be defined dynamically by calling (setf editor:variable-value). Variable values may be accessed by editor:variable-value.

A variable has only one string of documentation associated with it. editor:variable-value overwrites the existing documentation string, if there is any. You can see the documentation by the command Describe Editor Variable. It can can be accessed programmatically by editor:editor-variable-documentation.

Note: for backwards compatibility name can also be a string, which is converted to a symbol by uppercasing, replacing #\Space by #\-, and interning in the EDITOR package. This may lead to clashes and so you should use a symbol for name, not a string.

editor:define-editor-mode-variable

Function

Defines an editor variable in the specified mode.

mode

A string naming a mode.

name, value

As for editor:define-editor-variable.

documentation

As for editor:define-editor-variable, except that editor:define-editor-mode-variable installs the documentation only if the editor variable does not already have any documentation.

editor:define-editor-mode-variable defines a variable in the specified mode. There is one value per variable per mode.

editor:define-editor-mode-variable gives a readable value of defining a variable in a mode, and is recognized by the LispWorks source code location system. However mode variables can also be defined dynamically by calling (setf editor:variable-value). Mode variable values may be accessed by editor:variable-value.

editor:editor-variable-documentation

Function

editor-variable-name

A symbol naming an editor variable.

Returns the documentation associated with the editor variable, if any.

Note: For backwards compatibility a string editor-variable-name is also accepted, as described for editor:define-editor-variable.

editor:variable-value

Function

Returns the value of the editor variable name, where name is a symbol. An error is signalled if the variable is undefined. The argument kind can take the value :current, :buffer, :global or :mode. The default value of kind is :current.

When kind is :current the argument where should be nil (the default, meaning the current buffer) or an editor buffer object or the name of a buffer. The variable value for the specified buffer is returned or (if there is no current buffer) then the global variable value is returned.

kind can also be :buffer, and then where should be an editor buffer object.

For example, the code given below will, by default, return the value :ask-user.

(editor:variable-value 

  'editor:add-newline-at-eof-on-writing-file)

The value of variables may also be altered using this function. For example, the code given below will allow buffers to be saved to file without any prompt for a missing newline.

(setf

   (editor:variable-value 

      'editor:add-newline-at-eof-on-writing-file)

    nil)

editor:variable-value-if-bound

Function

Returns the value of the variable name. If the variable is not bound, nil is returned. The arguments are as for editor:variable-value.

editor:buffer-value

Function

Accesses the value of the editor variable name in the buffer specified by buffer.

name should be a symbol and buffer should be a point object or a buffer object.

If the editor variable is undefined and errorp is true, an error is signalled. If the variable is undefined and errorp is false, nil is returned. The default value of errorp is nil.

6.3.16 Windows

editor:current-window

Function

Returns the current window.

editor:redisplay

Function

Redisplays any window that appears to need it. In general, the contents of a window may not be redisplayed until there is an event to provoke it.

Note: editor:redisplay will update a modified editor buffer only when that buffer is the editor:current-buffer. Take care to call editor:redisplay in an appropriate context.

editor:window-text-pane

Function

Returns the capi:editor-pane associated with an editor window.

6.3.17 Examples

(editor:defcommand "Current Line" (p)  

    "Computes the line number of the current point and

     prints it in the Echo Area"

    "Prints the line number of the current point"  

    (let* ((cpoint (editor:current-point))

           (svpoint (editor:copy-point cpoint))

           (count 0))

          (editor:beginning-of-buffer-command nil)

          (loop

             (if (editor:point> cpoint svpoint)

                 (return))

             (unless (editor:next-line-command nil)

                 (return))

             (incf count))

          (editor:move-point cpoint svpoint)

          (editor:message "Current Line Number: ~S " count)))

(editor:defcommand "Goto Line" (p)

   "Moves the current point to a specified line number.

    The number can either be supplied via the prefix

    argument, or, if this is nil, it is prompted for."

   "Moves the current point to a specified line number."

   (let ((line-number  

          (or p (editor:prompt-for-integer  

                 :prompt "Line number: "

                 :help "Type in the number of the line to

                  go to"))))

        (editor:beginning-of-buffer-command nil)

        (editor:next-line-command line-number)))

(defun copy-string (from-buf to-buf)

   (let ((string (editor:points-to-string  

           (editor:buffers-start from-buf)

           (editor:buffers-end from-buf))))

        (editor:insert-string (editor:buffers-end to-buf) string)))

(copy-string (editor:buffer-from-name "t1") 

						(editor:buffer-from-name "t2"))