next up previous index
Next: Miscellaneous Up: Input/output Previous: Random numbers   Index

Unix files

In file.diesel:

A file object acts like a mutable, extensible, positionable stream of characters, as well as supporting lots of standard file I/O operations.

Files can be opened, given the name of the file and an open mode, using open_file. The optional if_error closure taken by open_file and many other file operations is invoked if there was a standard OS error during the operation, passing a string describing the kind of error. The os_error function invokes error with an appropriate error message derived from the error string and a user-supplied message. The nonfatal_os_error also prints the error message, but then successfully returns to the caller.

The three standard files can be returned by the stdin, stdout, and stderr functions. Six functions are available to query properties of the file: whether or not the file is readable and/or writable and whether or not writes always append. The read_partial functions read up to size characters into a buffer, starting at index from; they return how many characters actually were read. The read functions repeatedly call read_partial until all requested characters are read. The read_line functions work like read, except that they stop reading after they've seen (and copied to the buffer) a newline character. The read_whole_text_file functions create and return a string containing the whole file's contents; it correctly handles text files with varying CR/LF conventions on different platforms. The write functions write their argument character buffer (optionally copying only size characters) to the file. Collectors can be written to a file directly, more efficiently than first flattening the collector into a string. Individual characters can also be written to a file.

The mod_time operations return the modification timestamp of the file; get_mod_time is a convenience in case the file hasn't been opened yet. (The time data structure supports parsing the timestamp integer.)

In addition to the other stream-style operations, files support testing whether they have detected the end of the file (subtly different than actually being at the end of the file) and performing lseek-style repositioning relative either to the start of the file, the current position, or the end of the file. Note that file positions and file lengths are in terms of raw characters in the underlying file, ignoring any CR/LF conversion that might be performed by read operations.

extend module Stdlib;
module File;
fun stdin():file;
fun stdout():file;
fun stderr():file;
abstract class open_mode;
object open_for_reading isa open_mode;
object create_for_writing isa open_mode;
object open_for_append isa open_mode;
object open_for_update isa open_mode;
object create_for_update isa open_mode;
object open_for_appending_update isa open_mode;
object open_binary_for_reading isa open_mode;
object create_binary_for_writing isa open_mode;
object open_binary_for_append isa open_mode;
object open_binary_for_update isa open_mode;
object create_binary_for_update isa open_mode;
object open_binary_for_appending_update isa open_mode;
fun open_file(n:string, m:open_mode):file;
fun open_file(n:string, m:open_mode, if_error:&(string):file):file;
fun file_name(f:file):string;
fun is_readable(f:file):bool;
fun is_unreadable(f:file):bool;
fun is_writable(f:file):bool;
fun is_unwritable(f:file):bool;
fun is_read_write(f:file):bool;
fun is_append(f:file):bool;
fun read(f:file, buffer:m_indexed[char], size:int):void;
fun read(f:file, buffer:m_indexed[char], size:int,
                if_error:&(string):void):void;
fun read_whole_text_file(f:file):string;
fun read_whole_text_file(f:file, if_error:&(string):string):string;
fun read_partial(f:file, buffer:m_indexed[char], from:int, size:int
                        ):int;
fun read_partial(f:file, buffer:m_indexed[char], from:int, size:int,
                        if_error:&(string):int):int;
fun read_line(f:file):string;  - returns the line's contents with no trailing
n; ``'' if the line is empty

fun read_line(f:file, if_eof:&():string):string;
fun read_line(f:file, if_eof:&():string, if_error:&(string):string
                     ):string;
fun read_line_into(f:file, buffer:m_indexed[char], size:int):int;
fun read_line_into(f:file, buffer:m_indexed[char], size:int,
                          if_error:&(string):int):int;
fun write_char(f:file, x:char):void;
fun write_line(f:file):void;
fun write_line(f:file, buffer:indexed[char]):void;
fun write(f:file, buffer:indexed[char]):void;
fun write(f:file, buffer:indexed[char], size:int):void;
fun write(f:file, buffer:indexed[char], size:int,
                 if_error:&(string):void):void;
fun print(s:indexed[char], f:file):void;
fun write_to_file(o:any, fname:string):void;
fun write_to_file(o:any, fname:string, if_error:&(string):none):void;
fun write_collector(f:file, c:collector[`T <= indexed[char]]):void;
fun write_collector(f:file, c:collector[`T <= indexed[char]],
                           if_error:&(string):void):void;
fun detected_eof(f:file):bool;
fun close(f:file):void;
fun close(f:file, if_error:&(string):void):void;
fun get_mod_time(f_name:string):integer;
fun get_mod_time(f_name:string, if_error:&(string):integer):integer;
fun mod_time(f:file):integer;
fun mod_time(f:file, if_error:&(string):integer):integer;
fun mod_time_internal(f:file, if_error:&(string):int):int;
fun error_string(i:int):string;
fun os_error(err:string, s:string):none;
fun nonfatal_os_error(err:string, s:string):void;
fun position(f:file, if_error:&(string):int):int;
abstract class position_mode;
object from_start isa position_mode;
object from_current_position isa position_mode;
object from_end isa position_mode;
fun set_file_position(f:file, offset:int, if_error:&(string):void):void;
fun set_position_relative(f:file, offset:int, from:position_mode):void;
fun set_position_relative(f:file, offset:int, from:position_mode,
                                 if_error:&(string):void):void;
fun flush(f:file, if_error:&(string):void):void;
fun file_exists(s:string):bool;  - return whether the named file exists
fun path_name(t:string):string;
fun dirname(t:string):string;
fun strip_leading_path(t:string):string;
fun basename(t:string):string;
fun canonicalize_filename(s:string):string;
fun canonicalize_dirname(s:string):string;
fun shrink_filename(s:string):string;  - use SPMtilde; in place of the current user's home directory
fun is_abs_filename(s:string):bool;
The find_file operation takes a file name and a directory search path and returns the full path name for the first file that exists under that name in the search path.

fun find_file(base_name:string, dirs:ordered_collection[string],
                     if_fail:&(string):string):string;
fun find_file(base_name:string, dirs:sequence[string]):string;
fun expand_filename(s:string):string;  - replace leading SPMtilde;... with its expansion
fun expand_filename(s:string, if_error:&(string):string):string;
fun write_object_to_file_name(obj:any, f_name:string):void;
fun write_object_to_file_name(obj:any, f_name:string,
                                     if_error:&(string):void):void;
fun write_object_to_file(x:any, f:file, :bool | &(string):void):void;
fun write_object_to_file(x:any, f:file, use_bs:bool,
                                if_error:&(string):void):void;
fun read_object_from_file_name(f_name:string):dynamic;
fun read_object_from_file_name(f_name:string, use_bs:bool):dynamic;
fun read_object_from_file_name(f_name:string, use_bs:bool,
                                      if_error:&(string):dynamic):dynamic;
fun read_object_from_file(f:file, :bool | &(string):dynamic):dynamic;
fun read_object_from_file(f:file, use_bs:bool,
                                 if_error:&(string):dynamic):dynamic;
end module File;


next up previous index
Next: Miscellaneous Up: Input/output Previous: Random numbers   Index

Cecil/Vortex Project