Next: Miscellaneous
Up: Input/output
Previous: Random numbers
Index
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.
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;
Next: Miscellaneous
Up: Input/output
Previous: Random numbers
Index
Cecil/Vortex Project