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

$window-x-scroll(5)

0x004

$window-xcl-scroll(5)

0x008

$window-y-scroll(5)

0x010

Store the current buffer.

0x020

0x040

0x080

0x100

0x200

0x400

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: