FileSystem is a model object representing a complete file system. This object creates and manages File and Directory instances, dispatches events when the file system changes, and provides methods for showing 'open' and 'save' dialogs.
FileSystem automatically initializes when loaded. It depends on a pluggable "impl" layer, which it loads itself but must be designated in the require.config() that loads FileSystem.
There are three ways to get File or Directory instances:
All paths passed to FileSystem APIs must be in the following format:
All paths returned from FileSystem APIs additionally meet the following guarantees:
FileSystem dispatches the following events: change - Sent whenever there is a change in the file system. The handler is passed up to three arguments: the changed entry and, if that changed entry is a Directory, a list of entries added to the directory and a list of entries removed from the Directory. The entry argument can be:
* a File - the contents of the file have changed, and should be reloaded.
* a Directory - an immediate child of the directory has been added, removed,
or renamed/moved. Not triggered for "grandchildren".
- If the added & removed arguments are null, we don't know what was added/removed:
clients should assume the whole subtree may have changed.
- If the added & removed arguments are 0-length, there's no net change in the set
of files but a file may have been replaced: clients should assume the contents
of any immediate child file may have changed.
* null - a 'wholesale' change happened, and you should assume everything may
have changed.
For changes made externally, there may be a significant delay before a "change" event
is dispatched.
rename - Sent whenever a File or Directory is renamed. All affected File and Directory objects have been updated to reflect the new path by the time this event is dispatched. This event should be used to trigger any UI updates that may need to occur when a path has changed. Note that these events will only be sent for rename operations that happen within the filesystem. If a file is renamed externally, a change event on the parent directory will be sent instead.
FileSystem may perform caching. But it guarantees:
The FileSystem doesn't directly read or write contents--this work is done by a low-level implementation object. This allows client code to use the FileSystem API without having to worry about the underlying storage, which could be a local filesystem or a remote server.
Refcount of any pending filesystem mutation operations (e.g., writes, unlinks, etc.). Used to ensure that external change events aren't processed until after index fixups, operation-specific callbacks, and internal change events are complete. (This is important for distinguishing rename from an unrelated delete-add pair).
Queue of arguments with which to invoke _handleExternalChanges(); triggered once _activeChangeCount drops to zero.
Indicates that a filesystem-mutating operation has begun. As long as there are changes taking place, change events from the external watchers are blocked and queued, to be handled once changes have finished. This is done because for mutating operations that originate from within the filesystem, synthetic change events are fired that do not depend on external file watchers, and we prefer the former over the latter for the following reasons: 1) there is no delay; and 2) they may have higher fidelity --- e.g., a rename operation can be detected as such, instead of as a nearly simultaneous addition and deletion.
All operations that mutate the file system MUST begin with a call to _beginChange and must end with a call to _endChange.
Indicates that a filesystem-mutating operation has completed. See FileSystem._beginChange above.
Receives a result from the impl's watcher callback, and either processes it immediately (if _activeChangeCount is 0) or otherwise stores it for later processing.
Enqueue a new watch/unwatch request.
Finds a parent watched root for a given path, or returns null if a parent watched root does not exist.
Fire a change event. Clients listen for these events using FileSystem.on.
Fire a rename event. Clients listen for these events using FileSystem.on.
Return a (strict subclass of a) FileSystemEntry object for the specified path using the provided constuctor. For now, the provided constructor should be either File or Directory.
Notify the filesystem that the given directory has changed. Updates the filesystem's internal state as a result of the change, and calls back with the set of added and removed entries. Mutating FileSystemEntry operations should call this method before applying the operation's callback, and pass along the resulting change sets in the internal change event.
Returns true if the given path should be automatically added to the index & watch list when one of its ancestors is a watch-root. (Files are added automatically when the watch-root is first established, or later when a new directory is created and its children enumerated).
Entries explicitly created via FileSystem.getFile/DirectoryForPath() are always added to the index regardless of this filtering - but they will not be watched if the watch-root's filter excludes them.
Returns a canonical version of the path: no duplicated "/"es, no ".."s, and directories guaranteed to end in a trailing "/"
Process all queued watcher results, by calling _handleExternalChange() on each
Unwatch all watched roots. Calls unwatch on the underlying impl for each watched root and ignores errors.
Unwatch a filesystem entry beneath a given watchedRoot.
Watch a filesystem entry beneath a given watchedRoot.
Helper function to watch or unwatch a filesystem entry beneath a given watchedRoot.
Return a Directory object for the specified path.
Return a File object for the specified path.
Initialize this FileSystem instance.
Determines whether or not the supplied path is absolute, as opposed to relative.
Resolve a path.
Show an "Open" dialog and return the file(s)/directories selected by the user.
Show a "Save" dialog and return the path of the file to save.
Stop watching a filesystem root entry.
Start watching a filesystem root entry.