ServerJS/API/file

Tier 1

The require('file') module would provide support the File System API. In turn, the File System API would provide all methods that deal with path strings. File System API functions would return file stream objects, directory objects, and file stat objects. File stream objects would, for securability, be unaware of their corresponding path, and keep their underlying file system connection, albeit a file descriptor or FILE*, and their parent directory link, secret.

The File System API would provide the following methods:

• normal: removes '.' path components and simplifies '..' paths, if possible for a given path. If the file system is case sensitive, transforms all letters to lower-case to make them unambiguous.

• absolute: returns the absolute path, starting with the root of this file system object, for the given path, resolved relative to the current working directory. If the file system supports home directory aliases, absolute resolves those from the root of the file system. The resulting path is in normal form. On most systems, this is equivalent to expanding any user directory alias, joining the path to the current working directory, and normalizing the result.

• canonical: returns the canonical path to a given abstract path. Canonical paths are both absolute and intrinsic, such that all paths that refer to a given file (whether it exists or not) have the same corresponding canonical path. This function may not communicate information about the true parent directories of files in chroot environments. This function is equivalent to expanding a user directory alias, joining the given path to the current working directory, joining all symbolic links along the path, and normalizing the result.

• exists(path): whether a file exists at a given path: receives a path and returns whether that path, joined on the current working directory, corresponds to a file that exists. If the file is a broken symbolic link, returns false.

• stat(path): returns an object that represents a snapshot of the information about given file.
  1. The stat file must contain the following properties:
     1. mtime: the time that the file was last modified
     2. other properties will be specified in a future specification, including other times, ownership, permissions, and size.
  2. The path is resolved relative to the current working directory.
  3. Throws an error if the corresponding file does not exist or is inaccessible.

• list(path): returns a traversable, indexable representation of the names of files in a particular directory.
  1. The returned object implements the Array API for indexing, and may in fact be an Array if the underlying implementation is not sophhisticated enough to do lazy indexing. The prototype of the returned object contains all of the Array generics like "push", "pop", and such.
  2. The returned object may be immutable.
  3. The returned object must implement "next" and "prev", which walk backward and forward among the file names in the directory. Both throw an exception when they are beyond the bounds of the directory.
  4. The path is resolved relative to the current working directory.
  5. Throws an error if the directory does not exist or is inaccessible.

• open(path, mode, permissions, encoding): returns an IO stream object that supports the requested mode and encoding.
  1. The encoding must be undefined, "utf-8", or "utf-16". Other encodings may be specified in the future.
     1. An undefined encoding means "binary", and implies that read and write methods will operate on byte array objects (not yet specified) instead of strings. The "cookie" returned by "tell" and accepted by "seek" can only be an integer for binary encoding (although this tier does not specify those methods).
  2. The mode is a String and may contain:
     1. "r" that means that the stream may be read, and implies that the "read", "readLine", "readLines", "next", and "iter" methods must be supported by the returned stream object. "readLine" returns "" on EOF, and "next" throws an error instead. "iter" returns the stream object itself. "readLine" returns a string excluding the newline character.
     2. "w" that means that the stream may be written to, and implies that the "write", "writeLine", and "writeLines" methods must be supported by the stream object. Also implies that the file will be created or truncated if necessary, if not overridden by the "a" or "+" flags.
     3. "a" that means that the stream's position will begin at the end of the stream, and that the file will be created but not truncated.
     4. "+" that means that the stream will not be truncated.
     5. other options may be added in the future for advisory locks.
     6. the "b" option known in other languages will not be implemented since it is really an encoding argument.
  3. The permissions must be an integer of Unix style permissions. Other objects may be permitted in a later specification, like a Stat object or duck-type thereof.
  4. The path is resolved relative to the current working directory.
  5. Throws an error if the specified stream cannot be created.
• close(): Closes the file. Should be called automatically when the mode is changed, and when the garbage collector collects its last reference.

Tier 2

In progress. More information about other potential additions, please refer to the names.