| Movement Primitives | |
| Macros | |
| backspace | Delete character to the left of the cursor. |
| beginning_of_line | Goto beginning of line. |
| bookmark_list | Retrieve existing bookmark list. |
| delete_bookmark | Delete a bookmark. |
| down | Move position down one line. |
| drop_bookmark | Create or update a bookmark. |
| end_of_buffer | Move cursor to end of current buffer. |
| end_of_line | Goto end of line. |
| end_of_window | Goto end of the current window. |
| goto_line | Move to a particular line. |
| goto_old_line | Move to line before buffer modification. |
| left | Move position left one charcter. |
| move_abs | Move to an absolute location in the buffer. |
| move_rel | Move to a relative location in the buffer. |
| next_char | Move to the next character. |
| page_down | Move position down a page. |
| page_up | Move position up a page. |
| parse_filename | Parse a file into its components. |
| prev_char | Move to the previous character. |
| swap_anchor | Swaps the mark with the current position. |
| top_of_buffer | Move cursor to start of current buffer. |
| top_of_window | Goto top of the current window. |
void backspace( [int num = 1] )
Delete character to the left of the cursor.
The backspace() primitive moves the cursor and deletes the character to the left of the cursor in the current buffer.
The actions of backspace are dependent on the current insert mode.
If insert mode backspaces moves the cursor and deletes the previous character, all characters to the right move one character to the left.
If the cursor is at the beginning of the line then the current line is appended to the end of the previous line.
If overstrike mode backspaces moves the cursor and deletes the previous character, replacing it with a space.
If the previous character is a tab, it moves over virtual spaces between the current position and the tab character when moving back.
If the cursor is at the beginning of the line then the cursor is moved to end of the previous line.
| num | Optional integer, if stated specifies the number of characters the cursor to be moved backwards, if omitted only a single character position is moved. |
The backspace() primitive returns non-zero if successful impling the cursor moved, otherwise zero.
The num option is a GriefEdit extension.
int beginning_of_line()
Goto beginning of line.
The beginning_of_line() primitive moves the buffer cursor to the first character of the current line.
none
The beginning_of_line() primitive returns non-zero on success denoting that the cursor moved, otherwise zero if the cursor remained unchanged.
n/a
list bookmark_list()
Retrieve existing bookmark list.
The bookmark_list() primitive creates a list containing all currently defined bookmarks. For each definition the list shall contain a 4 integer record representing the bookmark as follows:
{ bookid, bufnum, line, column }If no bookmarks exist then a NULL list shall be returned.
none
The bookmark_list() primitive returns a list containing the bookmark definitions otherwise NULL if no bookmarks exist.
n/a
void delete_bookmark( int bookid )
Delete a bookmark.
The delete_bookmark() primitive deletes the bookmark bookid.
Upon successful completion, the REG_BOOKMARK event shall be triggered (See: register_macro).
| bookid | Bookmark identifier. |
nothing
n/a
int down( [int lines = 1] )
Move position down one line.
The down() primitive moves the cursor down one line to the same column on the next line.
| lines | Optional number of lines to move the cursor; may be negative in which case the cursor moves backwards behaving like up. |
The down() primitive returns non-zero on success denoting that the cursor moved, otherwise zero if the cursor remained unchanged.
n/a
int drop_bookmark( [int bookid], [string yesno], [int bufnum], [int line], [int column], [int local = FALSE] )
Create or update a bookmark.
The drop_bookmark() primitive either create a new or updates an existing bookmark. A bookmark is a named place holder with a buffer, representing a specific physical location within that buffer.
bookid is the unique identifier to be associated with the bookmark; any valid integer may be used as the identifier. The bookmark shall be associated with the buffer bufnum, line and column, if any are omitted the current buffer and location with that shall be used.
Upon there being an existing definition against the specified bookmark identifier, the user shall be prompted as follows, asking whether or not the bookmark should be replaced:
Overwrite existing bookmark [y/n]?
The yesno argument if given disables the user prompt. If supplied with either “y” or “yes” the bookmark shall automatically be replaced, otherwise the bookmark is retained without change with the user informed as follows:
Bookmark already exists.
Upon successful completion, the user shall be informed as follows regardless of whether a new or updated definition resulted:
Bookmark dropped.
| bookid | Optional bookmark identifier, if omitted a new unique book mark identifier shall be generated. |
| yesno | Optional string buffer containing the answer to be applied upon the bookmark pre-existing, if given as “y[es]” the bookmark shall be overridden otherwise is shall be related. Otherwise if omitted upon a preexisting bookmark the user shall be prompted. |
| bufnum | Optional buffer number, if omitted the current buffer shall be referenced. |
| line | Optional integer line number within the buffer, if omitted shall default to the top of the buffer (1). |
| column | Optional integer column number within the buffer, if omitted shall default to the left of the buffer (1). |
| local | Reserved for future use. |
The drop_bookmark() primitive returns the associated book mark identifier, otherwise 0 on error.
n/a
Support buffer local bookmark identifiers; improves Vim compatibility.
int end_of_buffer()
Move cursor to end of current buffer.
The end_of_buffer() primitive moves the buffer cursor to the end of the last line of the current buffer.
none
The end_of_buffer() primitive returns non-zero on success denoting that the cursor moved, otherwise zero if the cursor remained unchanged.
n/a
int end_of_line()
Goto end of line.
The end_of_line() primitive moves the buffer cursor to the last character of the current line.
none
The end_of_line() primitive returns non-zero on success denoting that the cursor moved, otherwise zero if the cursor remained unchanged.
n/a
int end_of_window()
Goto end of the current window.
The end_of_window() primitive moves the buffer cursor to the last line of the current window.
none
Returns non-zero if the current cursor position moved, otherwise zero if already positioned at the end of the window.
n/a
int goto_line( [int lineno] )
Move to a particular line.
The goto_line() primitive repositions the cursor to tbe beginning of the specified line lineno.
| lineno | Specifies the line number which to relocate the cursor, if omitted the user is prompted. |
The goto_line() primitive returns true if successful, otherwise zero or less if unsuccessful.
n/a
int goto_old_line( [int oldlineno] )
Move to line before buffer modification.
The goto_old_line() primitive repositions the cursor as close as possible to the beginning of the specified line oldlineno, representing the line prior to any buffer modifications.
For each buffer the previous line numbers are retained for any one edit session, that is they are maintained until the buffer is saved, at which point line references are reset to the resulting new image.
This primitive is provided for seeking lines within a buffer that are referred to in an external listing. For example within a previous compiler error report yet since that time inserts and/or line deletes have occurred to the source, yet despite these edits the original line can still be addressed.
| oldlineno | Specifies the old line number which to relocate the cursor, if omitted the user is prompted. |
The goto_old_line() primitive returns true if successful, otherwise zero or less if unsuccessful.
n/a
int left( [int columns = 1], [int wrap = TRUE] )
Move position left one charcter.
The left() primitive moves the cursor left one column retaining the current line; unless at the beginning of the line, in which case the cursor moves to the end of the previous line.
| columns | Optional number of columns to move the cursor; negative in which case the cursor movement is reversed behaving like right. |
| wrap | Optional boolean value controlling whether the cursor wraps when positioned at the beginning of line. If FALSE line wrapping shall be disabled. |
The left() primitive returns non-zero on success denoting that the cursor moved, otherwise zero if the cursor remained unchanged.
Unlike BRIEF, if the cursor is moved past the beginning of the current line, then the cursor wraps around to the end of the previous line.
wrap is a GriefEdit extension.
int move_abs( [int line = -1], [int column = -1], [int bufnum], [int clip = FALSE] )
Move to an absolute location in the buffer.
The move_abs() primitive moves the buffer cursor to an absolute location, with top of the buffer being position (1,1).
If a parameter is 0 or omitted, the corresponding line or column coordinate is unchanged; positive values set the line and/or column.
| line | Optional integer specifying the line number, if positive the cursor is set to the specified line. |
| column | Optional integer specifying the column number, if positive the cursor is set to the specified column. |
| bufnum | Optional buffer number, if specified the associated buffer is affected, otherwise the current buffer. |
| clip | Optional int flag, if non-zero the resulting buffer cursor shall be clipped to the buffer size. |
The move_abs() primitive returns non-zero on success denoting that the cursor moved, otherwise zero if the cursor remained unchanged.
bufnum and clip are extensions.
int move_rel( [int lines = 1], [int cols = 1] )
Move to a relative location in the buffer.
The move_rel() primitive moves the buffer cursor to a new position relative to the current position.
If a parameter is 0 or omitted, the corresponding line or column coordinate is unchanged. Positive values move the cursor towards the end of the line and/or column, likewise negative values move towards the beginning of the line and/or column.
| lines | Optional integer specifying the line number, if positive the cursor moves forwards the end of the file, likewise a negative moves to backwards towards the top. |
| cols | Optional integer specifying the column number, if positive the cursor moves forwards the front of the line, likewise a negative moves to backwards towards the beginning. |
The mov_rel() primitive returns non-zero on success denoting that the cursor moved, otherwise zero if the cursor remained unchanged.
n/a
int next_char( [int characters = 1] )
Move to the next character.
The next_char() primitive moves the current buffer position forward to the next character, wrapping around line ends when encountered.
The primitive is similar to right except it moves physical characters as opposed to logic characters, as the result tabs and newlines are both treated as one character.
Within navigating binary files newlines are not implied, as such are not counted within the character count.
| characters | Optional number of characters to move forward in the buffer, which if omitted is 1. |
The next_char() primitive returns non-zero on success denoting that the cursor moved, otherwise zero if the cursor remained unchanged.
n/a
int page_down( [int pages = 1] )
Move position down a page.
The page_down() primitive moves the buffer position down or forward one or more pages down, with a page being the current window size in lines.
| pages | If supplied, states the number of pages to move the cursor forward, otherwise the cursor is moved 1 page. |
The page_down() primitive returns non-zero on success denoting that the cursor moved, otherwise zero if the cursor remained unchanged.
pages is a GriefEdit extension.
int page_up( [int pages = 1] )
Move position up a page.
The page_up() primitive moves the buffer position up or backwards one or more pages up, with a page being the current window size in lines.
| pages | If supplied, states the number of pages to move the cursor backwards, otherwise the cursor is moved 1 page. |
The page_up() primitive returns non-zero on success denoting that the cursor moved, otherwise zero if the cursor remained unchanged.
pages is a GriefEdit extension.
int parse_filename( string fullname, [string &drive], [string &path], [string &filename], [string &ext] )
Parse a file into its components.
The parse_filename() primitive parsing and brakes the file name fullname into it components.
Since this primitive is not portable outside of a DOS/Windows environment, its use is not adviced.
| fullname | A string containing the file-name to be parsed. |
| drive | Optional string variable when supplied to be populated with the drive component, if any. |
| path | Optional string variable when supplied to be populated with the path component. |
| filename | Optional string variable when supplied to be populated with the file-name component. |
| ext | Optional string variable when supplied to be populated with the file extension. |
The parse_filename() primitive returns non-zero on success denoted the fullname was parsed, otherwise zero was unsuccessful and -1 if an empty fullname was supplied.
Provided for BRIEF compatibility.
int prev_char( [int characters = 1] )
Move to the previous character.
The prev_char() primitive moves the current buffer position backward to the previous character, wrapping around line ends when encountered.
The primitive is similar to left except it moves physical characters as opposed to logic characters, as the result tabs and newlines are both treated as one character.
Within navigating binary files newlines are not implied, as such are not counted within the character count.
| characters | Optional number of characters to move backward in the buffer, which if omitted is 1. |
The prev_char() primitive returns non-zero on success denoting that the cursor moved, otherwise zero if the cursor remained unchanged.
n/a
int top_of_buffer()
Move cursor to start of current buffer.
The top_of_buffer() primitive moves the buffer cursor to the start of the first line of the current buffer; this is eqivalent to using move_abs as follows.
move_abs(1,1);
none
The top_of_buffer() primitive returns non-zero on success denoting that the cursor moved, otherwise zero if the cursor remained unchanged.
n/a
int top_of_window()
Goto top of the current window.
The top_of_window() primitive moves the buffer cursor to the first line of the current window.
none
Returns non-zero if the current cursor position moved, otherwise zero if already positioned at the top of the window.
n/a
end_of_buffer, inq_position, move_abs, move_rel
$Id: $
To send feedback on this topic email: griefedit@gmail.com
Copyright © Adam Young All Rights Reserved.
Delete character to the left of the cursor.
void backspace( [int num = 1] )
Goto beginning of line.
int beginning_of_line()
Retrieve existing bookmark list.
list bookmark_list()
Delete a bookmark.
void delete_bookmark( int bookid )
Move position down one line.
int down( [int lines = 1] )
Create or update a bookmark.
int drop_bookmark( [int bookid], [string yesno], [int bufnum], [int line], [int column], [int local = FALSE] )
Move cursor to end of current buffer.
int end_of_buffer()
Goto end of line.
int end_of_line()
Goto end of the current window.
int end_of_window()
Move to a particular line.
int goto_line( [int lineno] )
Move to line before buffer modification.
int goto_old_line( [int oldlineno] )
Move position left one charcter.
int left( [int columns = 1], [int wrap = TRUE] )
Move to an absolute location in the buffer.
int move_abs( [int line = -1], [int column = -1], [int bufnum], [int clip = FALSE] )
Move to a relative location in the buffer.
int move_rel( [int lines = 1], [int cols = 1] )
Move to the next character.
int next_char( [int characters = 1] )
Move position down a page.
int page_down( [int pages = 1] )
Move position up a page.
int page_up( [int pages = 1] )
Parse a file into its components.
int parse_filename( string fullname, [string &drive], [string &path], [string &filename], [string &ext] )
Move to the previous character.
int prev_char( [int characters = 1] )
Swaps the mark with the current position.
int swap_anchor()
Move cursor to start of current buffer.
int top_of_buffer()
Goto top of the current window.
int top_of_window()
Delete character.
void delete_char( [int num] )
Seek a bookmark.
int goto_bookmark( int bookid = NULL, [int &bufnum], [int &line], [int &column] )
Register a callback procedure.
int register_macro( int type, string macro, [int local = FALSE] )
Move position up one line.
int up( [int lines = 1] )
Move position right one character.
int right( [int columns = 1], [int wrap = TRUE] )
Report the parent directory name of a file pathname.
int dirname( string path )
Return the last component of a pathname.
int basename( string pathname, [string suffix] )
Start marking a selection.
int drop_anchor( [int type = MK_NORMAL] )
Toggle the anchor status.
int mark( [int type = MK_NORMAL] )
Retrieve current buffer position.
int inq_position( [int &line], [int &col] )