| Scrap Primitives | |
| Macros | |
| copy | Copy marked area to scrap. |
| cut | Cut marked area to scrap. |
| delete_block | Deleted selected region. |
| drop_anchor | Start marking a selection. |
| end_anchor | Set the end of the anchor. |
| get_region | Retrieve marked region content. |
| inq_mark_size | Retrieve size of marked region. |
| inq_marked | Determine the current marked region. |
| inq_marked_size | Size the marked region. |
| inq_scrap | Obtain the scrap buffer identifier. |
| mark | Toggle the anchor status. |
| paste | Insert scrap buffer at cursor location. |
| raise_anchor | Raise the last dropped mark. |
| redo | Redo an undo operation. |
| set_scrap_info | Set the scrap buffer details. |
| transfer | Buffer to buffer transfer. |
| write_block | Write selected region. |
int copy( [int append = FALSE], [int keep = FALSE] )
Copy marked area to scrap.
The copy() primitive copies the content of the currently marked region to the scrap buffer, and releases the marked region on completion.
| append | Optional integer, if non-zero the copied region shall be appended to the scrap instead of replacing the scrap content. |
| keep | Optional integer, if non-zero the marked region is retained otherwise the anchor is released. |
The copy() primitive returns 1 on success, otherwise 0 on error.
n/a
int cut( [int append = FALSE], [int syscopy = FALSE] )
Cut marked area to scrap.
The cut() primitive moves the content of the currently marked region to the scrap buffer, and releases the marked region on completion.
| append | Optional integer, if non-zero the copied region shall be appended to the scrap instead of replacing the scrap content. |
| keep | Optional integer, if non-zero the marked region is retained otherwise the anchor is released. |
The cut() primitive returns 1 on success, otherwise 0 on error.
n/a
int delete_block()
Deleted selected region.
The delete_block() primitive deleted the current marked block, leaving the cursor position on the last line of the marked region.
The characters included in the mark depend on the its type, and once deleted the mark is removed.
On completion the following is echoed on the command prompt.
Block deleted.
In the event of no active region the following is echoed.
No marked block.
none
The delete_block() primitive returns one if the block was delete, otherwise zero.
int drop_anchor( [int type = MK_NORMAL] )
Start marking a selection.
The drop_anchor() primitive starts marking a block of the specified type at the current position in the current buffer.
Marked regions are highlighted to stand out on the screen either in a different colour or in reverse video dependent on the available display capacities.
The following are the available region types.
| Value |
Constant |
Description |
|---|---|---|
| 1 |
MK_NORMAL |
A normal mark. |
| 2 |
MK_COLUMN |
A column mark. |
| 3 |
MK_LINE |
A line mark. |
| 4 |
MK_NONINC |
A non-inclusive mark. |
| MK_NORMAL | A normal mark is a region which encompasses from the place where the anchor was dropped up to and including the current cursor position. |
| MK_COLUMN | A column mark allows a rectangular section of the buffer to be marked, highlighting the inclusive columns between the left and right boundaries. |
| MK_LINE | A line mark selects entire lines, and allows for easy movement of text from one part of a buffer to another. |
| MK_NONINC | A non-inclusive mark, like a normal, is a region which encompasses from the place where the anchor was dropped up to and but does not include the current cursor position. |
Regions are nestable, in that a drop_anchor may be issued without an intervening raise_anchor. Each mark is pushed into a LIFO (last-in, first-out) stack, allowing multiple marks to exist simultaneously; each mark must however be eventually raised. The most recent mark shall be the one displayed by the buffer.
The current active marked region can queried using inq_marked.
The marked region can be cleared by calling raise_anchor or performing a high level copy or cut buffer operations plus a numebr of the lower level functions, for example delete_block.
| type | Optional anchor type to be dropped, otherwise if omitted a MK_NORMAL anchor shall be created. |
The drop_anchor returns 1 if successful, otherwise 0 on error.
n/a
int end_anchor( [int line], [int column] )
Set the end of the anchor.
The end_anchor() primitive sets the end of the current marked region without the need to move the cursor.
| line | Optional new line, if omitted the line shall be unchanged. |
| column | Optional new column, if omitted the column shall be unchanged. |
The end_anchor returns 1 if successful, otherwise 0 on error.
n/a
int get_region( [int bufnum] )
Retrieve marked region content.
The get_region() primitive is similar to copy yet is copies the content of the current marked region and returns the result as a string.
| bufnum | Optional window identifier, if omitted the current buffer is referenced. |
The get_region() primitive returns the content of the current marked region as a string, otherwise an empty string.
n/a
cut, paste, copy, inq_marked
int inq_mark_size()
Retrieve size of marked region.
The inq_mark_size() primitive determines the number of characters what are in the currently marked region; this represents the the length of a string which would be necessary to hold its content, see get_region.
none
The inq_mark_size() primitive returns the number of characters in the currently marked region, otherwise 0 if there is no current region.
A GriefEdit extension.
int inq_marked( [int &start_line], [int &start_col], [int &end_line], [int &end_col] )
Determine the current marked region.
The inq_marked() primitive retrieves the current mark type and the associated coordinates of the marked area.
Region Types
| Value |
Constant |
Description |
|---|---|---|
| 0 |
MK_NONE |
No mark is set |
| 1 |
MK_NORMAL |
Normal mark |
| 2 |
MK_COLUMN |
Column mark |
| 3 |
MK_LINE |
Line mark |
| 4 |
MK_NONINC |
Non-inclusive |
| start_line | If specified the integer parameter is set to the line number at the top of the marked region. |
| start_col | If specified the integer parameter is set to the column number at the beginning of the marked region. |
| end_line | If specified the integer parameter is set to the line number marking the bottom of the marked region. |
| end_col | If specified the integer parameter is set to the column number at the end of the marked region. |
The inq_marked() primitive returns the current region type, otherwise 0 if no mark is active.
n/a
int inq_marked_size()
Size the marked region.
The inq_marked_size() primitive is reserved for future compatibility.
The inq_marked_size() primitive determines the number of characters contained within the current marked region.
Returns the character count within the marked region.
Function is currently a no-op, returning -1.
int inq_scrap( [int &last], [int &type] )
Obtain the scrap buffer identifier.
The inq_scrap() primitive retrieves the buffer identifier of the current scrap buffer.
| last | Not used; provided for BRIEF compatibility. If false the last newline in the scrap is not considered part of the scrap, otherwise true it is considered part of the scrap. |
| type | Optional integer variable reference, if stated shall be populated with the buffers mark type. |
The inq_scrap() primitive returns the scrap buffer identifier.
n/a
int mark( [int type = MK_NORMAL] )
Toggle the anchor status.
The mark() primitive toggles the status of the marked region. If the anchor is currently dropped it shall be raised, and if raised it shall be dropped.
To be independent of the current state macros should generally utilise drop_anchor and raise_anchor, with mark reserved for keyboard bindings.
| type | Optional anchor type to be dropped, if omitted a MK_NORMAL (1) mark shall be dropped. |
| Value |
Constant |
Description |
|---|---|---|
| 1 |
MK_NORMAL |
A normal mark. |
| 2 |
MK_COLUMN |
A column mark. |
| 3 |
MK_LINE |
A line mark. |
| 4 |
MK_NONINC |
A non-inclusive mark. |
The mark returns 1 if successful, otherwise 0 on error.
Unlike BRIEF the anchor status is always toggled.
BRIEF logic was equivalent to the following. If type was stated and an anchor of a different type current exists, the anchor is converted.
if (! inq_marked() || type) {
drop_anchor(type);
} else {
raise_anchor();
}
int paste( [int syspaste = FALSE] )
Insert scrap buffer at cursor location.
The paste() primitive insert the contents of the scrap buffer at the current cursor location.
The buffer is pasted according to the type of the mark which created it:
| syspaste | Optional boolean flag, is specified and is non-zero, then the text contents of the operating system buffer shall (e.g. clipboard under WIN32) shall be inserted into the current buffer where the cursor is located, if the feature is supported/available. |
The paste() primitive returns 1 on success, otherwise 0 on failure.
n/a
int raise_anchor()
Raise the last dropped mark.
The raise_anchor() primitive raises the last anchor mark that was dropped.
If no mark is dropped, this primitive has no effect.
none
The raise_anchor returns 1 if successful, otherwise 0 on error.
n/a
void set_scrap_info( [int last], [int type], [int bufnum] )
Set the scrap buffer details.
The set_scrap_info() primitive specifies the mark type and newline handling to be applied against the scrap buffer.
| last | Not used; provided for BRIEF compatibility. If false the last newline in the scrap is not considered part of the scrap, otherwise true it is considered part of the scrap. |
| type | Optional integer value, specifies the mark-type to be applied to the scrap buffer. |
| bufnum | Optional integer buffer identifier, if stated changes the current scrap buffer to the specified buffer. The resulting buffer shall be marked with the buffer flag BF_SCRAPBUF. |
The set_scrap_info() primitive returns 0 on success, otherwise -1 on error, for example in invalid buffer.
n/a
int transfer( int bufnum, int sline, [int scolumn], int eline, [int ecolumn] )
Buffer to buffer transfer.
The transfer() primitive moves the specified region from the buffer bufnum into the current buffer.
All characters in the source buffer between the start and end positions inclusive are included in the block.
The primitive has two forms determined by the number of coordinates arguments being either four or two, as followings:
Unlike the original BRIEF implementation, this version is more forgiving and is provided for compatibility; it is usually far easier to use the region macros.
| bufnum | Buffer identifier of the source. |
| sline | Starting line. |
| scolumn | Starting column. |
| eline | Ending line. |
| ecolumn | Ending column. |
The transfer() primitive returns non-zero on success, otherwise zero or less on error.
The short form of transfer is an extension yet less error prone and more convenient interface.
int write_block( [string filename], [int append = FALSE], [int keep = FALSE], [int pause = TRUE] )
Write selected region.
The write_block() primitive writes out the currently marked region to the file filename. If filename is not specified, then it is prompted for as follows
Write marked area as:
The characters included in the mark depend on the its type, and once written the mark is removed unless keep is specified.
Writing out a marked region does not affect the backup flag or the undo information flag; see undo and set_backup.
On completion the following is echoed on the command prompt.
Write successful.
In the event of no active region the following is echoed.
No marked block.
File Name
Several special leading characters within the stated filename act as modifiers on the output mode of the file.
| ’|’ | data is written to a pipe instead of a file. The string content after the | is passed as an argument to popen(). |
| ’>’, ‘>>’ | data shall be appended to the specified file following the >; same effect as stated append. |
| filename | Optional string value containing the path of the destination filename. If omitted the user shall be prompted. |
| append | Optional boolean value, if true the block is appended to the end of the file; otherwise the file content is replaced. |
| keep | Optional boolean value, if true the marked region is retainined, otherwise on completion the region is cleared. |
| pause | Optional boolean value control pipe completion handling. During pipe operations the command may destroy the screen. If omitted or is non-zero then the user is prompted to hit <Enter> before continuing. |
The write_block() primitive returns one on success, otherwise zero on error.
The filename and append options are GriefEdit extensions to BRIEF.
delete_block, write_buffer, undo, set_backup
$Id: $
To send feedback on this topic email: griefedit@gmail.com
Copyright © Adam Young All Rights Reserved.
Copy marked area to scrap.
int copy( [int append = FALSE], [int keep = FALSE] )
Cut marked area to scrap.
int cut( [int append = FALSE], [int syscopy = FALSE] )
Deleted selected region.
int delete_block()
Start marking a selection.
int drop_anchor( [int type = MK_NORMAL] )
Set the end of the anchor.
int end_anchor( [int line], [int column] )
Retrieve marked region content.
int get_region( [int bufnum] )
Retrieve size of marked region.
int inq_mark_size()
Determine the current marked region.
int inq_marked( [int &start_line], [int &start_col], [int &end_line], [int &end_col] )
Size the marked region.
int inq_marked_size()
Obtain the scrap buffer identifier.
int inq_scrap( [int &last], [int &type] )
Toggle the anchor status.
int mark( [int type = MK_NORMAL] )
Insert scrap buffer at cursor location.
int paste( [int syspaste = FALSE] )
Raise the last dropped mark.
int raise_anchor()
Redo an undo operation.
void redo()
Set the scrap buffer details.
void set_scrap_info( [int last], [int type], [int bufnum] )
Buffer to buffer transfer.
int transfer( int bufnum, int sline, [int scolumn], int eline, [int ecolumn] )
Write selected region.
int write_block( [string filename], [int append = FALSE], [int keep = FALSE], [int pause = TRUE] )
Delete character.
void delete_char( [int num] )
Undo previous edit operations.
int undo( [int move], [int pastwrite = -1], [int redo = FALSE] )
Set backup creation mode.
int set_backup( int mode, [int bufnum] )
Write to buffer content.
int write_buffer( [string filename], [int flags], [string encoding] )