JSFileApi: Difference between revisions

309 bytes removed ,  11 October 2011
Renamed modules/constructors
m (Fixed links)
(Renamed modules/constructors)
Line 28: Line 28:




= Module FileUtilities =
= 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 {DirectoryDescriptor} a descriptor which may be used to access this directory
       * @returns {RawDir} a descriptor which may be used to access this directory
       */     
       */     
     createTempDirectory: function() {
     createTempDirectory: function() {
  //Unix:    [FileUtilities.tmpdir] followed by [mkdtemp] and [FileUtilities.openDirectory]
  //Unix:    [Files.tmpdir] followed by [mkdtemp] and [Files.openDirectory]
  //Windows: [FileUtilities.tmpdir] followed by [GetTempFileName] and [FileUtilities.openDirectory]
  //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 FileDescriptorError
       * @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 FileDescriptorError
       * @throws RawFileError
       */
       */
     move: function(source, target, overwrite)
     move: function(source, target, overwrite)
     {
     {
  //Unix:    maps to [rename] or, when [rename] returns EXDEV, on [FileUtilities.copy]+[FileUtilities.remove]
  //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 {DirectoryDescriptor}
       * @return {RawDir}
       */
       */
     get profileDir() {
     get profileDir() {
Line 194: Line 194:
   
   
     /**
     /**
       * The kind of information that can be found by calling [FileDescriptor.info] or [DirectoryDescriptor.forEachFile].
       * 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 FileDescriptor =  
= Instances of RawFile =  


A <tt>FileDescriptor</tt> is a low-level object wrapping a native file descriptor (under variants of Unix) or a file handle (under Windows).
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 {FileDescriptorException} In case of file error.
       * @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 {FileDescriptorException} In case of file error.
       * @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 {FileDescriptorException} In case of file error.
       * @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 {FileUtilities.FileInfo} information about the file.
       * @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 {FileDescriptor.Seek.Methodmethod} Determine whether [delta] is to be taken from the start of the file, from the end or from the current position.
       * @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 DirectoryDescriptor =
= Instances of RawDir =


A <tt>DirectoryDescriptor</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>.
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 [FileDescriptor.Open.Access]. If this argument is not provided, we assume 0, i.e. no flags.
       * @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 [FileDescriptor.Content.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 [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 [FileDescriptor.Pragma.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 [RawFile.Pragma.Access]. If this argument is not provided, we assume 0, i.e. no flags.
       * @return {FileDescriptor} a FileDescriptor
       * @return {RawFile} a RawFile
       *
       *
       * @throws FileDescriptorError
       * @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. [FileDescriptor.open]
  //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 [FileDescriptor.OpenDir.Access]
       * @param {number=} accessMode A or-ing of flags, as specified by [RawFile.OpenDir.Access]
       *
       *
       * @returns {DirectoryDescriptor} a descriptor which may be used to access this directory
       * @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 {DirectoryDescriptor} a descriptor which may be used to access this directory
       * @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 {FileUtilities.FileInfo} information about the file.
       * @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 DirectoryDescriptor are iterable. Therefore, you can also loop through them using a standard [for..in].
       * 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, FileDescriptor.FileInfo, number, function() FileDescriptor)} 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.
       * @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.
184

edits