New Buffer Primitives in Epsilon 10

Lugaru's Epsilon
Programmer's
Editor 14.01

Previous	Up	Next
New File Primitives in Epsilon 10	Changes from Older Versions	New Process Primitives in Epsilon 10

Epsilon User's Manual and Reference > Changes from Older Versions > New EEL Primitives and Subroutines in Epsilon 10 >

New Buffer Primitives in Epsilon 10

to_another_buffer(char *buf)

The to_another_buffer( ) subroutine makes sure that buf is not the current buffer. If it is, the subroutine switches the current window to a different buffer. This subroutine is useful when you're about to delete a buffer.

zeroed buffer (*buffer_on_modify)(); buffer char _buf_readonly;
When a buffer is modified and its call_on_modify flag is set, Epsilon calls the on_modify( ) subroutine. By default, that subroutine calls the normal_on_modify( ) subroutine, which handles preventing modifications to read-only buffers, among other things.

But if the buffer_on_modify buffer-specific function pointer is nonzero for that buffer, on_modify( ) instead calls the subroutine it indicates. That subroutine may wish to call normal_on_modify( ) itself.

One of normal_on_modify( )'s tasks is to handle read-only buffers. There are several types of these, distinguished by the value of the _buf_readonly variable, which if nonzero indicates the buffer is read-only. A value of 1 means the user explicitly set the buffer read-only. The value 2 means Epsilon automatically set the buffer read-only because its corresponding file was read-only.

A value of 3 indicates pager mode; this is just like a normal read-only buffer, but if the user action causing the attempt at buffer modification happens to be the result of the <Space> or <Backspace> keys, Epsilon cancels the modification and pages forward or backward, respectively.

zeroed buffer char buffer_not_saveable;
The buffer-specific variable buffer_not_saveable , if nonzero, indicates that a buffer should not be saved, even if it has an associated file name. Commands like save-all-buffers try to save any modified buffer with an associated file name, but skip buffers marked in this way.

zeroed buffer (*buffer_maybe_break_line)();
The auto-fill minor mode normally calls a function named maybe_break_this_line( ) to break lines. A major mode may set the buffer-specific function pointer buffer_maybe_break_line to point to a different function; then auto-fill mode will call that function instead, for possibly breaking lines as well as for turning auto-fill on or off, or testing its state.

A buffer_maybe_break_line function will be called with one numeric parameter. If 0 or 1, it's being told to turn auto-fill off or on. The function may interpret this request to apply only to the current buffer, or to all buffers in that mode. It should return 0.

If its parameter is 2, it's being asked whether auto-fill mode is on. It should return a nonzero value to indicate that auto-fill mode is on.

If its parameter is 3, it's being asked to perform an auto-fill, if appropriate, triggered by the key in the variable key, which has not yet been inserted in the buffer. It may simply return 1 if the line is not wide enough yet, or after it has broken the line. Epsilon will then insert the key that triggered the filling request. If it returns zero, Epsilon will skip inserting the key that triggered the filling.

int buf_size(int buf) int get_buf_point(int buf) set_buf_point(int buf, int pos)
The buf_size( ) subroutine returns the size in bytes of the specified buffer, indicated by its buffer number. The get_buf_point( ) subroutine returns the value of point in the specified buffer. The set_buf_point( ) subroutine sets point in the specified buffer to the value pos.

simple_re_replace(int dir, char *str, char *repl)
The simple_re_replace( ) subroutine performs a regular expression replacement on the current buffer. It searches through the buffer, starting from the top, and passing dir and str directly to the re_search( ) primitive. It deletes each match and inserts the string repl instead. The replacement text is inserted literally, with no interpolation. If you want to use #1 in your replacement text, get a count of the matches, or other more involved things, call string_replace( ) instead.

mode_default_settings()
The mode_default_settings( ) subroutine resets a number of mode-specific variables to default settings. A command that establishes a mode can call this subroutine, if it doesn't want to provide explicit settings for all the usual mode-specific variables, such as comment pattern variables.

right_align_columns(char *pat)
The right_align_columns( ) subroutine locates all lines containing a match for the regular expression pattern pat. It notes the ending column of each match. (It assumes that pat occurs no more than one per line.)

Then, if some matches end at an earlier column than others, it adds indentation before each match as needed, so all matches will end at the same column.

char *get_mode_string_variable(char *pat) int guess_mode_without_extension(char *res, char *pat)
The get_mode_string_variable( ) subroutine retrieves the value of a string variable whose name depends on the current mode. The name may also refer to a function; its value will be returned. It constructs the name by using sprintf( ); pat should contain a %s and no other % characters; the current mode's name will replace the %s. If there's no such variable or function with that name, it returns NULL. The subroutine sets the got_bad_number variable nonzero to indicate that there was no such name, or zero otherwise.

The guess_mode_without_extension( ) subroutine tries to determine the correct mode for a file without an extension, mostly by examining its text. It can detect some Perl and C++ header files that lack any .perl or .hpp extension, as well as makefiles (based simply on the file's name). If it can determine the mode, it uses pat as a pattern for sprintf( ) (so it should contain one %s and no other %'s) and sets res to the pat, with its %s replaced by the mode name. Then it returns 1. If it can't guess the mode it returns 0.

reset_modified_buffer_region(char *tag) int modified_buffer_region(int *from, int *to, ?char *tag)
Sometimes an EEL function needs to know if a buffer has been modified since the last time it checked. Epsilon can maintain this information using tagged modification regions.

An EEL function first tells Epsilon to begin collecting this information for the current buffer by calling the reset_modified_buffer_region( ) primitive and passing a unique tag name. Later it can call the modified_buffer_region( ) primitive, passing the same tag name. Epsilon will set its from and to parameters to indicate the range of the buffer that has been modified since the first call.

For example, say a buffer contains six characters abcdef when reset_modified_buffer_region( ) is called. Then the user inserts and deletes some characters resulting in abxyf. A modified_buffer_region( ) would now report that characters in the range 2 to 4 have been changed. If the buffer contains many disjoint changes, from will indicate the start of the first change, and to the end of the last.

The modified_buffer_region( ) primitive returns 0 if the buffer hasn't been modified since the last reset_modified_buffer_region( ) with that tag. In this case from and to will be equal. (They might also be equal if only deletion of text had occurred, but then the primitive wouldn't have returned 0.) It returns 1 if the buffer has been modified. If reset_modified_buffer_region( ) has never been used with the specified tag in the current buffer, it returns -1, and sets the from and to variables to indicate the whole buffer.

The tag may be omitted when calling modified_buffer_region( ). In that case Epsilon uses an internal tag that's reset on each buffer display. So the primitive indicates which part of the current buffer has been modified since the last buffer display.

set_tagged_region(char *tag, int from, int to, short val) short get_tagged_region(char *tag, int pos, ?int *from, int *to)
Epsilon's character color primitives, set_character_color( ) and get_character_color( ), let you associate a color with a range of characters in a buffer. Some new primitives let you associate other attributes.

Each set of attributes consists of a tag (a unique string like "my-tag") and, for each character in the buffer, a number that represents the attribute. Each buffer has its own set of tags, and each tag has its own list of attributes, one for each character. (Epsilon stores the numbers in a way that's efficient when many adjacent characters have the same number, but nothing prevents each character from having a different attribute.)

The set_tagged_region( ) primitive sets the attribute of the characters in the range from to to, for the specified tag.

The get_tagged_region( ) primitive gets the attribute of the character at position pos in the buffer. If you provide pointers from and to, Epsilon will fill these in to indicate the largest range of characters adjacent to pos that have the same attribute as pos.

Epsilon's character color primitives set_character_color( ) and get_character_color( ) use a built-in tagged region with a tag name of "colors".

Previous Up Next
New File Primitives in Epsilon 10 Changes from Older Versions New Process Primitives in Epsilon 10