New EEL Primitives and Subroutines in Epsilon 11

int tokenize_lines(int buf1, int **lines1, int *len1,

                   int buf2, int **lines2, int *len2)

int lcs(int *lines1, int len1, int *lines2, int len2, char *outbuf)

These primitives help to compute a minimum set of differences between the lines of two buffers buf1 and buf2. See the implementation of the diff command for an example of their use.

Call the tokenize_lines( ) primitive first. It begins by counting the lines in each buffer (placing the results in len1 and len2). Then it uses the realloc( ) primitive to make room in the arrays passed by reference as lines1 and lines2, which may be null at the start. Each array will have room for one token (unique integer) for each line of its buffer. (The arrays may be freed after calling lcs( ), or reused in later calls.)

The tokenize_lines( ) primitive then fills in the arrays with unique tokens, chosen so that two lines will have the same token if and only if they're identical.

The lcs( ) primitive takes the resulting arrays and line counts, and writes a list of shared line ranges to the specified buffer, one per line, in ascending order. Each line range consists of a line number for the first buffer, a line number for the second (both 0-based) and a line count. For instance, a line "49 42 7" indicates that the seven lines starting at line 49 in the first buffer match the seven lines starting at line 42 in the second (counting lines from 0).

int lcs_char(int buf1, int from1, int to1, int buf2, int from2, int to2, char *outbuf)
The lcs_char( ) primitive is a character-oriented version of the tokenize_lines( ) and lcs( ) primitives described above. It compares ranges of characters in a pair of buffers.

It writes a list of shared character ranges to the specified buffer, one per line, in ascending order. Each character range consists of a character offset for the first buffer relative to from1, a character offset for the second buffer relative to from2, and a character count. For instance, a line "49 42 7" in the output buffer indicates that the seven characters in the range from1 + 47 to from1 + 47 + 7 in the first buffer match the seven characters in the range from2 + 42 to from2 + 42 + 7 in the second.

int is_relative(char *fname)
The is_relative( ) primitive returns nonzero if the file name looks like a relative pathname, not an absolute pathname. (It's not intended for use with URLs.)

do_buffer_to_hex(char *b, char transp[256])
The do_buffer_to_hex( ) primitive writes a hex view of the current buffer to the buffer b, creating or emptying it first. It ignores any narrowing in the original buffer. It uses the 256 byte transp array to help construct the last column of the hex view; each character from the buffer will be replaced by the character at that offset in the transp array.

int perform_conversion(int buf, int flags)
The perform_conversion() primitive converts between 16-bit Unicode UTF-16 encodings and the 8-bit encodings Latin 1 and UTF-8. It converts the specified buffer buf in place. Flags control its behavior.

In UTF-8 format, any characters outside the range 0-127 are represented as multi-byte sequences of graphic characters. Latin 1 format displays the proper glyph for characters in the range 128-255, unlike the UTF-8 format, but it cannot represent characters outside the range 0-255.

With no flags set, the primitive converts from the UTF-16 LE encoding to the UTF-8 encoding. The CONV_TO_16 flag makes it convert in the opposite direction, from an 8-bit encoding to a 16-bit one. The CONV_LATIN1 flag makes it convert to or from Latin 1 instead of UTF-8.

The primitive returns -1 if it succeeded. If the buffer contained characters that could not be represented in the new format, or byte sequences invalid in the old format, it generates default characters or skips past the invalid text as appropriate, and returns the offset in the modified buffer of the first such difficulty. With the CONV_TEST_ONLY flag, it does not modify the buffer, but only returns a result code indicating the location of the problem, if any, in the unmodified buffer.

By default, the primitive converts to or from the UTF-16 LE ("little endian") encoding. With the CONV_BIG_ENDIAN flag, it generates or reads UTF-16 BE instead. However, if the conversion is from, not to, a 16-bit format, and the buffer begins with a byte order mark (BOM) that indicates its endianness, the primitive ignores the CONV_BIG_ENDIAN flag and uses the BOM to determine the endianness.

By default, the resulting buffer begins with a byte order mark (unless the translation is to Latin 1, which defines no BOM). Add the CONV_OMIT_BOM flag to omit it.

Combine the CONV_REQUIRE_BOM flag with CONV_TEST_ONLY to have the primitive return an error indication if the buffer lacks a suitable BOM. CONV_REQUIRE_BOM without CONV_TEST_ONLY returns an error code if the buffer lacks a BOM, but converts anyway. For conversions from Latin 1, CONV_REQUIRE_BOM has no effect. For conversions from UTF-16, if there's a valid UTF-16 byte order mark, but its endianness doesn't match the specified CONV_BIG_ENDIAN flag, CONV_REQUIRE_BOM won't return an error indication; either UTF-16 LE or UTF-16 BE byte order marks will be accepted.

The primitive handles aborting by interpreting the abort_searching variable. Set it to 0 to have it ignore the abort key and continue, ABORT_JUMP to have it jump by calling the check_abort( ) primitive, or ABORT_ERROR to have it stop the conversion and return an ABORT_ERROR code.

unique_filename_identifier(char *fname, int id[3]) unique_file_ids_match(int a[3], int b[3])
The unique_filename_identifier( ) primitive takes a file name and fills the id array with a set of values that uniquely describe it. Two file names with the same array of values refer to the same file. (This can happen under Unix due to symbolic or hard links.) If the primitive sets id[0] to zero, no unique identifier was found; comparisons between two file names, one or both of which return id[0]==0, must assume that the names might or might not refer to the same file. At this writing only Epsilon for Unix supports this feature; in other versions, unique_filename_identifier( ) will always set id[0] to zero.

The unique_file_ids_match( ) subroutine compares two id arrays from unique_filename_identifier( ), returning nonzero if they indicate the two file names supplied to unique_filename_identifier( ) refer to the same file, and zero if they do not, or Epsilon cannot determine this.

do_resume_client()
Epsilon for Unix supports a client/server function, in which the first Epsilon started becomes a server and listens for messages from future instances, the clients. Typically these messages command the server to load a particular file for editing. The client sends the file name specified on its command line, and then exits.

Sometimes it's desirable for the client instance of Epsilon to wait for a signal from the server instance before exiting, an indication from the user that the he has finished editing the passed file. The do_resume_client( ) primitive sends such a signal to any clients that have sent files to the current instance of Epsilon and are now waiting for such a message.

int telnet_server_echoes(int id)
The telnet_server_echoes( ) primitive accepts a telnet session identifier returned from the telnet_host( ) primitive, and returns 1 if the server on that connection is currently set to echo characters sent to it, or 0 if it is not.

int lowaccess(char *fname, int mode) #define LOWACC_R 4 /* file is readable. */ #define LOWACC_W 2 /* file is writable. */ #define LOWACC_X 1 /* file is executable. */
Under Unix, the lowaccess( ) primitive calls the access() system call, passing a file name and a code indicating whether the file's read access, write access or execute access should be tested (or zero if only the file's existence need be checked). It returns 0 if the file is accessible for the specified purpose (can be read, can be written, can be executed, exists), or -1 if not. Under non-Unix systems, the primitive always returns -1.

char no_popup_errors;
Under MS-Windows, the file_error( ) primitive pops up a message box to report an error accessing a file. If EEL code sets this variable nonzero, Epsilon will display such messages in the echo area instead, as it does under other operating systems.

add_buffer_when_idle(int buf, int (*func)()) delete_buffer_when_idle(int buf, int (*func)())
Epsilon calls the when_idle( ) subroutine whenever it's waiting for a key or other event. A mode may wish to provide additional functions that run during idle time, beyond those the when_idle( ) subroutine performs itself (such as displaying the current function's name, highlighting matching delimiters, and so forth).

The add_buffer_when_idle( ) subroutine registers a function func so that it will be called during idle-time processing whenever buf is the current buffer. The delete_buffer_when_idle( ) subroutine removes the specified function from that buffer's list of buffer-specific idle-time functions. (It does nothing if the function was not on the list.)

A buffer-specific when-idle function takes a parameter times and must return a result in the same fashion as the when_idle( ) function itself. That is, its parameter indicates the number of times the subroutine has been called since Epsilon began waiting for a key. Every time Epsilon gets a key (or other event), it resets this count to zero. It must return a suggested timeout value in hundredths of a second, indicating how long Epsilon should wait before calling it again, or -1 to indicate that it doesn't need to be called again until Epsilon next becomes idle. The value is advisory; Epsilon may call the function more or less frequently than it requests.

buf_grab_bytes(int buf, int from, int to, char *dest)
The buf_grab_bytes( ) subroutine copies characters in the specified range in the buffer buf into the character array dest.

find_buffer_prefix(int buf, char *prefix)
The find_buffer_prefix( ) subroutine looks through all the lines in the buffer buf to see if they all start with the same string of characters. It puts any such common prefix shared by all the lines in prefix. For instance, if the buffer contains three lines "waters", "watering" and "waterfall", it would put the string "water" in dest.

columnize_buffer_text(int buf, int width, int margin)
The columnize_buffer_text( ) subroutine takes the lines in the buffer buf and reformats them into columns. It leaves a margin between columns of margin spaces, and chooses the number of columns so that the resulting buffer is at most width characters wide (unless an original line in the buffer is already wider than width).

count_lines_in_buf(int buf, int abortok)
The count_lines_in_buf( ) subroutine returns the number of newline characters in the buffer buf. If abortok is nonzero and the user press the abort key, the subroutine uses the check_abort( ) primitive to abort.

int process_send_text(int buf, char *text, int len)
Normally input to a process running in a concurrent process buffer comes from text the user inserts into the buffer. The process_send_text( ) primitive provides a way to send text directly to the process, bypassing the buffer. This is especially useful for passwords, since if a password appears in the buffer it might be seen, or retrieved with undo. The primitive sends len characters from text to the process associated with the buffer buf.

The primitive only functions in certain operating system versions of Epsilon (currently Unix and 32-bit Windows versions); check the FEAT_PROC_SEND_TEXT bit of the has_feature variable to test if it may be used.

int get_key_response(char *valid, int def)
The get_key_response( ) subroutine waits for the user to type a valid key in response to a prompt. The parameter valid lists the acceptable characters, such as "YN" for a yes/no question. (But see the ask_yn( ) subroutine, more suitable for yes/no questions.) The def parameter, if greater than zero, indicates which key should be the default if the user presses <Enter>. The subroutine returns the selected key.

Previous Up Next
EEL Programming Changes in Epsilon 11 Changes from Older Versions Changes to EEL Primitives and Subroutines in Epsilon 11