File System API Migration

Here are the API changes that will result from the [File System Evolution](File System) plan:

Old API	New API	Suggested action	Usage
FileUtils.readAsText(fileEntry)	FileUtils.readAsText(file)	Already drop-in compatible	13
FileUtils.writeText(fileEntry)	FileUtils.writeText(file)	Already drop-in compatible	5
FileIndexManager.getFileInfoList("all") FileIndexManager.getFileInfoList("...")	filesystem.getFileList() filesystem.getFileList(filter) _Note: returns an array of actual Files, but they provide the same properties as the old FileInfos)_	Shim with deprecation warning	7
FileIndexManager.getFilenameMatches("...", filename)	filesystem.getFileList(filter)	Shim with deprecation warning	None
ProjectManager.shouldShow(entry)	filesystem.shouldShow(fullPath)	Leave old API in place permanently	None?
ProjectManager.isBinaryFile(name/fullPath)	(unchanged)	(unchanged) But eventually, should move to LanguageManager.	None
new NativeFileSystem.FileEntry(fullPath) new NativeFileSystem.DirectoryEntry(fullPath)	filesystem.getFileForPath(fullPath) filesystem.getDirectoryForPath(fullPath)	Shim with deprecation warning	19
DirectoryEntry.getFile(relpath)	filesystem.resolve(dirFullPath + relpath)	TODO: Consider offering same/similar API on Directory	4
NativeFileSystem.resolveNativeFileSystemPath(fullPath)	filesystem.resolve(path)	Shim with deprecation warning	4
NativeFileSystem.requestNativeFileSystem(fullPath)... fs.root	filesystem.resolve(fullPath)	Shim with deprecation warning	6
entry.fullPath, entry.isFile, entry.isDirectory	(unchanged)	Properties are now immutable	fullPath: many isFile/Directory: 9
Concatenation: folderPath + "/" + filename	(unchanged)	Paths are normalized on ingest, eliminating doubled "/"es
Concatenation: folderPath + filename	(unchanged)	Directory.fullPath will always end in "/", so this remains safe	Unclear, but at least several
Substrings: relpath = fullPath.slice(dirFullPath.length)	(unchanged)	Directory.fullPath will always end in "/", so this remains safe
NativeFileSystem.isRelativePath()	???	???	None
NativeFileSystem.showOpenDialog() NativeFileSystem.showSaveDialog()	filesystem.showOpenDialog() filesystem.showSaveDialog()	Shim with deprecation warning	4
fileEntry.getMetadata()	file.stat() _TODO: document change in data structure too_	Do not shim (callers will break right away)	1
fileEntry.createWriter()... writer.write(text)	file.write(text)	Do not shim (callers will break right away)	5, but only used in 2
fileEntry.file()... new NativeFileSystem.FileReader().readAsText(fileObj)	file.readAsText()	Do not shim (callers will break right away)	None
directoryEntry.createReader().readEntries()	directory.getContents() ???	Do not shim (callers will break right away)	5
DirectoryEntry.getFile(relpath, {create:true})	filesystem.getFileForPath(fullPath).write("") Note: as a result, this can fold in writeText() or createWriter()/write() calls that used to immediately follow the getFile() call.	Do not shim (callers will break right away) TODO: add a cleaner create() API?	2
DirectoryEntry.getDirectory(relpath, {create:true})	filesystem.getDirectoryForPath(fullPath).create()	Do not shim (callers will break right away)	2
instanceof NativeFileSystem.InaccessibleFileEntry	instanceof InMemoryFile	Do not shim (callers will break right away)	1
entry.remove()	entry.moveToTrash()	Do not shim (callers will break right away)	None
NativeFileError.*	???	Do not shim (callers will break right away)	1
entry.filesystem (not a very useful API)	n/a	Do not shim (callers will break right away)	None
NativeFileSystem.Encodings.*	???	Do not shim (callers will break right away)	None
"projectFilesChange" event (sent from ProjectManager)	"change" event (sent from FileSystem)	Do not shim	2
brackets.fs.readFile() brackets.fs.writeFile()	file.readAsText() file.write(text)	Low-level API continues to exist	2
brackets.fs.stat()	file.stat()	Low-level API continues to exist	1
brackets.fs.readdir()	directory.getContents() ???	Low-level API continues to exist	1
brackets.fs.makedir(fullPath, mode)	filesystem.getDirectoryForPath(fullPath).create()	Low-level API continues to exist	1
brackets.fs.unlink(fullPath)	entry.unlink()	Low-level API continues to exist	None
brackets.fs.rename(oldFullPath, newFullPath)	entry.rename(newFullPath) (NOTE: Exact semantics of this call are still a bit TBD).	Low-level API continues to exist	None
brackets.fs.moveToTrash()	entry.moveToTrash()	Low-level API continues to exist	None
brackets.fs.copyFile()	???	Low-level API continues to exist	1
brackets.fs.isNetworkDrive()	???	Low-level API continues to exist TODO: will it be unused now though?	None
brackets.fs.chmod()	???	Low-level API continues to exist	None
brackets.fs.showOpenDialog() brackets.fs.showSaveDialog()	filesystem.showOpenDialog() filesystem.showSaveDialog()	Low-level API continues to exist	None
new NativeFileSystem.InaccessibleFileEntry(fakePath)	filesystem.getInMemoryFile(fakePath)	Low-level API continues to exist	None
brackets.fs.ERR_* brackets.fs.PATH_EXISTS_ERR brackets.fs.NO_ERROR	???	Low-level API continues to exist	1

"Usage" = how many extensions currently use the API

Extensions that will break

The following 12 extensions use at least one API on the "Do not shim" list:

• themes -- (DirectoryEntry.createReader())
• themesforbrackets -- (DirectoryEntry.createReader())
• interactive-linter -- (DirectoryEntry.getFile(), DirectoryEntry.createReader(), FileEntry.createWriter(), NativeFile Error (only minor bug))
• angularui.angularjs -- (FileEntry.getMetadata())
• timburgess.pagesuck -- (DirectoryEntry.getFile())
• ternific -- (DirectoryEntry.getFile(), DirectoryEntry.createReader(), FileEntry.createWriter())
• tomcat-manager -- (DirectoryEntry.getFile(), FileEntry.createWriter())
• simple-js-code-hints -- (DirectoryEntry.createReader())
• bsirlinger.github-access -- (DirectoryEntry.getFile({create}), DirectoryEntry.getDirectory({create}), FileEntry.createWriter())
• xunit -- (DirectoryEntry.getFile({create}), DirectoryEntry.getDirectory({create})
• workspaces -- (FileEntry.createWriter())
• pflynn.brackets.editor.nav -- (won't crash, only minor bug) (InaccessibleFileEntry)

We will file bugs with all extensions that are using removed APIs to make sure authors are aware of the change.