ServerJS/API/file

From MozillaWiki
Jump to navigation Jump to search

High Level

  1. make vs. create
    • make:
      • Mario Valente,
      • Wes Garland (but only for directories)
    • create:
      • George Moschovitis,
      • Wes Garland (but only for files)
      • Ondrej Zara
  2. dir vs. directory
    • directory:
      • Tom Robinson,
      • Kevin Dangoor,
      • George Mosochovitis,
      • Wes Garland
      • Ondrej Zara
    • dir:
      • Mario Valente
  3. cur vs. current
    • current:
      • Tom Robinson,
      • Kevin Dangoor,
      • Wes Garland,
      • Kris Kowal,
      • Mario Valente
      • Ondrej Zara
    • cur:
  4. 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
  5. constantCase, CONSTANT_CASE, kConstantCase
    • constantCase:
      • Kris Kowal,
      • Wes Garland,
      • Mario Valente,
    • CONSTANT_CASE:
      • Tom Robinson,
      • Kevin Dangoor
      • Ondrej Zara
  6. "static" methods
    • require(module).staticMethod:
      • Kris Kowal
      • Wes Garland
      • Mario Valente
      • Ondrej Zara
    • require(module).Klass.staticMethod:
      • Tom Robinson
      • George Mosochovitis
  7. 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

  • the location of the file system type.
    • 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.
  • 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:
      • Kris Kowal
  • 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):
      • Kris Kowal
      • Wes Garland
  • 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.
    • exists(path, true):
      • Wes Garland
      • Mario Valente
    • linkExists(path):
      • Kris Kowal
    • exists(path, "link"):
      • Kris Kowal (as a compromise)
  • moves a file from a source to a target path. both paths are joined on the current working directory.
    • move(source, target):
      • uncontested
  • 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.
    • rename(path, name):
    • should not be included in the spec:
      • Kris Kowal
  • copies a file from a source to a target path. Both paths are joined on the current working directory.
    • copy(source, target):
      • uncontested
  • 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.
    • makeDirectory(path):
      • Kris Kowal
    • createDirectory(path):
      • Mario Valente
  • 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.
    • makePath(path):
      • Kris Kowal
    • makeDirectory(path, true):
      • Wes Garland
    • makeDirectory(path, "path"):
      • Kris Kowal (as a compromise)
  • removes a file.
    • remove(path):
      • Kris Kowal
      • Tom Robinson
      • Kevin Dangoor
      • Wes Garland (as a compromise)
    • unlink(path):
      • Wes Garland
  • removes a file or directory and its recursive contents.
    • remove(path):
    • remove(path, true):
    • remove(path, "recursive")
    • removeRecursive(path)
  • creates a hard link of the source path as the target path. Both paths are joined on the current working directory.
    • link(source, target):
      • uncontested
  • 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.
    • symbolicLink(source, target):
      • Kris Kowal
    • link(source, target, true):
      • Wes Garland
    • link(source, target, "symbolic"):
      • Kris Kowal (as a compromise)
  • 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".
    • create(path, [permissions]):
      • Mario Valente
    • unnecessary:
      • Kris Kowal,
      • Wes Garland
  • 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]):
      • uncontested
  • 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.
    • update(path, stat):
      • Wes Garland
  • 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]):
      • Kris Kowal
  • 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.
    • lock(path, "shared|exclusive", [timeout=undefined]):
      • Wes Garland
      • Kris Kowal
  • 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.
    • tryLock(path, "shared|exclusive"):
      • Wes Garland
  • releases a lock for a given path.
    • unlock(path):
      • Kris Kowal
    • lock(path, "unlock")
  • 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):
      • Mario Valente
  • 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.
    • stat(path, true):
      • Wes Garland
    • linkStat(path):
      • Kris Kowal
    • stat(path, "link"):
      • Kris Kowal (as a compromise)
  • returns the size of the corresponding file.
    • size(path)
  • returns the total size of a tree of files.
    • size(path) // as a special case for a directory
    • size(path, "recursive")
    • 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.
    • open(path, "+arwxc", encoding):
      • Mario Valente
      • Kris Kowal
    • Mode:
      • +, update
      • a, append
      • r, read
      • w, write
      • x, exclusive (lock)
      • c, canon (nonblocking)
  • 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)
  • 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.
    • The glob pattern may include any of the following productions:
      • ? - exactly one character in a path component
      • * - any number of characters in a path component
      • ** - any number of characters in a path
      • {a,b,c} - the letters a, b, or c, or any other union of paths.
    • glob(pattern)
  • returns whether a given path matches a glob pattern.
    • match(pattern, path)
  • 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.
    • chroot(path)


Paths

More properites of a FileSystem.

  • a string directing a path up to the parent of the current directory, usually '..'.
    • 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 string directing a path back to itself, usually '.'.
    • self
  • a string that contains the path separator, usually '/', '\', or ':'.
    • separator
  • a string that contains the alternate path separator, if it exists. Otherwise, undefined.
    • alternateSeparator
  • a string that contains the extension separator, usually '.'.
    • extensionSeparator
  • whether the file system supports unicode file names
    • supportsUnicodeFileNames
  • 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.
    • join([path, [path, [path, [...]]]])
  • returns the path components for a given path
    • split(path)
  • 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)
  • returns the path of the directory containing a given path.
    • dirName(path):
      • Kris Kowal
    • dirname(path)
      • Wes Garland
  • returns the last path component without its extension. The extension begins after the first extension separator.
    • baseName(path):
      • Kris Kowal
    • basename(path):
      • Wes Garland
  • returns the extension of the given path. The extension begins after the first extension separator.
    • extension(path):
      • George Mosochovitis
      • Kris Kowal
      • Wes Garland
  • 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)
  • returns whether a given path has no self and parent path components.
    • 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.
    • isAbsolute(path)
  • 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.
    • isCanonical(path)
  • returns whether the given paths both refer to the same intrinsic file. Both paths are resolved relative to the working directory.
    • same(path, path)

Stat Object

  • the Date that the file was last accessed.
    • lastAccessed:
      • Kris Kowal
    • atime:
      • Tom Robinson
      • Kevin Dangoor
  • the Date that the file was last modified.
    • lastModified:
      • Kris Kowal
      • Mario Valente
    • mtime:
      • Tom Robinson
      • Kevin Dangoor
  • the Date that the file's stat/metadata was last modified.
    • lastChanged:
      • Wes Garland
    • lastStatModified:
      • Kris Kowal
    • ctime:
      • Tom Robinson
      • Kevin Dangoor
  • 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.
    • created:
    • creationTime:
    • firstModified:
  • a String name for the type of the file. One of: "file", "directory", "characterSpecial", "blockSpecial", "fifo", "link", "socket", or "unknown"
    • type:
    • kind:
    • ommit entirely:
      • Kris Kowal
  • whether the corresponding object is a file (not a directory).
    • isFile:
      • Kris Kowal
  • whether the corresponding object is a directory
    • isDirectory
  • whether the corresponding object is a symbolic link
    • isLink
  • whether the corresponding object is a mount point
    • isMountPoint:
    • ommit entirely:
      • Wes Garland
  • whether the corresponding object is a socket
    • isSocket
  • whether the corresponding object is a pipe
    • isPipe
    • isFifo
  • whether the correpsonding object is a block device
    • isBlockDevice
  • the size of the corresponding object in bytes
    • size
  • the name or id of the owner of the file (following symlinks)
    • owner
  • the name or id of the group owner of the file (following symlinks)
    • groupOwner
  • the name or id of the owner of the file or symbolic link
    • linkOwner
  • the name or id of the group owner of the file or symbolic link
    • linkGroupOwner
  • whether the owner of the process at the time of this stat object's construction is the same as the owner of this file.
    • owned
  • whether the corresponding object can be opened for reading by the current process owner
    • isReadable
  • whether the corresponding object can be opened for writing by the current process owner
    • isWritable
  • whether the corresponding object is an executable for the current process owner
    • isExecutable
  • whether the corresponding executable file will be forced to run as the owner of the file if any user executes it.
    • executesAsOwner
  • whether the corresponding executable file wil be forced to run with its group owner if any user executes it.
    • executesAsGroupOwner
  • an object that represents the permissions granted to the owner of the file.
    • This object would contain:
      • isReadable
      • isWritable
      • isExecutable
    • ownerPermissions
  • an object that represents the permissions granted to the group that owns the file.
    • The object would contain:
      • isReadable
      • isWritable
      • isExecutable
    • groupPermissions
  • an object that represents the permissions granted to anyone who has no claim to the file.
    • The object would contain:
      • isReadable
      • isWritable
      • isExecutable
    • worldPermissions
  • returns an object that represents the permissions granted to the user corresponding to a particular name or identifier.
    • The returned object would contain:
      • isReadable
      • isWritable
      • isExecutable
    • getPermissions(user)
  • the inode/vnode number of the underlying object (optional)
    • inode
  • the device number of the underlying object (optional)
    • device


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.

IO Objects

  • reads as many bytes as are available from an IO stream and returns the number of actually read bytes.
    • read()
  • reads as many bytes as are available but less than a given number from an IO stream and returns the number of actually read bytes.
    • read(n)
  • reads a line of characters from a line buffered IO object. Returns a blank line on EOF.
    • readLine()
  • returns an Array-like view of the lines in an IO stream, or simply an Array of Strings.
    • readLines()
  • returns the next line in the stream. Throws a StopIteration exception on EOF.
    • next()
  • returns an iteration on the lines of the IO stream, which is simply itself since it implements "next".
    • iter()
  • calls a relation with each line of input from the IO stream.
    • forEach(relation)
  • reads bytes into a buffer, up to as many as the length of the buffer, pending availablility. Returns the number of bytes actually read.
    • readInto(buffer)
  • writes bytes to a stream. Returns the number of bytes that were actually written.
    • write(buffer)
  • moves the position of the cursor in a random access IO stream.
    • Accepts a code that determines whether to move the position relative to the beginning, end, or current position:
      • 0 or "begin": beginning of file (default)
      • 1 or "relative": current position
      • 2 or "end": end of file
    • seek(pos, whence)
  • 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()
  • 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)
  • returns whether the cursor is at the end of the IO stream.
    • isEof():
      • Kris Kowal
    • atEOF():
      • Wes Garland (non-commital)
    • eof()
  • flushes buffers for an IO stream
    • flush()
  • blocks until an advisory lock is acquired. Throws an error if a lock cannot be acquired on the system.
    • lock("exclusive|shared")
  • tries to grab an advisory lock without blocking, and returns whether it succeeded.
    • tryLock("exclusive|shared")
  • releases an advisory lock.
    • unlock()
  • closes a stream
    • close()
  • whether the IO stream is readable
    • isReadable
  • whether the IO stream is writable
    • isWritable
  • whether the IO stream supports random access
    • isSeekable
  • whether the IO stream is attached to a virtual or real teletype.
    • isTTY:
      • Wes Garland
    • isTty:
      • Kris Kowal
  • the descriptor of the underlying file, an opaque reference to the file descriptor, or undefined if file descriptors are not supported.
    • fileNo
  • the underlying unbuffered IO stream, if it exists. Otherwise undefined.
    • raw
  • creates a duplicate of the IO stream, with its own buffereing and cursor.
    • copy()
      • Kris Kowal
    • 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)


Notes for Further Discussion

  • input, output, stdin, stdout, STDIN, STDOUT
  • ...placed on environment or in a module?
  • separation of knowledge of paths between file system and files
  • currentDirectory, getCurrentDirectory
  • temporary files and directories
  • opening a temp file with an implied immediate exclusive lock
  • dup and dup2 and other file-descriptor specific constructs for permissive environments.
  • canRead, canWrite, poll, select
  • taxonomy of IO classes
  • default encoding for String, line-buffered IO


Inspiration

http://www.python.org/dev/peps/pep-3116/
PEP on new File IO
http://java.sun.com/j2se/1.4.2/docs/api/java/io/File.html
Java File API
http://java.sun.com/j2se/1.4.2/docs/api/java/io/FileOutputStream.html
Java Output API
http://java.sun.com/j2se/1.4.2/docs/api/java/io/FileInputStream.html
Java Input API
http://www.erights.org/javadoc/java/io/File.html
E Secure File API
http://www.cs.berkeley.edu/~daw/joe-e/api/org/joe_e/file/Filesystem.html
Joe-E Secure File System API
http://docs.python.org/library/os.path.html
Python Path API
http://www.ruby-doc.org/core/classes/File.html
Ruby File API
http://www.ruby-doc.org/core/classes/IO.html
Ruby IO API
http://spreadsheets.google.com/pub?key=p9uiX8MUHeTiP0kPT591RUw
A matrix of existing ServerJS File API nomenclature and support
Retrieved from "https://wiki.mozilla.org/index.php?title=ServerJS/API/file&oldid=136105"