git.r.bdr.sh - rbdr/dotfiles/blob - 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.