/** -*-C-*-ish
    Kaya standard library
    Copyright (C) 2004, 2005 Edwin Brady

    This file is distributed under the terms of the GNU Lesser General
    Public Licence. See COPYING for licence.
*/
"<summary>File input/output and filesystem access</summary>
<prose>This module contains functions for file input and output, and filesystem access. File names may be given as absolute file paths, or relative to the current directory (which may be changed with <functionref>System::chdir</functionref>). Additional functions for handling binary files may be found in the <moduleref>Binary</moduleref> module.</prose>"
module IO;

import Prelude;

%include "stdlib.h";
%include "sys/stat.h";
%include "sys/types.h";

// Chris Morris, 18/6/05 - moved data definitions above foreign{} and
// added AccessMode type.
"<summary>File handling error</summary>
<prose>This Exception is thrown when file handling functions fail.</prose>"
Exception FileError;
"<summary>Directory handling error</summary>
<prose>This Exception is thrown when directory handling functions fail.</prose>"
Exception DirError;
"<summary>Invalid file mode error</summary>
<prose>This Exception is thrown when a file mode is invalid.</prose>"
Exception InvalidMode;

"<summary>Closed file</summary>
<prose>An attempt was made to read from or write to a closed file handle.</prose>"
Exception ClosedFile;

"<summary>Read only file</summary>
<prose>An attempt was made to write to a read-only file.</prose>"
Exception ReadOnlyFile;

"<summary>Write only file</summary>
<prose>An attempt was made to read from a write-only file.</prose>"
Exception WriteOnlyFile;

"<summary>Modes for file opening.</summary>
<prose>Selects a mode for <functionref>open</functionref> to use. The <code>Binary</code> mode is only needed for reading and writing binary files on Windows systems.</prose>"
public data FileMode = Read | Write | Append | Binary;

// internal data type
data AccessMode = FExists | FExecute | FWrite | FRead;

"<summary>A file handle</summary>
<prose>A file handle. This may not be directly queried.</prose>"
abstract data File(Ptr ptr, Bool open, Bool read, Bool write, Bool append, Bool binary);

"<summary>A directory handle</summary>
<prose>A directory handle. As with the <code>File</code> type for file handles, this type may not be directly queried in any way.</prose>"
abstract data Dir(Ptr ptr);
"<summary>A directory entry</summary>
<prose>An entry within a directory. Currently only the name of the entry is recorded.</prose>"
public data DirEntry(String name);

"<summary>File information</summary>
<prose>Information about a file. The <code>mode</code> field describes the file mode, <code>nlinks</code> is the number of links to the file, and <code>atime</code>, <code>mtime</code> and <code>ctime</code> are the access, modify (last change to contents) and change (last change to contents or mode) times measured in seconds since midnight Jan 1 1970. The <functionref>Time::gmtime</functionref> function may be useful to deal with these fields.</prose>
<related><dataref>Mode</dataref></related>
<related><functionref>stat</functionref></related>"
public data Stat(Mode mode, Int nlinks,
		 Int atime, Int mtime, Int ctime);
	
"<summary>File modes</summary>
<prose>This describes the mode of the file. The first three fields describe the access <dataref>Permission</dataref> for the file owner, the file group, and others, while the remaining fields state whether a particular file property is true.</prose>
<prose>This data type mostly applies to the filesystems normally found on POSIX systems. On Windows, the file permission and type model is somewhat different, so this data type may not hold especially useful information there.</prose>
<related><dataref>Permission</dataref></related>
<related><dataref>Stat</dataref></related>"  
public data Mode([Permission] ownerperms,
		 [Permission] groupperms,
		 [Permission] othersperms,
		 Bool socket,
		 Bool symlink,
		 Bool regular,
		 Bool block,
		 Bool dir,
		 Bool chardev,
		 Bool fifo,
		 Bool setUID,
		 Bool setGID,
		 Bool sticky);

"<summary>File permissions</summary>
<prose>Selects whether a file is readable, writable or executable.</prose>
<related><dataref>Mode</dataref></related>
<related><dataref>Permissions</dataref></related>"
public data Permission = ReadP | WriteP | ExecuteP;

"<summary>Directory creation permissions</summary>
<prose>Describes the permissions with which a directory will be created.</prose>
<related><dataref>Permission</dataref></related>
<related><functionref>mkdir</functionref></related>"
public data Permissions([Permission] owner, [Permission] group, [Permission] others, Bool setuid, Bool setgid, Bool sticky);

"<summary>Directory tree</summary>
<prose>A directory tree</prose>
<related><dataref>DirInfo</dataref></related>
<related><functionref>dirinfo</functionref></related>"
public data DirTree([DirInfo] files);

"<summary>Directory entry</summary>
<prose>This data type describes a directory entry, which may either be a sub-directory (which is then described recursively) or a file (or a file-equivalent such as a block device).</prose>
<related><functionref>getDirInfo</functionref></related>"
public data DirInfo 
    = Directory(String dname, [DirInfo] children)
    | Filename(String fname);

foreign "stdfuns.o" {
    Ptr do_tmpFile() = do_tmpFile;
    Ptr fopen(String name, String mode) = do_fopen;
    Ptr freopen(String name, String mode, Ptr f) = do_freopen;
    Bool validFile(Ptr h) = validFile;
    String getLine(Ptr vm,Ptr h) = getLine;
    String do_getString(Ptr vm, Ptr h) = getString;
    Char do_fgetc(Ptr h) = do_fgetc;
    Void doputChar(Int c,Ptr h) = do_fputc;
    Void doPutStr(Ptr h, String s, Int len) = putString;
    Void putLine(Ptr h, String s, Int len) = putLine;
    "<argument name='h'>A file handle</argument>
<argument name='p'>The byte position to seek to (if the file contains multi-byte UTF-8 characters, and is being read as a string, be aware of the problems that positioning the pointer part way through a multi-byte character may cause)</argument>
<summary>Seek to a position in a file</summary>
<prose>Seek to the specified byte of the file. Files opened with the <code>Append</code> file mode will always have writes occur at the end of the file, though this function will affect reading.</prose>
<related><functionref>fpos</functionref></related>"
    Void do_fseek(Ptr h, Int p) = do_fseek;
    Int do_fpos(Ptr h) = do_ftell;
    Bool feof(Ptr h) = do_feof;
    Int do_fflush(Ptr h) = do_fflush;
    Void fclose(Ptr h) = do_fclose;
    Int do_unlink(String fn) = do_unlink;
    Int do_mkdir(String fn, Int umask) = do_mkdir;
    Int do_access(String fn, AccessMode mode) = do_access;
    "<argument name='old'>The current file name (and path)</argument>
<argument name='new'>The new file name (and path)</argument>
<summary>Rename a file</summary>
<prose>Rename a file, moving it to a new directory if necessary. If a file with the name <variable>new</variable> already exists, it will be replaced.</prose>"
    public Void rename(String old, String new) = do_rename;

    Ptr do_opendir(String name) = do_opendir;
    Int do_closedir(Ptr dirh) = do_closedir;
    Ptr do_readdir(Ptr dirh) = do_readdir;
    String dir_getname(Ptr vm,Ptr ent) = dir_getname;

    Stat do_stat(Ptr vm, String name) = do_stat;
    Ptr getstdin() = getstdin;
    Ptr getstdout() = getstdout;
    Ptr getstderr() = getstderr;
}

/* utility functions to validate file handles */
Bool isOpen(File file) = file.open;
Bool isReadable(File file) = file.read;
Bool isWritable(File file) = file.write || file.append;

"<argument name='file'>A file handle</argument>
<summary>Check that a file handle is readable</summary>
<prose>Checks that a file handle is readable, and throws either a <exceptref>ClosedFile</exceptref> or <exceptref>WriteOnlyFile</exceptref> Exception if not.</prose>
<related><functionref>openCheck</functionref></related>
<related><functionref>writeCheck</functionref></related>"
public Void readCheck(File file) {
  openCheck(file);
  if (!isReadable(file)) {
    throw(WriteOnlyFile);
  }
}

"<argument name='file'>A file handle</argument>
<summary>Check that a file handle is open</summary>
<prose>Checks that a file handle is still open, and throws a <exceptref>ClosedFile</exceptref> Exception if not.</prose>
<related><functionref>readCheck</functionref></related>
<related><functionref>writeCheck</functionref></related>"
public Void openCheck(File file) {
  if (!isOpen(file)) {
    throw(ClosedFile);
  }
}

"<argument name='file'>A file handle</argument>
<summary>Check that a file handle is writable</summary>
<prose>Checks that a file handle is writable, and throws either a <exceptref>ClosedFile</exceptref> or <exceptref>ReadOnlyFile</exceptref> Exception if not.</prose>
<related><functionref>openCheck</functionref></related>
<related><functionref>readCheck</functionref></related>"
public Void writeCheck(File file) {
  openCheck(file);
  if (!isWritable(file)) {
    throw(ReadOnlyFile);
  }
}

"<argument name='h'>A file handle</argument>
<summary>Current position of file pointer</summary>
<prose>Get the current byte position of the file pointer.</prose>
<related><functionref>fseek</functionref></related>"
public Int fpos(File h) {
  openCheck(h);
  return do_fpos(h.ptr);
}


"<argument name='h'>A file handle</argument>
<argument name='p'>The byte position to seek to (if the file contains multi-byte UTF-8 characters, and is being read as a string, be aware of the problems that positioning the pointer part way through a multi-byte character may cause)</argument>
<summary>Seek to a position in a file</summary>
<prose>Seek to the specified byte of the file. Files opened with the <code>Append</code> file mode will always have writes occur at the end of the file, though this function will affect reading.</prose>
<related><functionref>fpos</functionref></related>"
public Void fseek(File h, Int p) {
  openCheck(h);
  do_fseek(h.ptr,p);
}

"<argument name='h'>A readable file handle</argument>
<summary>Read a string from a binary file</summary>
<prose>Reads a string (up to NULL termination) from a binary file. If the end of the file is reached, the string read up to that point will be returned. The string is assumed to be UTF-8 encoded.</prose>
<related><functionref>get</functionref></related>
<related><functionref>putStr</functionref></related>"
public String getString(File h) {
  readCheck(h);
  return do_getString(getVM,h.ptr);
}
"<argument name='h'>A readable file handle</argument>
<summary>Read one byte from a file.</summary>
<prose>Read one byte from a file. While the return type is <code>Char</code>, the meaning of values greater than Char(127) will depend on the encoding of the input file, rather than being the UCS character of that number.</prose>
<related><functionref>get</functionref></related>
<related><functionref>putChar</functionref></related>"
public Char getChar(File h) {
  readCheck(h);
  return do_fgetc(h.ptr);
}

"<summary>Standard input stream</summary>
<prose>Returns a file handle pointing to the standard input stream. If none of the optional <moduleref>Curses</moduleref> modules for terminal control are available, basic user input can be obtained using <functionref>IO::get</functionref>.</prose>
<example>input = get(stdin);</example>
<related><functionref>stdout</functionref></related>
<related><functionref>stderr</functionref></related>
<related><functionref>IO::get</functionref></related>"
public File stdin() = File(getstdin,true,true,false,false,false);
"<summary>Standard output stream</summary>
<prose>Returns a file handle pointing to the standard output stream. This may be more appropriate in some circumstances than using <functionref>putStr</functionref> for output.</prose>
<example>input = get(stdin);</example>
<related><functionref>stdin</functionref></related>
<related><functionref>stderr</functionref></related>
<related><functionref>putStr</functionref></related>"
public File stdout() = File(getstdout,true,false,false,true,false);
"<summary>Standard error stream</summary>
<prose>Returns a file handle pointing to the standard error stream. Errors can be written to standard error using <functionref>IO::put</functionref>.</prose>
<example>put(stderr(),\"ERROR: Antler remover jammed!\");</example>
<related><functionref>stdin</functionref></related>
<related><functionref>stdout</functionref></related>
<related><functionref>IO::put</functionref></related>"
public File stderr() = File(getstderr,true,false,false,true,false);

"<argument name='ptr'>The pointer</argument>
<argument name='mode'>The file mode, if known. This should be set if possible.</argument>
<summary>Create a File from a pointer</summary>
<prose>This coerces a pointer to a C file handle into a <code>File</code>. This function is intended solely for writing interfaces to C code that returns file handles, and should not be used for other purposes.</prose>
<related><functionref>ptr</functionref></related>"
public File file(Ptr ptr, [FileMode] mode = [Read,Write,Append]) {
  return File(ptr,true,elem(Read,mode),elem(Write,mode),elem(Append,mode),elem(Binary,mode));
}

"<argument name='ptr'>The file handle</argument>
<summary>Create a Ptr from a file handle</summary>
<prose>This retrieves a C pointer from a file handle, which may sometimes be needed for writing foreign function interfaces. This function should not be used for any other purpose.</prose>
<related><functionref>file</functionref></related>"
public Ptr ptr(File file) {
  openCheck(file);
  return file.ptr;
  // if anyone can think of a way to allow people to write foreign
  // interfaces that involve file handles without exposing this
  // function, that would be great! - CIM
}

"<argument name='h'>A writable or appendable file handle</argument>
<argument name='s'>The string to write</argument>
<summary>Write a string to a binary file</summary>
<prose>Write a string (including NULL termination) to a binary file. The string will be written to the file in UTF-8 encoding.</prose>
<related><functionref>getString</functionref></related>
<related><functionref>put</functionref></related>"
public Void putStr(File h, String s) {
  writeCheck(h);
  doPutStr(h.ptr,s,length(s));
}

String getFileMode([FileMode] mode) {
  for m in mode {
    case m of {
      Read -> read = true;
      | Write -> write = true;
      | Append -> append = true;
      | Binary -> binary = true;
    }
  }
  if (read && write) { fmode = "r+"; }
  else if (read && append) { fmode = "a+"; }
  else if (read) { fmode = "r"; }
  else if (write) { fmode = "w"; }
  else if (append) { fmode = "a"; }
  else {
    throw(InvalidMode);
  }

  if (binary) { fmode+="b"; }
  return fmode;
}

"<argument name='fname'>The name of the file</argument>
<argument name='mode'>A list of file modes</argument>
<summary>Open a file.</summary>
<prose>Open the named file with the specified file modes. Not all combinations of modes are legal, and an <exceptref>InvalidMode</exceptref> Exception will be thrown if an illegal mode is selected. A <exceptref>FileError</exceptref> Exception will be thrown if opening fails for any other reason. Legal mode combinations are:</prose>
<list>
<item><code>[Read,Write]</code>: read and write to any point in the file</item>
<item><code>[Read,Append]</code>: read from any point in the file, write to the end only (creating the file if it does not exist)</item>
<item><code>[Read]</code>: read from any point in the file</item>
<item><code>[Write]</code>: write to any point in the file, creating the file if it does not exist, and truncating it otherwise.</item>
<item><code>[Append]</code>: write to the end of the file, creating the file if it doesn't exist.</item>
</list>
<prose><code>Binary</code> can be added to any of the combinations above to open the file in binary mode on Windows (it has no effect on POSIX platforms).</prose>
<related><functionref>close</functionref></related>
<related><functionref>reopen</functionref></related>"
public File open(String fname, [FileMode] mode)
{
    fmode = getFileMode(mode);

    h = fopen(fname,fmode);
    // Check h is valid.
    if (validFile(h)) {
	return File(h,true,elem(Read,mode),elem(Write,mode),elem(Append,mode),elem(Binary,mode));
    }
    else {
	throw(FileError);
    }
}

"<argument name='fname'>The file name</argument>
<argument name='mode'>A list of file modes</argument>
<argument name='f'>The existing file handle</argument>
<summary>Re-open a file.</summary>
<prose>Re-open a file. This functions exactly like <functionref>open</functionref> except that rather than opening a new file, it changes an existing file handle. This is mainly useful for re-opening the standard input, output and error streams on a different file.</prose>
<example>in = reopen(\"inputscript\",[Read],stdin);</example>
<related><functionref>close</functionref></related>
<related><functionref>open</functionref></related>
<related><functionref>stdin</functionref></related>
<related><functionref>stdout</functionref></related>
<related><functionref>stderr</functionref></related>"
public File reopen(String fname,[FileMode] mode, File f)
{
    openCheck(f);
    fmode = getFileMode(mode);
    h = freopen(fname,fmode,f.ptr);
    // Check h is valid.
    if (validFile(h)) {
      read = elem(Read,mode);
      write = elem(Write,mode);
      append = elem(Append,mode);
      binary = elem(Binary,mode);
      //        f.mode = mode;
        f.ptr = h;
	f.read = read; f.write = write; f.append = append; f.binary = binary;
	return File(h,true,read,write,append,binary);
    }
    else {
	throw(FileError);
    }
}

"<argument name='handle'>A file handle opened for reading</argument>
<summary>Read a line from a file</summary>
<prose>Read a line from a file, including the terminating newline ('\\n').</prose>"
public String get(File handle)
{
    readCheck(handle);
    return getLine(getVM,handle.ptr);
}

"<argument name='handle'>A file handle opened for writing or appending</argument>
<argument name='val'>The string to write</argument>
<summary>Write a string to a file.</summary>
<prose>Write a string to a file. Unlike <functionref>putStr</functionref> this will not write a NULL terminator to the file, and so should be used when dealing with non-binary files.</prose>
<prose><code>put(stdout,str)</code> is equivalent to <code>Builtins::putStr(str)</code></prose>"
public Void put(File handle, String val)
{
    writeCheck(handle);
    putLine(handle.ptr,val,length(val));
}

"<argument name='handle'>A writable file handle</argument>
<argument name='c'>The byte to write</argument>
<summary>Write a character to a file.</summary>
<prose>Write a binary character to a file. <code>Char(200)</code> will write a byte with a value of 200, not the multibyte representation of <code>Char(200)</code> in UTF-8. Writing a character with a value greater than 256 is undefined.</prose>
<related><functionref>getChar</functionref></related>
<related><functionref>put</functionref></related>
<related><functionref>putInt</functionref></related>
<related><functionref>putStr</functionref></related>"
public Void putChar(File handle, Char c)
{
    writeCheck(handle);
    doputChar(Int(c),handle.ptr);
}

"<argument name='handle'>A writable file handle</argument>
<argument name='i'>The integer to write</argument>
<summary>Write an integer to a file (as binary)</summary>
<prose>Write an integer to a file as a set of four binary bytes. The most significant byte is written first.</prose>
<related><functionref>getInt</functionref></related>
<related><functionref>put</functionref></related>
<related><functionref>putChar</functionref></related>
<related><functionref>putStr</functionref></related>"
public Void putInt(File handle, Int i)
{
    writeCheck(handle);
    putChar(handle, Char(i>>24));
    putChar(handle, Char((i>>16) & 255));
    putChar(handle, Char((i>>8) & 255));
    putChar(handle, Char(i & 255));
}

"<argument name='handle'>A readable file handle</argument>
<summary>Get a binary integer from a file.</summary>
<prose>Retrieves the next four bytes from the file, and converts them to an integer, most significant byte first.</prose>
<related><functionref>get</functionref></related>
<related><functionref>getChar</functionref></related>
<related><functionref>getString</functionref></related>
<related><functionref>putInt</functionref></related>"
public Int getInt(File handle)
{
    readCheck(handle);
    c1 = Int(getChar(handle));
    c2 = Int(getChar(handle));
    c3 = Int(getChar(handle));
    c4 = Int(getChar(handle));
    return (c1<<24)+(c2<<16)+(c3<<8)+c4;
}

"<argument name='handle'>The file handle</argument>
<summary>Check for end of file.</summary>
<prose>This returns true if the end of the file has been reached, and false otherwise. It is always false after <functionref>fseek</functionref>.</prose>
<example>lines = [];
while (!eof(h)) {
    push(lines,get(h));
}</example>
<related><functionref>open</functionref></related>"
public Bool eof(File handle)
{
    openCheck(handle);
    return feof(handle.ptr);
}

"<argument name='handle'>The file handle</argument>
<summary>Flush all data to a file.</summary>
<prose>Flush all buffered data to the file on the handle. An Exception will be thrown if the file is not writable, or if an error occurred when writing the data.</prose>"
public Void flush(File handle)
{
    writeCheck(handle);
   
    // FIXME: Capture errno and strerror(errno).
    if (do_fflush(handle.ptr) != 0) {
        throw(FileError);
    }
}

"<argument name='handle'>Close a file handle</argument>
<summary>Close a file.</summary>
<prose>Close a file handle after you no longer need it. It is strongly recommended that you do not close the three standard file handles - use <functionref>reopen</functionref> to open them onto <code>/dev/null</code> instead.</prose>"
public Void close(File handle)
{
    openCheck(handle);
    fclose(handle.ptr);
    handle.open = false;
}

"<argument name='fname'>A file name</argument>
<summary>Read a text file.</summary>
<prose>Reads the entire contents of <variable>fname</variable> into a String. This function assumes that the file is a text file, rather than a binary file.</prose>
<related><functionref>Binary::readBlock</functionref></related>
<related><functionref>writeFile</functionref></related>"
public String readFile(String fname)
{
    contents = "";
    f = open(fname,[Read]);
    while(!eof(f)) {
	contents = contents+get(f);
    }
    close(f);
    return contents;
}

"<argument name='fname'>A file name</argument>
<argument name='content'>The content to write</argument>
<summary>Write a text file.</summary>
<prose>Writes <variable>content</variable> into <variable>fname</variable>, replacing the file if it exists, and creating it otherwise.</prose>
<related><functionref>Binary::writeBlock</functionref></related>
<related><functionref>readFile</functionref></related>"
public Void writeFile(String fname, String content) 
{
    f = open(fname,[Write]);
    put(f,content);
    close(f);
}

"<summary>Create and open a temporary file.</summary>
<prose>Create and open a temporary file (in binary read+write mode), and return a file handle. You can then apply any of the normal IO operations to this file.</prose>"
public File tmpFile() {
  return File(do_tmpFile,true,true,true,false,true);
}

"<argument name='fname'>The file name</argument>
<summary>Unlinks a file.</summary>
<prose>Unlinks a file, throwing a <exceptref>FileError</exceptref> Exception on failure. If the last link to a file is removed, this file is deleted.</prose>"
public Void unlink(String fname)
{
  r = do_unlink(fname);
  if (r != 0) {
      throw(FileError);
  }
}

"<argument name='dname'>The directory name</argument>
<argument name='mode'>The permissions to set. This is optional, and if omitted will default to setting all access permissions allowed by the current process umask, but will not set the setUID, setGID, or sticky bit. On Windows, this parameter is ignored completely as the file permissions system is very different.</argument>
<summary>Makes a directory.</summary>
<prose>Makes a directory, throwing a <exceptref>FileError</exceptref> Exception if creation fails. The permissions set will be affected by the current process umask (see the mkdir(2) man page) on Posix systems.</prose>
<related><dataref>Permissions</dataref></related>"
public Void mkdir(String dname, Permissions mode = Permissions([ReadP,WriteP,ExecuteP],[ReadP,WriteP,ExecuteP],[ReadP,WriteP,ExecuteP],false,false,false)) 
{
  modeint = (64*permBits(mode.owner))+(8*permBits(mode.group))+permBits(mode.others);
  if (mode.setuid) {
    modeint += 2048;
  }
  if (mode.setgid) {
    modeint += 1024;
  }
  if (mode.sticky) {
    modeint += 512;
  } 
  r = do_mkdir(dname,modeint);
  if (r != 0) {
      throw(FileError);
  }
}

Int permBits([Permission] mode) {
  p = 0;
  if (elem(ReadP,mode)) {
    p += 4;
  } 
  if (elem(WriteP,mode)) {
    p += 2;
  } 
  if (elem(ExecuteP,mode)) {
    p += 1;
  } 
  return p;
}

"<argument name='fname'>The file name</argument>
<summary>Checks a file exists</summary>
<prose>Returns true if the filename exists, false otherwise. If the file exists, but the current process is unable to determine this (for example, because the file is in an unreadable directory), false will be returned.</prose>
<related><functionref>fileExecutable</functionref></related>
<related><functionref>fileReadable</functionref></related>
<related><functionref>fileWritable</functionref></related>
<related><functionref>stat</functionref></related>"
public Bool fileExists(String fname) {
  if (do_access(fname,FExists) == 0) {
    return true;
  } else {
    return false;
  }
}

"<argument name='fname'>The file name</argument>
<summary>Checks a file is readable</summary>
<prose>Returns true if the file is readable by the current proces, false otherwise.</prose>
<related><functionref>fileExecutable</functionref></related>
<related><functionref>fileExists</functionref></related>
<related><functionref>fileWritable</functionref></related>
<related><functionref>stat</functionref></related>"
public Bool fileReadable(String fname) {
  if (do_access(fname,FRead) == 0) {
    return true;
  } else {
    return false;
  }
}

"<argument name='fname'>The file name</argument>
<summary>Checks a file is writable</summary>
<prose>Returns true if the file is writable by the current proces, false otherwise.</prose>
<related><functionref>fileExecutable</functionref></related>
<related><functionref>fileExists</functionref></related>
<related><functionref>fileReadable</functionref></related>
<related><functionref>stat</functionref></related>"
public Bool fileWritable(String fname) {
  if (do_access(fname,FWrite) == 0) {
    return true;
  } else {
    return false;
  }
}

"<argument name='fname'>The file name</argument>
<summary>Checks a file is executable</summary>
<prose>Returns true if the file is executable by the current proces, false otherwise.</prose>
<related><functionref>fileExists</functionref></related>
<related><functionref>fileReadable</functionref></related>
<related><functionref>fileWritable</functionref></related>
<related><functionref>stat</functionref></related>"
public Bool fileExecutable(String fname) {
  if (do_access(fname,FExecute) == 0) {
    return true;
  } else {
    return false;
  }
}

"<argument name='fname'>The directory name</argument>
<summary>Open a directory</summary>
<prose>Open a directory for reading, throwing a <exceptref>DirError</exceptref> Exception on error.</prose>
<related><functionref>closeDir</functionref></related>
<related><functionref>dirinfo</functionref></related>
<related><functionref>listDir</functionref></related>
<related><functionref>readDir</functionref></related>"
public Dir openDir(String fname) {
    ptr = do_opendir(fname);
    if (null(ptr)) {
	throw(DirError);
    }
    return Dir(ptr);
}

"<argument name='h'>The directory handle</argument>
<summary>Close a directory handle</summary>
<prose>Close a directory handle, throwing a <exceptref>DirError</exceptref> Exception on error.</prose>
<related><functionref>dirinfo</functionref></related>
<related><functionref>listDir</functionref></related>
<related><functionref>openDir</functionref></related>
<related><functionref>readDir</functionref></related>"
public Void closeDir(Dir h) {
    if (do_closedir(h.ptr)!=0) {
	throw(DirError);
    }
}

"<argument name='h'>The directory handle</argument>
<summary>Get the next directory entry.</summary>
<prose>Get the next directory entry from an open directory handle. A <exceptref>DirError</exceptref> Exception will be thrown on error, or on reaching the end of the directory.</prose>
<related><functionref>closeDir</functionref></related>
<related><functionref>dirinfo</functionref></related>
<related><functionref>listDir</functionref></related>
<related><functionref>openDir</functionref></related>"
public DirEntry readDir(Dir h) {
    Ptr ent = do_readdir(h.ptr);
    if (null(ent)) {
	throw(DirError);
    }
    name = dir_getname(getVM,ent);
    return DirEntry(name);
}

"<argument name='dirname'>The name of the directory</argument>
<summary>Get a list of files in a directory</summary>
<prose>Returns a list of all file and sub-directory names in the directory, including <code>\".\"</code> and <code>\"..\"</code>.</prose>"
public [String] listDir(String dirname) {
    dir = openDir(dirname);
    fs = [];
    try {
	while(true) {
	    ent = readDir(dir); // Throws at the end. Yeuch.
	    push(fs,ent.name);
	}
    }
    catch(e) {
	if (e==DirError) {
	    closeDir(dir);
	    return fs;
	}
	else {
	    throw(e);
	}
    }
    return fs;
}

"<argument name='fname'>The file name</argument>
<summary>Get file information.</summary>
<prose>Get detailed information about the access permissions and type of a file.</prose>
<related><dataref>Stat</dataref></related>"
public Stat stat(String fname)
{
//    putStrLn("statting "+fname);
// FIXME: do_stat might throw, we need to get the errno and convert it to
// some useful message with the C strerror function.
    return do_stat(getVM(),fname);
}

"<argument name='fname'>The initial directory</argument>
<summary>Return a directory tree</summary>
<prose>Return the directory tree rooted at <variable>fname</variable>.</prose>"
public DirTree dirinfo(String fname)
{
    return DirTree(getDirInfo(fname));
}

"<argument name='fname'>The initial directory</argument>
<summary>Return a list of directory trees</summary>
<prose>Return the directory trees and filenames in <variable>fname</variable>.</prose>
<related><functionref>dirinfo</functionref></related>
<related><functionref>listDir</functionref></related>"
public [DirInfo] getDirInfo(String fname) {
    fs = listDir(fname);
    inf = [];
    for f in fs {
	realf = fname+"/"+f;
	stats = stat(realf);
	if (stats.mode.dir) {
	    if (f!="." && f!="..") {
		children = getDirInfo(realf);
		push(inf, Directory(f, children));
	    }
	}
	else {
	    push(inf, Filename(f));
	}
    }
    return inf;
}