Merge remote-tracking branch 'origin/master'

[rbdr/dotfiles] / atom / packages / ex-mode / node_modules / fs-plus / README.md

# fs plus [![Build Status](https://travis-ci.org/atom/fs-plus.svg?branch=master)](https://travis-ci.org/atom/fs-plus)

Yet another filesystem helper based on node's [fs](http://nodejs.org/api/fs.html)
module.  This library exports everything from node's fs module but with some
extra helpers.

## Using

```sh
npm install fs-plus
```

```coffee
fs = require 'fs-plus'
```

## Documentation

### `getHomeDirectory()`
Returns the absolute path to the home directory.

### `absolute(relativePath)`
Make the given path absolute by resolving it against the current
working directory.

### Params

 - **String** `relativePath`: The string representing the relative path. If the
   path is prefixed with '~', it will be expanded to the current user's home
   directory.

### Return

 - **String**: The absolute path or the relative path if it's unable to
   determine its real path.

### `normalize(pathToNormalize)`
Normalize the given path treating a leading `~` segment as referring to the
home directory. This method does not query the filesystem.

#### Params

 - **String** `pathToNormalize`: The string containing the abnormal path. If the
   path is prefixed with '~', it will be expanded to the current user's home
   directory.

#### Return
 - **String** Returns a normalized path.

### `getAppDataDirectory()`
Get path to store application specific data.

#### Return
 - **String** Returns the absolute path or null if platform isn't supported

    - Mac: `~/Library/Application Support/`
    - Win: `%AppData%`
    - Linux: `/var/lib`

### `isAbsolute(pathToCheck)`
Is the given path absolute?

#### Params
 - **String** `pathToCheck`: The relative or absolute path to check.

#### Return
 - **Bolean** Returns `true` if the path is absolute, `false` otherwise.

### `existsSync(pathToCheck)`
Returns `true` if a file or folder at the specified path exists.

### `isDirectorySync(directoryPath)`
Returns `true` if the given path exists and is a directory.

### `isDirectory(directoryPath)`
Asynchronously checks that the given path exists and is a directory.

### `isFileSync(filePath)`
Returns true if the specified path exists and is a file.

### `isSymbolicLinkSync(symlinkPath)`
Returns `true` if the specified path is a symbolic link.

### `isSymbolicLink(symlinkPath, callback)`
Calls back with `true` if the specified path is a symbolic link.

### `isExecutableSync(pathToCheck)`
Returns `true` if the specified path is executable.

### `getSizeSync(pathToCheck)`
Returns the size of the specified path.

### `listSync(rootPath, extensions)`
Returns an Array with the paths of the files and directories
contained within the directory path. It is not recursive.

## Params
 - **String** `rootPath`: The absolute path to the directory to list.
 - **Array** `extensions`: An array of extensions to filter the results by. If none are
   given, none are filtered (optional).

### `list(rootPath, extensions)`
Asynchronously lists the files and directories in the given path. The listing is not recursive.

### `listTreeSync(rootPath)`
Get all paths under the given path.

#### Params
 - **String** `rootPath` The {String} path to start at.

#### Return
 - **Array** Returns an array of strings under the given path.

### `moveSync(source, target)`
Moves the file or directory to the target synchronously.

### `removeSync(pathToRemove)`
Removes the file or directory at the given path synchronously.

### `writeFileSync(filePath, content, options)`
Open, write, flush, and close a file, writing the given content synchronously.
It also creates the necessary parent directories.

### `writeFile(filePath, content, options, callback)`
Open, write, flush, and close a file, writing the given content
asynchronously.
It also creates the necessary parent directories.

### `copySync(sourcePath, destinationPath)`
Copies the given path recursively and synchronously.

### `makeTreeSync(directoryPath)`
Create a directory at the specified path including any missing
parent directories synchronously.

### `makeTree(directoryPath, callback)`
Create a directory at the specified path including any missing
parent directories asynchronously.

### `traverseTreeSync(rootPath, onFile, onDirectory)`
Recursively walk the given path and execute the given functions
synchronously.

#### Params
 - **String** `rootPath`: The string containing the directory to recurse into.
 - **Function** `onFile`: The function to execute on each file, receives a single argument
   the absolute path.
 - **Function** `onDirectory`: The function to execute on each directory, receives a single
   argument the absolute path (defaults to onFile). If this
   function returns a falsy value then the directory is not
   entered.

### `traverseTree(rootPath, onFile, onDirectory, onDone)`
Public: Recursively walk the given path and execute the given functions
asynchronously.

### `md5ForPath(pathToDigest)`
Hashes the contents of the given file.

#### Params
 - **String** `pathToDigest`: The string containing the absolute path.

#### Return
 - **String** Returns a string containing the MD5 hexadecimal hash.

### `resolve(loadPaths, pathToResolve, extensions)`
Finds a relative path among the given array of paths.

#### Params
 - **Array** `loadPaths`: An array of absolute and relative paths to search.
 - **String** `pathToResolve` The string containing the path to resolve.
 - **Array** `extensions` An array of extensions to pass to {resolveExtensions} in
   which case pathToResolve should not contain an extension
   (optional).

#### Return
Returns the absolute path of the file to be resolved if it's found and
undefined otherwise.

### `resolveOnLoadPath()`
Like `.resolve` but uses node's modules paths as the load paths to
search.

### `resolveExtension(pathToResolve, extensions)`
Finds the first file in the given path which matches the extension
in the order given.

#### Params
 - **String** `pathToResolve`: the string containing relative or absolute path of the
   file in question without the extension or '.'.
 - **Array** `extensions`: the ordered array of extensions to try.

#### Return
Returns the absolute path of the file if it exists with any of the given
extensions, otherwise it's undefined.

### `isCompressedExtension(ext)`
Returns true for extensions associated with compressed files.

### `isImageExtension(ext)`
Returns true for extensions associated with image files.

### `isPdfExtension(ext)`
Returns true for extensions associated with pdf files.

### `isBinaryExtension(ext)`
Returns true for extensions associated with binary files.

### `isReadmePath(readmePath)`
Returns true for files named similarily to 'README'

### `isMarkdownExtension(ext)`
Returns true for extensions associated with Markdown files.

### `isCaseInsensitive()`
Is the filesystem case insensitive?
Returns `true` if case insensitive, `false` otherwise.

### `isCaseSensitive()`
Is the filesystem case sensitive?
Returns `true` if case sensitive, `false` otherwise.