Lugaru's Epsilon
Editor 14.01

Epsilon User's Manual and Reference
   Primitives and EEL Subroutines
      Buffer Primitives
         Changing Buffer Contents
         Moving Text Between Buffers
         Getting Text from a Buffer
         . . .
      Display Primitives
         Creating & Destroying Windows
         Window Resizing Primitives
         Preserving Window Arrangements
         . . .
      . . .

Previous   Up    Next
Primitives and EEL Subroutines  Primitives and EEL Subroutines   Moving Text Between Buffers

Epsilon User's Manual and Reference > Primitives and EEL Subroutines > Buffer Primitives >

Changing Buffer Contents

insert(int ch)
user buffer int point;

An Epsilon buffer contains text that you can edit. Most of the primitives in this section act on, or refer to, one of the buffers designated as the current buffer.

The insert( ) primitive inserts a single character into the current buffer. Its argument says what character to insert. The buffer's insertion point, or just point, refers to the particular position in each buffer where insertions occur.

The int variable named point stores this position. Its value denotes the number of characters from the beginning of the buffer to the spot at which insertions happen. For example, a value of zero for point means that insertions would occur at the beginning of the buffer. A value of one for point means that insertions would occur after the first character, etc.

To change the insertion point, you can assign a new value to point. For example, the statement

point = 3;

makes insertions occur after the third character in the buffer, assuming the buffer has at least 3 characters. If you set point to a value less than zero, point takes the value zero. Similarly, if you set point to a value greater than the size of the buffer, its value becomes the number of characters in the buffer.

When the current buffer changes, the value of the variable point automatically changes with it. We call variables with this behavior buffer-specific variables. See Buffer-specific Variables.

int size()

The primitive function size( ) returns the number of characters in the current buffer. You cannot set the size directly: you can change the size of the buffer only by inserting or deleting characters. For this reason, we implemented size( ) as a function, not a variable like point.

The variable point refers not to a character position, but rather to a character boundary, a place between characters (or at the beginning or end of a buffer). The legal values for point range from zero to size( ). We will refer to a value in this range, inclusive of the ends, as a position. A position is a place between characters in a buffer, or at the beginning of the buffer, or at the end. The value of a position is the number of characters before it in the buffer. In EEL, ints (integers) hold positions.

When Epsilon inserts a character, it goes before point, not after it. If Epsilon didn't work this way, inserting a, then b, then c would result in cba, not abc.

delete(int pos1, int pos2)
int delete_if_highlighted()

The delete( ) primitive deletes all characters between the two positions supplied as arguments to it. The order of the arguments doesn't matter.

The delete( ) primitive doesn't save deleted text in a kill buffer. The kill commands themselves manage the kill buffers, and use the delete( ) primitive to actually remove the text.

Commands that insert text often begin by calling the delete_if_highlighted( ) subroutine. If there's a highlighted region, this subroutine deletes it and returns 1. Otherwise (or if the typing-deletes-highlight variable has been set to zero), it returns 0.

replace(int pos, int ch)
int character(int pos)
int curchar()

The replace( ) primitive changes the character at position pos to ch. The parameter pos refers to the position before the character in question. Therefore, the value of pos can range from 0 to size()-1, inclusively.

The character( ) primitive returns the character after the position specified by its argument, pos. The curchar( ) returns the same value as character(point). These two primitives return -1 when the position involved isn't valid, such as at the end of the buffer or before its start (when pos is less than zero). For example, character(size()) returns -1, as does curchar( ) with point at the end of the buffer.

stuff(char *str)
int bprintf(char *format, ...)
int buffer_printf(char *name, char *format, ...)
int buf_printf(int bnum, char *format, ...)
buf_stuff(int bnum, char *s, int len)

The stuff( ) function inserts an entire string into the current buffer.

The bprintf( ) function also inserts a string, but it takes a format string plus other arguments and builds the string to insert using the rules in Printf-style Format Strings. The buffer_printf( ) function operates similarly, except that it takes the name of the buffer into which to insert the string. It creates the buffer if necessary. Similarly, buf_printf( ) takes a buffer number, and inserts the formatted string into that buffer. All of the primitives described in this paragraph return the number of characters they inserted into the buffer.

The buf_stuff( ) primitive includes a length parameter, so it can handle text that may contain null characters. It inserts the len characters at s into the buffer bnum.

Previous   Up    Next
Primitives and EEL Subroutines  Primitives and EEL Subroutines   Moving Text Between Buffers

Lugaru Epsilon Programmer's Editor 14.01 manual. Copyright (C) 1984, 2020 by Lugaru Software Ltd. All rights reserved.