# set-position(2)

[Home] [Commands] [Variables] [Macro-Dev] [Glossary]

## NAME

set-position - Store the current position
goto-position - Restore a stored position

## SYNOPSIS

n set-position "label"
n goto-position "label"

## DESCRIPTION

set-position stores current window, buffer, cursor and mark position information against the given '`label`' (a single alpha-numeric character). goto-position takes the positional information stored against the given '`label`' and restores the window, buffer and cursor positions from those previously set.

A call to set-position with the same label over-writes the previous stored information, a call to goto-position does not alter the information and may be restored multiple times.

The numerical argument to set-position is used to define the information that is stored in the position item. The argument is intrepreted as a bitmask, flagging what information is to be stored. The bit mask is defined as follows:

`0x001`

Store the current window.

`0x002`

Store the current window's horizonal scroll (value of $window-x-scroll(5)).

`0x004`

Store the current window's current line horizonal scroll (value of $window-xcl-scroll(5)).

`0x008`

Store the current window's vertical scroll (value of $window-y-scroll(5)).

`0x010`

Store the current buffer.

`0x020`

Store the current window's current line using an alpha mark.

`0x040`

Store the current window's current line number (value of $window-line(5)).

`0x080`

Store the current window's current column offset (value of $window-col(5)).

`0x100`

Store the current window's mark line using an alpha mark.

`0x200`

Store the current window's mark line number (value of $window-line(5) when mark was set).

`0x400`

Store the current window's mark column offset (value of $window-col(5) when mark was set).

When n is not specified, the default value is `0x0bf`, i.e. store all information required to return to the window, buffer and cursor position.

The argument supplied to goto-position similarly interpreted as a bitmask, restoring the positional information. When the numerical argument n is omitted the same default is used when omitted on the store. On restoring a position, information stored during the call to set-position which is not requested in corresponding goto is ignored, similarly information requested in a goto which was not stored in the set is also ignored.

## EXAMPLE

The following example shows the typical use of these commands:

    set-position "a"
        .
        .
    goto-position "a"

The following example stores the current position at the start of a macro sequence, if `my-command` is not successful ($status equals 0) the original position is restored:

    set-position "\x80"
    !force my-command
    !if &equ $status 0
        ; command failed, return to the original position
        goto-position "\x80"
    !endif

Note '`\x80`' is interpreted as the character with the ASCII value of 0x80 which is a non-alphanumeric character, this is permitted in macros to avoid using alphanumerics.

The following example shows how the current position can be restored after re-reading a file:

    0xce set-position
    read-file $buffer-fname @mna
    ; a numeric argument of 0xce is not
    ; required as this is the default
    goto-position

## NOTES

The position item may store and restore the current line by using an alpha mark or the line number. The restrore strategy will determine what is required, as follows:-

The main benefit from using an alpha mark is that the position is maintained even when the buffer is edited, for example if the position is stored at line 10 and a line is subsequently inserted at the top of the buffer, if the line number was used then it would return back to the 10th line which is the old 9th line whereas if an alpha mark were used it would correctly return to the 11th line, as expected.

The disadvantage of using an alpha mark is that it is only associated with that buffer. In some cases a position may need to be restored in another buffer (e.g. when re-reading a buffer the original buffer may be deleted first), in this situation the buffer line number must be used.

Commands set-window and goto-window, which simple stored and returned to the current window, were replaced by set-position and goto-position in August 2000. The following macro implementations can be used as a replacement:

    define-macro set-window
        1 set-position "\x80"
    !emacro

    define-macro goto-window
        goto-position "\x80"
    !emacro

## SEE ALSO

set-alpha-mark(2), find-buffer(2), $window-x-scroll(5), $window-xcl-scroll(5), $window-y-scroll(5), $window-line(5), $window-col(5).

(c) Copyright JASSPA 2009
Last Modified: 2009/08/29
Generated On: 2009/10/12

</HMTL>