ServerJS/Filesystem API/Names: Difference between revisions

*** 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.

* moves a file from a source to a target path.  Both paths are joined on the current working directory.

** move(source, target):

* 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.

* copies a file from a source to a target path.  Both paths are joined on the current working directory.

** copy(source, target):

* 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.

** mkdir(path)

*** Kevin Dangoor

* 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.

** mkdirs(path)

*** Kevin Dangoor

* removes a file.

** unlink(path):

*** Wes Garland

* removes a file or directory and its recursive contents.

** 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.

** 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".

*** 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.

** omit entirely:

*** Kris Kowal

* 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.

** touch(path, [date]):

*** Kris Kowal

* 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.

*** Kris Kowal

** lock(path, "rw|")

* 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.

** tryLock(path, "shared|exclusive"):

** lock(path, "rw")

* releases a lock for a given path.

** lock(path, "unlock")

** lock(path, "u")

* 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, "link"):

*** Kris Kowal (as a compromise)

* returns the size of the corresponding file.

** size(path)

* returns the total size of a tree of files.

* 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.