| Buffer Primitives | |
| Constants | |
| Buffer Flags | Buffer attribute constants. |
| Macros | |
| attach_buffer | Attach a buffer to a window. |
| create_buffer | Create and load a buffer. |
| create_nested_buffer | Create or reference a buffer. |
| delete_buffer | Delete a buffer. |
| delete_char | Delete character. |
| delete_line | Delete current line. |
| delete_to_eol | Delete to end-of-line. |
| find_line_flags | Locate next line with specific flags. |
| find_marker | Locate next marker. |
| goto_bookmark | Seek a bookmark. |
| inq_attribute | Retrieve the current attributes. |
| inq_buffer_flags | Retrieve buffer flags. |
| inq_buffer_title | Retrieve a buffer title. |
| inq_buffer_type | Retrieve buffer type. |
| inq_byte_pos | Get current position in buffer stream. |
| inq_encoding | Retrieve a buffers character encoding. |
| inq_file_change | Determine state of underlying file. |
| inq_indent | Get current indentation settings. |
| inq_line_flags | Retrieve a lines associated flags. |
| inq_line_length | Determine the longest line length. |
| inq_lines | Retrieve the line count. |
| inq_margins | Retrieve buffer formatting margins. |
| inq_modified | Determine a buffers modification status. |
| inq_names | Retrieve associated buffer names. |
| inq_position | Retrieve current buffer position. |
| inq_process_position | Get position of process buffer. |
| inq_ruler | Retrieves the ruler specification. |
| inq_system | Determine if buffer is a system buffer. |
| inq_tab | Derive the tab increment. |
| inq_tabs | Retrieves the buffer tab specification. |
| inq_terminator | Retrieve a buffers line terminator. |
| inq_time | Retrieve the last modification time. |
| mark_line | Create a line marker. |
| mode_string | Conversion stat mode to a string representation. |
| next_buffer | Identifier of the next buffer. |
| previous_buffer | Identifier of the previous buffer. |
| Print formatted string to stdout. | |
| set_attribute | Set the color attributes. |
| set_buffer | Set the current buffer. |
| set_buffer_flags | Set buffer flags. |
| set_buffer_title | Set a buffers title. |
| set_buffer_type | Set the buffer storage type. |
| set_encoding | Set a buffers character encoding. |
| set_indent | Set the buffers default indentation. |
| set_line_flags | Associate line flags. |
| set_margins | Set buffer formatting margins. |
| set_process_position | Set process insertion position. |
| set_ruler | Configure the buffer ruler. |
| set_tab | Derive the buffer tab stops. |
| set_terminator | Set a buffers line terminator. |
| sort_buffer | Sort buffer content. |
| tabs | Set buffer tab stops. |
| tagdb_close | Tag database close. |
| tagdb_open | Tag database open. |
| tagdb_search | Tag database search. |
| write_buffer | Write to buffer content. |
Buffer attribute constants.
Buffer flags are represented by bit-fields grouped in one of four sets. The following section describes the possible values for theses flags:
First flag set, representing status and control primary buffer options.
| Constant |
Description |
|---|---|
| BF_CHANGED |
Changed. |
| BF_BACKUP |
Backup required on next write. |
| BF_RDONLY |
Read-only. |
| BF_READ |
Buffer content still to be read. |
| BF_EXEC |
File is executable. |
| BF_PROCESS |
Buffer has process attached. |
| BF_BINARY |
Binary buffer. |
| BF_ANSI |
If TRUE, ANSI-fication is done. |
| BF_TABS |
Buffer inserts real-tabs. |
| BF_SYSBUF |
Buffer is a system buffer. |
| BF_LOCK |
File lock. |
| BF_NO_UNDO |
Dont keep undo info. |
| BF_NEW_FILE |
File is a new file, so write even if no changes. |
| BF_CR_MODE |
Append <CR> to end of each line on output. |
| BF_SYNTAX |
Enable syntax highlighting (unless ANSI). |
| BF_SYNTAX_MATCH |
Hilite matching braces. |
| BF_MAN |
If TRUE, man style \b is done. |
| BF_SPELL |
Enable spell. |
| BF_FOLDING |
Test folding/hiding. |
| BF_RULER |
Display ruler. |
| BF_VOLATILE |
Buffer is volatile. |
| BF_EOF_DISPLAY |
Show <EOF> markers. |
| BF_HIDDEN |
Hidden buffer, from buffer list |
| BF_AUTOREAD |
Automatically re-read buffer, if underlying changes. |
| BF_AUTOWRITE |
Automatically write buffer, if modified |
| BF_SCRAPBUF |
Scrap buffer. |
| BF_DELAYED |
Content load delayed until first reference. |
Second buffer set, controlling general UI formatting options.
| Constant |
Description |
|---|---|
| BF2_ATTRIBUTES |
Character attributes, enables character cell coloring. |
| BF2_DIALOG |
Dialog |
| BF2_CURSOR_ROW |
Display cursor cross-hair. |
| BF2_CURSOR_COL |
|
| BF2_TILDE_DISPLAY |
|
| BF2_EOL_HILITE |
Limit hilites to EOL. |
| BF2_LINE_NUMBERS |
Line numbers |
| BF2_LINE_OLDNUMBERS |
If has line numbers, display old lines |
| BF2_LINE_STATUS |
Markup modified lines. |
| BF2_LINE_SYNTAX |
Syntax preprocessor flags |
| BF2_TITLE_FULL |
Label window using full path name |
| BF2_TITLE_SCROLL |
Scroll title with window |
| BF2_TITLE_LEFT |
Left justify title |
| BF2_TITLE_RIGHT |
Right justify title |
| BF2_SUFFIX_RO |
Read-only suffix on title |
| BF2_SUFFIX_MOD |
Modified suffix on title |
| BF2_EOL_CURSOR |
Limit cursor to EOL |
| BF2_EOF_CURSOR |
Limit cursor to EOF |
| BF2_HILITERAL |
Hilite literal characters |
| BF2_HIWHITESPACE |
Hilite whitespace |
| BF2_HIMODIFIED |
Hilite modified lines |
| BF2_HIADDITIONAL |
Hilite added lines |
| BF2_HISTATUSLINE |
Status line |
Third flag set, controlling indirect buffer functionality which are generally implemented at a macro level.
| Constant |
Description |
|---|---|
| BF3_AUTOSAVE |
Auto-save |
| BF3_AUTOINDENT |
Auto-indent |
| BF3_AUTOWRAP |
Auto-wrap |
| BF3_PASTE_MODE |
Paste mode, disables a number of auto functions. |
Fourth flag set, controlling file conversion options.
void attach_buffer( int bufnum )
Attach a buffer to a window.
The attach_buffer() primitive attaches the specified buffer to the current window, so that the window becomes a view port into the buffer content.
This interface is generally used in combination with set_buffer, set_window and/or buffer/window creation. Care should be taken to always have both the current buffer attached to the current window at end of any macros returning control backup, otherwise results are undefined.
For example, create a buffer and window and then associate the two.
int buf = create_buffer("buffer);
int win = create_window(20, 10, 60, 2);
attach_buffer(buf);When the specified buffer is attached to the current window, the top title of the window is changed to reflect the buffer or file-name associated with the buffer.
| bufnum | Buffer identifier to be attached. |
A few events automatically affect the attached buffer.
nothing
n/a
int create_buffer( string bufname, [string filename], [int sysflag = FALSE], [int editflags = 0], [string encoding = ""] )
Create and load a buffer.
The create_buffer() primitive creates a buffer containing the content of an optional underlying file filename, with the filename being ae full or relative path name of a file which should be read into the buffer. If this parameter is omitted, then an initially empty buffer will be created.
The buffer name bufname should be unique, and if the buffer already exists a unique name shall be derived by prefixing its name with “ [x]”; x being the next available unique sequence.
The optional arguments sysflag, editflags and encoding control a variety of the buffer features.
Upon buffer loads firstly the _extension callback is executed and either an extension specific callback of the form _ext or _default shall be executed.
In addition any related register_macro callbacks are executed.
The following creates the buffer named “Read-Me” and populates it with the content of the file “readme.txt”.
int buf;
if ((buf = create_buffer("Read-Me", "readme.txt")) >= 0) {
attach_buffer(newbuf);
return buf;
}
message("error loading buffer ...");
return -1;
| bufname | String containing the unique buffer name. The name is used as the buffer title, which is usually the same as the underlying filename yet it need not be; for example an abbreviated form. The buffer names does not affect the file that shall be loaded into the buffer. |
| filename | Optional string containing the file that the buffer should contain, if omitted an empty buffer is created. |
| sysflag | Optional integer boolean flag stating whether or not the buffer is a system buffer, FALSE for non-system otherwise TRUE for system; if omitted the buffer is assumed to be a non-system. See inq_system is more details on system buffers. |
| editflags | Optional buffer creation flags. These flags control the file mode, see the edit_file primitive for additional information describing this field. |
| encoding | Optional buffer encoding hint. |
The create_buffer() primitive returns the buffer identifier associated with the newly created buffer, otherwise -1 if the buffer was not created.
Note the buffer does not become the current buffer until the set_buffer primitive is used against the returned buffer identifier.
n/a
attach_buffer, delete_buffer, set_buffer, create_nested_buffer, set_buffer_title
int create_nested_buffer( string bufname, [string filename], [int sysflag], [int editflags], [string encoding] )
Create or reference a buffer.
The create_nested_buffer() primitive is similar to the create_buffer primitive yet if the buffer already exists its reference counter is incremented.
For each nested buffer increment delete_buffer must be called, with the buffer only being removed upon the reference count being zero.
This primitive but is provided for convenience when temporary access to a buffer is required, see the ff macro for a working example.
| bufname | String containing the unique buffer name. The name is used as the buffer title, which is usually the same as the underlying filename yet it need not be; for example an abbreviated form. The buffer names does not affect the file that shall be loaded into the buffer. |
| filename | Optional string containing the file that the buffer should contain, if omitted an empty buffer is created. |
| sysflag | Optional integer boolean flag stating whether or not the buffer is a system buffer, FALSE for non-system otherwise TRUE for system; if omitted the buffer is assumed to be a non-system. See inq_system is more details on system buffers. |
| editflags | Optional buffer creation flags. These flags control the file mode, see the edit_file primitive for additional information describing this field. |
| encoding | Optional buffer encoding hint. |
The create_nested_buffer() primitive returns the buffer identifier associated with the newly created buffer, otherwise -1 if the buffer was not created.
n/a
attach_buffer, delete_buffer, set_buffer, create_buffer, set_buffer_title
void delete_buffer( int bufnum )
Delete a buffer.
The delete_buffer() primitive deletes the specified buffer, the buffer contents and all associated resources are released.
Any changes made to the buffer since it was last written shall be lost, as such if required the content should be written using write_buffer.
In the case of a process buffer, the underlying sub-process is shutdown.
Once deleted, the associated buffer handle is invalid.
| bufnum | Non-optional buffer number. |
nothing
n/a
void delete_char( [int num] )
Delete character.
The delete_char() primitive deletes one or more characters at the current cursor position.
This primitive is the default assignment for the <Delete> key on the keyboard.
| num | Optional integer, if stated specifies the number of characters to be deleted, if omitted only a single character is removed. |
nothing
n/a
int find_line_flags( [int bufnum], [int lineno], int mode, int and_mask, [int or_value], [int value] )
Locate next line with specific flags.
The find_line_flag() primitive positions the cursor at the next line which matches the specified flag value.
bufnum and lineno allow explicit buffer and line number references to be stated, otherwise if omitted the current buffer and/or associated line number shall be used.
flags defines direction and type of equivalence test to be utilised. and_mask and or_value parameterise the equivalence expression.
| bufnum | Optional buffer number, if omitted the current buffer shall be referenced. |
| lineno | Starting line number. |
| mode | Search mode flags. |
| LF_FORWARDS | Forward search (default). |
| LF_BACKWARDS | Backwards search. |
| LF_MATCH_EQ | Absolute value match against the line flags AND’ed against and_mask and then OR’ed against or_value. ie. ((flags & and_mask) | or_value) == value) |
| LF_MATCH_ANY | Match line flags were any flags contained within the and_mask are set, ie. ((flags & and_masK) != 0). |
The find_line_flag() primitive returns the matched line number, 0 if not suitable match was found, otherwise -1 on error, for example invalid parameters.
int find_marker( [int marker = L_MARKED] )
Locate next marker.
The find_marker() primitive positions the cursor at the next line which has a user defined marker enabled. On successful completion the marker is removed.
marker is the optional marker against which to search, by default L_MARKED. Only L_MARKED or one of the L_USERx definitions maybe be specified, if other bits or more then one user bit is stated the search shall not succeed.
The find_marker() primitive returns 1 on success and 0 if no additional markers exist.
The marker parameter is a GriefEdit extension.
int goto_bookmark( int bookid = NULL, [int &bufnum], [int &line], [int &column] )
Seek a bookmark.
The goto_bookmark() primitive changes the current buffer and cursor location to the values associated with the named bookmark.
bookid is the unique identifier or name associated with the bookmark; any valid integer may be used as the identifier. If omitted the user shall be prompted for the bookmark identifier.
Go to bookmark:
If any of the arguments bufnum, line or column are specified, these are modified to contain the related bookmark values without effecting the current buffer or location. If all are omitted the bookmark is applied, updating the buffer and/or cursor location as required.
| bookid | Bookmark identifier. |
| bufnum | Optional integer reference, if specified shall be populated with the associate buffer number. |
| line | Optional integer reference, if specified shall be populated with the buffer line number. |
| column | Optional integer reference, if specified shall be populated with the buffer column number. |
The goto_bookmark() primitive returns a non-zero value and populate any of the supplied arguments bufnum, line and col. Otherwise on error returns zero and a related error shall be displayed.
No such bookmark
goto_bookmark: No such buffer
The following two examples deal with the bookmark labelled as 9.
Retrieves the bookmark definition and echos the details to the user.
int buf, line, column;
goto_bookmark(9, buf, line, column);
message("bookmark: buf=%d, %d/%d", buf, line, column);
Applies the bookmark definition.
goto_bookmark(9);
n/a
int inq_attribute( [int &normal], [int bufnum] )
Retrieve the current attributes.
The inq_attribute() primitive retrieves the text and optionally the normal attribute for the specified buffer bufnum.
| normal | Optional integer reference, if stated is populated with the clear/normal attribute value. |
| bufnum | Optional buffer number, if omitted the current buffer shall be referenced. |
The inq_attribute() primitive returns the current text attribute, otherwise -1 on error.
A GriefEdit extension.
int inq_buffer_flags( [int bufnum], [string flag|int set = 1], [string ~flags] )
Retrieve buffer flags.
The inq_buffer_flags() primitive retrieves one of the set of flags associated with the specific buffers, see Buffer Flags.
| bufnum | Optional buffer number, if omitted the current buffer shall be referenced. |
| flag/set | Optional internal set identifier, if omitted the primary set(1) shall be referenced. |
| ... | Optional string of comma separated flag names. |
The following table summaries the existing flags, for additional on a specific flag consult the set_buffer_flags primitive.
The inq_buffer_flags() primitive returns the value associated with the selected set of flags.
The string flag parameter variant is a GRIEF extension.
Many of the flags are GRIEF specific; CRiSP ™ has a similar primitive yet as the two were developed independently features differ.
string inq_buffer_title( [int bufnum] )
Retrieve a buffer title.
The inq_buffer_title() primitive retrieves the title associated with the specified buffer.
| bufnum | Optional buffer number, if omitted the current buffer shall be referenced. |
String containing the current buffer title.
n/a
int inq_buffer_type( [int bufnum], [string &desc], [string &encoding] )
Retrieve buffer type.
The inq_buffer_type() primitive retrieves the buffer type of the buffer bufnum.
| bufnum | Optional buffer number, if omitted the current buffer shall be referenced. |
| desc | Optional string variable reference to be populated with the buffer encoding description. |
| encoding | Optional string variable reference to be populated with the buffers character encoding name. |
The inq_buffer_type() primitive returns on the following manifest constants representing the base encoding of the referenced buffer.
The following manifest constants define the available Buffer Types.
| Constant |
Description |
|---|---|
| BFTYP_UNKNOWN |
Unknown buffer type. |
| BFTYP_UNIX |
Unix, LF line termination. |
| BFTYP_DOS |
DOS, CF/LF line termination. |
| BFTYP_MAC |
Old style MAX, CR termination. |
| BFTYP_BINARY |
Binary. |
| BFTYP_ANSI |
ANSI. |
| BFTYP_EBCDIC |
EBCDIC. |
| BFTYP_UTF8 |
UTF8. |
| BFTYP_UTF16 |
UTF16/USC2. |
| BFTYP_UTF32 |
UTF32/USC4. |
| BFTYP_UTFEBCDIC |
UTF8/EBCDIC. |
| BFTYP_BOCU1 |
Binary Ordered Compression for Unicode. |
| BFTYP_SCSU |
Standard Compression Scheme for Unicode. |
| BFTYP_UTF7 |
7-bit Unicode Transformation Format. |
| BFTYP_GB |
GB. |
| BFTYP_BIG5 |
BIG5. |
| BFTYP_ISO2022 |
ISO-2022. |
| BFTYP_SBCS |
Single Byte. |
| BFTYP_DBCS |
Double Byte. |
| BFTYP_MBCS |
Multi-Byte (Non Unicode). |
| BFTYP_OTHER |
Other supported. |
| BFTYP_UNSUPPORTED |
Known file-type, yet no internal support. |
n/a
int inq_byte_pos( [int bufnum], [int line], [int col], [int flags] )
Get current position in buffer stream.
The inq_byte_pos() primitive is reserved for future compatibility.
The inq_byte_pos() primitive calculates and returns the byte offset from the start of the specified buffer with the first byte within the underlying buffer being at offset 0.
This primitive is similar the native library function tell.
| bufnum | Optional buffer number, if omitted the current buffer shall be referenced. |
| line | Optional line number. |
| col | Optional column. |
| flags | Offset origin flag, omitted when 0x00. |
The inq_byte_pos() primitive returns the current value of the file-position indicator for the associated buffer measured in bytes from the beginning of the file. Otherwise, it returns -1 on error.
n/a
string inq_encoding( [int bufnum] )
Retrieve a buffers character encoding.
The inq_encoding() primitive retrieves the character encoding associated with the referenced buffer. See set_encoding for possible encodings.
| bufnum | Optional buffer number, if omitted the current buffer shall be referenced. |
The inq_encoding() primitive returns the associated encoding.
A GriefEdit extension.
int inq_file_change( [int bufnum] )
Determine state of underlying file.
The inq_file_change() primitive determines the state of the file which underlies the specified buffer bufnum. This primitive checks whether the associated file has been modified or deleted.
| bufnum | Optional buffer number, if omitted the current buffer shall be referenced. |
The inq_file_change() primitive returns the reason code for the file state change.
| 0 | No change. |
| 1 | File status detected; possible in-place changes. |
| 2 | File modified, size differences detected. |
| 3 | Underlying file does not exist (i.e. has been deleted). |
| -1 | Unknown error, the cause of the error condition can be derived from the system return code (See: errno). |
A GriefEdit extension.
int inq_indent( [int bufnum] )
Get current indentation settings.
The inq_indent() primitive retrieves the current buffer indentation of the specified buffer bufnum.
| bufnum | Optional buffer number, if omitted the current buffer shall be referenced. |
Returns the non-zero indentation value if indentation is active, otherwise 0.
A GriefEdit extension.
int inq_line_flags( [int bufnum], [int lineno], [int& iflags] )
Retrieve a lines associated flags.
The inq_line_flags() primitive retrieves the flags associated with the specified line.
The line flags was a set of 32 bit values, with the upper 16 bits being defined for GriefEdit usage and lower 16 bits for user/macro usage.
| bufnum | Optional buffer number, if omitted the current buffer shall be referenced. |
| lineno | Line number within the selected buffer, otherwise if omitted the current line is referenced. |
| iflags | Optional storage for the associated internal flags. |
Associated line flags.
Internal flags are an GriefEdit extension.
int inq_line_length( [int bufnum] )
Determine the longest line length.
The inq_line_length() primitive determines the length of the longest line within the specified buffer bufnum.
The calculate line length corresponds to the logical column position at the end of the line, taking into account any tabs and control characters.
If the designated buffer contains a marked region, then only the lines within the marked region are including within the result.
| bufnum | Optional buffer number, if omitted the current buffer shall be referenced. |
The inq_line_length() primitive returns the longest line within the referenced buffer or region, otherwise -1 on error.
Unlike BRIEF the longest current line is returned. BRIEF returned the upper global line length rounded up the the next multiple of 16, for example 202 would have been rounded to 208, not a buffer specific value.
int inq_lines( [int bufnum] )
Retrieve the line count.
The inq_lines() primitive returns the current line number of the specified buffer bufnum.
| bufnum | Optional buffer number, if omitted the current buffer shall be referenced. |
The inq_lines() primitive returns the line count within the referenced buffer, otherwise -1 on error.
n/a
int inq_margins( [int bufnum], [int &left], [int &right], [int &style], [int &colorcolumn], [int global = TRUE] )
Retrieve buffer formatting margins.
The inq_margins() primitive retrieves one or more of the specified buffers bufnum current margins.
| bufnum | Optional buffer number, if omitted the current buffer shall be referenced. A negative bufnum (e.g. -1) shall retrieve the global margin parameters, which are applied when no buffer specific margin has been set. |
| left | Optional left margin. |
| right | Optional right margin. |
| style | Optional justification style. |
| colorcolumn | Optional colour column. |
| global | Optional integer flag, if given as FALSE when retrieving buffer margins the global settings shall not be applied when no buffer specific value is available. |
The inq_margins() primitive returns 0 on success, otherwise -1 on error.
A GriefEdit extension.
int inq_modified( [int bufnum] )
Determine a buffers modification status.
The inq_modified() primitive determine whether the specified buffer bufnum has been modified.
| bufnum | Optional buffer number, if omitted the current buffer shall be referenced. |
The following echos to the command prompt the current buffers modification status.
message("Buffer has %sbeen modified.",
inq_modified() ? "" : "not ");The inq_modified() primitive returns the modification status, true when modified otherwise false if the buffer has no changes since loading or the last save.
n/a
int inq_names( [string fullname], [string ext], [string bufname], [int bufnum] )
Retrieve associated buffer names.
The inq_names() primitive retrieves the file and/or buffer names associated with the specified buffer bufnum.
| fullname | Optional string variable reference, if specified shall be populated with the full path name of the underlying file, that is used on write_buffer calls. |
| ext | Optional string variable reference, if specified shall be populated the file extension taken from the full path. |
| bufname | Optional string variable reference, if specified shall be populated with buffer name which is used as the buffer title, see set_buffer_title; which is usually the basename, i.e. full path without the path. |
| bufnum | Optional buffer number, if omitted the current buffer shall be referenced. |
The inq_names() primitive returns 0 on success, otherwise -1 on error.
n/a
int inq_position( [int &line], [int &col] )
Retrieve current buffer position.
The inq_position() primitive retrieves the current cursor position in the current buffer.
| line | Optional integer variable when supplied shall be populated with the current buffer line. |
| col | Optional integer variable when supplied shall be populated with the current buffer column. |
The inq_position() primitive returns 0 if the current position is not past the end of the buffer. Otherwise, the number of lines between the end of the buffer and the current position.
n/a
int inq_process_position( [int &line], [int &column] )
Get position of process buffer.
The inq_process_position() primitive retrieves the current cursor position for the underlying process, this primitive is similar to inq_position.
The process position is used for output from the process; rather than inserting the output from the process where the users cursor is, a separate cursor is maintained instead.
This permits the user to move around the buffer whilst the process is generating output without the process output being sprinkled through the buffer.
| line | Optional integer variable to be populated with the cursor line. |
| column | Optional integer variable to be populated with the cursor row. |
The inq_process_position() primitive returns 0 on sucess, otherwise -1 if the current buffer is not attached to a process.
n/a
string|list inq_ruler( [int bufnum], [int min_count], [int aslist = FALSE] )
Retrieves the ruler specification.
The inq_ruler() primitive retrieves the effective indentation specification of the current buffer.
| bufnum | Optional buffer number, if omitted the current buffer shall be referenced. |
| min_count | Optional integer, allows the specification of the minimum number of tab points which shall be presented within the returned specification. |
| aslist | Optional integer boolean flags, if TRUE the tab specification is returned in the form of a list of integers, otherwise by default as a string specification. |
The inq_ruler() primitive either returns a space separated string or an integer list containing the current indentation specification; both are suitable for use by set_ruler.
A GriefEdit extension.
int inq_system( [int bufnum] )
Determine if buffer is a system buffer.
The inq_system() primitive determines whether the specified buffer bufnum is marked as a system buffer.
System buffers do not appear in buffer lists, are not editable by users and are handled specially by many macros. System buffer are generally utilised by macros for internal work pads.
| bufnum | Optional buffer number, if omitted the current buffer shall be referenced. |
The inq_system() primitive returns non-zero if the associated buffer is a system buffer, otherwise 0 if the buffer is a normal buffer.
n/a
int inq_tab( [int bufnum] )
Derive the tab increment.
The inq_tab() primitive derives the tab increment in force at the current cursor position.
| bufnum | Optional buffer number, if omitted the current buffer shall be referenced. |
Returns the current tab increment, otherwise the default of 8 if none is active.
An GriefEdit extension.
string|list inq_tabs( [int bufnum], [int min_count], [int aslist = FALSE] ))
Retrieves the buffer tab specification.
The inq_tabs() primitive retrieves the effective tabs specification of the current buffer.
| bufnum | Optional buffer number, if omitted the current buffer shall be referenced. |
| min_count | Optional integer, allows the specification of the minimum number of tab points which shall be presented within the returned specification. |
| aslist | Optional integer boolean flags, if TRUE the tab specification is returned in the form of a list of integers, otherwise by default as a string specification. |
The inq_tabs() primitive either returns a space separated string or an integer list containing the current tabs specification; both are suitable for use by tabs.
A GriefEdit extension.
int inq_terminator( [int bufnum], [string &term] )
Retrieve a buffers line terminator.
The inq_terminator() primitive retrieves the line terminator of the specified buffer bufnum.
| bufnum | Optional buffer number, if omitted the current buffer shall be referenced. |
| term | Optional string variable reference, to be populated with the line terminator of referenced buffer. |
The inq_termintor() primitive returns the line terminator type of the specified buffer (See: set_terminator), otherwise -1 on error.
A GriefEdit extension.
int inq_time( [int bufnum], [int &ctime] )
Retrieve the last modification time.
The inq_time() primitive returns the time at which the last modification occurred of the specified buffer bufnum, represented by the number seconds since the beginning of the current edit session.
| bufnum | Optional buffer number, if omitted the current buffer shall be referenced. |
| ctime | Optional integer value reference, if specified shall be populated with the associated system time, being the number of second since 1970/01/01 UTC. |
The inq_time() primitive returns the time in seconds of last modification, 0 if the buffer has not been modified during the current edit session, otherwise -1 if the buffer is invalid.
n/a
int mark_line( int flag, [int toggleall], [int bufnum], [int lineno = 0], [int marker = L_MARKED] )
Create a line marker.
The mark_line primitive controls the value of the user defined line marker within the current buffer. This mark maybe be utilised by macro developers to maintain a collection of lines on which can then can be queried using find_marker() for additional processing.
The flags parameter controls the mark value; if non-zero true then the marker is set otherwise it is cleared. When toggleall is stated then the mark status of all lines is toggled, ignoring the flag specification.
bufnum and lineno allow explicit buffer and line number references to be stated, otherwise if omitted the current buffer and/or associated line number shall be used.
marker is the optional marker against which to search, by default L_MARKED. Only L_MARKED or one of the L_USERx definitions maybe be specified.
Markers are only a temporary resource which maybe cleared when line are modified, deleted etc.
The mark_line primitives returns 1 if the marker was already set, 0 if the marker was not set, otherwise -1 when beyond the end of the buffer.
The options bufnum, lineno and marker are GriefEdit extensions.
string mode_string( [int mode], [int format = 0], [string path] )
Conversion stat mode to a string representation.
The mode_string() primitive decodes the specified mode into a human readable form using a style similar to ls long listing format output detailing type and permissions, for example
drwxr-xr-x-
The decoded mode string consists of a ten character string, using the following format ((see File Modes ))
<type> <owner> <group> <other> <sticky>
The first character indicates the file type and is not related to permissions, when format is omitted or (0) shall be on of the following:
| ’d’ | Directory. |
| ’c’ | Character-device. |
| ’b’ | Block-device. |
| ’l’ | Link. |
| ’p’ | Fifo/pipe. |
| ’s’ | Sockets. |
| ’n’ | Name. |
| ’D’ | Door. |
| ’-’ | Normal. |
The alternative format shall be used when format is given as a non-zero value. In addition if specified source shall be utilised to verify the status of the link.
| ’/’ | Directories. |
| ’-’ | Character devices. |
| ’+’ | Block devices. |
| ’~’ | Directory link. |
| ’!’ | Broken link. |
| ’@’ | Link. |
| ’|’ | Fifo/pipe. |
| ’=’ | Sockets. |
| ’$’ | Name/door. |
| ’*’ | Executable. |
| ’ ‘ | Normal (space). |
Following are three permission sets defining the user, group and other access rights.
Each of the three characters represent the read, write, and execute permissions for each of the groups in the order (rwx).
| ’r’ | Read permission. |
| ’w’ | Write permission. |
| ’x’ | Execute permission |
| ’-’ | No associated permission read, write or execute. |
The trailing character details the one of two special attributes.
| ’S’ | S_ISUID is set. |
| ’T’ | S_ISVTX is set. |
| mode | Optional mode specification, otherwise the associate mode of current buffer is decoded. |
| format | Optional format, when stated and non-zero the <type> field is decoded using an alternative form. |
| path | Optional source of the mode, is supplied shall be utilised to verify the status of links. |
Returns the decoded mode string.
A GriefEdit extension.
int next_buffer( [int sysflag = 0], [int previous], [int tab] )
Identifier of the next buffer.
The next_buffer() primitive retrieves the buffer identifier of the next buffer after the current buffer in the buffer list, optionally filtering system buffers.
The buffer list, which is maintained by the GRIEF kernel, is a circular list of all buffers. Upon the end of list being reached, the first buffer on the list is returned as the next.
The next_buffer primitive does not alter the current buffer, the set_buffer can be used to select the returned buffer.
| sysflag | Optional system buffer filter selection. If either omitted or zero system buffers shall be filtered from the returned identifiers. Otherwise all buffers including system shall be returned. |
| prev | Optional boolean flag, if stated as non-zero then the previous buffer in the buffer list is retrieved. |
| tab | Reserved for future use; tab identifier. |
The next_buffer() primitive returns the buffer identifier of the next or previous buffer.
n/a
previous_buffer, set_buffer, create_buffer, inq_buffer, inq_system
int previous_buffer( [int sysflag = 0], [int tab] )
Identifier of the previous buffer.
The previous_buffer() primitive retrieves the buffer identifier of the previous buffer after the current buffer in the buffer list, optionally filtering system buffers.
The buffer list, which is maintained by the GRIEF kernel, is a circular list of all buffers. Upon the beginning of list being reached, the last buffer on the list is returned as the previous.
The previous_buffer primitive does not alter the current buffer, the set_buffer can be used to select the returned buffer.
| sysflag | Optional system buffer filter selection. If either omitted or zero system buffers shall be filtered from the returned identifiers. Otherwise all buffers including system shall be returned. |
| tab | Reserved for future use; tab identifier. |
The previous_buffer() primitive returns the buffer identifier of the previous buffer.
n/a
next_buffer, set_buffer, create_buffer, inq_buffer, inq_system
int set_attribute( [int|string text], [int|string normal], [int bufnum] )
Set the color attributes.
The set_attribute() primitive set the text and/or normal attributes for the specified buffer bufnum.
| text | Optional text attribute either by value or name. |
| normal | Optional clear/normal attribute either by value or name. |
| bufnum | Optional buffer number, if omitted the current buffer shall be referenced. |
The set_attribute() primitive returns the previous text attribute, otherwise -1 on error.
A GriefEdit extension.
int set_buffer( int bufnum )
Set the current buffer.
The set_buffer() primitive makes the buffer identifier specified by bufnum the current buffer, without effecting the current window. The current is the one referenced by all buffer operations which are not given an explicit buffer identifier.
Generally set_buffer is utilised in one of two ways;
The set_buffer() primitive unlike edit_file does not cause any registered macros to be executed.
The referenced buffer does not always need to be attached to a window nor the one currently associated with the current window set_window, yet upon macro exit the current buffer and current window should be attached otherwise the side-effects may be disastrous.
| bufnum | Buffer identifier to be selected. |
The set_buffer() primitive returns the identifier of the previous current buffer otherwise -1 if an invalid buffer identifier was stated.
On failure the following diagnostics message shall be echoed on the command prompt.
'set_buffer': no such buffer
n/a
void set_buffer_flags( [int bufnum], [string|int or_mask], [string|int and_mask], [int set = 1] )
Set buffer flags.
The set_buffer_flags() primitive modifies the internal flags associated with the specified buffer, see Buffer Flags.
If specified one or more flags shall be cleared using the and_mask, in additional one or more flags are set using the or_mask.
Each buffer maintains several sets of integer flags which can be modified. Against the selected flag set the optional and_mask (clear) and then the optional or_mask (set) is applied.
| bufnum | Optional buffer number, if omitted the current buffer shall be referenced. |
| set_mask | Optional mask of flags to set. May either be an integer of AND’ed together flag constants, or alternatively a string of comma separated flag names. |
| clear_mask | Optional mask of flags to clear. May either be an integer of AND’ed together flag constants, or alternatively a string of comma separated flag names. |
| set | Optional integer stating the flag set to be modified, if omitted defaults to the primary set(1). |
nothing
The string mask variants and set parameter are GRIEF extension.
Many of the flags are GRIEF specific; CRiSP ™ has a similar primitive yet as the two were developed independently features differ.
int set_buffer_title( [int bufnum], [string title] )
Set a buffers title.
The set_buffer_title() primitive sets the buffer title of the stated buffer otherwise the current buffer when omitted. The specified title is displayed on the top edge of the buffers associated window.
| bufnum | Optional buffer number, if omitted the current buffer shall be referenced. |
| title | Optional string value of the title to associated. If omitted specified, then the buffer title is remove with the buffers underlying filename being used. |
The set_buffer_title() primitives return zero on success, otherwise -1 if the specified buffer does not exist.
n/a
int set_buffer_type( [int bufnum], [int type = NULL], [string encoding = NULL] )
Set the buffer storage type.
The set_buffer_type() primitive optionally set the buffer type and/or the character encoding associated with the specified buffer.
Note that the specified encoding has priority over the buffer type, in that an incompatible encoding with the stated type or pre-existing buffer type shall imply the default buffer type associated with the encoding. The inq_buffer_type() primitive should be used to determine the resulting buffer type on completion.
| bufnum | Optional buffer number, if omitted the current buffer shall be referenced. |
| type | Optional integer buffer type which states the basic buffer encoding include an implied line termination. |
| encoding | Optional string which sets the specific buffer encoding beyond the buffer type, for example the page code utilized by a BFTYPE_DOS buffer. |
The following manifest constants define the available Buffer Types.
| Constant |
Description |
|---|---|
| BFTYP_UNKNOWN |
Unknown buffer type. |
| BFTYP_UNIX |
Unix, LF line termination. |
| BFTYP_DOS |
DOS, CF/LF line termination. |
| BFTYP_MAC |
Old style MAX, CR termination. |
| BFTYP_BINARY |
Binary. |
| BFTYP_ANSI |
ANSI. |
| BFTYP_EBCDIC |
EBCDIC. |
| BFTYP_UTF8 |
UTF8. |
| BFTYP_UTF16 |
UTF16/USC2. |
| BFTYP_UTF32 |
UTF32/USC4. |
| BFTYP_UTFEBCDIC |
UTF8/EBCDIC. |
| BFTYP_BOCU1 |
Binary Ordered Compression for Unicode. |
| BFTYP_SCSU |
Standard Compression Scheme for Unicode. |
| BFTYP_UTF7 |
7-bit Unicode Transformation Format. |
| BFTYP_GB |
GB. |
| BFTYP_BIG5 |
BIG5. |
| BFTYP_ISO2022 |
ISO-2022. |
| BFTYP_SBCS |
Single Byte. |
| BFTYP_DBCS |
Double Byte. |
| BFTYP_MBCS |
Multi-Byte (Non Unicode). |
| BFTYP_OTHER |
Other supported. |
| BFTYP_UNSUPPORTED |
Known file-type, yet no internal support. |
The set_buffer_type() primitive returns the 0 on success , otherwise -1 on error.
A GriefEdit extension.
int set_encoding( [string encoding = NULL], [int bufnum = NULL] )
Set a buffers character encoding.
The set_encoding() primitive sets or clears the character encoding associated with the referenced buffer.
The following table lists the character encodes which maybe available dependent on build options and system support.
| Name |
Buffer Type |
Code Page |
Description |
|---|---|---|---|
| US-ASCII |
BFTYP_SBCS |
646 |
ANSI/ASCII |
| ISO-8859-1 |
BFTYP_SBCS |
28591 |
Western Europe |
| ISO-8859-2 |
BFTYP_SBCS |
28592 |
Western and Central Europe |
| ISO-8859-3 |
BFTYP_SBCS |
28593 |
Western Europe and South European (Turkish, Maltese plus Esperanto) |
| ISO-8859-4 |
BFTYP_SBCS |
28594 |
Western Europe and Baltic countries (Lithuania, Estonia and Lapp) |
| ISO-8859-5 |
BFTYP_SBCS |
28595 |
Cyrillic alphabet |
| ISO-8859-6 |
BFTYP_SBCS |
28596 |
Arabic |
| ISO-8859-7 |
BFTYP_SBCS |
28597 |
Greek |
| ISO-8859-8 |
BFTYP_SBCS |
28598 |
Hebrew |
| ISO-8859-9 |
BFTYP_SBCS |
28599 |
Western Europe with amended Turkish character set |
| ISO-8859-10 |
BFTYP_SBCS |
Western Europe with rationalised character set for Nordic languages |
|
| ISO-8859-13 |
BFTYP_SBCS |
28603 |
Baltic languages plus Polish |
| ISO-8859-14 |
BFTYP_SBCS |
Celtic languages (Irish Gaelic, Scottish, Welsh |
|
| ISO-8859-15 |
BFTYP_SBCS |
28605 |
Euro sign and other rationalisations to ISO 8859-1 |
| ISO-8859-16 |
BFTYP_SBCS |
Central, Eastern and Southern European languages |
|
| CP037 |
BFTYP_EBCDIC |
37 |
EBCDIC-US |
| CP038 |
BFTYP_EBCDIC |
38 |
EBCDIC-INT |
| CP930 |
BFTYP_EBCDIC |
930 |
|
| CP1047 |
BFTYP_EBCDIC |
1047 |
|
| UTF-8 |
BFTYP_UTF8 |
65001 |
|
| UTF-16 |
BFTYP_UTF16 |
||
| UTF-16be |
BFTYP_UTF16 |
1201 |
|
| UTF-16le |
BFTYP_UTF16 |
1200 |
|
| UTF-32 |
BFTYP_UTF32 |
||
| UTF-32be |
BFTYP_UTF32 |
||
| UTF-32le |
BFTYP_UTF32 |
||
| BOCU-1 |
BFTYP_BOCU1 |
||
| SCSU |
BFTYP_SCSU |
||
| UTF-7 |
BFTYP_UTF7 |
65002 |
|
| UTF-2 |
BFTYP_UCS2 |
BFTYP_UTF16 aliases |
|
| UTF-2be |
BFTYP_UCS2 |
||
| UTF-2le |
BFTYP_UCS2 |
||
| UTF-4 |
BFTYP_UCS4 |
BFTYP_UTF32 aliases |
|
| UTF-4be |
BFTYP_UCS4 |
||
| UTF-4le |
BFTYP_UCS4 |
||
| cp437 |
BFTYP_SBCS |
437 |
OEM/US, ASCII |
| cp737 |
BFTYP_SBCS |
737 |
Greek, ISO-8859-7 |
| cp775 |
BFTYP_SBCS |
775 |
Baltic |
| cp850 |
BFTYP_SBCS |
850 |
Like ISO-8859-4 |
| cp852 |
BFTYP_SBCS |
852 |
Like ISO-8859-1 |
| cp855 |
BFTYP_SBCS |
855 |
Like ISO-8859-2 |
| cp857 |
BFTYP_SBCS |
857 |
Like ISO-8859-5 |
| cp860 |
BFTYP_SBCS |
860 |
Like ISO-8859-9 |
| cp861 |
BFTYP_SBCS |
861 |
Like ISO-8859-1 |
| cp862 |
BFTYP_SBCS |
862 |
Like ISO-8859-1 |
| cp863 |
BFTYP_SBCS |
863 |
Like ISO-8859-8 |
| cp865 |
BFTYP_SBCS |
865 |
Like ISO-8859-1 |
| cp866 |
BFTYP_SBCS |
866 |
Like ISO-8859-5 |
| cp869 |
BFTYP_SBCS |
869 |
Greek, like ISO-8859-7 |
| cp874 |
BFTYP_SBCS |
874 |
Thai |
| cp1046 |
BFTYP_SBCS |
1046 |
Arabic DOS code |
| windows-1250 |
BFTYP_SBCS |
1250 |
Central European languages that use Latin script (Polish, Czech etc). |
| windows-1251 |
BFTYP_SBCS |
1251 |
Cyrillic alphabets |
| windows-1252 |
BFTYP_SBCS |
1252 |
Western languages |
| windows-1253 |
BFTYP_SBCS |
1253 |
Greek |
| windows-1254 |
BFTYP_SBCS |
1254 |
Turkish |
| windows-1255 |
BFTYP_SBCS |
1255 |
Hebrew |
| windows-1256 |
BFTYP_SBCS |
1256 |
Arabic |
| windows-1257 |
BFTYP_SBCS |
1257 |
Baltic languages |
| windows-1258 |
BFTYP_SBCS |
1258 |
Vietnamese |
| Mac-Arabic |
BFTYP_SBCS |
||
| Mac-Celtic |
BFTYP_SBCS |
||
| Mac-Centeuro |
BFTYP_SBCS |
||
| Mac-Croatian |
BFTYP_SBCS |
||
| Mac-Cyrillic |
BFTYP_SBCS |
||
| Mac-Devanaga |
BFTYP_SBCS |
||
| Mac-Dingbats |
BFTYP_SBCS |
||
| Mac-Farsi |
BFTYP_SBCS |
||
| Mac-Gaelic |
BFTYP_SBCS |
||
| Mac-Greek |
BFTYP_SBCS |
||
| Mac-Gujarati |
BFTYP_SBCS |
||
| Mac-Gurmukhi |
BFTYP_SBCS |
||
| Mac-Hebrew |
BFTYP_SBCS |
||
| Mac-Iceland |
BFTYP_SBCS |
||
| Mac-Inuit |
BFTYP_SBCS |
||
| Mac-Roman |
BFTYP_SBCS |
||
| Mac-Romanian |
BFTYP_SBCS |
||
| Mac-Thai |
BFTYP_SBCS |
||
| Mac-Turkish |
BFTYP_SBCS |
||
| cp10000 |
BFTYP_SBCS |
10000 |
MacRoman |
| cp10006 |
BFTYP_SBCS |
10006 |
MacGreek |
| cp10007 |
BFTYP_SBCS |
10007 |
MacCyrillic |
| cp10029 |
BFTYP_SBCS |
10029 |
MacLatin2 |
| cp10079 |
BFTYP_SBCS |
10079 |
MacIcelandic |
| cp10081 |
BFTYP_SBCS |
10081 |
MacTurkish |
| KOI8-R |
BFTYP_SBCS |
20866 |
Russian, using cynrillic alphabet. |
| KOI8-U |
BFTYP_SBCS |
21866 |
Ukrainian, using cynrillic alphabet. |
| KOI8-T |
BFTYP_SBCS |
Ukrainian |
|
| PT154 |
BFTYP_SBCS |
Ukrainian |
|
| KOI7 |
BFTYP_SBCS |
Ukrainian |
|
| MIK |
BFTYP_SBCS |
0 |
Bulgarian |
| ISCII |
BFTYP_SBCS |
Indian Script Code for Information Interchange. |
|
| TSCII |
BFTYP_SBCS |
Tamil Script Code for Information Interchange. |
|
| VSCII |
BFTYP_SBCS |
Vietnamese Standard Code for Information Interchange. |
|
| DEC-MCS |
BFTYP_SBCS |
-2 |
|
| DEC-KANJI |
BFTYP_SBCS |
-2 |
|
| DEC-HANYU |
BFTYP_SBCS |
-2 |
|
| HP-Roman8 |
BFTYP_SBCS |
-3 |
|
| HP-Arabic8 |
BFTYP_SBCS |
-3 |
|
| HP-Greek8 |
BFTYP_SBCS |
-3 |
|
| HP-Hebrew8 |
BFTYP_SBCS |
-3 |
|
| HP-Turkish8 |
BFTYP_SBCS |
-3 |
|
| HP-Kana8 |
BFTYP_SBCS |
-3 |
|
| GB2312 |
BFTYP_GB |
Guojia Biaozhun/Simplified Chinese. |
|
| GBK |
BFTYP_GB |
936 |
Chinese/GB (CP936). |
| GB18030 |
BFTYP_GB |
Chinese National Standard/GB. |
|
| HZ |
BFTYP_HZ |
RFC1843, Arbitrarily Mixed Chinese and ASCII. |
|
| Big5 |
BFTYP_BIG5 |
950 |
Chinese/Big-5 (CP950). |
| Big5-5E |
BFTYP_BIG5 |
Big-5. |
|
| Big5-2003 |
BFTYP_BIG5 |
Big-5. |
|
| Big5-HKSCS |
BFTYP_BIG5 |
Big-5/Hong Kong Supplement. |
|
| Shift_JIS |
BFTYP_MBCS |
Shift JIS. |
|
| EUC-JP |
BFTYP_MBCS |
Japan/EUC. |
|
| CP932 |
BFTYP_MBCS |
932 |
Windows-31J. |
| EUC-CN |
BFTYP_MBCS |
Chinese/EUC. |
|
| EUC-TW |
BFTYP_MBCS |
Tawian/EUC. |
|
| EUC-KR |
BFTYP_MBCS |
949 |
Korean/EUC (CP949). |
| ISO-2022-CN |
BFTYP_ISO2022 |
||
| ISO-2022-KK |
BFTYP_ISO2022 |
||
| ISO-2022-KP |
BFTYP_ISO2022 |
| encoding | Optional encoding name, if omitted the encoding is derived from the buffer type (See: set_buffer_type). |
| bufnum | Optional buffer number, if omitted the current buffer shall be referenced. |
nothing
A GriefEdit extension
int set_indent( [int indent], [int bufnum] )
Set the buffers default indentation.
The set_indent() primitive configures the indentation value for the specified buffer, representing the buffers default ruler. Indentation stops are set every indent stops after the last stop, with the first column within a line being column 1.
Indenting does not change the size represented by physical tabbing, it determines the buffers default indentation when a tab-character is self_inserted(), backfilling with either spaces and/or physical tabs dependent on whether or not hard=tabs are enabled (See: use_tab_char).
An indent value of 0, shall disable the buffers indentation setting defaulting to the current tab stop (See: tabs) unless a ruler is also in effect. If omitted the user shall be prompted for a new value as follows:
Enter indent amount:
Note that any user specified ruler (See: set_ruler) shall have priority over both this setting and the tabs configuration.
| indent | Optional buffer indentation, if omitted the user shall be prompted. |
| bufnum | Optional buffer number, if omitted the current buffer shall be referenced. |
The set_indent() primitive returns the applied indentation value, otherwise if the user was prompted and they aborted -1 is returned.
A GriefEdit extension.
int set_line_flags( [int bufnum], [int start], [int end], [int and_mask], [int or_value] )
Associate line flags.
The set_line_flags primitive allows the flags of one or more line within a specific buffer to be modified.
The buffer flags was a set of 32 bit values separated into two namespaces, with the upper 8 bits being defined for user/macro usage and lower bits for system user/macro usage. As such only the lower 16 bits maybe affected by this primitive.
The defines L_USER1 thru L_USER7 maybe used as manifest constants to access the user/macro area.
| bufnum | Buffer number, if omitted the current buffer is referenced. |
| start | Start line number of region within the selected buffer, otherwise if omitted the current line is referenced. |
| end | End of the region within the selected buffer, otherwise if omitted the current line is referenced as such one line shall be affected. |
| and_mask | Value AND’ed with the flags of matched lines. |
| or_value | Value OR’ed with the flags of matched lines. |
GriefEdit enforces two flag namespaces system and user each of 16 bits with only the lower user 16 bits being read-write, whereas CRiSP ™ allows read-write to all 32 bits.
The set_line_flags primitive returns the number at lines which were modified.
int set_margins( [int bufnum], [int left = NULL], [int right = NULL], [int style = NULL], [int colorcolumn = NULL] )
Set buffer formatting margins.
The set_margins() primitive configures one or more of the specified buffers bufnum margins.
| bufnum | Optional buffer number, if omitted the current buffer shall be referenced. A negative bufnum (e.g. -1) shall set the global margin parameters, which are applied when no buffer specific margin has been set. |
| left | Optional integer left margin. A non-positive value shall clear the buffer specific margin. |
| right | Optional integer right margin. A non-positive value shall clear the buffer speific margin. |
| style | Optional justification style. |
| colorcolumn | Optional colour column. |
The set_margins() primitive returns 0 on success otherwise -1 on error.
A GriefEdit extension.
int set_process_position( [int line], [int column] )
Set process insertion position.
The set_process_position() primitive sets the line and/or column associated with the input from a subprocess.
Processes maintain their own independent input in the buffer so that it is easier to write macros which manipulate subprocesses.
| 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. |
The set_process_position() primitive returns 0 on success, otherwise -1 if the current buffer is not attached to a process.
n/a
int set_ruler( [int bufnum], [list|string|int ...] )
Configure the buffer ruler.
The set_ruler() primitive configures the indentation ruler of the current buffer to the positions specified within ruler.
The primitive supports a number of alternative specification forms being either a set of integer parameters, a single string parameter containing space/comma separated numbers or a single list of integers. If omitted the ruler is cleared.
Regardless of the form each should be a sequence of columns in ascending order. The indentations for the reminder of the line are set using the difference between the last two stated positions, starting at the last specified.
| bufnum | Optional buffer number, if omitted the current buffer shall be referenced. |
| ruler | Optional ruler specification, being the sequence of columns in ascending order otherwise the ruler is cleared. |
The set_ruler() primitive returns the number of applied ruler points, 0 is the ruler was cleared otherwise -1 on error.
A GriefEdit extension.
int set_tab( [int increment], [int bufnum] )
Derive the buffer tab stops.
The set_tab() primitive derives a tabs configuration from the specified tab increment increment. If omitted the user shall be prompted for the tab increment.
Enter tab amount:
| increment | Optional positive integer, stating the tab increment if omitted the user shall be prompted. |
| bufnum | Optional buffer number, if omitted the current buffer shall be referenced. |
Returns the applied tab increment, otherwise -1 on error.
A GriefEdit extension.
int set_terminator( [int bufnum], int|string term )
Set a buffers line terminator.
The set_terminator() primitive retrieves the line terminator of the specified buffer bufnum.
| bufnum | Optional buffer number, if omitted the current buffer shall be referenced. |
| term | Either the integer enumeration or string description of the line terminator to be assigned. |
| Constant |
Description |
|---|---|
| LTERM_UNDEFINED |
Unknown/default. |
| LTERM_NONE |
<none> (i.e. binary) |
| LTERM_UNIX |
CR/LF |
| LTERM_DOS |
LF |
| LTERM_MAC |
CR |
| LTERM_NEL |
NEL |
| LTERM_UCSNL |
Unicode next line |
| LTERM_USER |
User defined |
The set_terminator() primitive returns 1 is the line terminator was modified, 0 when no change occurred, otherwise -1 on error.
A GriefEdit extension.
int sort_buffer( [int bufnum], [string|int comparator = 0], [int start], [int end], [int type = 3] )
Sort buffer content.
The sort_buffer() primitive sorts the lines in the current buffer or the buffer specified by bufnum. If the buffer specified has a region marked, then only those lines within the region are sorted.
By default lines are sorted alphabetically yet the sort can be modified using the user specified macro or using one of the predefined system sort macros.
| bufnum | Optional buffer number, if omitted the current buffer shall be referenced. |
| comparator | Optional string comparison macro or integer direction. A string value states the comparison macro to be executed. Whereas an integer value states the direction, with zero selecting the built “sort_buffer::forward” comparator and a non-zero value selecting “sort_buffer::backwards”. If omitted the comparator defaults to forward. |
| start | Optional integer line number stating the start of the region to be sorted, if omitted the buffer top is used unless a marked region is active. |
| end | Optional integer line number stating the end of the region to be sorted, if omitted the buffer end is used unless a marked region is active. |
| type | Optional integer stating the sort type, being |
| 1 | quicksort. |
| 2 | mergesort |
| 3 | heapsort (default). |
The sort_buffer() primitive returns the number of lines sorted, otherwise a negative value on error.
Second argument allowing either a sort-order or user specified callback plus type selection are GriefEdit extensions.
int tabs( [string tabs | list tabs | int tab, ...] )
Set buffer tab stops.
The tabs() primitive configures the tabs of the current buffer to the positions specified within tabs.
The primitive supports a number of alternative specification forms being a set of integer parameters, a single string parameter containing space/comma separated numbers or a single list of integers. If omitted the user shall be prompted for each of the tab points, with an empty reply terminating the sequence as follows:
Enter tab stop (return terminates):
Regardless of the form each should be a sequence of columns in ascending order. Tabs for the reminder of the line are set using the difference between the last two tabs stated, starting at the last specified.
The following sets the first tab at four spaces and all sequence tabs to three resulting in the tabs at (5, 8, 11, 14 ...)
tabs(5, 8);
As the tab primitive allows a number of specification forms, all the following are equivalent;
tabs("5 8");
tabs("5,8");
list ttabs = {5, 8};
tabs(ttabs);| ’tabs’ | Optional tabs specification, being the sequence of columns in ascending order otherwise the user is prompted. |
The tabs() primitive returns the number of applied tab points otherwise if the user was prompted and they aborted -1 is returned.
BRIEF limited the number of unique tab stops at 8, under GriefEdit this limit is 80.
int tagdb_open( string file, [int options], [int background] )
Tag database open.
The tagdb_open() primitive given a pathname for a ctags database, returns a handle being a non-negative integer for use in subsequent database search operations using tagdb_search. The tag database handle shall remain open until <tagtb_close> is executed against the handle.
ctags is a tool which permit easy navigation thru a large set of source files. ctags supports many languages including c, c++ and Java just to name a few.
GriefEdit relies on an external tag file generator. There are many versions of ctags; however, the recommended version is “Exuberant Ctags” available from
http://ctags.sourceforge.net/.
GriefEdit is generally bundled with a recent version within the bin installation folder as extags. Therefore, you would not need to download/install a tag binary to use this feature.
| file | tag database path. |
| options | Optional integer flags, being one or more of the following constants OR’ed together forming open options. |
| background | Optional integer boolean value, if true the database loading shall be moved into the background. |
The tagdb_open() primitive returns the new database descriptor, otherwise -1 if an error occurred.
A GriefEdit extension.
int tagdb_search( int handle, string word, [int flags] )
Tag database search.
The tagdb_search() primitive searches the tag database for symbols matching pattern.
Consult the tags macro source for an example.
| handle | Tag database handle. |
| pattern | String containing the search pattern. |
| flags | Optional integer flags. |
The tagdb_search returns a list containing the search results, otherwise a NULL list on error or no match was found.
A GriefEdit extension.
int write_buffer( [string filename], [int flags], [string encoding] )
Write to buffer content.
The write_buffer() primitive writes the content of the current buffer to its associated file.
| filename | Options string containing the name of the output filename. If omitted then the file is written to the name associated with the current buffer during creation using <<create_buffer>. |
| flags | Optional integer flags, one or more of the following flags OR’ed together control the functions of the write operation. |
| encoding | Optional string containing the character encoding to be utilised within the output file. |
| Constant |
Description |
|---|---|
| WRITE_APPEND |
Append, otherwise overwrite. |
| WRITE_NOTRIGGER |
Do not generate buffer triggers. |
| WRITE_NOREGION |
Ignore any selected region. |
| WRITE_FORCE |
Force write, even if no change. |
| WRITE_BACKUP |
Generate a backup image regardless whether already performed for this edit session. |
| Value |
Description |
|---|---|
| -1 |
Disk space occurred. |
| -2 |
Output file could not be created. |
| -3 |
The output file was created with a different temporary name but could not be renamed to the target file due to permission errors. |
| -4 |
User aborted the attempt to save the file from one of the callback triggers. |
| -5 |
The output buffer does not have a valid filename. |
| -6 |
The originally loaded file has changed its permissions, size or status on disk. This option avoids potentially losing work when someone else has written to the file whilst we were editing it. |
| -7 |
The file is read-only, either due to file writes having been disabled by the command line switch (-R) or the current file permissions. |
In many cases the underlying cause of the error condition can be derived from the system return code (See: errno), for example out of disk space.
Flags are incompatible with CrispEdit™
write_buffer([string filename], [int and_flags], [or_flags])
$Id: $
To send feedback on this topic email: griefedit@gmail.com
Copyright © Adam Young All Rights Reserved.
Attach a buffer to a window.
void attach_buffer( int bufnum )
Create and load a buffer.
int create_buffer( string bufname, [string filename], [int sysflag = FALSE], [int editflags = 0], [string encoding = ""] )
Create or reference a buffer.
int create_nested_buffer( string bufname, [string filename], [int sysflag], [int editflags], [string encoding] )
Delete a buffer.
void delete_buffer( int bufnum )
Delete character.
void delete_char( [int num] )
Delete current line.
void delete_line()
Delete to end-of-line.
void delete_to_eol()
Locate next line with specific flags.
int find_line_flags( [int bufnum], [int lineno], int mode, int and_mask, [int or_value], [int value] )
Locate next marker.
int find_marker( [int marker = L_MARKED] )
Seek a bookmark.
int goto_bookmark( int bookid = NULL, [int &bufnum], [int &line], [int &column] )
Retrieve the current attributes.
int inq_attribute( [int &normal], [int bufnum] )
Retrieve buffer flags.
int inq_buffer_flags( [int bufnum], [string flag|int set = 1], [string ~flags] )
Retrieve a buffer title.
string inq_buffer_title( [int bufnum] )
Retrieve buffer type.
int inq_buffer_type( [int bufnum], [string &desc], [string &encoding] )
Get current position in buffer stream.
int inq_byte_pos( [int bufnum], [int line], [int col], [int flags] )
Retrieve a buffers character encoding.
string inq_encoding( [int bufnum] )
Determine state of underlying file.
int inq_file_change( [int bufnum] )
Get current indentation settings.
int inq_indent( [int bufnum] )
Retrieve a lines associated flags.
int inq_line_flags( [int bufnum], [int lineno], [int& iflags] )
Determine the longest line length.
int inq_line_length( [int bufnum] )
Retrieve the line count.
int inq_lines( [int bufnum] )
Retrieve buffer formatting margins.
int inq_margins( [int bufnum], [int &left], [int &right], [int &style], [int &colorcolumn], [int global = TRUE] )
Determine a buffers modification status.
int inq_modified( [int bufnum] )
Retrieve associated buffer names.
int inq_names( [string fullname], [string ext], [string bufname], [int bufnum] )
Retrieve current buffer position.
int inq_position( [int &line], [int &col] )
Get position of process buffer.
int inq_process_position( [int &line], [int &column] )
Retrieves the ruler specification.
string|list inq_ruler( [int bufnum], [int min_count], [int aslist = FALSE] )
Determine if buffer is a system buffer.
int inq_system( [int bufnum] )
Derive the tab increment.
int inq_tab( [int bufnum] )
Retrieves the buffer tab specification.
string|list inq_tabs( [int bufnum], [int min_count], [int aslist = FALSE] ))
Retrieve a buffers line terminator.
int inq_terminator( [int bufnum], [string &term] )
Retrieve the last modification time.
int inq_time( [int bufnum], [int &ctime] )
Create a line marker.
int mark_line( int flag, [int toggleall], [int bufnum], [int lineno = 0], [int marker = L_MARKED] )
Conversion stat mode to a string representation.
string mode_string( [int mode], [int format = 0], [string path] )
Identifier of the next buffer.
int next_buffer( [int sysflag = 0], [int previous], [int tab] )
Identifier of the previous buffer.
int previous_buffer( [int sysflag = 0], [int tab] )
Print formatted string to stdout.
int print()
Set the color attributes.
int set_attribute( [int|string text], [int|string normal], [int bufnum] )
Set the current buffer.
int set_buffer( int bufnum )
Set buffer flags.
void set_buffer_flags( [int bufnum], [string|int or_mask], [string|int and_mask], [int set = 1] )
Set a buffers title.
int set_buffer_title( [int bufnum], [string title] )
Set the buffer storage type.
int set_buffer_type( [int bufnum], [int type = NULL], [string encoding = NULL] )
Set a buffers character encoding.
int set_encoding( [string encoding = NULL], [int bufnum = NULL] )
Set the buffers default indentation.
int set_indent( [int indent], [int bufnum] )
Associate line flags.
int set_line_flags( [int bufnum], [int start], [int end], [int and_mask], [int or_value] )
Set buffer formatting margins.
int set_margins( [int bufnum], [int left = NULL], [int right = NULL], [int style = NULL], [int colorcolumn = NULL] )
Set process insertion position.
int set_process_position( [int line], [int column] )
Configure the buffer ruler.
int set_ruler( [int bufnum], [list|string|int ...] )
Derive the buffer tab stops.
int set_tab( [int increment], [int bufnum] )
Set a buffers line terminator.
int set_terminator( [int bufnum], int|string term )
Sort buffer content.
int sort_buffer( [int bufnum], [string|int comparator = 0], [int start], [int end], [int type = 3] )
Set buffer tab stops.
int tabs( [string tabs | list tabs | int tab, ...] )
Tag database close.
int tagdb_close( int handle )
Tag database open.
int tagdb_open( string file, [int options], [int background] )
Tag database search.
int tagdb_search( int handle, string word, [int flags] )
Write to buffer content.
int write_buffer( [string filename], [int flags], [string encoding] )
Set the active window.
int set_window( int winnum )
Creates a tiled window.
int create_tiled_window( int lx, int by, int rx, int ty, [int bufnum] )
Create a popup window.
int create_window( int lx, int by, int rx, int ty, [string message] )
Retrieve a buffer identifier.
int inq_buffer( [string filename] )
Buffer load handler.
void _extension( string ext )
Default extension handler.
void _default( string ext )
Register a callback procedure.
int register_macro( int type, string macro, [int local = FALSE] )
Edit a file.
int edit_file( ... )
Delete character to the left of the cursor.
void backspace( [int num = 1] )
Deleted selected region.
int delete_block()
Retrieve existing bookmark list.
list bookmark_list()
Delete a bookmark.
void delete_bookmark( int bookid )
Create or update a bookmark.
int drop_bookmark( [int bookid], [string yesno], [int bufnum], [int line], [int column], [int local = FALSE] )
Last system errno number.
extern int errno;
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] )
Attach a process to a process.
int connect( int mode, string shell = NULL, string cwd = NULL )
Calculate distance to next tab.
int distance_to_tab( [int column] )
Calculate distance to next indent.
int distance_to_indent( [int column] )
Obtain file information.
int stat( [string path], [int size], [int mtime], [int ctime], [int atime], [int mode], [int uid], [string uid2name], [int gid], [string gid2name], [int nlink], [int inode] )
Get symbolic link status.
int lstat( string path, [int size], [int mtime], [int ctime], [int atime], [int mode], [int uid], [string uid2name], [int gid], [string gid2name], [int nlink], [int inode] )
Issue an error message on the command line.
int error( string format, ... )
Display a message on the command line.
int message( string format, ... )
Formatted diagnostics output.
int dprintf( string format, ... )
Configure use of hard/soft tabs.
int use_tab_char( [int|string yesno], [int global = FALSE] )
Sort list.
list sort_list( list lst, [string|int comparator = 0], [int type = 3] )