
(********************************************************************)
(*                                                                  *)
(*  file.s7i      Interface type describing sequential files        *)
(*  Copyright (C) 1989 - 2011  Thomas Mertes                        *)
(*                                                                  *)
(*  This file is part of the Seed7 Runtime Library.                 *)
(*                                                                  *)
(*  The Seed7 Runtime Library is free software; you can             *)
(*  redistribute it and/or modify it under the terms of the GNU     *)
(*  Lesser General Public License as published by the Free Software *)
(*  Foundation; either version 2.1 of the License, or (at your      *)
(*  option) any later version.                                      *)
(*                                                                  *)
(*  The Seed7 Runtime Library is distributed in the hope that it    *)
(*  will be useful, but WITHOUT ANY WARRANTY; without even the      *)
(*  implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR *)
(*  PURPOSE.  See the GNU Lesser General Public License for more    *)
(*  details.                                                        *)
(*                                                                  *)
(*  You should have received a copy of the GNU Lesser General       *)
(*  Public License along with this program; if not, write to the    *)
(*  Free Software Foundation, Inc., 51 Franklin Street,             *)
(*  Fifth Floor, Boston, MA  02110-1301, USA.                       *)
(*                                                                  *)
(********************************************************************)


(**
 *  Interface type for sequential files.
 *  The file interface is implemented with [[null_file]],
 *  [[external_file]], [[utf8|utf8_file]], [[utf16|utf16_file]],
 *  [[socket]], [[echo|echo_file]], [[line|line_file]],
 *  [[dir|dir_file]] and many other types.
 *)
const type: file is sub object interface;


(**
 *  Write a string to a file.
 *)
const proc: write (inout file: aFile, in string: stri)       is DYNAMIC;


(**
 *  Write end-of-line to a file.
 *  The implementation function decides how writing end-of-line is
 *  done. It can be done by writing "\n", but other solutions are also
 *  possible.
 *)
const proc: writeln (inout file: aFile)                      is DYNAMIC;


const proc: backSpace (inout file param)                     is DYNAMIC;


(**
 *  Close a file.
 *)
const proc: close (inout file: aFile)                        is DYNAMIC;


(**
 *  Forces that all buffered data of ''aFile'' is sent to its destination.
 *  Depending on the implementation type this causes data to be sent
 *  to the file system, screen, network or other destination.
 *)
const proc: flush (inout file: aFile)                        is DYNAMIC;


(**
 *  Read a character from a file.
 *  @return the character read, or EOF at the end of the file.
 *)
const func char: getc (inout file: aFile)                    is DYNAMIC;


(**
 *  Read a string with a maximum length from a file.
 *  @return the string read.
 *)
const func string: gets (inout file: aFile, in integer: maxLength) is DYNAMIC;


(**
 *  Read a word from a file.
 *  Before reading the word it skips spaces and tabs. The function
 *  accepts words ending with " ", "\t", end-of-line or [[char#EOF|EOF]].
 *  The word ending characters are not copied into the string.
 *  When the function is left inFile.bufferChar contains the
 *  word ending character (' ', '\t', '\n' or EOF). 
 *  @return the word read.
 *)
const func string: getwd (inout file: aFile)                 is DYNAMIC;


(**
 *  Read a line from a file.
 *  The function reads a string up to end-of-line or [[char#EOF|EOF]].
 *  The line ending characters are not copied into the string.
 *  When the function is left inFile.bufferChar contains the
 *  line ending character ('\n' or EOF). 
 *  @return the line read.
 *)
const func string: getln (inout file: aFile)                 is DYNAMIC;


const func string: getk (in file param)                      is DYNAMIC;
const func boolean: eoln (in file param)                     is DYNAMIC;


(**
 *  Determine the end-of-file indicator.
 *  The end-of-file indicator is set when at least one request to read
 *  from the file failed.
 *  @return TRUE if the end-of-file indicator is set, FALSE otherwise.
 *)
const func boolean: eof (in file: aFile)                     is DYNAMIC;


(**
 *  Determine if at least one character can be read successfully.
 *  This function allows a file to be handled like an iterator.
 *  @return FALSE if ''getc'' would return EOF, TRUE otherwise.
 *)
const func boolean: hasNext (in file: aFile)                 is DYNAMIC;


const func boolean: inputReady (in file: aFile)              is DYNAMIC;


(**
 *  Obtain the length of a file.
 *  The file length is measured in bytes.
 *  @return the length of a file, or 0 if it cannot be obtained.
 *)
const func integer: length (in file: aFile)                  is DYNAMIC;


(**
 *  Set the current file position.
 *  The file position is measured in bytes from the start of the file.
 *  The first byte in the file has the position 1.
 *)
const proc: seek (inout file: aFile, in integer: pos)        is DYNAMIC;


(**
 *  Obtain the current file position.
 *  The file position is measured in bytes from the start of the file.
 *  The first byte in the file has the position 1.
 *  @return the current file position.
 *)
const func integer: tell (in file: aFile)                    is DYNAMIC;


(**
 *  Compare two file values.
 *  This function does neither compare file contents nor file names.
 *  The order of two files is determined by comparing the memory
 *  positions of their internal data representation. Therefore the
 *  result of ''compare'' is arbitrary and may change when the
 *  program is executed again. Inside a program the result of
 *  ''compare'' is consistent and can be used to maintain hash
 *  tables.
 *  @return -1, 0 or 1 if the first argument is considered to be
 *          respectively less than, equal to, or greater than the
 *          second.
 *)
const func integer: compare (in file: file1, in file: file2) is action "ITF_CMP";


(**
 *  Compute the hash value of a file.
 *  @return the hash value.
 *)
const func integer: hashCode (in file: aFile)                is action "ITF_HASHCODE";


const func char: (in file param).bufferChar           is DYNAMIC;
const varfunc char: (inout file param).bufferChar     is DYNAMIC;
const func boolean: (in file param).io_empty          is DYNAMIC;
const varfunc boolean: (inout file param).io_empty    is DYNAMIC;
const func boolean: (in file param).io_ok             is DYNAMIC;
const varfunc boolean: (inout file param).io_ok       is DYNAMIC;

const func boolean: io_ok (in file: aFile) is
  return aFile.io_ok;

const func boolean: io_error (in file: aFile) is
  return not aFile.io_ok;

const func boolean: io_empty (in file: aFile) is
  return aFile.io_empty;

const func boolean: io_filled (in file: aFile) is
  return not aFile.io_empty;


(**
 *  Discard a line from a file.
 *  The function discards characters up to end-of-line or [[char#EOF|EOF]].
 *  When the function is left inFile.bufferChar contains the
 *  line ending character ('\n' or EOF). 
 *)
const proc: readln (inout file: aFile) is func
  local
    var string: stri is "";
  begin
    stri := getln(aFile);
    aFile.io_empty := stri = "";
    aFile.io_ok := TRUE;
  end func;


(**
 *  Write a string followed by end-of-line to a file.
 *  The file implementation type of ''aFile'' decides how writing
 *  end-of-line is done. It can be done by writing '\n', but other
 *  solutions are also possible.
 *)
const proc: writeln (inout file: aFile, in string: stri) is func
  begin
    write(aFile, stri);
    writeln(aFile);
  end func;


(**
 *  Read a word from a file.
 *  Before reading the word it skips spaces and tabs. The function
 *  accepts words ending with " ", "\t", end-of-line or [[char#EOF|EOF]].
 *  The word ending characters are not copied into the string.
 *  When the function is left inFile.bufferChar contains the
 *  word ending character (' ', '\t', '\n' or EOF). 
 *)
const proc: read (inout file: aFile, inout string: stri) is func
  begin
    stri := getwd(aFile);
    aFile.io_empty := stri = "";
    aFile.io_ok := TRUE;
  end func;


(**
 *  Read a line from a file.
 *  The function reads a string up to end-of-line or [[char#EOF|EOF]].
 *  The line ending characters are not copied into the string.
 *  When the function is left inFile.bufferChar contains the
 *  line ending character ('\n' or EOF). 
 *)
const proc: readln (inout file: aFile, inout string: stri) is func
  begin
    stri := getln(aFile);
    aFile.io_empty := stri = "";
    aFile.io_ok := TRUE;
  end func;


(**
 *  Copy a file from source to destination.
 *  The ''source'' file is copied to ''dest'' until end-of-file
 *  is reached.
 *)
const proc: copyFile (inout file: source, inout file: dest) is func
  local
    var string: buffer is "";
   begin
    buffer := gets(source, 1000000);
    while buffer <> "" do
      # writeln(literal(buffer));
      # writeln(length(buffer));
      write(dest, buffer);
      buffer := gets(source, 1000000);
    end while;
    # writeln("finished");
  end func;
