184
edits
m (Fixed links) |
(Renamed modules/constructors) |
||
Line 28: | Line 28: | ||
= Module | = Module Files = | ||
This module is the first access point to the file API. It contains constructors, functions to copy, move files, etc. as well as the constants used in the API. | This module is the first access point to the file API. It contains constructors, functions to copy, move files, etc. as well as the constants used in the API. | ||
Line 42: | Line 42: | ||
* Note: For the time being, there is no guarantee *when* the temporary directory is cleaned | * Note: For the time being, there is no guarantee *when* the temporary directory is cleaned | ||
* | * | ||
* @returns { | * @returns {RawDir} a descriptor which may be used to access this directory | ||
*/ | */ | ||
createTempDirectory: function() { | createTempDirectory: function() { | ||
//Unix: [ | //Unix: [Files.tmpdir] followed by [mkdtemp] and [Files.openDirectory] | ||
//Windows: [ | //Windows: [Files.tmpdir] followed by [GetTempFileName] and [Files.openDirectory] | ||
}, | }, | ||
Line 62: | Line 62: | ||
* @param {string} target The name of the file/directory to be created. | * @param {string} target The name of the file/directory to be created. | ||
* @param {boolean} overwrite If [false] and if the target already exists, fail. | * @param {boolean} overwrite If [false] and if the target already exists, fail. | ||
* @throws | * @throws RawFileError | ||
*/ | */ | ||
copy: function(source, target, overwrite) | copy: function(source, target, overwrite) | ||
Line 82: | Line 82: | ||
* @param {string} target The name of the file/directory to be created. | * @param {string} target The name of the file/directory to be created. | ||
* @param {boolean} overwrite If [false] and if the target already exists, fail. | * @param {boolean} overwrite If [false] and if the target already exists, fail. | ||
* @throws | * @throws RawFileError | ||
*/ | */ | ||
move: function(source, target, overwrite) | move: function(source, target, overwrite) | ||
{ | { | ||
//Unix: maps to [rename] or, when [rename] returns EXDEV, on [ | //Unix: maps to [rename] or, when [rename] returns EXDEV, on [Files.copy]+[Files.remove] | ||
//Windows: maps to [MoveFile] http://msdn.microsoft.com/en-us/library/aa365239(v=VS.85).aspx | //Windows: maps to [MoveFile] http://msdn.microsoft.com/en-us/library/aa365239(v=VS.85).aspx | ||
//Check if it works with directories | //Check if it works with directories | ||
Line 110: | Line 110: | ||
* Computed lazily, cached. | * Computed lazily, cached. | ||
* | * | ||
* @return { | * @return {RawDir} | ||
*/ | */ | ||
get profileDir() { | get profileDir() { | ||
Line 194: | Line 194: | ||
/** | /** | ||
* The kind of information that can be found by calling [ | * The kind of information that can be found by calling [RawFile.info] or [RawDir.forEachFile]. | ||
* | * | ||
* Note that some or all fields may be computed lazily. | * Note that some or all fields may be computed lazily. | ||
Line 238: | Line 238: | ||
Error: function(){} | Error: function(){} | ||
= Instances of | = Instances of RawFile = | ||
A <tt> | A <tt>RawFile</tt> is a low-level object wrapping a native file descriptor (under variants of Unix) or a file handle (under Windows). | ||
== Reading == | == Reading == | ||
Line 251: | Line 251: | ||
* @param {number} size The maximal number of bytes to read. This method can read less bytes if the file is shorter. | * @param {number} size The maximal number of bytes to read. This method can read less bytes if the file is shorter. | ||
* @return {number} The number of bytes read. | * @return {number} The number of bytes read. | ||
* @throws { | * @throws {RawFileException} In case of file error. | ||
* @throws {INDEX_SIZE_ERR} In case of array error. | * @throws {INDEX_SIZE_ERR} In case of array error. | ||
*/ | */ | ||
Line 267: | Line 267: | ||
* @param {number} size The maximal number of bytes to read. This method can read less bytes if the file is shorter. | * @param {number} size The maximal number of bytes to read. This method can read less bytes if the file is shorter. | ||
* @return {number} The number of bytes read. | * @return {number} The number of bytes read. | ||
* @throws { | * @throws {RawFileException} In case of file error. | ||
* @throws {INDEX_SIZE_ERR} In case of array error. | * @throws {INDEX_SIZE_ERR} In case of array error. | ||
*/ | */ | ||
Line 285: | Line 285: | ||
* | * | ||
* @return {number} The number of bytes written. | * @return {number} The number of bytes written. | ||
* @throws { | * @throws {RawFileException} In case of file error. | ||
* @throws {INDEX_SIZE_ERR} In case of array error. | * @throws {INDEX_SIZE_ERR} In case of array error. | ||
*/ | */ | ||
Line 306: | Line 306: | ||
* Gather information about the file | * Gather information about the file | ||
* | * | ||
* @return { | * @return {Files.FileInfo} information about the file. | ||
*/ | */ | ||
stat: function() { | stat: function() { | ||
Line 329: | Line 329: | ||
* | * | ||
* @param {number} delta Number of bytes. Can be positive or negative. | * @param {number} delta Number of bytes. Can be positive or negative. | ||
* @param { | * @param {RawFile.Seek.Methodmethod} Determine whether [delta] is to be taken from the start of the file, from the end or from the current position. | ||
*/ | */ | ||
seek: function(delta, method) { | seek: function(delta, method) { | ||
Line 354: | Line 354: | ||
}, | }, | ||
= Instances of | = Instances of RawDir = | ||
A <tt> | A <tt>RawDir</tt> is a slightly higher-level object wrapping a directory _name_ (for reasons of portability & iteration, this seemed more appropriate than _opening_ the directory during construction). On the Unix side, some of the methods rely upon (or have to reimplement) systems that obey recent versions of Posix, with functions such as <tt>openat</tt>. | ||
== Opening/creating == | == Opening/creating == | ||
Line 364: | Line 364: | ||
* | * | ||
* @param {string} leafName The name of the file. | * @param {string} leafName The name of the file. | ||
* @param {number=} accessMode A or-ing of flags, as specified by [ | * @param {number=} accessMode A or-ing of flags, as specified by [RawFile.Open.Access]. If this argument is not provided, we assume 0, i.e. no flags. | ||
* @param {number=} contentMode A or-ing of flags, as specified by [ | * @param {number=} contentMode A or-ing of flags, as specified by [RawFile.Content.Access]. If this argument is not provided, we assume 0, i.e. no flags. | ||
* @param {number=} pragmaMode A or-ing of flags, as specified by [ | * @param {number=} pragmaMode A or-ing of flags, as specified by [RawFile.Pragma.Access]. If this argument is not provided, we assume 0, i.e. no flags. | ||
* @return { | * @return {RawFile} a RawFile | ||
* | * | ||
* @throws | * @throws RawFileError | ||
*/ | */ | ||
openFile: function(leafName, accessMode, contentMode, pragmaMode) { | openFile: function(leafName, accessMode, contentMode, pragmaMode) { | ||
//Linux: [openat] | //Linux: [openat] | ||
//Unix: decide between gnulib [openat] and simply [open] | //Unix: decide between gnulib [openat] and simply [open] | ||
//Windows: cf. [ | //Windows: cf. [RawFile.open] | ||
}, | }, | ||
Line 389: | Line 389: | ||
* | * | ||
* @param {string} leafName The platform-specific name of the directory. | * @param {string} leafName The platform-specific name of the directory. | ||
* @param {number=} accessMode A or-ing of flags, as specified by [ | * @param {number=} accessMode A or-ing of flags, as specified by [RawFile.OpenDir.Access] | ||
* | * | ||
* @returns { | * @returns {RawDir} a descriptor which may be used to access this directory | ||
*/ | */ | ||
openDirectory: function(leafName, accessMode) { | openDirectory: function(leafName, accessMode) { | ||
Line 403: | Line 403: | ||
* Note: For the time being, there is no guarantee that the temporary directory will be cleaned | * Note: For the time being, there is no guarantee that the temporary directory will be cleaned | ||
* | * | ||
* @returns { | * @returns {RawDir} a descriptor which may be used to access this directory | ||
*/ | */ | ||
createTempDirectory: function() | createTempDirectory: function() | ||
Line 413: | Line 413: | ||
* Gather information about the directory | * Gather information about the directory | ||
* | * | ||
* @return { | * @return {Files.FileInfo} information about the file. | ||
*/ | */ | ||
stat: function() { | stat: function() { | ||
Line 429: | Line 429: | ||
* Apply a treatment to all files in the directory. | * Apply a treatment to all files in the directory. | ||
* | * | ||
* Note: objects of type | * Note: objects of type RawDir are iterable. Therefore, you can also loop through them using a standard [for..in]. | ||
* | * | ||
* @param {string=} filter. If provided, uses OS-accelerated, platform-specific, filtering, where available. | * @param {string=} filter. If provided, uses OS-accelerated, platform-specific, filtering, where available. | ||
* @param {function(string, | * @param {function(string, RawFile.FileInfo, number, function() RawFile)} onFile A function called for each file in the directory, with the name of the file, a (lazy) file info for that file and a file number. If the function returns anything [null], the loop stops immediately and returns the value returned by that function. | ||
* | * | ||
* @returns The first value returned by [onFile], or [undefined] otherwise. | * @returns The first value returned by [onFile], or [undefined] otherwise. |
edits