]> git.r.bdr.sh - rbdr/dotfiles/blob - atom/packages/ex-mode/node_modules/fs-plus/README.md
Update prezto
[rbdr/dotfiles] / atom / packages / ex-mode / node_modules / fs-plus / README.md
1 # fs plus [![Build Status](https://travis-ci.org/atom/fs-plus.svg?branch=master)](https://travis-ci.org/atom/fs-plus)
2
3 Yet another filesystem helper based on node's [fs](http://nodejs.org/api/fs.html)
4 module. This library exports everything from node's fs module but with some
5 extra helpers.
6
7 ## Using
8
9 ```sh
10 npm install fs-plus
11 ```
12
13 ```coffee
14 fs = require 'fs-plus'
15 ```
16
17 ## Documentation
18
19 ### `getHomeDirectory()`
20 Returns the absolute path to the home directory.
21
22 ### `absolute(relativePath)`
23 Make the given path absolute by resolving it against the current
24 working 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)`
38 Normalize the given path treating a leading `~` segment as referring to the
39 home 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()`
51 Get 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)`
61 Is 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)`
70 Returns `true` if a file or folder at the specified path exists.
71
72 ### `isDirectorySync(directoryPath)`
73 Returns `true` if the given path exists and is a directory.
74
75 ### `isDirectory(directoryPath)`
76 Asynchronously checks that the given path exists and is a directory.
77
78 ### `isFileSync(filePath)`
79 Returns true if the specified path exists and is a file.
80
81 ### `isSymbolicLinkSync(symlinkPath)`
82 Returns `true` if the specified path is a symbolic link.
83
84 ### `isSymbolicLink(symlinkPath, callback)`
85 Calls back with `true` if the specified path is a symbolic link.
86
87 ### `isExecutableSync(pathToCheck)`
88 Returns `true` if the specified path is executable.
89
90 ### `getSizeSync(pathToCheck)`
91 Returns the size of the specified path.
92
93 ### `listSync(rootPath, extensions)`
94 Returns an Array with the paths of the files and directories
95 contained 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)`
103 Asynchronously lists the files and directories in the given path. The listing is not recursive.
104
105 ### `listTreeSync(rootPath)`
106 Get 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)`
115 Moves the file or directory to the target synchronously.
116
117 ### `removeSync(pathToRemove)`
118 Removes the file or directory at the given path synchronously.
119
120 ### `writeFileSync(filePath, content, options)`
121 Open, write, flush, and close a file, writing the given content synchronously.
122 It also creates the necessary parent directories.
123
124 ### `writeFile(filePath, content, options, callback)`
125 Open, write, flush, and close a file, writing the given content
126 asynchronously.
127 It also creates the necessary parent directories.
128
129 ### `copySync(sourcePath, destinationPath)`
130 Copies the given path recursively and synchronously.
131
132 ### `makeTreeSync(directoryPath)`
133 Create a directory at the specified path including any missing
134 parent directories synchronously.
135
136 ### `makeTree(directoryPath, callback)`
137 Create a directory at the specified path including any missing
138 parent directories asynchronously.
139
140 ### `traverseTreeSync(rootPath, onFile, onDirectory)`
141 Recursively walk the given path and execute the given functions
142 synchronously.
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)`
154 Public: Recursively walk the given path and execute the given functions
155 asynchronously.
156
157 ### `md5ForPath(pathToDigest)`
158 Hashes 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)`
167 Finds 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
177 Returns the absolute path of the file to be resolved if it's found and
178 undefined otherwise.
179
180 ### `resolveOnLoadPath()`
181 Like `.resolve` but uses node's modules paths as the load paths to
182 search.
183
184 ### `resolveExtension(pathToResolve, extensions)`
185 Finds the first file in the given path which matches the extension
186 in 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
194 Returns the absolute path of the file if it exists with any of the given
195 extensions, otherwise it's undefined.
196
197 ### `isCompressedExtension(ext)`
198 Returns true for extensions associated with compressed files.
199
200 ### `isImageExtension(ext)`
201 Returns true for extensions associated with image files.
202
203 ### `isPdfExtension(ext)`
204 Returns true for extensions associated with pdf files.
205
206 ### `isBinaryExtension(ext)`
207 Returns true for extensions associated with binary files.
208
209 ### `isReadmePath(readmePath)`
210 Returns true for files named similarily to 'README'
211
212 ### `isMarkdownExtension(ext)`
213 Returns true for extensions associated with Markdown files.
214
215 ### `isCaseInsensitive()`
216 Is the filesystem case insensitive?
217 Returns `true` if case insensitive, `false` otherwise.
218
219 ### `isCaseSensitive()`
220 Is the filesystem case sensitive?
221 Returns `true` if case sensitive, `false` otherwise.