]> git.r.bdr.sh - rbdr/dotfiles/blame - atom/packages/ex-mode/node_modules/fs-plus/README.md
Update prezto
[rbdr/dotfiles] / atom / packages / ex-mode / node_modules / fs-plus / README.md
CommitLineData
24c7594d
BB
1# fs plus [![Build Status](https://travis-ci.org/atom/fs-plus.svg?branch=master)](https://travis-ci.org/atom/fs-plus)
2
3Yet another filesystem helper based on node's [fs](http://nodejs.org/api/fs.html)
4module. This library exports everything from node's fs module but with some
5extra helpers.
6
7## Using
8
9```sh
10npm install fs-plus
11```
12
13```coffee
14fs = require 'fs-plus'
15```
16
17## Documentation
18
19### `getHomeDirectory()`
20Returns the absolute path to the home directory.
21
22### `absolute(relativePath)`
23Make the given path absolute by resolving it against the current
24working directory.
25
26### Params
27
28 - **String** `relativePath`: The string representing the relative path. If the
29 path is prefixed with '~', it will be expanded to the current user's home
30 directory.
31
32### Return
33
34 - **String**: The absolute path or the relative path if it's unable to
35 determine its real path.
36
37### `normalize(pathToNormalize)`
38Normalize the given path treating a leading `~` segment as referring to the
39home directory. This method does not query the filesystem.
40
41#### Params
42
43 - **String** `pathToNormalize`: The string containing the abnormal path. If the
44 path is prefixed with '~', it will be expanded to the current user's home
45 directory.
46
47#### Return
48 - **String** Returns a normalized path.
49
50### `getAppDataDirectory()`
51Get path to store application specific data.
52
53#### Return
54 - **String** Returns the absolute path or null if platform isn't supported
55
56 - Mac: `~/Library/Application Support/`
57 - Win: `%AppData%`
58 - Linux: `/var/lib`
59
60### `isAbsolute(pathToCheck)`
61Is the given path absolute?
62
63#### Params
64 - **String** `pathToCheck`: The relative or absolute path to check.
65
66#### Return
67 - **Bolean** Returns `true` if the path is absolute, `false` otherwise.
68
69### `existsSync(pathToCheck)`
70Returns `true` if a file or folder at the specified path exists.
71
72### `isDirectorySync(directoryPath)`
73Returns `true` if the given path exists and is a directory.
74
75### `isDirectory(directoryPath)`
76Asynchronously checks that the given path exists and is a directory.
77
78### `isFileSync(filePath)`
79Returns true if the specified path exists and is a file.
80
81### `isSymbolicLinkSync(symlinkPath)`
82Returns `true` if the specified path is a symbolic link.
83
84### `isSymbolicLink(symlinkPath, callback)`
85Calls back with `true` if the specified path is a symbolic link.
86
87### `isExecutableSync(pathToCheck)`
88Returns `true` if the specified path is executable.
89
90### `getSizeSync(pathToCheck)`
91Returns the size of the specified path.
92
93### `listSync(rootPath, extensions)`
94Returns an Array with the paths of the files and directories
95contained within the directory path. It is not recursive.
96
97## Params
98 - **String** `rootPath`: The absolute path to the directory to list.
99 - **Array** `extensions`: An array of extensions to filter the results by. If none are
100 given, none are filtered (optional).
101
102### `list(rootPath, extensions)`
103Asynchronously lists the files and directories in the given path. The listing is not recursive.
104
105### `listTreeSync(rootPath)`
106Get all paths under the given path.
107
108#### Params
109 - **String** `rootPath` The {String} path to start at.
110
111#### Return
112 - **Array** Returns an array of strings under the given path.
113
114### `moveSync(source, target)`
115Moves the file or directory to the target synchronously.
116
117### `removeSync(pathToRemove)`
118Removes the file or directory at the given path synchronously.
119
120### `writeFileSync(filePath, content, options)`
121Open, write, flush, and close a file, writing the given content synchronously.
122It also creates the necessary parent directories.
123
124### `writeFile(filePath, content, options, callback)`
125Open, write, flush, and close a file, writing the given content
126asynchronously.
127It also creates the necessary parent directories.
128
129### `copySync(sourcePath, destinationPath)`
130Copies the given path recursively and synchronously.
131
132### `makeTreeSync(directoryPath)`
133Create a directory at the specified path including any missing
134parent directories synchronously.
135
136### `makeTree(directoryPath, callback)`
137Create a directory at the specified path including any missing
138parent directories asynchronously.
139
140### `traverseTreeSync(rootPath, onFile, onDirectory)`
141Recursively walk the given path and execute the given functions
142synchronously.
143
144#### Params
145 - **String** `rootPath`: The string containing the directory to recurse into.
146 - **Function** `onFile`: The function to execute on each file, receives a single argument
147 the absolute path.
148 - **Function** `onDirectory`: The function to execute on each directory, receives a single
149 argument the absolute path (defaults to onFile). If this
150 function returns a falsy value then the directory is not
151 entered.
152
153### `traverseTree(rootPath, onFile, onDirectory, onDone)`
154Public: Recursively walk the given path and execute the given functions
155asynchronously.
156
157### `md5ForPath(pathToDigest)`
158Hashes the contents of the given file.
159
160#### Params
161 - **String** `pathToDigest`: The string containing the absolute path.
162
163#### Return
164 - **String** Returns a string containing the MD5 hexadecimal hash.
165
166### `resolve(loadPaths, pathToResolve, extensions)`
167Finds a relative path among the given array of paths.
168
169#### Params
170 - **Array** `loadPaths`: An array of absolute and relative paths to search.
171 - **String** `pathToResolve` The string containing the path to resolve.
172 - **Array** `extensions` An array of extensions to pass to {resolveExtensions} in
173 which case pathToResolve should not contain an extension
174 (optional).
175
176#### Return
177Returns the absolute path of the file to be resolved if it's found and
178undefined otherwise.
179
180### `resolveOnLoadPath()`
181Like `.resolve` but uses node's modules paths as the load paths to
182search.
183
184### `resolveExtension(pathToResolve, extensions)`
185Finds the first file in the given path which matches the extension
186in the order given.
187
188#### Params
189 - **String** `pathToResolve`: the string containing relative or absolute path of the
190 file in question without the extension or '.'.
191 - **Array** `extensions`: the ordered array of extensions to try.
192
193#### Return
194Returns the absolute path of the file if it exists with any of the given
195extensions, otherwise it's undefined.
196
197### `isCompressedExtension(ext)`
198Returns true for extensions associated with compressed files.
199
200### `isImageExtension(ext)`
201Returns true for extensions associated with image files.
202
203### `isPdfExtension(ext)`
204Returns true for extensions associated with pdf files.
205
206### `isBinaryExtension(ext)`
207Returns true for extensions associated with binary files.
208
209### `isReadmePath(readmePath)`
210Returns true for files named similarily to 'README'
211
212### `isMarkdownExtension(ext)`
213Returns true for extensions associated with Markdown files.
214
215### `isCaseInsensitive()`
216Is the filesystem case insensitive?
217Returns `true` if case insensitive, `false` otherwise.
218
219### `isCaseSensitive()`
220Is the filesystem case sensitive?
221Returns `true` if case sensitive, `false` otherwise.