File Reading Primitives

int file_read(char *file, int transl)

The file_read( ) primitive reads the named file into the current buffer, replacing the text that was there. It returns an error code if an error occurred, or 0 if the read was successful. The transl parameter specifies the line translation to be done on the file. The buffer's translation-type variable will be set to its value. If transl is FILETYPE_AUTO, Epsilon will examine the file as it's read and set translation-type to an appropriate translation type.

int new_file_read(char *name, int transl, struct file_info *f_info, int start, int max)
The new_file_read( ) primitive reads a file like file_read( ) but provides more options. The f_info parameter is a pointer to a structure, which Epsilon fills in with information on the file's write date, file type, and so forth. The structure has the same format as the check_file( ) primitive uses (see File Properties). If the f_info parameter is null, Epsilon doesn't get such information.

When Epsilon reads the file, it starts at offset start and reads at most max characters. You can use this to read only part of a big file. If start or max are negative, they are (individually) ignored: Epsilon starts at the beginning, or reads the whole file, respectively. The start parameter refers to the file before Epsilon strips <Return>'s, while max counts the characters after stripping.

int do_file_read(char *s, int transl) /* files.e */ buffer char _read_aborted; int read_file(char *file, int transl) /* files.e */ int find_remote_file(char *file, int transl) file_convert_read(int flags) do_readonly_warning() update_readonly_warning(struct file_info *p)
Instead of calling the above primitives directly, extensions typically call one of several subroutines, all defined in files.e, that do things beyond simply reading in the file. Each takes the same two parameters as file_read( ), and returns either 0 or an error code.

The do_file_read( ) subroutine records the file's date and time, so Epsilon can later warn the user that a file's been modified on disk, if necessary. If the user aborted reading the file, do_file_read( ) sets the _read_aborted variable to 1; it uses the value 2 if an error occurred reading the file. Epsilon then warns the user if he tries to save the partial file. This subroutine also handles reading URLs by calling the find_remote_file( ) subroutine, and character set translations such as OEM translations (see Character Encoding Conversions) by calling file_convert_read( ).

The read_file( ) subroutine calls do_file_read( ), then displays either an error message, if a read error occurred, or the message "New file." It also handles calling do_readonly_warning( ) when it detects a read-only file, or update_readonly_warning( ) otherwise. (The latter can turn off a buffer's read-only attribute, if the file is no longer read-only.)

int find_in_other_buf(char *file, int transl) /* files.e */ call_mode(char *file) /* files.e */
The find_in_other_buf( ) subroutine makes up a unique buffer name for the file, based on its name, and then calls read_file( ). It then goes into the appropriate mode for the file, based on the file's extension, by calling the call_mode( ) subroutine. (See Language Modes.)

int find_it(char *fname, int transl) /* files.e */ int std_find_it(char *fname) /* files.e */ int ask_find_it(char *fname) /* files.e */ int get_default_translation_type(char *fname) /* files.e */ int look_file(char *fname) /* buffer.e */
The find_it( ) subroutine first looks in all existing buffers for the named file, just as the find-file command would. If it finds the file, it simply switches to that buffer. (It also checks the copy of the file on disk, and warns the user if it's been modified.) If the file isn't already in a buffer, it calls find_in_other_buf( ), and returns 0 or its error code. The find_it( ) subroutine uses the look_file( ) subroutine to search through existing buffers for the file.

While find_it( ) requires you to pass the appropriate translation type, the std_find_it( ) and ask_find_it( ) subroutines supply this themselves. The std_find_it( ) subroutine always uses the default translation type for a file with the given name. The ask_find_it( ) subroutine usually does the same, but if the calling command was invoked with a numeric prefix argument, it prompts the user for the translation rules. The get_default_translation_type( ) subroutine returns the default translation type for a given file name.

The look_file( ) subroutine, defined in buffer.e, returns 0 if no buffer has the file. Otherwise, it returns 1 and switches to the buffer by setting bufnum.

int do_find(char *file, int transl) /* files.e */
Finally, the do_find( ) subroutine is at the top of this tree of file-reading functions. It checks to see if its "file name" parameter is a directory. If it is (or if it's a file pattern with wildcard characters), it calls dired_one( ) to run dired on the pattern. If it's a normal file, do_find( ) calls find_it( ).

int err_file_read(char *file, int transl) /* files.e */
Use the err_file_read( ) subroutine when you want to read a file that must exist, but you don't want all the extras that higher-level functions provide: checking file dates, choosing a buffer, setting up for read-only files, and so forth. It calls file_read( ) to read the file into the current buffer, and displays an error message if the file couldn't be read for any reason. It returns the error code, or 0 if there were no errors.

short abort_file_io;
By default, primitives that read and write files respond to the user pressing the abort key by asking whether they should abort the input/output operation. An EEL program can select a different behavior by using save_var to set the primitive variable abort_file_io. The default setting, ABORT_ASK, asks the user whether to abort the operation. If he says no, the operation continues. If he says yes, the primitive returns an error code, EREADABORT for reading primitives or EWRITEABORT for writing primitives. The setting ABORT_ERROR omits asking the user; it immediately returns an error code if the user aborts. The setting ABORT_IGNORE tells Epsilon to ignore the abort key and continue. The setting ABORT_JUMP makes pressing the abort key abort the current function by calling the check_abort( ) primitive, again without prompting first. (See Control Flow.)

Previous Up Next
Colors Primitives and EEL Subroutines File Writing Primitives