ServerJS/API/file: Difference between revisions

Jump to navigation Jump to search

ServerJS/API/file (view source)

Revision as of 06:38, 26 March 2009

5,149 bytes added ,  26 March 2009
m
Reinserted etymologies.
m (Reinserted etymologies.)
Line 1: Line 1:
= High Level =


# make vs. create
= API and Proposed Names =
#* make:
 
#** Mario Valente,
The following sections are organized with a bullet point per function.  Each point includes a specification for the behavior of a given method, intended to be suitable for documentation. Under each definition is a list of potential names for that function, and in bullets beneath that, everyone is encouraged to write their name under their preference.  Please feel to leave comments as well.
#** Wes Garland (but only for directories)
 
#* create:
In the next section, "General Preferences", there are several broad sweeping points about whether to use certain conventions in a consistent fashion. All of the name options are intended to conform to the prevalent opinion among those elections. For example, "make" and "create" and "dir" and "directory" are both general preference elections, so if you would prefer "makeDir" over "createDirectory", please vote independently for "make" and "dir" in the general preferences.
#** George Moschovitis,
#** Wes Garland (but only for files)
#** Ondrej Zara
# dir vs. directory
#* directory:
#** Tom Robinson,
#** Kevin Dangoor,
#** George Mosochovitis,
#** Wes Garland
#** Ondrej Zara
#* dir:
#** Mario Valente
# cur vs. current
#* current:
#** Tom Robinson,
#** Kevin Dangoor,
#** Wes Garland,
#** Kris Kowal,
#** Mario Valente
#** Ondrej Zara
#** George Moschovitis
#* cur:
# canonize, realize, normalize, qualify, cannon, real, normal, qualified, absolute, cannonicalize
#* remove . and ..:
#** normalize:
#*** Tom Robinson,
#*** Kevin Dangoor,
#*** Kris Kowal,
#*** George Mosochovitis
#** qualify:
#*** Wes Garland
#** expand:
#*** Ondrej Zara
#* remove . and .., start at /:
#** absolute:
#*** Tom Robinson,
#*** Kevin Dangoor,
#*** Kris Kowal,
#*** George Mosochovitis,
#*** Wes Garland,
#*** Mario Valente
#** qualified:
#*** Wes Garland
#** normalize:
#*** Ondrej Zara
#* remove . and .., start at /, follow symlinks:
#** canonical:
#*** Tom Robinson,
#*** Kevin Dangoor,
#*** Kris Kowal
#** absolute:
#*** George Mosochovitis,
#*** Wes Garland,
#*** Mario Valente,
#** real:
#*** Tom Robinson,
#*** Kevin Dangoor
#** qualified:
#*** Wes Garland
# constantCase, CONSTANT_CASE, kConstantCase
#* constantCase:
#** Kris Kowal,
#** Wes Garland,
#** Mario Valente,
#* CONSTANT_CASE:
#** Tom Robinson,
#** Kevin Dangoor
#** Ondrej Zara
#** George Moschovitis
# "static" methods
#* require(module).staticMethod:
#** Kris Kowal
#** Wes Garland
#** Mario Valente
#** Ondrej Zara
#* require(module).Klass.staticMethod:
#** Tom Robinson
#** George Mosochovitis
# properties, accessors, mutators
#* foo.setX(x); foo.getX()
#** For:
#** Against:
#* foo.setX(x); foo.X()
#** For:
#** Against:
#* no convention
#** For:
#** Against:
#* foo.x = x; foo.x
#** For:
#*** Davey Waterson
#*** Wes Garland
#*** Daniel Friesen
#*** Sam Phillips
#** Against:
#*** Tom Robinson
#*** Kris Kowal


= API and Proposed Names =


== File System Object ==
== File System Object ==


* the location of the file system type.
The "file" module would conform to the File System API, as well as objects returned by "chroot".  There is no definitive implementation of a FileSystem class, so "chroot" is the only way to construct new objects that conform to the FileSystem API.  In permissive environments, the "file" module may have direct access to ambient authority through a foreign function interface, or may itself be a dynamically loaded module.  In secured environments, the "file" module must copy the properties of "environment.fs" onto its exports.
** environment.fs
 
** The file module would not expose a FileSystem constructor, since that implies "ambient authority" to get wholesale access to the file system, although platform specific modules that depend on ambient authority in a permissive environment might be used to construct this FileSystem object, and it could be then safely chrooted or passed directly to a sandbox in its environment with the same name.  The "fs" object would conform to the following API.
In a secure sandbox, the following statements would be equivalent.
* the location of the file system object provided to your environment.
 
** is provided as "environment.fs" in all modules and has all of the properties and methods defined for the FileSystem type:
require('file').open(foo)
*** Kris Kowal
environment.fs.open(foo)
 
Since "fs" must be frozen to be secure, there is no need for the "file" module to assemble aparatus for late binding to "fs" methods.


* 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.
* 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.
** exists(path):
** exists(path):
*** Kris Kowal
*** Kris Kowal
*** Wes Garland
*** Wes Garland
*** (Python: os.path.exists, Ruby: exist?, exists?, Java: exists, JSExt: access, Spidermonkey: Helma: v8cgi: JSExt: EJScript: Synchronet: exists, jslibs: exist)


* whether a symbolic link or file exists at a given path: receives a path and returns whether that path, joined on the current working directory, corresponds to a file, albeit a broken symbolic link, that exists.
* whether a symbolic link or file exists at a given path: receives a path and returns whether that path, joined on the current working directory, corresponds to a file, albeit a broken symbolic link, that exists.
Line 128: Line 32:
** exists(path, "link"):
** exists(path, "link"):
*** Kris Kowal (as a compromise)
*** Kris Kowal (as a compromise)
** (Python: os.path.lexists)


* moves a file from a source to a target path.  both paths are joined on the current working directory.
* moves a file from a source to a target path.  Both paths are joined on the current working directory.
** move(source, target):
** move(source, target):
*** uncontested
** (Ruby: move, Python: shutil.move, Java: File.renameTo)


* renames a file: receives two paths.  The first is a path, joined on the current working directory, that refers to the file to rename.  The second argument is a path relative to the former file's fully qualified path.
* renames a file: receives two paths.  The first is a path, joined on the current working directory, that refers to the file to rename.  The second argument is a path relative to the former file's fully qualified path.
Line 137: Line 42:
** should not be included in the spec:
** should not be included in the spec:
*** Kris Kowal
*** Kris Kowal
** (Ruby: rename)


* copies a file from a source to a target path.  Both paths are joined on the current working directory.
* copies a file from a source to a target path.  Both paths are joined on the current working directory.
** copy(source, target):
** copy(source, target):
*** uncontested
** (Ruby: copy, systemCopy, Python: copy, Unix: cp)
 
* copies a file and its recursive contents to a target path.  Both paths are joined on the current working directory.  If "synbolicLinks" is truthy, symbolic links in the source tree are represented as symbolic links in the new tree; if falsy, the contents of the linked files are copied to the new tree.  If ignore is given, it must be a relation that will receive as its arguments the directory being visited by copytree(), and a list of its contents. Since this is called recursively (or walking an equivalent iteration), the ignore relation will be called once for each directory that is copied. The relation must return a sequence of directory and file names relative to the current directory (i.e. a subset of the items in its second argument); these names will then be ignored in the copy process.
** copyTree(source, target, symbolicLinks = false, ignore = undefined)
** copy(source, target, "recursive")
** copy(source, target, true)
** (Python: copytree)


* makes a directory at a given path in the base directory implied by the given path.  Throws an exception if the base directory does not exist, or if the given path already exists.
* makes a directory at a given path in the base directory implied by the given path.  Throws an exception if the base directory does not exist, or if the given path already exists.
Line 147: Line 59:
** createDirectory(path):
** createDirectory(path):
*** Mario Valente
*** Mario Valente
** (Unix: mkdir)


* makes any directories that are missing on a given path.  Does not throw an exception if any of the base paths are missing, and does not throw an exception if all of the path already exists. Only throws an exception if it can't make the path exist.
* creates recursive directories.  Makes all intermediate-level directories needed to contain the leaf directory. Throws an exception if the leaf directory already exists or cannot be created. The default mode is 0777 (octal). On some systems, mode is ignored. Where it is used, the current umask value is first masked out.
** makePath(path):
** makePath(path):
*** Kris Kowal
*** Kris Kowal
** makeDirectory(path, true):
** makeDirectory(path, true):
*** Wes Garland
*** Wes Garland
** makeDirectory(path, "recursive"):
** makeDirectory(path, "path"):
** makeDirectory(path, "path"):
*** Kris Kowal (as a compromise)
*** Kris Kowal (as a compromise)
** makeTree(path)
** (Unix: mkdir -p, Ruby: makedirs, mkpath, Python: os.makedirs)


* removes a file.
* removes a file.
Line 164: Line 80:
** unlink(path):
** unlink(path):
*** Wes Garland
*** Wes Garland
** (Ruby: unlink, delete, Python: unlink, remove, Java: delete, Posix: unlink, Unix: rm, Spidermonkey: Helma: EJScript: Synchronet: remove, jslibs: Delete)


* removes a file or directory and its recursive contents.
* removes a file or directory and its recursive contents.
Line 170: Line 87:
** remove(path, "recursive")
** remove(path, "recursive")
** removeRecursive(path)
** removeRecursive(path)
** removeTree(path, ignoreErrors = false, onError = undefined)
** (Unix: rm -r, Python: rmtree)


* creates a hard link of the source path as the target path.  Both paths are joined on the current working directory.
* creates a hard link of the source path as the target path.  Both paths are joined on the current working directory.
** link(source, target):
** link(source, target):
*** uncontested
*** uncontested
** (Python: link, Ruby: link, Unix: ln)


* creates a symbolic link on a given "target" file name.  The source path becomes the text of the symbolic link, which the underlying system will join on the containing directory when it's followed, while the target path is joined on the current working directory.
* creates a symbolic link on a given "target" file name.  The source path becomes the text of the symbolic link, which the underlying system will join on the containing directory when it's followed, while the target path is joined on the current working directory.
Line 182: Line 102:
** link(source, target, "symbolic"):
** link(source, target, "symbolic"):
*** Kris Kowal (as a compromise)
*** Kris Kowal (as a compromise)
** (Ruby: symlink, Python: symlink, Unix: ln -s)


* creates an empty file at a given path in its implied base directory.  The path is resolved relative to the current working directory.  Accepts an optional ``Permissions`` object (or a duck-type thereof, or the, typically octal, numeric representation of permissions in Unix) that notes which permissions the file will be created with, assuming that those permissions are in the "umask".
* creates an empty file at a given path in its implied base directory.  The path is resolved relative to the current working directory.  Accepts an optional ``Permissions`` object (or a duck-type thereof, or the, typically octal, numeric representation of permissions in Unix) that notes which permissions the file will be created with, assuming that those permissions are in the "umask".
Line 189: Line 110:
*** Kris Kowal,
*** Kris Kowal,
*** Wes Garland
*** Wes Garland
** (Java: createNewFile, Posix: creat, Unix: touch)


* truncates a the file at a given path.  Accepts an optional length that default to zero.  The path is resolved on the current working directory.
* truncates a the file at a given path.  Accepts an optional length that default to zero.  The path is resolved on the current working directory.
** truncate(path, [length = 0]):
** truncate(path, [length = 0]):
*** uncontested
** omit entirely:
*** Kris Kowal
** (Ruby: truncate, Python: ftruncate applies to open files only)


* updates the stat/metadata of the file at a given path.  Accepts a stat object.  Implicitly updates the time that the file's metadata/stat was updated to the current time, regardless of the metadata modification time provided by the stat object.
* updates the stat/metadata of the file at a given path.  Accepts a stat object.  Implicitly updates the time that the file's metadata/stat was updated to the current time, regardless of the metadata modification time provided by the stat object.
*** Wes Garland
** update(path, stat):
** update(path, stat):
*** Wes Garland
** chstat(path, stat):
** setStat(path, stat):
** restat(path, stat):
** (a low-level alternative to Python's copy2 and copyStat)


* updates the modification time of the file at a given path.  Accepts an alternate modification time to set the file.  Also implicitly updates the time that the file's metadata/stat object was updated to the current time, regardless of the chosen modification time.
* updates the modification time of the file at a given path.  Accepts an alternate modification time to set the file.  Also implicitly updates the time that the file's metadata/stat object was updated to the current time, regardless of the chosen modification time.
** touch(path, [date]):
** touch(path, [date]):
*** Kris Kowal
*** Kris Kowal
** (Unix: touch)


* locks the file at a given path with either an exclusive or shared lock.  The path is resolved on the current working directory.  Blocks until the lock is acquired, or if a timeout is defined, when that timeout occurs.
* locks the file at a given path with either an exclusive or shared advisory lock.  The path is resolved on the current working directory.  Blocks until the lock is acquired, or if a timeout is defined, when that timeout occurs.
** lock(path, "shared|exclusive", [timeout=undefined]):
** lock(path, "shared|exclusive", [timeout=undefined]):
*** Wes Garland
*** Wes Garland
*** Kris Kowal
*** Kris Kowal
** lock(path, "rw|")
** (Posix: lock, Python: lock)


* attempts to lock a file at a given path.  The path is resolved relative to the current working directory.  Does not block if the file is not lockable.  Returns whether the lock was obtained.
* attempts to acquire an advisory lock a file at a given path but does not block.  The path is resolved relative to the current working directory.  Does not block if the file is not lockable.  Returns whether the lock was obtained.
*** Wes Garland
** tryLock(path, "shared|exclusive"):
** tryLock(path, "shared|exclusive"):
*** Wes Garland
** lock(path, "rw")
** (Python: lock)


* releases a lock for a given path.
* releases a lock for a given path.
Line 215: Line 148:
*** Kris Kowal
*** Kris Kowal
** lock(path, "unlock")
** lock(path, "unlock")
** lock(path, "u")
** (Python: lock)


* retrieves an object that represents the metadata of a distinct file, for a given path.  The path is resolved relative to the current working directory.  The returned object has the properties described in the Stat API.
* retrieves an object that represents the metadata of a distinct file, for a given path.  The path is resolved relative to the current working directory.  The returned object has the properties described in the Stat API.
** stat(path):
** stat(path):
*** Mario Valente
*** Mario Valente
** (Python: os.stat, Ruby: File.stat, Posix: stat)


* retrieves an object that represents the metadata of a distinct file or symbolic link to a file at a given path.  The path is resolved relative to the current working directory.  The returned object has the properties described in the Stat API.
* retrieves an object that represents the metadata of a distinct file or symbolic link to a file at a given path.  The path is resolved relative to the current working directory.  The returned object has the properties described in the Stat API.
Line 227: Line 163:
** stat(path, "link"):
** stat(path, "link"):
*** Kris Kowal (as a compromise)
*** Kris Kowal (as a compromise)
** (Python: os.lstat, Ruby: File.lstat)


* returns the size of the corresponding file.
* returns the size of the corresponding file.
** size(path)
** size(path)
** (Python: size, Ruby: size?: Java: length, Posix: st_size)


* returns the total size of a tree of files.
* returns the total size of a tree of files.
Line 236: Line 174:
** recursiveSize(path)
** recursiveSize(path)


* returns an IO object for accessing or manipulating the data in a file at a given path.  The path is resolved relative to the current working directory.
* returns an IO object for accessing or manipulating the data in a file at a given path.  The path is resolved relative to the current working directory.  The given permissions object may be a Unix numeric representation of permissions, a Stat object, or any object that provides the members of Stat regarding permissions.
** open(path, "+arwxc", encoding):
** open(path, "+arwxc", permissions, encoding):
*** Mario Valente
*** Mario Valente
*** Kris Kowal
*** Kris Kowal
Line 247: Line 185:
*** x, exclusive (lock)
*** x, exclusive (lock)
*** c, canon (nonblocking)
*** c, canon (nonblocking)
** (Java: FileStream classes, Python: open, file, Ruby: File.new, universal precedent among SSJS frameworks)


* return a Dir object for a given directory path.  The path is resolved relative to the current working directory.  The Dir object is an bidirectional iterator of a snapshot of the contents of the directory, and may be either a lazy Array or genuine array, depending on whether the underlying implementation can retrieve indicies on demand.
* return a Dir object for a given directory path.  The path is resolved relative to the current working directory.  The Dir object is an bidirectional iterator of a snapshot of the contents of the directory, and may be either a lazy Array or genuine array, depending on whether the underlying implementation can retrieve indicies on demand.
** list(path)
** list(path)
** (Python: os.listdir, Ruby: Dir)


* returns an object that, like a Dir, supports the iterator protocol (next, prev) and the Array protocol (length, [index]) for all files that match a given glob pattern.
* returns an object that, like a Dir, supports the iterator protocol (next, prev) and the Array protocol (length, [index]) for all files that match a given glob pattern.
Line 258: Line 198:
*** {a,b,c} - the letters a, b, or c, or any other union of paths.
*** {a,b,c} - the letters a, b, or c, or any other union of paths.
** glob(pattern)
** glob(pattern)
** (Ruby: Dir[])


* returns whether a given path matches a glob pattern.
* returns whether a given path matches a glob pattern.
** match(pattern, path)
** match(pattern, path)
** (Ruby: fnmatch)


* returns a new object that implements the file system API that uses the directory at the given path as its root.  Resolves the path relative to the current working directory.
* returns a new object that implements the file system API that uses the directory at the given path as its root.  Resolves the path relative to the current working directory.
Line 268: Line 210:
== Paths ==
== Paths ==


More properites of a FileSystem.
More properites of a FileSystem object.


* a string directing a path up to the parent of the current directory, usually '..'.
* a string directing a path up to the parent of the current directory, usually '..'.
** parent
** PARENT
** (a function that gets an opaque reference to the actual parent node on the file system, as referenced by the directory's parent hard link, has been deliberately omitted to avoid leaking the capability to access that object from within a chroot file system)
** (a function that gets an opaque reference to the actual parent node on the file system, as referenced by the directory's parent hard link, has been deliberately omitted to avoid leaking the capability to access that object from within a chroot file system)
** (Python: pardir)


* a string directing a path back to itself, usually '.'.
* a string directing a path back to itself, usually '.'.
** self
** SELF
** (Python: curdir)


* a string that contains the path separator, usually '/', '\', or ':'.
* a string that contains the path separator, usually '/', '\', or ':'.
** separator
** SEPARATOR
** (Python: sep, Spidermonkey: separator, Ruby: SEPARATOR, Separator)


* a string that contains the alternate path separator, if it exists.  Otherwise, undefined.
* a string that contains the alternate path separator, if it exists.  Otherwise, undefined.
** alternateSeparator
** ALTERNATE_SEPARATOR
** (Python: altsep, Ruby: ALT_SEPARATOR)


* a string that contains the extension separator, usually '.'.
* a string that contains the extension separator, usually '.'.
** extensionSeparator
** EXTENSION_SEPRATOR
** (Python: extsep)


* whether the file system supports unicode file names
* whether the file system supports unicode file names
** supportsUnicodeFileNames
** SUPPORTS_UNICODE_FILE_NAMES


* accepts a variadic list of paths as arguments and follows each successive path from the current working directory, left to right, and returns the normalized path of the ultimate file or directory.  Paths that end with a directory separator refer to the contents of a directory as a place to continue resolving, whereas paths that do not end with a directory separator indicate that the next path should be followed from the directory containing that file.
* accepts a variadic list of paths as arguments and follows each successive path from the current working directory, left to right, and returns the normalized path of the ultimate file or directory.  Paths that end with a directory separator refer to the contents of a directory as a place to continue resolving, whereas paths that do not end with a directory separator indicate that the next path should be followed from the directory containing that file.
Line 297: Line 244:
* takes a string and returns an escaped path component of that string, such that directory separators and other special characters do not partition it into multiple path components
* takes a string and returns an escaped path component of that string, such that directory separators and other special characters do not partition it into multiple path components
** escape(string)
** escape(string)
** (not precedented)


* returns the path of the directory containing a given path.
* returns the path of the directory containing a given path.
Line 303: Line 251:
** dirname(path)
** dirname(path)
*** Wes Garland
*** Wes Garland
** (Python: Unix: dirname)


* returns the last path component without its extension.  The extension begins after the first extension separator.
* returns the last path component without its extension.  The extension begins after the first extension separator.
Line 309: Line 258:
** basename(path):
** basename(path):
*** Wes Garland
*** Wes Garland
** (Python: Unix: basename)


* returns the extension of the given path.  The extension begins after the first extension separator.
* returns the extension of the given path.  The extension begins after the first extension separator.
Line 315: Line 265:
*** Kris Kowal
*** Kris Kowal
*** Wes Garland
*** Wes Garland
** (Ruby: extname)


* 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.
* 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.
** normal(path)
** normal(path)
** (Python: normpath)
* 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 epxanding any user directory alias, joining the path to the current working directory, and normalizing the result.
** absolute(path)
** (Python: abspath)
* 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 an user directory alias, joining the given path to the current working directory, joining all symbolic links along the path, and normalizing the result.
** canonical(path)
** (Python: realpath)


* returns whether a given path has no self and parent path components.
* returns whether a given path has no self and parent path components.
** isNormal(path)
** isNormal(path)
* 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.
** absolute(path)


* returns whether the given path is normal and starts with the root of the file system.
* returns whether the given path is normal and starts with the root of the file system.
** isAbsolute(path)
** isAbsolute(path)
 
** (Python: isabs)
* returns the intrinsic path to a given file.  Resolves the path relative to the current working directory.  This involves tracing the hard parent links of it and its ancestors until reaching the root of the file system.  If the file system was returned by chroot, returns undefined if the parent links traverse to a path that's inaccessible from the chroot, if the file system is chrooted.
** canonical(path)


* returns whether the given path is the same as the corresponding cannonical path.
* returns whether the given path is the same as the corresponding cannonical path.
Line 336: Line 291:
* returns whether the given paths both refer to the same intrinsic file.  Both paths are resolved relative to the working directory.
* returns whether the given paths both refer to the same intrinsic file.  Both paths are resolved relative to the working directory.
** same(path, path)
** same(path, path)


== Stat Object ==
== Stat Object ==


* the Date that the file was last accessed.
* the Date that the file was last accessed.
** lastAccessed:
*** Kris Kowal
** atime:
** atime:
*** Tom Robinson
*** Tom Robinson
*** Kevin Dangoor
*** Kevin Dangoor
*** Ondrej Zara
*** Ondrej Zara
** lastAccessed:
*** Kris Kowal
** (Python: getatime, Ruby: atime)


* the Date that the file was last modified.
* the Date that the file was last modified.
** mtime:
*** Tom Robinson
*** Kevin Dangoor
*** Ondrej Zara
** lastModified:
** lastModified:
*** Kris Kowal
*** Kris Kowal
*** Mario Valente
*** Mario Valente
** mtime:
** (Python: getmtime, Ruby: mtime, Java: Spidermonkey: Helma: lastModified, jslibs: modifyTime, EJScript: modified, Synchronet: date)
 
* the Date that the file's stat/metadata was last modified.
** ctime:
*** Tom Robinson
*** Tom Robinson
*** Kevin Dangoor
*** Kevin Dangoor
*** Ondrej Zara
*** Ondrej Zara
* the Date that the file's stat/metadata was last modified.
** lastChanged:
** lastChanged:
*** Wes Garland
*** Wes Garland
** lastStatModified:
** lastStatModified:
*** Kris Kowal
*** Kris Kowal
** ctime:
** (Ruby: ctime, Python: getctime)
*** Tom Robinson
*** Kevin Dangoor
*** Ondrej Zara


* the Date that the file was created, if the underlying file system makes that datum available (most Unix systems do not store creation time, but Windows and some Unix varieties do).  Returns undefined if the underlying file system does not provide a time.
* the Date that the file was created, if the underlying file system makes that datum available (most Unix systems do not store creation time, but Windows and some Unix varieties do).  Returns undefined if the underlying file system does not provide a time.
Line 370: Line 329:
** creationTime:
** creationTime:
** firstModified:
** firstModified:
** omit entirely:
*** Kris Kowal
** (Spidermonkey: jslibs: creationTime, EJScript: create)


* a String name for the type of the file.  One of: "file", "directory", "characterSpecial", "blockSpecial", "fifo", "link", "socket", or "unknown"
* a String name for the type of the file.  One of: "file", "directory", "characterSpecial", "blockSpecial", "fifo", "link", "socket", or "unknown"
** type:
** type:
** kind:
** kind:
** ommit entirely:
** omit entirely:
*** Kris Kowal
*** Kris Kowal


Line 383: Line 345:
* whether the corresponding object is a directory
* whether the corresponding object is a directory
** isDirectory
** isDirectory
** (Spidermonkey: isDir, Helma: isDir, JSExt: isdir)


* whether the corresponding object is a symbolic link
* whether the corresponding object is a symbolic link
Line 389: Line 352:
* whether the corresponding object is a mount point
* whether the corresponding object is a mount point
** isMountPoint:
** isMountPoint:
** ommit entirely:
** omit entirely:
*** Wes Garland
*** Wes Garland
*** Ondrej Zara
*** Ondrej Zara
Line 406: Line 369:
** size
** size
*** Ondrej Zara
*** Ondrej Zara
** (jslibs: size, Helma: getLength, Spidermonkey: wxJS: EJScript: Synchronet: length)


* the name or id of the owner of the file (following symlinks)
* the name or id of the owner of the file (following symlinks)
Line 433: Line 397:
* whether the corresponding executable file will be forced to run as the owner of the file if any user executes it.
* whether the corresponding executable file will be forced to run as the owner of the file if any user executes it.
** executesAsOwner
** executesAsOwner
** setuid


* whether the corresponding executable file wil be forced to run with its group owner if any user executes it.
* whether the corresponding executable file wil be forced to run with its group owner if any user executes it.
** executesAsGroupOwner
** executesAsGroupOwner
** setgid
* whether the corresponding directory will permit anyone to create files in it, but only let the owner of a file delete it.
** sticky


* an object that represents the permissions granted to the owner of the file.
* an object that represents the permissions granted to the owner of the file.
Line 470: Line 439:
* the device number of the underlying object (optional)
* the device number of the underlying object (optional)
** device
** device


== File Object ==
== File Object ==


File objects can only be constructed by methods of FileSystem objects.  Different IO types might be returned for calls to open with different modes, generally following the protocol outlined in Python's PEP 3116.   
File objects can only be constructed by methods of FileSystem objects.  Different IO types might be returned for calls to open with different modes, generally following the protocol outlined in Python's PEP 3116.   


== IO Objects ==
== IO Objects ==
Line 485: Line 456:
* reads a line of characters from a line buffered IO object.  Returns a blank line on EOF.
* reads a line of characters from a line buffered IO object.  Returns a blank line on EOF.
** readLine()
** readLine()
** (Python: JSExt: readline, Spidermonkey: Helma: Synchronet: readln)


* returns an Array-like view of the lines in an IO stream, or simply an Array of Strings.
* returns an Array-like view of the lines in an IO stream, or simply an Array of Strings.
** readLines()
** readLines()
** (Python: readlines, JSExt: readlines, EJScript: getLines)


* returns the next line in the stream.  Throws a StopIteration exception on EOF.
* returns the next line in the stream.  Throws a StopIteration exception on EOF.
Line 510: Line 483:
*** 2 or "end": end of file
*** 2 or "end": end of file
** seek(pos, whence)
** seek(pos, whence)
** (universal precedent)


* returns the current position of the random access cursor for an IO stream.  The position may be a "cookie" object or a Number, depending on the IO type.
* returns the current position of the random access cursor for an IO stream.  The position may be a "cookie" object or a Number, depending on the IO type.
** tell()
** tell()
** (wxJS: JSExt: Python: Ruby: tell)


* truncates the size of a file to the current cursor position or a given position, which must be either a "cookie" object or a Number, depending on the IO type.
* truncates the size of a file to the current cursor position or a given position, which must be either a "cookie" object or a Number, depending on the IO type.
** truncate(pos)
** truncate(pos)
** (Ruby: truncate, Python: ftruncate)


* returns whether the cursor is at the end of the IO stream.
* returns whether the cursor is at the end of the IO stream.
** isEof():
** eof()
*** Kris Kowal
*** Kris Kowal
** atEOF():
** atEOF():
*** Wes Garland (non-commital)
*** Wes Garland (non-commital)
** eof()
** (Helma: wxJS: JSExt: Synchronet: eof)


* flushes buffers for an IO stream
* flushes buffers for an IO stream
** flush()
** flush()
** (universal precedent)


* blocks until an advisory lock is acquired.  Throws an error if a lock cannot be acquired on the system.
* blocks until an advisory lock is acquired.  Throws an error if a lock cannot be acquired on the system.
Line 532: Line 509:
* tries to grab an advisory lock without blocking, and returns whether it succeeded.
* tries to grab an advisory lock without blocking, and returns whether it succeeded.
** tryLock("exclusive|shared")
** tryLock("exclusive|shared")
** (related to isOpen in many existing SSJS frameworks, but without a race condition hazard)


* releases an advisory lock.
* releases an advisory lock.
Line 564: Line 542:
*** Kris Kowal
*** Kris Kowal
** dup()
** dup()
= File Module =
The file module would export a copy of every property on "environment.fs", for convenience.  Thus::
require('file').open(foo)
Would be equivalent to:
environment.fs.open(foo)




Line 591: Line 558:




= Inspiration =
= General Preferences =
 
# make vs. create
#* make:
#** Mario Valente,
#** Wes Garland (but only for directories)
#* create:
#** George Moschovitis,
#** Wes Garland (but only for files)
#** Ondrej Zara
# dir vs. directory
#* directory:
#** Tom Robinson,
#** Kevin Dangoor,
#** George Mosochovitis,
#** Wes Garland
#** Ondrej Zara
#* dir:
#** Mario Valente
# cur vs. current
#* current:
#** Tom Robinson,
#** Kevin Dangoor,
#** Wes Garland,
#** Kris Kowal,
#** Mario Valente
#** Ondrej Zara
#** George Moschovitis
#* cur:
# canonize, realize, normalize, qualify, cannon, real, normal, qualified, absolute, cannonicalize
#* remove . and ..:
#** normalize:
#*** Tom Robinson,
#*** Kevin Dangoor,
#*** Kris Kowal,
#*** George Mosochovitis
#** qualify:
#*** Wes Garland
#** expand:
#*** Ondrej Zara
#* remove . and .., start at /:
#** absolute:
#*** Tom Robinson,
#*** Kevin Dangoor,
#*** Kris Kowal,
#*** George Mosochovitis,
#*** Wes Garland,
#*** Mario Valente
#** qualified:
#*** Wes Garland
#** normalize:
#*** Ondrej Zara
#* remove . and .., start at /, follow symlinks:
#** canonical:
#*** Tom Robinson,
#*** Kevin Dangoor,
#*** Kris Kowal
#** absolute:
#*** George Mosochovitis,
#*** Wes Garland,
#*** Mario Valente,
#** real:
#*** Tom Robinson,
#*** Kevin Dangoor
#** qualified:
#*** Wes Garland
# constantCase, CONSTANT_CASE, kConstantCase
#* CONSTANT_CASE:
#** Tom Robinson,
#** Kevin Dangoor
#** Ondrej Zara
#** George Moschovitis
#* constantCase:
#** Kris Kowal,
#** Wes Garland,
#** Mario Valente,
# "static" methods
#* require(module).staticMethod:
#** Kris Kowal
#** Wes Garland
#** Mario Valente
#** Ondrej Zara
#* require(module).Klass.staticMethod:
#** Tom Robinson
#** George Mosochovitis
# properties, accessors, mutators
#* foo.setX(x); foo.getX()
#** For:
#** Against:
#* foo.setX(x); foo.X()
#** For:
#** Against:
#* no convention
#** For:
#** Against:
#* foo.x = x; foo.x
#** For:
#*** Davey Waterson
#*** Wes Garland
#*** Daniel Friesen
#*** Sam Phillips
#** Against:
#*** Tom Robinson
#*** Kris Kowal
 
 
= References =


; http://www.python.org/dev/peps/pep-3116/: PEP on new File IO
; http://www.python.org/dev/peps/pep-3116/: PEP on new File IO
KrisKowal
171

edits

Retrieved from "https://wiki.mozilla.org/Special:MobileDiff/136332"

Navigation menu