Unix files

In file.cecil:

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

template object unix_file
isa m_positionable_stream[char], extensible_stream[char];

method stdin():unix_file; 
method stdout():unix_file; 
method stderr():unix_file; 
abstract object open_mode; 
concrete representation open_for_reading isa open_mode; 
concrete representation create_for_writing isa open_mode; 
concrete representation open_for_append isa open_mode; 
concrete representation open_for_update isa open_mode; 
concrete representation create_for_update isa open_mode; 
concrete representation open_for_appending_update isa open_mode; 
concrete representation open_binary_for_reading isa open_mode; 
concrete representation create_binary_for_writing isa open_mode; 
concrete representation open_binary_for_append isa open_mode; 
concrete representation open_binary_for_update isa open_mode; 
concrete representation create_binary_for_update isa open_mode; 
concrete representation open_binary_for_appending_update isa open_mode; 
method open_file(n@:string, m@:open_mode):unix_file; 
method open_file(n@:string, m@:open_mode, if_error:&(int):unix_file):unix_file; 
method name(f@:unix_file):string; 
method is_readable(f@:unix_file):bool; 
method is_unreadable(f@:unix_file):bool; 
method is_writable(f@:unix_file):bool; 
method is_unwritable(f@:unix_file):bool; 
method is_read_write(f@:unix_file):bool; 
method is_append(f@:unix_file):bool; 
method read(f@:unix_file, buffer@:m_indexed[char], size:int):int; 
method read(f@:unix_file, buffer@:m_indexed[char], size:int, 
if_error:&(int):int):int;
method read(f@:unix_file, buffer@:m_vstring, size@:int, 
if_error:&(int):int):int;
method read_line(f@:unix_file, if_eof@closure:&():string):string; - returns the line's contents with no trailing
n; ``'' if the line is empty 
method read_line(f@:unix_file, if_eof@closure:&():string, 
if_error@closure:&(i:int):string):string;
method read_line(f@:unix_file, buffer@:m_indexed[char], size:int):int; 
method read_line(f@:unix_file, buffer@:m_indexed[char], size:int, 
if_error:&(int):int):int;
method read_line(f@:unix_file, buffer@:m_vstring, size:int, 
if_error:&(int):int):int;
method write_char(f@:unix_file, x:char):void; 
method write_line(f@:unix_file):void; 
method write_line(f@:unix_file, buffer@:indexed[char]):void; 
method write(f@:unix_file, buffer@:indexed[char]):void; 
method write(f@:unix_file, buffer@:indexed[char], size:int):void; 
method write(f@:unix_file, buffer@:indexed[char], size:int, 
if_error:&(int):void):void;
method write(f@:unix_file, buffer@:vstring, size@:int, 
if_error:&(int):void):void;
method print(s@:indexed[char], f:unix_file):void; 
method write_to_file(o:any, fname:string):void; 
method write_to_file(o:any, fname:string, if_error:&(int):none):void; 
method position(f@:unix_file):int; 
method position(f@:unix_file, if_error:&(int):int):int; 
abstract object position_mode; 
concrete representation from_start isa position_mode; 
concrete representation from_current_position isa position_mode; 
concrete representation from_end isa position_mode; 
method set_position(f@:unix_file, offset:int, if_error:&(int):void):void; 
method set_position_relative(f@:unix_file, offset:int, 
from@:position_mode):void;
method set_position_relative(f@:unix_file, offset:int, from@:position_mode, 
if_error:&(int):void):void;
method detected_eof(f@:unix_file):bool; 
method length(f@:unix_file):int; 
method flush(f@:unix_file):void; 
method flush(f@:unix_file, if_error:&(int):void):void; 
method close(f@:unix_file):void; 
method close(f@:unix_file, if_error:&(int):void):void; 
method get_mod_time(f_name@:string, if_error:&(int):int):int; 
method get_mod_time_internal(f_name@:string, if_error:&(int):int):int; 
method mod_time(f@:unix_file):int; 
method mod_time(f@:unix_file, if_error:&(int):int):int; 
method error_string(i:int):string; 
method unix_error(i:int, s:string):none; 
method nonfatal_unix_error(i:int, s:string):void; 
extend unix_file isa m_positionable_stream[char], extensible_stream[char]; 
method next(f@:unreadable_unix_file, at_end:&():char):char; 
method next(f@:readable_unix_file, at_end:&():char):char; 
method peek_next(f@:unix_file, at_end:&():char):char; 
method peek_prev(f@:unix_file, at_start:&():char):char; 
method prev(f@:unix_file, at_start:&():char):char; 
method set_next(f@:unwritable_unix_file, x:char):void; 
method set_next(f@:writable_unix_file, x:char):void; 
method set_peek_next(f@:unix_file, x:char):void; 
method set_peek_prev(f@:unix_file, x:char):void; 
method set_prev(f@:unix_file, x:char):void; 
method add_last(f@:unwritable_unix_file, x:char):void; 
method add_last(f@:writable_unix_file, x:char):void; 

Unix 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 Unix error during the operation, passing the Unix errno value as the integer argument to the closure. The error_string function converts errno to an error message, using the Unix sys_errlist. The unix_error function invokes error with an appropriate error message derived from a user-supplied message and the errno code. The nonfatal_unix_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 functions read up to size characters into a buffer; they return how many characters actually were 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 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, unix_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.

method file_exists(s:string):bool; 
method parse_path(path_string@:string, path_separator:char):extensible_sequence[string]; 
method parse_path(path_string@:string):extensible_sequence[string]; 
method path_name(t@:string):string; 
method strip_leading_path(t@:string):string; 
method dirname(t@:string):string; 
method basename(t@:string):string; 
method expand_filename(s@:string):string; 
method expand_filename(s@:string, if_error:&(int):string):string; 
method shrink_filename(s@:string):string; 
method is_abs_filename(s@:string):bool; 
method find_file(base_name@:string, dirs@:ordered_collection[string], 
if_fail:&(string):string):string;
method find_file(base_name@:string, dirs@:sequence[string]):string; 
method write_object_to_file_name(obj:any, f_name:string):void; 
method write_object_to_file_name(obj:any, f_name:string, 
if_error:&(int):void):void;
method write_object_to_file(x:any, f@:unix_file, use_bs@:bool):void; 
method write_object_to_file(x:any, f@:unix_file, 
if_error@closure:&(int):void):void;
method write_object_to_file(x:any, f@:unix_file, use_bs@:bool, 
if_error:&(int):void):void;
method read_object_from_file_name(f_name@:string):dynamic; 
method read_object_from_file_name(f_name@:string, use_bs:bool):dynamic; 
method read_object_from_file_name(f_name@:string, use_bs:bool, 
if_error:&(int):dynamic):dynamic;
method read_object_from_file(f@:unix_file, use_bs@:bool):dynamic; 
method read_object_from_file(f@:unix_file, 
if_error@closure:&(int):dynamic):dynamic;
method read_object_from_file(f@:unix_file, use_bs:bool, 
if_error:&(int):dynamic):dynamic;

A number of file-related operations have been defined. The find_file operation takes a file name and a directory search path and returns an absolute path name for the first file that matches the name in the search path. To do this work find_file invokes file_exists to test whether a given file name is defined and expand to expand away user file-name prefixes. The parse_path helper function converts a Unix search path string (directory names separated by colons) into a sequence of directory names.