''' Summary '''
A listing and description of VFS functions made available to Javascript, used to provide file information and access.

[KEEP IN SYNC WITH TDD AND CODE!]

= VFS Global Functions =

Scope: this documentation only covers the Javascript binding, not VFS itself.

These stateless functions provide basic file system access within the VFS sandbox. Expected use is in map/saved game selection dialogs; more complex tasks should utilize the complete vfs.h native code interface.

== !BuildFileList ==
 * '''Overview:'''
  * Return an array of pathname strings, one for each matching entry in the specified directory.
 * '''Syntax:'''
  * pathnames = Engine.!BuildFileList(directory [, filter_string [, recurse]]);
 * '''Parameters:'''
  * directory: VFS path
  * filter_string: default "" matches everything; otherwise, see vfs_next_dirent.[[BR]]
  * recurse: should subdirectories be included in the search? default false.
 * '''Returns:'''
  * Array of matching pathnames
 * '''Notes:'''
  * Full pathnames of each file/subdirectory are returned, ready for use as a "filename" for the other functions.

== !FileExists ==
 * '''Overview:'''
  * Return true iff the specified file exits.
 * '''Syntax:'''
  * filexists = Engine.!FileExists(filename);
 * '''Parameters:'''
   * filename: VFS filename (may include path)
 * '''Returns:'''
   * true iff file exists, false otherwise
 * '''Notes:'''

== GetFileMTime ==
 * '''Overview:'''
  * Return time [seconds since 1970] of the last modification to the specified file.
 * '''Syntax:'''
  * mtime = Engine.GetFileMTime(filename);
 * '''Parameters:'''
  * filename: VFS filename (may include path)
 * '''Returns:'''
  * Seconds-since-1970
 * '''Notes:'''

== !GetFileSize ==
 * '''Overview:'''
  * Return current size of file.
 * '''Syntax:'''
  * size = Engine.!GetFileSize(filename);
 * '''Parameters:'''
  * filename: VFS filename (may include path)
 * '''Returns:'''
  * Size in bytes
 * '''Notes:'''

== !ReadFile ==
 * '''Overview:'''
  * Return file contents in a string.
 * '''Syntax:'''
  * contents = Engine.!ReadFile(filename);
 * '''Parameters:'''
  * filename: VFS filename (may include path)
 * '''Returns:'''
  * String
 * '''Notes:'''

== !ReadFileLines ==
 * '''Overview:'''
  * Return file contents as an array of lines.
 * '''Syntax:'''
  * lines = Engine.!ReadFileLines(filename);
 * '''Parameters:'''
  * filename: VFS filename (may include path)
 * '''Returns:'''
  * Array of strings
 * '''Notes:'''