From 6e09aa17b6c71b385fe9af087fa3aa960a68dc55 Mon Sep 17 00:00:00 2001 From: Chema Date: Tue, 6 Nov 2012 02:21:21 +0100 Subject: [PATCH 1/7] Added jsdoc to w3 specs --- src/file/NativeFileSystem.js | 324 +++++++++++++++++++++++++++-------- 1 file changed, 253 insertions(+), 71 deletions(-) diff --git a/src/file/NativeFileSystem.js b/src/file/NativeFileSystem.js index 9b6baa5d8d2..f18ff34fe3e 100644 --- a/src/file/NativeFileSystem.js +++ b/src/file/NativeFileSystem.js @@ -24,21 +24,50 @@ /*jslint vars: true, plusplus: true, devel: true, nomen: true, indent: 4, maxerr: 50*/ /*global $, define, brackets, FileError, InvalidateStateError */ +/** + * Generally NativeFileSystem mimics the File-System API working draft: + * http://www.w3.org/TR/2011/WD-file-system-api-20110419 + * + * A more recent version of the specs can be found at: + * http://www.w3.org/TR/2012/WD-file-system-api-20120417 + * + * Other relevant w3 specs related to this API are: + * http://www.w3.org/TR/2011/WD-FileAPI-20111020 + * http://www.w3.org/TR/2011/WD-file-writer-api-20110419 + * http://www.w3.org/TR/progress-events + * + * The w3 entry point requestFileSystem is replaced with our own requestNativeFileSystem. + * + * The current implementation is incomplete and notably does not + * support the Blob data type and synchronous APIs. DirectoryEntry + * and FileEntry read/write capabilities are mostly implemented, but + * delete is not. File writing is limited to UTF-8 text. + * + * + * Basic usage examples: + * + * CREATE_DIRECTORY + * NativeFileSystem.DirectoryEntry().getDirectory(path) + * + * GET_FILE + * NativeFileSystem.DirectoryEntry(path).getFile(filename) + * + * GET_FILE + * NativeFileSystem.requestNativeFileSystem( + * + * GET_METADATA + * var fileEntry = new NativeFileSystem.FileEntry(path) + * fileEntry.getMetadata(success, error) + * + * OPEN_FILE + * NativeFileSystem.showOpenDialog() + */ + define(function (require, exports, module) { "use strict"; var Async = require("utils/Async"); - /* - * Generally NativeFileSystem mimics the File API working draft - * http://www.w3.org/TR/file-system-api/. The w3 entry point - * requestFileSystem is replaced with our own requestNativeFileSystem. - * - * The current implementation is incomplete and noteably does not - * support the Blob data type and synchronous APIs. DirectoryEntry - * and FileEntry read/write capabilities are mostly implemented, but - * delete is not. File writing is limited to UTF-8 text. - */ var NativeFileSystem = { /** @@ -50,16 +79,20 @@ define(function (require, exports, module) { */ ASYNC_TIMEOUT: 2000, - /** showOpenDialog + /** + * Shows a modal dialog for selecting and opening files * - * @param {bool} allowMultipleSelection - * @param {bool} chooseDirectories - * @param {string} title - * @param {string} initialPath - * @param {Array.} fileTypes - * @param {function(...)} successCallback - * @param {function(...)} errorCallback - * @constructor + * @param {bool} allowMultipleSelection Allows selecting more than one file at a time + * @param {bool} chooseDirectories Allows directories as + * @param {string} title The title for the window + * @param {string} initialPath The folder opened inside the window initially. If initialPath + * is not set, or it doesn't exist, the window would show the last + * browsed folder depending on the OS preferences + * @param {Array.} fileTypes List of extensions that are allowed to be opened. A null value + * allows any extension to be selected. + * @param {function(...)} successCallback Callback function for successful operations. Receives an + array with the selected paths as first parameter. + * @param {function(...)} errorCallback Callback function for error operations. */ showOpenDialog: function (allowMultipleSelection, chooseDirectories, @@ -88,11 +121,12 @@ define(function (require, exports, module) { ); }, - /** requestNativeFileSystem - * - * @param {string} path - * @param {function(...)} successCallback - * @param {function(...)} errorCallback + /** + * Implementation of w3 requestFileSystem entry point + * @param {string} path Path of the file in the system + * @param {function(...)} successCallback Callback function for successful operations. Receives a + * DirectoryEntry pointing to the path + * @param {function(...)} errorCallback Callback function for errors, including permission errors. */ requestNativeFileSystem: function (path, successCallback, errorCallback) { brackets.fs.stat(path, function (err, data) { @@ -158,7 +192,7 @@ define(function (require, exports, module) { * * Internal static class that contains constants for file * encoding types to be used by internal file system - * implimentation. + * implementation. */ NativeFileSystem._FSEncodings = {}; NativeFileSystem._FSEncodings.UTF8 = "utf8"; @@ -187,11 +221,15 @@ define(function (require, exports, module) { var Encodings = NativeFileSystem.Encodings; var _FSEncodings = NativeFileSystem._FSEncodings; - /** class: Entry + /** + * Implementation of w3 Entry interface: + * http://www.w3.org/TR/2011/WD-file-system-api-20110419/#the-entry-interface + * + * Base class for representing entries in a file system (FileEntry or DirectoryEntry) * - * @param {string} name - * @param {string} isFile * @constructor + * @param {string} fullPath The full absolute path from the root to the entry + * @param {boolean} isDirectory Indicates that the entry is a directory */ NativeFileSystem.Entry = function (fullPath, isDirectory) { this.isDirectory = isDirectory; @@ -221,31 +259,65 @@ define(function (require, exports, module) { this.filesystem = null; }; + /** + * Moves this Entry to a different location on the file system. + * @param {DirectoryEntry} parent The directory to move the entry to + * @param {string} newName The new name of the entry. If not specified, defaults to the current name + * @param {function(Array.)} successCallback Callback function for successful operations + * @param {function(FileError)} errorCallback Callback function for error operations + */ NativeFileSystem.Entry.prototype.moveTo = function (parent, newName, successCallback, errorCallback) { // TODO (issue #241) // http://www.w3.org/TR/2011/WD-file-system-api-20110419/#widl-Entry-moveTo }; + /** + * Copies this Entry to a different location on the file system. + * @param {DirectoryEntry} parent The directory to copy the entry to + * @param {string} newName The new name of the entry. If not specified, defaults to the current name + * @param {function(Array.)} successCallback Callback function for successful operations + * @param {function(FileError)} errorCallback Callback function for error operations + */ NativeFileSystem.Entry.prototype.copyTo = function (parent, newName, successCallback, errorCallback) { // TODO (issue #241) // http://www.w3.org/TR/2011/WD-file-system-api-20110419/#widl-Entry-copyTo }; + /** + * Generates a URL that can be used to identify this Entry + * @param {string} mimeType The mime type to be used to interpret the file for a FileEntry + * @returns {string} A usable URL to identify this Entry in the current filesystem + */ NativeFileSystem.Entry.prototype.toURL = function (mimeType) { // TODO (issue #241) // http://www.w3.org/TR/2011/WD-file-system-api-20110419/#widl-Entry-toURL }; + /** + * Deletes a file or directory + * @param {function()} successCallback Callback function for successful operations + * @param {function(FileError)} errorCallback Callback function for error operations + */ NativeFileSystem.Entry.prototype.remove = function (successCallback, errorCallback) { // TODO (issue #241) // http://www.w3.org/TR/2011/WD-file-system-api-20110419/#widl-Entry-remove }; + /** + * Look up the parent DirectoryEntry that contains this Entry + * @param {function(Array.)} successCallback Callback function for successful operations + * @param {function(FileError)} errorCallback Callback function for error operations + */ NativeFileSystem.Entry.prototype.getParent = function (successCallback, errorCallback) { // TODO (issue #241) // http://www.w3.org/TR/2011/WD-file-system-api-20110419/#widl-Entry-remove }; + /** + * Look up metadata about this Entry + * @param {function(Metadata)} successCallback Callback function for successful operations + * @param {function(FileError)} errorCallback Callback function for error operations + */ NativeFileSystem.Entry.prototype.getMetadata = function (successCallBack, errorCallback) { brackets.fs.stat(this.fullPath, function (err, stat) { if (err === brackets.fs.NO_ERROR) { @@ -259,18 +331,26 @@ define(function (require, exports, module) { /** - * Stores information about a FileEntry - */ + * Implementation of w3 Metadata interface: + * http://www.w3.org/TR/2011/WD-file-system-api-20110419/#the-metadata-interface + * + * Supplies information about the state of a file or directory + * @constructor + * @param {Date} modificationTime Time at which the file or directory was last modified + */ NativeFileSystem.Metadata = function (modificationTime) { // modificationTime is read only this.modificationTime = modificationTime; }; - /** class: FileEntry - * This interface represents a file on a file system. + /** + * Implementation of w3 FileEntry interface: + * http://www.w3.org/TR/2011/WD-file-system-api-20110419/#the-fileentry-interface + * + * A FileEntry represents a file on a file system. * - * @param {string} name * @constructor + * @param {string} name Full path of the file in the file system * @extends {Entry} */ NativeFileSystem.FileEntry = function (name) { @@ -284,15 +364,23 @@ define(function (require, exports, module) { /** * Creates a new FileWriter associated with the file that this FileEntry represents. - * - * @param {function (FileWriter)} successCallback - * @param {function (FileError)} errorCallback + * @param {function(FileWriter)} successCallback Callback function for successful operations + * @param {function(FileError)} errorCallback Callback function for error operations */ NativeFileSystem.FileEntry.prototype.createWriter = function (successCallback, errorCallback) { var fileEntry = this; - // [NoInterfaceObject] - // interface FileWriter : FileSaver + /** + * Implementation of w3 FileWriter interface: + * http://www.w3.org/TR/2011/WD-file-writer-api-20110419/#the-filewriter-interface + * + * A FileWriter expands on the FileSaver interface to allow for multiple write actions, + * rather than just saving a single Blob. + * + * @constructor + * @param {Blob} data The Blob of data to be saved to a file + * @extends {FileSaver} + */ var FileWriter = function (data) { NativeFileSystem.FileSaver.call(this, data); @@ -301,16 +389,28 @@ define(function (require, exports, module) { this._position = 0; }; + /** + * The length of the file + */ FileWriter.prototype.length = function () { return this._length; }; + /** + * The byte offset at which the next write to the file will occur. + */ FileWriter.prototype.position = function () { return this._position; }; - // TODO (issue #241): handle Blob data instead of string + /** + * Write the supplied data to the file at position + * @param {string} data The data to write + */ FileWriter.prototype.write = function (data) { + // TODO (issue #241): handle Blob data instead of string + // http://www.w3.org/TR/2011/WD-file-writer-api-20110419/#widl-FileWriter-write + if (data === null || data === undefined) { throw new Error(); } @@ -363,10 +463,26 @@ define(function (require, exports, module) { }); }; + /** + * Seek sets the file position at which the next write will occur + * @param {number} offset An absolute byte offset into the file. If offset is greater than + * length, length is used instead. If offset is less than zero, length + * is added to it, so that it is treated as an offset back from the end + * of the file. If it is still less than zero, zero is used + */ FileWriter.prototype.seek = function (offset) { + // TODO (issue #241) + // http://www.w3.org/TR/2011/WD-file-writer-api-20110419/#widl-FileWriter-seek }; + /** + * Changes the length of the file to that specified + * @param {number} size The size to which the length of the file is to be adjusted, + * measured in bytes + */ FileWriter.prototype.truncate = function (size) { + // TODO (issue #241) + // http://www.w3.org/TR/2011/WD-file-writer-api-20110419/#widl-FileWriter-truncate }; var fileWriter = new FileWriter(); @@ -396,10 +512,9 @@ define(function (require, exports, module) { }; /** - * Obtains the File objecte for a FileEntry object - * - * @param {function(...)} successCallback - * @param {function(...)} errorCallback + * Returns a File that represents the current state of the file that this FileEntry represents + * @param {function(File)} successCallback Callback function for successful operations + * @param {function(FileError)} errorCallback Callback function for error operations */ NativeFileSystem.FileEntry.prototype.file = function (successCallback, errorCallback) { var newFile = new NativeFileSystem.File(this); @@ -409,7 +524,7 @@ define(function (require, exports, module) { }; /** - * This interface extends the FileException interface described in to add + * This class extends the FileException interface described in to add * several new error codes. Any errors that need to be reported synchronously, * including all that occur during use of the synchronous filesystem methods, * are reported using the FileException exception. @@ -439,14 +554,17 @@ define(function (require, exports, module) { ); /** - * This interface provides methods to monitor the asynchronous writing of blobs + * Implementation of w3 FileSaver interface + * http://www.w3.org/TR/2011/WD-file-writer-api-20110419/#the-filesaver-interface + * + * FileSaver provides methods to monitor the asynchronous writing of blobs * to disk using progress events and event handler attributes. * - * This interface is specified to be used within the context of the global + * FileSaver is specified to be used within the context of the global * object (Window) and within Web Workers. * - * @param {Blob} data * @constructor + * @param {Blob} data The Blob of data to be saved to a file */ NativeFileSystem.FileSaver = function (data) { // FileSaver private member vars @@ -464,18 +582,20 @@ define(function (require, exports, module) { DONE: { value: 3, writable: false } } ); - - // FileSaver methods - + /** - * + * The state the FileSaver object is at the moment (INIT, WRITING, DONE) */ NativeFileSystem.FileSaver.prototype.readyState = function () { return this._readyState; }; - - // TODO (issue #241): http://dev.w3.org/2009/dap/file-system/file-writer.html#widl-FileSaver-abort-void + + /** + * Aborts a saving operation + */ NativeFileSystem.FileSaver.prototype.abort = function () { + // TODO (issue #241): http://dev.w3.org/2009/dap/file-system/file-writer.html#widl-FileSaver-abort-void + // If readyState is DONE or INIT, terminate this overall series of steps without doing anything else.. if (this._readyState === NativeFileSystem.FileSaver.INIT || this._readyState === NativeFileSystem.FileSaver.DONE) { return; @@ -499,10 +619,13 @@ define(function (require, exports, module) { }; /** - * This interface represents a directory on a file system. + * Implementation of w3 DirectoryEntry interface: + * http://www.w3.org/TR/2011/WD-file-system-api-20110419/#the-directoryentry-interface + * + * The DirectoryEntry class represents a directory on a file system. * * @constructor - * @param {string} name + * @param {string} name Full path of the directory in the file system * @extends {Entry} */ NativeFileSystem.DirectoryEntry = function (name) { @@ -516,6 +639,15 @@ define(function (require, exports, module) { return "[DirectoryEntry " + this.fullPath + "]"; }; + /** + * Creates or looks up a directory + * @param {string} path Either an absolute path or a relative path from this DirectoryEntry + * to the directory to be looked up or created + * @param {Object} options Object with the flags "create" and "exclusive" to modify the method behavior + * based on http://www.w3.org/TR/2011/WD-file-system-api-20110419/#widl-DirectoryEntry-getDirectory + * @param {function(Entry)} successCallback Callback function for successful operations + * @param {function(FileError)} errorCallback Callback function for error operations + */ NativeFileSystem.DirectoryEntry.prototype.getDirectory = function (path, options, successCallback, errorCallback) { var directoryFullPath = path; @@ -601,11 +733,20 @@ define(function (require, exports, module) { }); }; + /** + * Deletes a directory and all of its contents, if any + * @param {function()} successCallback Callback function for successful operations + * @param {function(FileError)} errorCallback Callback function for error operations + */ NativeFileSystem.DirectoryEntry.prototype.removeRecursively = function (successCallback, errorCallback) { // TODO (issue #241) // http://www.w3.org/TR/2011/WD-file-system-api-20110419/#widl-DirectoryEntry-removeRecursively }; + /** + * Creates a new DirectoryReader to read Entries from this Directory + * @returns {DirectoryReader} A DirectoryReader instance to read the Directory's entries + */ NativeFileSystem.DirectoryEntry.prototype.createReader = function () { var dirReader = new NativeFileSystem.DirectoryReader(); dirReader._directory = this; @@ -708,17 +849,22 @@ define(function (require, exports, module) { }); }; - /** class: DirectoryReader + /** + * Implementation of w3 DirectoryReader interface: + * http://www.w3.org/TR/2011/WD-file-system-api-20110419/#the-directoryreader-interface + * + * A DirectoryReader lets a user list files and directories in a directory + * + * @constructor */ NativeFileSystem.DirectoryReader = function () { }; - /** readEntries - * - * @param {function(...)} successCallback - * @param {function(...)} errorCallback - * @returns {Array.} + /** + * Read the next block of entries from this directory + * @param {function(Array.)} successCallback + * @param {function(FileError)} errorCallback */ NativeFileSystem.DirectoryReader.prototype.readEntries = function (successCallback, errorCallback) { var rootPath = this._directory.fullPath; @@ -790,8 +936,14 @@ define(function (require, exports, module) { }); }; - /** class: FileReader + /** + * Implementation of w3 FileReader interface: + * http://www.w3.org/TR/2011/WD-FileAPI-20111020/#FileReader-interface * + * A FileReader provides methods to read File objects or Blob objects into memory, and to + * access the data from those Files or Blobs using progress events and event handler attributes + * + * @constructor * @extends {EventTarget} */ NativeFileSystem.FileReader = function () { @@ -820,29 +972,44 @@ define(function (require, exports, module) { // TODO (issue #241): extend EventTarget (draft status, not implememnted in webkit) // NativeFileSystem.FileReader.prototype = new NativeFileSystem.EventTarget() + /** + * Reads a Blob as an array buffer + * @param {Blob} blob The data to read + */ NativeFileSystem.FileReader.prototype.readAsArrayBuffer = function (blob) { // TODO (issue #241): implement // http://www.w3.org/TR/2011/WD-FileAPI-20111020/#dfn-readAsArrayBuffer }; + /** + * Reads a Blob as a binary string + * @param {Blob} blob The data to read + */ NativeFileSystem.FileReader.prototype.readAsBinaryString = function (blob) { // TODO (issue #241): implement // http://www.w3.org/TR/2011/WD-FileAPI-20111020/#dfn-readAsBinaryStringAsync }; + /** + * Reads a Blob as a data url + * @param {Blob} blob The data to read + */ NativeFileSystem.FileReader.prototype.readAsDataURL = function (blob) { // TODO (issue #241): implement // http://www.w3.org/TR/2011/WD-FileAPI-20111020/#dfn-readAsDataURL }; + /** + * Aborts a File reading operation + */ NativeFileSystem.FileReader.prototype.abort = function () { // TODO (issue #241): implement // http://www.w3.org/TR/2011/WD-FileAPI-20111020/#dfn-abort }; - /** readAsText - * - * @param {Blob} blob + /** + * Reads a Blob as text + * @param {Blob} blob The data to read * @param {string} encoding (IANA Encoding Name) */ NativeFileSystem.FileReader.prototype.readAsText = function (blob, encoding) { @@ -910,10 +1077,14 @@ define(function (require, exports, module) { }); }; - /** class: Blob + /** + * Implementation of w3 Blob interface: + * http://www.w3.org/TR/2011/WD-FileAPI-20111020/#blob + * + * A Blob represents immutable raw data. * * @constructor - * param {Entry} entry + * @param {string} fullPath Absolute path of the Blob */ NativeFileSystem.Blob = function (fullPath) { this._fullPath = fullPath; @@ -925,15 +1096,27 @@ define(function (require, exports, module) { this.type = null; }; + /** + * Returns a new Blob object with bytes ranging from the optional start parameter + * up to but not including the optional end parameter + * @param {number} start Start point of a slice treated as a byte-order position + * @param {number} end End point of a slice. If end is undefined, size will be used. If + * end is negative, max(size+end, 0) will be used. In any other case, + * the slice will finish at min(end, size) + * @param {string} contentType HTTP/1.1 Content-Type header on the Blob + * @returns {Blob} + */ NativeFileSystem.Blob.prototype.slice = function (start, end, contentType) { // TODO (issue #241): implement // http://www.w3.org/TR/2011/WD-FileAPI-20111020/#dfn-slice }; - /** class: File + /** + * Implementation of w3 Blob interface: + * http://www.w3.org/TR/2011/WD-FileAPI-20111020/#file * * @constructor - * param {Entry} entry + * @param {Entry} entry The Entry pointing to the File * @extends {Blob} */ NativeFileSystem.File = function (entry) { @@ -946,8 +1129,7 @@ define(function (require, exports, module) { this.lastModifiedDate = null; }; - /** class: FileError - * + /** * Implementation of HTML file API error code return class. Note that we don't * actually define the error codes here--we rely on the browser's built-in FileError * class's constants. In other words, external clients of this API should always From 6a93363021f668ca85c4ea2eb7130416b5ba2bf3 Mon Sep 17 00:00:00 2001 From: Chema Date: Tue, 6 Nov 2012 02:21:55 +0100 Subject: [PATCH 2/7] Removed unused NativeFileSystem requires --- src/language/CSSUtils.js | 3 +-- src/project/FileIndexManager.js | 3 +-- src/project/WorkingSetView.js | 1 - 3 files changed, 2 insertions(+), 5 deletions(-) diff --git a/src/language/CSSUtils.js b/src/language/CSSUtils.js index 561cee2f60f..9399b8c2311 100644 --- a/src/language/CSSUtils.js +++ b/src/language/CSSUtils.js @@ -38,8 +38,7 @@ define(function (require, exports, module) { DocumentManager = require("document/DocumentManager"), EditorManager = require("editor/EditorManager"), HTMLUtils = require("language/HTMLUtils"), - FileIndexManager = require("project/FileIndexManager"), - NativeFileSystem = require("file/NativeFileSystem").NativeFileSystem; + FileIndexManager = require("project/FileIndexManager"); /** * Extracts all CSS selectors from the given text diff --git a/src/project/FileIndexManager.js b/src/project/FileIndexManager.js index 0e6e2dd78a5..b24180bf43d 100644 --- a/src/project/FileIndexManager.js +++ b/src/project/FileIndexManager.js @@ -39,8 +39,7 @@ define(function (require, exports, module) { "use strict"; - var NativeFileSystem = require("file/NativeFileSystem").NativeFileSystem, - PerfUtils = require("utils/PerfUtils"), + var PerfUtils = require("utils/PerfUtils"), ProjectManager = require("project/ProjectManager"), Dialogs = require("widgets/Dialogs"), Strings = require("strings"); diff --git a/src/project/WorkingSetView.js b/src/project/WorkingSetView.js index 4d5dfe7affc..7d275f08c1e 100644 --- a/src/project/WorkingSetView.js +++ b/src/project/WorkingSetView.js @@ -40,7 +40,6 @@ define(function (require, exports, module) { Menus = require("command/Menus"), EditorManager = require("editor/EditorManager"), FileViewController = require("project/FileViewController"), - NativeFileSystem = require("file/NativeFileSystem").NativeFileSystem, ViewUtils = require("utils/ViewUtils"); From 2237cd3c5820fed75a31155e60c8ae91c00ce17f Mon Sep 17 00:00:00 2001 From: Chema Date: Tue, 6 Nov 2012 18:44:25 +0100 Subject: [PATCH 3/7] Basic usage examples --- src/file/NativeFileSystem.js | 45 +++++++++++++++++++++++++++--------- 1 file changed, 34 insertions(+), 11 deletions(-) diff --git a/src/file/NativeFileSystem.js b/src/file/NativeFileSystem.js index f18ff34fe3e..88888046486 100644 --- a/src/file/NativeFileSystem.js +++ b/src/file/NativeFileSystem.js @@ -46,21 +46,44 @@ * * Basic usage examples: * - * CREATE_DIRECTORY - * NativeFileSystem.DirectoryEntry().getDirectory(path) + * - CREATE A DIRECTORY + * NativeFileSystem.DirectoryEntry().getDirectory(path, {create: true}); * - * GET_FILE - * NativeFileSystem.DirectoryEntry(path).getFile(filename) + * - CHECK IF A FILE OR FOLDER EXISTS + * NativeFileSystem.requestNativeFileSystem(path + * , function() { console.log("Entry exists"); } + * , function() { console.log("Entry does not exist"); }); * - * GET_FILE - * NativeFileSystem.requestNativeFileSystem( + * - READ A FILE + * reader = new NativeFileSystem.FileReader(); + * fileEntry.file(function (file) { + * reader.onload = function (event) { + * var text = event.target.result; + * }; * - * GET_METADATA - * var fileEntry = new NativeFileSystem.FileEntry(path) - * fileEntry.getMetadata(success, error) + * reader.onerror = function (event) { + * }; + * + * reader.readAsText(file, Encodings.UTF8); + * }); * - * OPEN_FILE - * NativeFileSystem.showOpenDialog() + * - WRITE TO A FILE + * writer = fileEntry.createWriter(function (fileWriter) { + * fileWriter.onwriteend = function (e) { + * }; + * + * fileWriter.onerror = function (err) { + * }; + * + * fileWriter.write(text); + * }); + * + * - GET THE METADATA OF A FILE + * var fileEntry = new NativeFileSystem.FileEntry(path); + * fileEntry.getMetadata(function(metadata) {}, function(error) {}); + * + * - LET THE USER SELECT FILES OR FOLDERS FROM THE FILE SYSTEM + * NativeFileSystem.showOpenDialog(true, true, "Choose a file...", null, function(files) {}, function(err) {}); */ define(function (require, exports, module) { From e06b0a84d98a95ffbfdba7fd8d930079c050e2bf Mon Sep 17 00:00:00 2001 From: Chema Date: Tue, 6 Nov 2012 18:50:11 +0100 Subject: [PATCH 4/7] Added some callback parameters documentation --- src/file/NativeFileSystem.js | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/src/file/NativeFileSystem.js b/src/file/NativeFileSystem.js index 88888046486..986fc8dd2e0 100644 --- a/src/file/NativeFileSystem.js +++ b/src/file/NativeFileSystem.js @@ -106,16 +106,16 @@ define(function (require, exports, module) { * Shows a modal dialog for selecting and opening files * * @param {bool} allowMultipleSelection Allows selecting more than one file at a time - * @param {bool} chooseDirectories Allows directories as + * @param {bool} chooseDirectories Allows directories to be opened * @param {string} title The title for the window * @param {string} initialPath The folder opened inside the window initially. If initialPath * is not set, or it doesn't exist, the window would show the last * browsed folder depending on the OS preferences * @param {Array.} fileTypes List of extensions that are allowed to be opened. A null value * allows any extension to be selected. - * @param {function(...)} successCallback Callback function for successful operations. Receives an + * @param {function(Array.)} successCallback Callback function for successful operations. Receives an array with the selected paths as first parameter. - * @param {function(...)} errorCallback Callback function for error operations. + * @param {function(FileError)} errorCallback Callback function for error operations. */ showOpenDialog: function (allowMultipleSelection, chooseDirectories, @@ -147,9 +147,9 @@ define(function (require, exports, module) { /** * Implementation of w3 requestFileSystem entry point * @param {string} path Path of the file in the system - * @param {function(...)} successCallback Callback function for successful operations. Receives a + * @param {function(DirectoryEntry)} successCallback Callback function for successful operations. Receives a * DirectoryEntry pointing to the path - * @param {function(...)} errorCallback Callback function for errors, including permission errors. + * @param {function(FileError)} errorCallback Callback function for errors, including permission errors. */ requestNativeFileSystem: function (path, successCallback, errorCallback) { brackets.fs.stat(path, function (err, data) { From ef508ee4437195a402f05598a8a7d675473d0437 Mon Sep 17 00:00:00 2001 From: Chema Date: Sat, 17 Nov 2012 02:13:39 +0100 Subject: [PATCH 5/7] Completed Nullable/Optional parameters information --- src/file/NativeFileSystem.js | 104 ++++++++++++++++++----------------- 1 file changed, 53 insertions(+), 51 deletions(-) diff --git a/src/file/NativeFileSystem.js b/src/file/NativeFileSystem.js index 282798c3346..8539d0e21af 100644 --- a/src/file/NativeFileSystem.js +++ b/src/file/NativeFileSystem.js @@ -125,14 +125,14 @@ define(function (require, exports, module) { * @param {bool} chooseDirectories Allows directories to be opened * @param {string} title The title for the window * @param {string} initialPath The folder opened inside the window initially. If initialPath - * is not set, or it doesn't exist, the window would show the last - * browsed folder depending on the OS preferences + * is not set, or it doesn't exist, the window would show the last + * browsed folder depending on the OS preferences * @param {Array.} fileTypes List of extensions that are allowed to be opened. A null value - * allows any extension to be selected. - * @param {!function(Array.)} successCallback Callback function for successful operations. Receives an - array with the selected paths as first parameter. + * allows any extension to be selected. + * @param {!function(Array.)} successCallback Callback function for successful operations. + Receives an array with the selected paths as first parameter. * @param {!function(number)} errorCallback Callback function for error operations. - * (TODO #2057: should this pass a FileError?) + * (TODO #2057: should this pass a FileError?) */ showOpenDialog: function (allowMultipleSelection, chooseDirectories, @@ -164,8 +164,8 @@ define(function (require, exports, module) { /** * Implementation of w3 requestFileSystem entry point * @param {!string} path Path of the file in the system - * @param {!function(DirectoryEntry)} successCallback Callback function for successful operations. Receives a - * DirectoryEntry pointing to the path + * @param {!function(DirectoryEntry)} successCallback Callback function for successful operations. + * Receives a DirectoryEntry pointing to the path * @param {!function(number)} errorCallback Callback function for errors, including permission errors. * (TODO #2057: should pass a FileError) */ @@ -225,8 +225,7 @@ define(function (require, exports, module) { } }; - /** class: Encodings - * + /** * Static class that contains constants for file * encoding types. */ @@ -234,8 +233,7 @@ define(function (require, exports, module) { NativeFileSystem.Encodings.UTF8 = "UTF-8"; NativeFileSystem.Encodings.UTF16 = "UTF-16"; - /** class: _FSEncodings - * + /** * Internal static class that contains constants for file * encoding types to be used by internal file system * implementation. @@ -307,10 +305,10 @@ define(function (require, exports, module) { /** * Moves this Entry to a different location on the file system. - * @param {DirectoryEntry} parent The directory to move the entry to - * @param {string} newName The new name of the entry. If not specified, defaults to the current name - * @param {function(Array.)} successCallback Callback function for successful operations - * @param {function(FileError)} errorCallback Callback function for error operations + * @param {!DirectoryEntry} parent The directory to move the entry to + * @param {!string=} newName The new name of the entry. If not specified, defaults to the current name + * @param {!function(Array.)=} successCallback Callback function for successful operations + * @param {!function(FileError)=} errorCallback Callback function for error operations */ NativeFileSystem.Entry.prototype.moveTo = function (parent, newName, successCallback, errorCallback) { // TODO (issue #241) @@ -319,10 +317,10 @@ define(function (require, exports, module) { /** * Copies this Entry to a different location on the file system. - * @param {DirectoryEntry} parent The directory to copy the entry to - * @param {string} newName The new name of the entry. If not specified, defaults to the current name - * @param {function(Array.)} successCallback Callback function for successful operations - * @param {function(FileError)} errorCallback Callback function for error operations + * @param {!DirectoryEntry} parent The directory to copy the entry to + * @param {!string=} newName The new name of the entry. If not specified, defaults to the current name + * @param {!function(Array.)=} successCallback Callback function for successful operations + * @param {!function(FileError)=} errorCallback Callback function for error operations */ NativeFileSystem.Entry.prototype.copyTo = function (parent, newName, successCallback, errorCallback) { // TODO (issue #241) @@ -331,18 +329,21 @@ define(function (require, exports, module) { /** * Generates a URL that can be used to identify this Entry - * @param {string} mimeType The mime type to be used to interpret the file for a FileEntry + * @param {!string=} mimeType The mime type to be used to interpret the file for a FileEntry * @returns {string} A usable URL to identify this Entry in the current filesystem */ NativeFileSystem.Entry.prototype.toURL = function (mimeType) { // TODO (issue #241) // http://www.w3.org/TR/2011/WD-file-system-api-20110419/#widl-Entry-toURL + + // Check updated definition at + // http://www.w3.org/TR/2012/WD-file-system-api-20120417/#widl-Entry-toURL-DOMString }; /** * Deletes a file or directory - * @param {function()} successCallback Callback function for successful operations - * @param {function(FileError)} errorCallback Callback function for error operations + * @param {!function()} successCallback Callback function for successful operations + * @param {!function(FileError)=} errorCallback Callback function for error operations */ NativeFileSystem.Entry.prototype.remove = function (successCallback, errorCallback) { // TODO (issue #241) @@ -351,8 +352,8 @@ define(function (require, exports, module) { /** * Look up the parent DirectoryEntry that contains this Entry - * @param {function(Array.)} successCallback Callback function for successful operations - * @param {function(FileError)} errorCallback Callback function for error operations + * @param {!function(Array.)} successCallback Callback function for successful operations + * @param {!function(FileError)=} errorCallback Callback function for error operations */ NativeFileSystem.Entry.prototype.getParent = function (successCallback, errorCallback) { // TODO (issue #241) @@ -362,7 +363,7 @@ define(function (require, exports, module) { /** * Look up metadata about this Entry * @param {!function(Metadata)} successCallback Callback function for successful operations - * @param {!function(number)} errorCallback Callback function for error operations + * @param {!function(number)=} errorCallback Callback function for error operations * (TODO #2057: should pass a FileError) */ NativeFileSystem.Entry.prototype.getMetadata = function (successCallBack, errorCallback) { @@ -397,7 +398,7 @@ define(function (require, exports, module) { * A FileEntry represents a file on a file system. * * @constructor - * @param {string} name Full path of the file in the file system + * @param {!string} name Full path of the file in the file system * @extends {Entry} */ NativeFileSystem.FileEntry = function (name) { @@ -412,8 +413,8 @@ define(function (require, exports, module) { /** * Creates a new FileWriter associated with the file that this FileEntry represents. * @param {!function(FileWriter)} successCallback Callback function for successful operations - * @param {!function(number)} errorCallback Callback function for error operations - * (TODO #2057: should pass a FileError) + * @param {!function(number)=} errorCallback Callback function for error operations + * (TODO #2057: should pass a FileError) */ NativeFileSystem.FileEntry.prototype.createWriter = function (successCallback, errorCallback) { var fileEntry = this; @@ -513,10 +514,10 @@ define(function (require, exports, module) { /** * Seek sets the file position at which the next write will occur - * @param {number} offset An absolute byte offset into the file. If offset is greater than - * length, length is used instead. If offset is less than zero, length - * is added to it, so that it is treated as an offset back from the end - * of the file. If it is still less than zero, zero is used + * @param {!number} offset An absolute byte offset into the file. If offset is greater than + * length, length is used instead. If offset is less than zero, length + * is added to it, so that it is treated as an offset back from the end + * of the file. If it is still less than zero, zero is used */ FileWriter.prototype.seek = function (offset) { // TODO (issue #241) @@ -525,7 +526,7 @@ define(function (require, exports, module) { /** * Changes the length of the file to that specified - * @param {number} size The size to which the length of the file is to be adjusted, + * @param {!number} size The size to which the length of the file is to be adjusted, * measured in bytes */ FileWriter.prototype.truncate = function (size) { @@ -562,7 +563,7 @@ define(function (require, exports, module) { /** * Returns a File that represents the current state of the file that this FileEntry represents * @param {!function(File)} successCallback Callback function for successful operations - * @param {!function(FileError)} errorCallback Callback function for error operations + * @param {!function(FileError)=} errorCallback Callback function for error operations */ NativeFileSystem.FileEntry.prototype.file = function (successCallback, errorCallback) { var newFile = new NativeFileSystem.File(this); @@ -691,11 +692,12 @@ define(function (require, exports, module) { * Creates or looks up a directory * @param {!string} path Either an absolute path or a relative path from this DirectoryEntry * to the directory to be looked up or created - * @param {{!{create:?boolean, exclusive:?boolean}}} options Object with the flags "create" and "exclusive" to modify the method behavior - * based on http://www.w3.org/TR/2011/WD-file-system-api-20110419/#widl-DirectoryEntry-getDirectory + * @param {{!{create:?boolean, exclusive:?boolean}}} options Object with the flags "create" + * and "exclusive" to modify the method behavior based on + * http://www.w3.org/TR/2011/WD-file-system-api-20110419/#widl-DirectoryEntry-getDirectory * @param {!function(Entry)} successCallback Callback function for successful operations * @param {!function(FileError)} errorCallback Callback function for error operations - * (TODO #2057: should consistently pass a FileError) + * (TODO #2057: should consistently pass a FileError) */ NativeFileSystem.DirectoryEntry.prototype.getDirectory = function (path, options, successCallback, errorCallback) { var directoryFullPath = path; @@ -784,8 +786,8 @@ define(function (require, exports, module) { /** * Deletes a directory and all of its contents, if any - * @param {function()} successCallback Callback function for successful operations - * @param {function(FileError)} errorCallback Callback function for error operations + * @param {!function()} successCallback Callback function for successful operations + * @param {!function(FileError)=} errorCallback Callback function for error operations */ NativeFileSystem.DirectoryEntry.prototype.removeRecursively = function (successCallback, errorCallback) { // TODO (issue #241) @@ -806,13 +808,13 @@ define(function (require, exports, module) { /** * Creates or looks up a file. * - * @param {string} path Either an absolute path or a relative path from this + * @param {!string} path Either an absolute path or a relative path from this * DirectoryEntry to the file to be looked up or created. It is an error * to attempt to create a file whose immediate parent does not yet * exist. - * @param {!{create:?boolean, exclusive:?boolean}} options - * @param {!function(FileEntry)} successCallback - * @param {!function(FileError|number)} errorCallback (TODO #2057: should consistently pass a FileError) + * @param {!{create:?boolean, exclusive:?boolean}=} options + * @param {!function(FileEntry)=} successCallback + * @param {!function(FileError|number)=} errorCallback (TODO #2057: should consistently pass a FileError) */ NativeFileSystem.DirectoryEntry.prototype.getFile = function (path, options, successCallback, errorCallback) { var fileFullPath = path; @@ -913,7 +915,7 @@ define(function (require, exports, module) { /** * Read the next block of entries from this directory * @param {!function(Array.)} successCallback - * @param {!function(FileError|number)} errorCallback (TODO #2057: should consistently pass a FileError) + * @param {!function(FileError|number)=} errorCallback (TODO #2057: should consistently pass a FileError) */ NativeFileSystem.DirectoryReader.prototype.readEntries = function (successCallback, errorCallback) { var rootPath = this._directory.fullPath; @@ -1148,11 +1150,11 @@ define(function (require, exports, module) { /** * Returns a new Blob object with bytes ranging from the optional start parameter * up to but not including the optional end parameter - * @param {number} start Start point of a slice treated as a byte-order position - * @param {number} end End point of a slice. If end is undefined, size will be used. If - * end is negative, max(size+end, 0) will be used. In any other case, - * the slice will finish at min(end, size) - * @param {string} contentType HTTP/1.1 Content-Type header on the Blob + * @param {!number=} start Start point of a slice treated as a byte-order position + * @param {!number=} end End point of a slice. If end is undefined, size will be used. If + * end is negative, max(size+end, 0) will be used. In any other case, + * the slice will finish at min(end, size) + * @param {!string=} contentType HTTP/1.1 Content-Type header on the Blob * @returns {Blob} */ NativeFileSystem.Blob.prototype.slice = function (start, end, contentType) { @@ -1161,7 +1163,7 @@ define(function (require, exports, module) { }; /** - * Implementation of w3 Blob interface: + * Implementation of w3 File interface: * http://www.w3.org/TR/2011/WD-FileAPI-20111020/#file * * @constructor From 7bb9c2f7d8edcd27eec1ca9648d7057453593468 Mon Sep 17 00:00:00 2001 From: Chema Date: Thu, 13 Dec 2012 00:56:42 +0100 Subject: [PATCH 6/7] Review and update after changes in nativefilesystem --- src/file/NativeFileSystem.js | 77 +++++++++++++++--------------------- 1 file changed, 31 insertions(+), 46 deletions(-) diff --git a/src/file/NativeFileSystem.js b/src/file/NativeFileSystem.js index 08237c7a529..b876178ada8 100644 --- a/src/file/NativeFileSystem.js +++ b/src/file/NativeFileSystem.js @@ -91,17 +91,7 @@ define(function (require, exports, module) { var Async = require("utils/Async"), NativeFileError = require("file/NativeFileError"); - - /* - * Generally NativeFileSystem mimics the File API working draft - * http://www.w3.org/TR/file-system-api/. The w3 entry point - * requestFileSystem is replaced with our own requestNativeFileSystem. - * - * The current implementation is incomplete and noteably does not - * support the Blob data type and synchronous APIs. DirectoryEntry - * and FileEntry read/write capabilities are mostly implemented, but - * delete is not. File writing is limited to UTF-8 text. - */ + var NativeFileSystem = { /** @@ -118,16 +108,15 @@ define(function (require, exports, module) { * * @param {bool} allowMultipleSelection Allows selecting more than one file at a time * @param {bool} chooseDirectories Allows directories to be opened - * @param {string} title The title for the window + * @param {string} title The title of the window * @param {string} initialPath The folder opened inside the window initially. If initialPath - * is not set, or it doesn't exist, the window would show the last - * browsed folder depending on the OS preferences + * is not set, or it doesn't exist, the window would show the last + * browsed folder depending on the OS preferences * @param {Array.} fileTypes List of extensions that are allowed to be opened. A null value - * allows any extension to be selected. + * allows any extension to be selected. * @param {!function(Array.)} successCallback Callback function for successful operations. - Receives an array with the selected paths as first parameter. - * @param {!function(number)} errorCallback Callback function for error operations. - * (TODO #2057: should this pass a FileError?) + Receives an array with the selected paths as first parameter. + * @param {!function(DOMError)} errorCallback Callback function for error operations. */ showOpenDialog: function (allowMultipleSelection, chooseDirectories, @@ -160,9 +149,8 @@ define(function (require, exports, module) { * Implementation of w3 requestFileSystem entry point * @param {!string} path Path of the file in the system * @param {!function(DirectoryEntry)} successCallback Callback function for successful operations. - * Receives a DirectoryEntry pointing to the path - * @param {!function(number)} errorCallback Callback function for errors, including permission errors. - * (TODO #2057: should pass a FileError) + * Receives a DirectoryEntry pointing to the path + * @param {!function(DOMError)} errorCallback Callback function for errors, including permission errors. */ requestNativeFileSystem: function (path, successCallback, errorCallback) { brackets.fs.stat(path, function (err, data) { @@ -177,9 +165,9 @@ define(function (require, exports, module) { /** * NativeFileSystem implementation of LocalFileSystem.resolveLocalFileSystemURL() * - * @param {!string} url - * @param {!function(Entry)} successCallback - * @param {!function(FileError)} errorCallback (TODO #2057: should pass a DOMError) + * @param {!string} path A URL referring to a local file in a filesystem accessable via this API. + * @param {!function(Entry)} successCallback Callback function for successful operations. + * @param {!function(DOMError)=} errorCallback Callback function for error operations. */ resolveNativeFileSystemPath: function (path, successCallback, errorCallback) { brackets.fs.stat(path, function (err, stats) { @@ -194,7 +182,7 @@ define(function (require, exports, module) { successCallback(entry); } else if (errorCallback) { - errorCallback(NativeFileSystem._nativeToFileError(err)); + errorCallback(new NativeFileError(NativeFileSystem._fsErrorToDOMErrorName(err))); } }); }, @@ -292,7 +280,7 @@ define(function (require, exports, module) { * @constructor * @param {string} fullPath The full absolute path from the root to the entry * @param {boolean} isDirectory Indicates that the entry is a directory - * @param {FileSystem} fs + * @param {FileSystem} fs File system that contains this entry */ NativeFileSystem.Entry = function (fullPath, isDirectory, fs) { this.isDirectory = isDirectory; @@ -325,7 +313,7 @@ define(function (require, exports, module) { * @param {!DirectoryEntry} parent The directory to move the entry to * @param {!string=} newName The new name of the entry. If not specified, defaults to the current name * @param {!function(Array.)=} successCallback Callback function for successful operations - * @param {!function(FileError)=} errorCallback Callback function for error operations + * @param {!function(DOMError)=} errorCallback Callback function for error operations */ NativeFileSystem.Entry.prototype.moveTo = function (parent, newName, successCallback, errorCallback) { // TODO (issue #241) @@ -337,7 +325,7 @@ define(function (require, exports, module) { * @param {!DirectoryEntry} parent The directory to copy the entry to * @param {!string=} newName The new name of the entry. If not specified, defaults to the current name * @param {!function(Array.)=} successCallback Callback function for successful operations - * @param {!function(FileError)=} errorCallback Callback function for error operations + * @param {!function(DOMError)=} errorCallback Callback function for error operations */ NativeFileSystem.Entry.prototype.copyTo = function (parent, newName, successCallback, errorCallback) { // TODO (issue #241) @@ -360,7 +348,7 @@ define(function (require, exports, module) { /** * Deletes a file or directory * @param {!function()} successCallback Callback function for successful operations - * @param {!function(FileError)=} errorCallback Callback function for error operations + * @param {!function(DOMError)=} errorCallback Callback function for error operations */ NativeFileSystem.Entry.prototype.remove = function (successCallback, errorCallback) { // TODO (issue #241) @@ -370,7 +358,7 @@ define(function (require, exports, module) { /** * Look up the parent DirectoryEntry that contains this Entry * @param {!function(Array.)} successCallback Callback function for successful operations - * @param {!function(FileError)=} errorCallback Callback function for error operations + * @param {!function(DOMError)=} errorCallback Callback function for error operations */ NativeFileSystem.Entry.prototype.getParent = function (successCallback, errorCallback) { // TODO (issue #241) @@ -415,7 +403,7 @@ define(function (require, exports, module) { * * @constructor * @param {!string} name Full path of the file in the file system - * @param {Filesystem} fs + * @param {FileSystem} fs File system that contains this entry * @extends {Entry} */ NativeFileSystem.FileEntry = function (name, fs) { @@ -627,9 +615,6 @@ define(function (require, exports, module) { * FileSaver provides methods to monitor the asynchronous writing of blobs * to disk using progress events and event handler attributes. * - * FileSaver is specified to be used within the context of the global - * object (Window) and within Web Workers. - * * @constructor * @param {Blob} data The Blob of data to be saved to a file */ @@ -693,7 +678,7 @@ define(function (require, exports, module) { * * @constructor * @param {string} name Full path of the directory in the file system - * @param {FileSystem} fs + * @param {FileSystem} fs File system that contains this entry * @extends {Entry} */ NativeFileSystem.DirectoryEntry = function (name, fs) { @@ -808,7 +793,7 @@ define(function (require, exports, module) { /** * Deletes a directory and all of its contents, if any * @param {!function()} successCallback Callback function for successful operations - * @param {!function(FileError)=} errorCallback Callback function for error operations + * @param {!function(DOMError)=} errorCallback Callback function for error operations */ NativeFileSystem.DirectoryEntry.prototype.removeRecursively = function (successCallback, errorCallback) { // TODO (issue #241) @@ -830,12 +815,14 @@ define(function (require, exports, module) { * Creates or looks up a file. * * @param {!string} path Either an absolute path or a relative path from this - * DirectoryEntry to the file to be looked up or created. It is an error - * to attempt to create a file whose immediate parent does not yet - * exist. - * @param {!{create:?boolean, exclusive:?boolean}=} options - * @param {!function(FileEntry)=} successCallback - * @param {!function(FileError|number)=} errorCallback (TODO #2057: should consistently pass a FileError) + * DirectoryEntry to the file to be looked up or created. It is an error + * to attempt to create a file whose immediate parent does not yet + * exist. + * @param {!{create:?boolean, exclusive:?boolean}=} options Object with the flags "create" + * and "exclusive" to modify the method behavior based on + * http://www.w3.org/TR/2011/WD-file-system-api-20110419/#widl-DirectoryEntry-getFile + * @param {!function(FileEntry)=} successCallback Callback function for successful operations + * @param {!function(DOMError)=} errorCallback Callback function for error operations */ NativeFileSystem.DirectoryEntry.prototype.getFile = function (path, options, successCallback, errorCallback) { var fileFullPath = path, @@ -936,9 +923,8 @@ define(function (require, exports, module) { /** * Read the next block of entries from this directory - * @param {!function(Array.)} successCallback - * @param {!function(DOMError} errorCallback - * @returns {Array.} + * @param {!function(Array.)} successCallback Callback function for successful operations + * @param {!function(DOMError)=} errorCallback Callback function for error operations */ NativeFileSystem.DirectoryReader.prototype.readEntries = function (successCallback, errorCallback) { var rootPath = this._directory.fullPath, @@ -1026,7 +1012,6 @@ define(function (require, exports, module) { * access the data from those Files or Blobs using progress events and event handler attributes * * @constructor - * @extends {EventTarget} */ NativeFileSystem.FileReader = function () { // TODO (issue #241): this classes should extend EventTarget From 16f227b9a50aa3940ae788826e800a2f7c38a16c Mon Sep 17 00:00:00 2001 From: Chema Date: Fri, 14 Dec 2012 21:32:56 +0100 Subject: [PATCH 7/7] Added better examples and fixed nullable operator misuse --- src/file/NativeFileSystem.js | 176 +++++++++++++++++++---------------- 1 file changed, 98 insertions(+), 78 deletions(-) diff --git a/src/file/NativeFileSystem.js b/src/file/NativeFileSystem.js index b876178ada8..566b00cb257 100644 --- a/src/file/NativeFileSystem.js +++ b/src/file/NativeFileSystem.js @@ -47,42 +47,61 @@ * Basic usage examples: * * - CREATE A DIRECTORY - * NativeFileSystem.DirectoryEntry().getDirectory(path, {create: true}); + * var directoryEntry = ... // NativeFileSystem.DirectoryEntry + * directoryEntry.getDirectory(path, {create: true}); + * * * - CHECK IF A FILE OR FOLDER EXISTS - * NativeFileSystem.requestNativeFileSystem(path - * , function() { console.log("Entry exists"); } - * , function() { console.log("Entry does not exist"); }); + * NativeFileSystem.resolveNativeFileSystemPath(path + * , function(entry) { console.log("Path for " + entry.name + " resolved"); } + * , function(err) { console.log("Error resolving path: " + err.name); }); + * * * - READ A FILE - * reader = new NativeFileSystem.FileReader(); - * fileEntry.file(function (file) { - * reader.onload = function (event) { - * var text = event.target.result; - * }; * - * reader.onerror = function (event) { - * }; - * - * reader.readAsText(file, Encodings.UTF8); - * }); + * (Using file/NativeFileSystem) + * reader = new NativeFileSystem.FileReader(); + * fileEntry.file(function (file) { + * reader.onload = function (event) { + * var text = event.target.result; + * }; + * + * reader.onerror = function (event) { + * }; + * + * reader.readAsText(file, Encodings.UTF8); + * }); + * + * (Using file/FileUtils) + * FileUtils.readAsText(fileEntry).done(function (rawText, readTimestamp) { + * console.log(rawText); + * }).fail(function (err) { + * console.log("Error reading text: " + err.name); + * }); + * + * + * - WRITE TO A FILE + * + * (Using file/NativeFileSystem) + * writer = fileEntry.createWriter(function (fileWriter) { + * fileWriter.onwriteend = function (e) { + * }; + * + * fileWriter.onerror = function (err) { + * }; + * + * fileWriter.write(text); + * }); * - * - WRITE TO A FILE - * writer = fileEntry.createWriter(function (fileWriter) { - * fileWriter.onwriteend = function (e) { - * }; + * (Using file/FileUtils) + * FileUtils.writeText(text, fileEntry).done(function () { + * console.log("Text successfully updated"); + * }).fail(function (err) { + * console.log("Error writing text: " + err.name); + * ]); * - * fileWriter.onerror = function (err) { - * }; - * - * fileWriter.write(text); - * }); - * - * - GET THE METADATA OF A FILE - * var fileEntry = new NativeFileSystem.FileEntry(path); - * fileEntry.getMetadata(function(metadata) {}, function(error) {}); * - * - LET THE USER SELECT FILES OR FOLDERS FROM THE FILE SYSTEM + * - PROMPT THE USER TO SELECT FILES OR FOLDERS WITH OPERATING SYSTEM'S FILE OPEN DIALOG * NativeFileSystem.showOpenDialog(true, true, "Choose a file...", null, function(files) {}, function(err) {}); */ @@ -106,17 +125,17 @@ define(function (require, exports, module) { /** * Shows a modal dialog for selecting and opening files * - * @param {bool} allowMultipleSelection Allows selecting more than one file at a time - * @param {bool} chooseDirectories Allows directories to be opened - * @param {string} title The title of the window + * @param {boolean} allowMultipleSelection Allows selecting more than one file at a time + * @param {boolean} chooseDirectories Allows directories to be opened + * @param {string} title The title of the dialog * @param {string} initialPath The folder opened inside the window initially. If initialPath * is not set, or it doesn't exist, the window would show the last * browsed folder depending on the OS preferences * @param {Array.} fileTypes List of extensions that are allowed to be opened. A null value * allows any extension to be selected. - * @param {!function(Array.)} successCallback Callback function for successful operations. + * @param {function(Array.)} successCallback Callback function for successful operations. Receives an array with the selected paths as first parameter. - * @param {!function(DOMError)} errorCallback Callback function for error operations. + * @param {function(DOMError)=} errorCallback Callback function for error operations. */ showOpenDialog: function (allowMultipleSelection, chooseDirectories, @@ -147,10 +166,11 @@ define(function (require, exports, module) { /** * Implementation of w3 requestFileSystem entry point - * @param {!string} path Path of the file in the system - * @param {!function(DirectoryEntry)} successCallback Callback function for successful operations. + * @param {string} path Path to a directory. This directory will serve as the root of the + * FileSystem instance. + * @param {function(DirectoryEntry)} successCallback Callback function for successful operations. * Receives a DirectoryEntry pointing to the path - * @param {!function(DOMError)} errorCallback Callback function for errors, including permission errors. + * @param {function(DOMError)=} errorCallback Callback function for errors, including permission errors. */ requestNativeFileSystem: function (path, successCallback, errorCallback) { brackets.fs.stat(path, function (err, data) { @@ -165,9 +185,9 @@ define(function (require, exports, module) { /** * NativeFileSystem implementation of LocalFileSystem.resolveLocalFileSystemURL() * - * @param {!string} path A URL referring to a local file in a filesystem accessable via this API. - * @param {!function(Entry)} successCallback Callback function for successful operations. - * @param {!function(DOMError)=} errorCallback Callback function for error operations. + * @param {string} path A URL referring to a local file in a filesystem accessable via this API. + * @param {function(Entry)} successCallback Callback function for successful operations. + * @param {function(DOMError)=} errorCallback Callback function for error operations. */ resolveNativeFileSystemPath: function (path, successCallback, errorCallback) { brackets.fs.stat(path, function (err, stats) { @@ -189,7 +209,7 @@ define(function (require, exports, module) { /** * Converts a brackets.fs.ERR_* error code to a NativeFileError.* error name - * @param {!number} fsErr A brackets.fs error code + * @param {number} fsErr A brackets.fs error code * @return {string} An error name out of the possible NativeFileError.* names */ _fsErrorToDOMErrorName: function (fsErr) { @@ -252,7 +272,7 @@ define(function (require, exports, module) { * Converts an IANA encoding name to internal encoding name. * http://www.iana.org/assignments/character-sets * - * @param {String} encoding The IANA encoding string. + * @param {string} encoding The IANA encoding string. */ NativeFileSystem.Encodings._IANAToFS = function (encoding) { //IANA names are case-insensitive @@ -311,9 +331,9 @@ define(function (require, exports, module) { /** * Moves this Entry to a different location on the file system. * @param {!DirectoryEntry} parent The directory to move the entry to - * @param {!string=} newName The new name of the entry. If not specified, defaults to the current name - * @param {!function(Array.)=} successCallback Callback function for successful operations - * @param {!function(DOMError)=} errorCallback Callback function for error operations + * @param {string=} newName The new name of the entry. If not specified, defaults to the current name + * @param {function(Array.)=} successCallback Callback function for successful operations + * @param {function(DOMError)=} errorCallback Callback function for error operations */ NativeFileSystem.Entry.prototype.moveTo = function (parent, newName, successCallback, errorCallback) { // TODO (issue #241) @@ -323,9 +343,9 @@ define(function (require, exports, module) { /** * Copies this Entry to a different location on the file system. * @param {!DirectoryEntry} parent The directory to copy the entry to - * @param {!string=} newName The new name of the entry. If not specified, defaults to the current name - * @param {!function(Array.)=} successCallback Callback function for successful operations - * @param {!function(DOMError)=} errorCallback Callback function for error operations + * @param {string=} newName The new name of the entry. If not specified, defaults to the current name + * @param {function(Array.)=} successCallback Callback function for successful operations + * @param {function(DOMError)=} errorCallback Callback function for error operations */ NativeFileSystem.Entry.prototype.copyTo = function (parent, newName, successCallback, errorCallback) { // TODO (issue #241) @@ -334,7 +354,7 @@ define(function (require, exports, module) { /** * Generates a URL that can be used to identify this Entry - * @param {!string=} mimeType The mime type to be used to interpret the file for a FileEntry + * @param {string=} mimeType The mime type to be used to interpret the file for a FileEntry * @returns {string} A usable URL to identify this Entry in the current filesystem */ NativeFileSystem.Entry.prototype.toURL = function (mimeType) { @@ -347,8 +367,8 @@ define(function (require, exports, module) { /** * Deletes a file or directory - * @param {!function()} successCallback Callback function for successful operations - * @param {!function(DOMError)=} errorCallback Callback function for error operations + * @param {function()} successCallback Callback function for successful operations + * @param {function(DOMError)=} errorCallback Callback function for error operations */ NativeFileSystem.Entry.prototype.remove = function (successCallback, errorCallback) { // TODO (issue #241) @@ -357,8 +377,8 @@ define(function (require, exports, module) { /** * Look up the parent DirectoryEntry that contains this Entry - * @param {!function(Array.)} successCallback Callback function for successful operations - * @param {!function(DOMError)=} errorCallback Callback function for error operations + * @param {function(Array.)} successCallback Callback function for successful operations + * @param {function(DOMError)=} errorCallback Callback function for error operations */ NativeFileSystem.Entry.prototype.getParent = function (successCallback, errorCallback) { // TODO (issue #241) @@ -367,8 +387,8 @@ define(function (require, exports, module) { /** * Look up metadata about this Entry - * @param {!function(Metadata)} successCallback Callback function for successful operations - * @param {!function(DOMError)=} errorCallback Callback function for error operations + * @param {function(Metadata)} successCallback Callback function for successful operations + * @param {function(DOMError)=} errorCallback Callback function for error operations */ NativeFileSystem.Entry.prototype.getMetadata = function (successCallBack, errorCallback) { brackets.fs.stat(this.fullPath, function (err, stat) { @@ -402,7 +422,7 @@ define(function (require, exports, module) { * A FileEntry represents a file on a file system. * * @constructor - * @param {!string} name Full path of the file in the file system + * @param {string} name Full path of the file in the file system * @param {FileSystem} fs File system that contains this entry * @extends {Entry} */ @@ -419,8 +439,8 @@ define(function (require, exports, module) { /** * Creates a new FileWriter associated with the file that this FileEntry represents. - * @param {!function(FileWriter)} successCallback Callback function for successful operations - * @param {!function(DOMError)=} errorCallback Callback function for error operations + * @param {function(FileWriter)} successCallback Callback function for successful operations + * @param {function(DOMError)=} errorCallback Callback function for error operations */ NativeFileSystem.FileEntry.prototype.createWriter = function (successCallback, errorCallback) { var fileEntry = this; @@ -520,7 +540,7 @@ define(function (require, exports, module) { /** * Seek sets the file position at which the next write will occur - * @param {!number} offset An absolute byte offset into the file. If offset is greater than + * @param {number} offset An absolute byte offset into the file. If offset is greater than * length, length is used instead. If offset is less than zero, length * is added to it, so that it is treated as an offset back from the end * of the file. If it is still less than zero, zero is used @@ -532,7 +552,7 @@ define(function (require, exports, module) { /** * Changes the length of the file to that specified - * @param {!number} size The size to which the length of the file is to be adjusted, + * @param {number} size The size to which the length of the file is to be adjusted, * measured in bytes */ FileWriter.prototype.truncate = function (size) { @@ -568,8 +588,8 @@ define(function (require, exports, module) { /** * Returns a File that represents the current state of the file that this FileEntry represents - * @param {!function(File)} successCallback Callback function for successful operations - * @param {!function(DOMError)=} errorCallback Callback function for error operations + * @param {function(File)} successCallback Callback function for successful operations + * @param {function(DOMError)=} errorCallback Callback function for error operations */ NativeFileSystem.FileEntry.prototype.file = function (successCallback, errorCallback) { var newFile = new NativeFileSystem.File(this); @@ -584,7 +604,7 @@ define(function (require, exports, module) { * including all that occur during use of the synchronous filesystem methods, * are reported using the FileException exception. * - * @param {number} code The code attribute, on getting, must return one of the + * @param {?number=} code The code attribute, on getting, must return one of the * constants of the FileException exception, which must be the most appropriate * code from the table below. */ @@ -696,13 +716,13 @@ define(function (require, exports, module) { /** * Creates or looks up a directory - * @param {!string} path Either an absolute path or a relative path from this DirectoryEntry + * @param {string} path Either an absolute path or a relative path from this DirectoryEntry * to the directory to be looked up or created - * @param {{!{create:?boolean, exclusive:?boolean}}} options Object with the flags "create" + * @param {{create:?boolean, exclusive:?boolean}=} options Object with the flags "create" * and "exclusive" to modify the method behavior based on * http://www.w3.org/TR/2011/WD-file-system-api-20110419/#widl-DirectoryEntry-getDirectory - * @param {!function(Entry)} successCallback Callback function for successful operations - * @param {!function(DOMError)} errorCallback Callback function for error operations + * @param {function(Entry)=} successCallback Callback function for successful operations + * @param {function(DOMError)=} errorCallback Callback function for error operations */ NativeFileSystem.DirectoryEntry.prototype.getDirectory = function (path, options, successCallback, errorCallback) { var directoryFullPath = path, @@ -792,8 +812,8 @@ define(function (require, exports, module) { /** * Deletes a directory and all of its contents, if any - * @param {!function()} successCallback Callback function for successful operations - * @param {!function(DOMError)=} errorCallback Callback function for error operations + * @param {function()} successCallback Callback function for successful operations + * @param {function(DOMError)=} errorCallback Callback function for error operations */ NativeFileSystem.DirectoryEntry.prototype.removeRecursively = function (successCallback, errorCallback) { // TODO (issue #241) @@ -814,15 +834,15 @@ define(function (require, exports, module) { /** * Creates or looks up a file. * - * @param {!string} path Either an absolute path or a relative path from this + * @param {string} path Either an absolute path or a relative path from this * DirectoryEntry to the file to be looked up or created. It is an error * to attempt to create a file whose immediate parent does not yet * exist. - * @param {!{create:?boolean, exclusive:?boolean}=} options Object with the flags "create" + * @param {{create:?boolean, exclusive:?boolean}=} options Object with the flags "create" * and "exclusive" to modify the method behavior based on * http://www.w3.org/TR/2011/WD-file-system-api-20110419/#widl-DirectoryEntry-getFile - * @param {!function(FileEntry)=} successCallback Callback function for successful operations - * @param {!function(DOMError)=} errorCallback Callback function for error operations + * @param {function(FileEntry)=} successCallback Callback function for successful operations + * @param {function(DOMError)=} errorCallback Callback function for error operations */ NativeFileSystem.DirectoryEntry.prototype.getFile = function (path, options, successCallback, errorCallback) { var fileFullPath = path, @@ -923,8 +943,8 @@ define(function (require, exports, module) { /** * Read the next block of entries from this directory - * @param {!function(Array.)} successCallback Callback function for successful operations - * @param {!function(DOMError)=} errorCallback Callback function for error operations + * @param {function(Array.)} successCallback Callback function for successful operations + * @param {function(DOMError)=} errorCallback Callback function for error operations */ NativeFileSystem.DirectoryReader.prototype.readEntries = function (successCallback, errorCallback) { var rootPath = this._directory.fullPath, @@ -1077,7 +1097,7 @@ define(function (require, exports, module) { /** * Reads a Blob as text * @param {Blob} blob The data to read - * @param {string} encoding (IANA Encoding Name) + * @param {string=} encoding (IANA Encoding Name) */ NativeFileSystem.FileReader.prototype.readAsText = function (blob, encoding) { var self = this; @@ -1166,11 +1186,11 @@ define(function (require, exports, module) { /** * Returns a new Blob object with bytes ranging from the optional start parameter * up to but not including the optional end parameter - * @param {!number=} start Start point of a slice treated as a byte-order position - * @param {!number=} end End point of a slice. If end is undefined, size will be used. If + * @param {number=} start Start point of a slice treated as a byte-order position + * @param {number=} end End point of a slice. If end is undefined, size will be used. If * end is negative, max(size+end, 0) will be used. In any other case, * the slice will finish at min(end, size) - * @param {!string=} contentType HTTP/1.1 Content-Type header on the Blob + * @param {string=} contentType HTTP/1.1 Content-Type header on the Blob * @returns {Blob} */ NativeFileSystem.Blob.prototype.slice = function (start, end, contentType) {