From 383a26985cab5b8a184cea9fa776d2fa6da8a5fe Mon Sep 17 00:00:00 2001 From: RyanZim Date: Mon, 2 Jan 2017 09:36:00 -0500 Subject: [PATCH] Move API docs to seperate docs/ folder Merge mkdirs() docs with ensureDir() docs Resolves #298 --- README.md | 356 +++--------------------------------------- docs/copy.md | 28 ++++ docs/emptyDir.md | 18 +++ docs/ensureDir.md | 20 +++ docs/ensureFile.md | 20 +++ docs/ensureLink.md | 19 +++ docs/ensureSymlink.md | 19 +++ docs/move.md | 17 ++ docs/outputFile.md | 21 +++ docs/outputJson.md | 24 +++ docs/readJson.md | 33 ++++ docs/remove.md | 20 +++ docs/writeJson.md | 21 +++ 13 files changed, 285 insertions(+), 331 deletions(-) create mode 100644 docs/copy.md create mode 100644 docs/emptyDir.md create mode 100644 docs/ensureDir.md create mode 100644 docs/ensureFile.md create mode 100644 docs/ensureLink.md create mode 100644 docs/ensureSymlink.md create mode 100644 docs/move.md create mode 100644 docs/outputFile.md create mode 100644 docs/outputJson.md create mode 100644 docs/readJson.md create mode 100644 docs/remove.md create mode 100644 docs/writeJson.md diff --git a/README.md b/README.md index 55f1db41..b725add9 100644 --- a/README.md +++ b/README.md @@ -85,342 +85,36 @@ try { Methods ------- -- [copy](#copy) -- [copySync](#copy) -- [emptyDir](#emptydirdir-callback) -- [emptyDirSync](#emptydirdir-callback) -- [ensureFile](#ensurefilefile-callback) -- [ensureFileSync](#ensurefilefile-callback) -- [ensureDir](#ensuredirdir-callback) -- [ensureDirSync](#ensuredirdir-callback) -- [ensureLink](#ensurelinksrcpath-dstpath-callback) -- [ensureLinkSync](#ensurelinksrcpath-dstpath-callback) -- [ensureSymlink](#ensuresymlinksrcpath-dstpath-type-callback) -- [ensureSymlinkSync](#ensuresymlinksrcpath-dstpath-type-callback) -- [mkdirs](#mkdirsdir-callback) -- [mkdirsSync](#mkdirsdir-callback) -- [move](#movesrc-dest-options-callback) -- [outputFile](#outputfilefile-data-options-callback) -- [outputFileSync](#outputfilefile-data-options-callback) -- [outputJson](#outputjsonfile-data-options-callback) -- [outputJsonSync](#outputjsonfile-data-options-callback) -- [readJson](#readjsonfile-options-callback) -- [readJsonSync](#readjsonfile-options-callback) -- [remove](#removedir-callback) -- [removeSync](#removedir-callback) -- [walk](#walk) -- [walkSync](#walksyncdir) -- [writeJson](#writejsonfile-object-options-callback) -- [writeJsonSync](#writejsonfile-object-options-callback) +- [copy](docs/copy.md) +- [copySync](docs/copy.md) +- [emptyDir](docs/emptyDir.md) +- [emptyDirSync](docs/emptyDir.md) +- [ensureFile](docs/ensureFile.md) +- [ensureFileSync](docs/ensureFile.md) +- [ensureDir](docs/ensureDir.md) +- [ensureDirSync](docs/ensureDir.md) +- [ensureLink](docs/ensureLink.md) +- [ensureLinkSync](docs/ensureLink.md) +- [ensureSymlink](docs/ensureSymlink.md) +- [ensureSymlinkSync](docs/ensureSymlink.md) +- [mkdirs](docs/ensureDir.md) +- [mkdirsSync](docs/ensureDir.md) +- [move](docs/move.md) +- [outputFile](docs/outputFile.md) +- [outputFileSync](docs/outputFile.md) +- [outputJson](docs/outputJson.md) +- [outputJsonSync](docs/outputJson.md) +- [readJson](docs/readJson.md) +- [readJsonSync](docs/readJson.md) +- [remove](docs/remove.md) +- [removeSync](docs/remove.md) +- [writeJson](docs/writeJson.md) +- [writeJsonSync](docs/writeJson.md) **NOTE:** You can still use the native Node.js methods. They are copied over to `fs-extra`. -### copy() - -**copy(src, dest, [options], callback)** - - -Copy a file or directory. The directory can have contents. Like `cp -r`. - -Options: -- overwrite (boolean): overwrite existing file or directory, default is `true`. _Note that the copy operation will silently fail if you set this to `false` and the destination exists._ Use the `errorOnExist` option to change this behavior. -- errorOnExist (boolean): when `overwrite` is `false` and the destination exists, throw an error. Default is `false`. -- dereference (boolean): dereference symlinks, default is `false`. -- preserveTimestamps (boolean): will set last modification and access times to the ones of the original source files, default is `false`. -- filter: Function to filter copied files. Return `true` to include, `false` to exclude. This can also be a RegExp, however this is deprecated (See [issue #239](https://github.com/jprichardson/node-fs-extra/issues/239) for background). _Warning: `copySync` currently applies the filter only to files (see [#180](https://github.com/jprichardson/node-fs-extra/issues/180)). This will be fixed in a future release._ - -Sync: `copySync()` - -Example: - -```js -var fs = require('fs-extra') - -fs.copy('/tmp/myfile', '/tmp/mynewfile', function (err) { - if (err) return console.error(err) - console.log("success!") -}) // copies file - -fs.copy('/tmp/mydir', '/tmp/mynewdir', function (err) { - if (err) return console.error(err) - console.log('success!') -}) // copies directory, even if it has subdirectories or files -``` - - -### emptyDir(dir, [callback]) - -Ensures that a directory is empty. Deletes directory contents if the directory is not empty. If the directory does not exist, it is created. The directory itself is not deleted. - -Alias: `emptydir()` - -Sync: `emptyDirSync()`, `emptydirSync()` - -Example: - -```js -var fs = require('fs-extra') - -// assume this directory has a lot of files and folders -fs.emptyDir('/tmp/some/dir', function (err) { - if (!err) console.log('success!') -}) -``` - - -### ensureFile(file, callback) - -Ensures that the file exists. If the file that is requested to be created is in directories that do not exist, these directories are created. If the file already exists, it is **NOT MODIFIED**. - -Alias: `createFile()` - -Sync: `createFileSync()`,`ensureFileSync()` - - -Example: - -```js -var fs = require('fs-extra') - -var file = '/tmp/this/path/does/not/exist/file.txt' -fs.ensureFile(file, function (err) { - console.log(err) // => null - // file has now been created, including the directory it is to be placed in -}) -``` - - -### ensureDir(dir, callback) - -Ensures that the directory exists. If the directory structure does not exist, it is created. - -Sync: `ensureDirSync()` - - -Example: - -```js -var fs = require('fs-extra') - -var dir = '/tmp/this/path/does/not/exist' -fs.ensureDir(dir, function (err) { - console.log(err) // => null - // dir has now been created, including the directory it is to be placed in -}) -``` - - -### ensureLink(srcpath, dstpath, callback) - -Ensures that the link exists. If the directory structure does not exist, it is created. - -Sync: `ensureLinkSync()` - - -Example: - -```js -var fs = require('fs-extra') - -var srcpath = '/tmp/file.txt' -var dstpath = '/tmp/this/path/does/not/exist/file.txt' -fs.ensureLink(srcpath, dstpath, function (err) { - console.log(err) // => null - // link has now been created, including the directory it is to be placed in -}) -``` - - -### ensureSymlink(srcpath, dstpath, [type], callback) - -Ensures that the symlink exists. If the directory structure does not exist, it is created. - -Sync: `ensureSymlinkSync()` - - -Example: - -```js -var fs = require('fs-extra') - -var srcpath = '/tmp/file.txt' -var dstpath = '/tmp/this/path/does/not/exist/file.txt' -fs.ensureSymlink(srcpath, dstpath, function (err) { - console.log(err) // => null - // symlink has now been created, including the directory it is to be placed in -}) -``` - - -### mkdirs(dir, callback) - -Creates a directory. If the parent hierarchy doesn't exist, it's created. Like `mkdir -p`. - -Alias: `mkdirp()` - -Sync: `mkdirsSync()` / `mkdirpSync()` - - -Examples: - -```js -var fs = require('fs-extra') - -fs.mkdirs('/tmp/some/long/path/that/prob/doesnt/exist', function (err) { - if (err) return console.error(err) - console.log("success!") -}) - -fs.mkdirsSync('/tmp/another/path') -``` - - -### move(src, dest, [options], callback) - -Moves a file or directory, even across devices. - -Options: -- overwrite (boolean): overwrite existing file or directory, default is `false` - -Example: - -```js -var fs = require('fs-extra') - -fs.move('/tmp/somefile', '/tmp/does/not/exist/yet/somefile', function (err) { - if (err) return console.error(err) - console.log("success!") -}) -``` - - -### outputFile(file, data, [options], callback) - -Almost the same as `writeFile` (i.e. it [overwrites](http://pages.citebite.com/v2o5n8l2f5reb)), except that if the parent directory does not exist, it's created. `options` are what you'd pass to [`fs.writeFile()`](https://nodejs.org/api/fs.html#fs_fs_writefile_file_data_options_callback). - -Sync: `outputFileSync()` - - -Example: - -```js -var fs = require('fs-extra') -var file = '/tmp/this/path/does/not/exist/file.txt' - -fs.outputFile(file, 'hello!', function (err) { - console.log(err) // => null - - fs.readFile(file, 'utf8', function (err, data) { - console.log(data) // => hello! - }) -}) -``` - - - -### outputJson(file, data, [options], callback) - -Almost the same as `writeJson`, except that if the directory does not exist, it's created. -`options` are what you'd pass to [`jsonFile.writeFile()`](https://github.com/jprichardson/node-jsonfile#writefilefilename-options-callback). - -Alias: `outputJSON()` - -Sync: `outputJsonSync()`, `outputJSONSync()` - - -Example: - -```js -var fs = require('fs-extra') -var file = '/tmp/this/path/does/not/exist/file.txt' - -fs.outputJson(file, {name: 'JP'}, function (err) { - console.log(err) // => null - - fs.readJson(file, function(err, data) { - console.log(data.name) // => JP - }) -}) -``` - - - -### readJson(file, [options], callback) - -Reads a JSON file and then parses it into an object. `options` are the same -that you'd pass to [`jsonFile.readFile`](https://github.com/jprichardson/node-jsonfile#readfilefilename-options-callback). - -Alias: `readJSON()` - -Sync: `readJsonSync()`, `readJSONSync()` - - -Example: - -```js -var fs = require('fs-extra') - -fs.readJson('./package.json', function (err, packageObj) { - console.log(packageObj.version) // => 0.1.3 -}) -``` - -`readJsonSync()` can take a `throws` option set to `false` and it won't throw if the JSON is invalid. Example: - -```js -var fs = require('fs-extra') -var file = path.join('/tmp/some-invalid.json') -var data = '{not valid JSON' -fs.writeFileSync(file, data) - -var obj = fs.readJsonSync(file, {throws: false}) -console.log(obj) // => null -``` - - -### remove(dir, callback) - -Removes a file or directory. The directory can have contents. Like `rm -rf`. - -Sync: `removeSync()` - - -Examples: - -```js -var fs = require('fs-extra') - -fs.remove('/tmp/myfile', function (err) { - if (err) return console.error(err) - - console.log('success!') -}) - -fs.removeSync('/home/jprichardson') //I just deleted my entire HOME directory. -``` - - -### writeJson(file, object, [options], callback) - -Writes an object to a JSON file. `options` are the same that -you'd pass to [`jsonFile.writeFile()`](https://github.com/jprichardson/node-jsonfile#writefilefilename-options-callback). - -Alias: `writeJSON()` - -Sync: `writeJsonSync()`, `writeJSONSync()` - -Example: - -```js -var fs = require('fs-extra') -fs.writeJson('./package.json', {name: 'fs-extra'}, function (err) { - console.log(err) -}) -``` - - Third Party ----------- diff --git a/docs/copy.md b/docs/copy.md new file mode 100644 index 00000000..617510f8 --- /dev/null +++ b/docs/copy.md @@ -0,0 +1,28 @@ +# copy(src, dest, [options], callback) + +Copy a file or directory. The directory can have contents. Like `cp -r`. + +**Sync:** `copySync()` + +## Options: +- overwrite (boolean): overwrite existing file or directory, default is `true`. _Note that the copy operation will silently fail if you set this to `false` and the destination exists._ Use the `errorOnExist` option to change this behavior. +- errorOnExist (boolean): when `overwrite` is `false` and the destination exists, throw an error. Default is `false`. +- dereference (boolean): dereference symlinks, default is `false`. +- preserveTimestamps (boolean): will set last modification and access times to the ones of the original source files, default is `false`. +- filter: Function to filter copied files. Return `true` to include, `false` to exclude. This can also be a RegExp, however this is deprecated (See [issue #239](https://github.com/jprichardson/node-fs-extra/issues/239) for background). + +## Example: + +```js +var fs = require('fs-extra') + +fs.copy('/tmp/myfile', '/tmp/mynewfile', function (err) { + if (err) return console.error(err) + console.log("success!") +}) // copies file + +fs.copy('/tmp/mydir', '/tmp/mynewdir', function (err) { + if (err) return console.error(err) + console.log('success!') +}) // copies directory, even if it has subdirectories or files +``` diff --git a/docs/emptyDir.md b/docs/emptyDir.md new file mode 100644 index 00000000..d57c1519 --- /dev/null +++ b/docs/emptyDir.md @@ -0,0 +1,18 @@ +# emptyDir(dir, [callback]) + +Ensures that a directory is empty. Deletes directory contents if the directory is not empty. If the directory does not exist, it is created. The directory itself is not deleted. + +**Alias:** `emptydir()` + +**Sync:** `emptyDirSync()`, `emptydirSync()` + +## Example: + +```js +var fs = require('fs-extra') + +// assume this directory has a lot of files and folders +fs.emptyDir('/tmp/some/dir', function (err) { + if (!err) console.log('success!') +}) +``` diff --git a/docs/ensureDir.md b/docs/ensureDir.md new file mode 100644 index 00000000..ac704e0f --- /dev/null +++ b/docs/ensureDir.md @@ -0,0 +1,20 @@ +# ensureDir(dir, callback) + +Ensures that the directory exists. If the directory structure does not exist, it is created. Like `mkdir -p`. + +**Aliases:** `mkdirs()`, `mkdirp()` + +**Sync:** `ensureDirSync()`, `mkdirsSync()`, `mkdirpSync()` + + +## Example: + +```js +var fs = require('fs-extra') + +var dir = '/tmp/this/path/does/not/exist' +fs.ensureDir(dir, function (err) { + console.log(err) // => null + // dir has now been created, including the directory it is to be placed in +}) +``` diff --git a/docs/ensureFile.md b/docs/ensureFile.md new file mode 100644 index 00000000..21fcc8e2 --- /dev/null +++ b/docs/ensureFile.md @@ -0,0 +1,20 @@ +# ensureFile(file, callback) + +Ensures that the file exists. If the file that is requested to be created is in directories that do not exist, these directories are created. If the file already exists, it is **NOT MODIFIED**. + +**Alias:** `createFile()` + +**Sync:** `createFileSync()`,`ensureFileSync()` + + +## Example: + +```js +var fs = require('fs-extra') + +var file = '/tmp/this/path/does/not/exist/file.txt' +fs.ensureFile(file, function (err) { + console.log(err) // => null + // file has now been created, including the directory it is to be placed in +}) +``` diff --git a/docs/ensureLink.md b/docs/ensureLink.md new file mode 100644 index 00000000..25df997b --- /dev/null +++ b/docs/ensureLink.md @@ -0,0 +1,19 @@ +# ensureLink(srcpath, dstpath, callback) + +Ensures that the link exists. If the directory structure does not exist, it is created. + +**Sync:** `ensureLinkSync()` + + +## Example: + +```js +var fs = require('fs-extra') + +var srcpath = '/tmp/file.txt' +var dstpath = '/tmp/this/path/does/not/exist/file.txt' +fs.ensureLink(srcpath, dstpath, function (err) { + console.log(err) // => null + // link has now been created, including the directory it is to be placed in +}) +``` diff --git a/docs/ensureSymlink.md b/docs/ensureSymlink.md new file mode 100644 index 00000000..a29754bf --- /dev/null +++ b/docs/ensureSymlink.md @@ -0,0 +1,19 @@ +# ensureSymlink(srcpath, dstpath, [type], callback) + +Ensures that the symlink exists. If the directory structure does not exist, it is created. + +**Sync:** `ensureSymlinkSync()` + + +## Example: + +```js +var fs = require('fs-extra') + +var srcpath = '/tmp/file.txt' +var dstpath = '/tmp/this/path/does/not/exist/file.txt' +fs.ensureSymlink(srcpath, dstpath, function (err) { + console.log(err) // => null + // symlink has now been created, including the directory it is to be placed in +}) +``` diff --git a/docs/move.md b/docs/move.md new file mode 100644 index 00000000..5ff9153f --- /dev/null +++ b/docs/move.md @@ -0,0 +1,17 @@ +# move(src, dest, [options], callback) + +Moves a file or directory, even across devices. + +## Options: +- overwrite (boolean): overwrite existing file or directory, default is `false` + +## Example: + +```js +var fs = require('fs-extra') + +fs.move('/tmp/somefile', '/tmp/does/not/exist/yet/somefile', function (err) { + if (err) return console.error(err) + console.log("success!") +}) +``` diff --git a/docs/outputFile.md b/docs/outputFile.md new file mode 100644 index 00000000..16a96c6d --- /dev/null +++ b/docs/outputFile.md @@ -0,0 +1,21 @@ +# outputFile(file, data, [options], callback) + +Almost the same as `writeFile` (i.e. it [overwrites](http://pages.citebite.com/v2o5n8l2f5reb)), except that if the parent directory does not exist, it's created. `options` are what you'd pass to [`fs.writeFile()`](https://nodejs.org/api/fs.html#fs_fs_writefile_file_data_options_callback). + +**Sync:** `outputFileSync()` + + +## Example: + +```js +var fs = require('fs-extra') +var file = '/tmp/this/path/does/not/exist/file.txt' + +fs.outputFile(file, 'hello!', function (err) { + console.log(err) // => null + + fs.readFile(file, 'utf8', function (err, data) { + console.log(data) // => hello! + }) +}) +``` diff --git a/docs/outputJson.md b/docs/outputJson.md new file mode 100644 index 00000000..4ef07276 --- /dev/null +++ b/docs/outputJson.md @@ -0,0 +1,24 @@ +# outputJson(file, data, [options], callback) + +Almost the same as [`writeJson`](writeJson.md), except that if the directory does not exist, it's created. +`options` are what you'd pass to [`jsonFile.writeFile()`](https://github.com/jprichardson/node-jsonfile#writefilefilename-options-callback). + +**Alias:** `outputJSON()` + +**Sync:** `outputJsonSync()`, `outputJSONSync()` + + +## Example: + +```js +var fs = require('fs-extra') +var file = '/tmp/this/path/does/not/exist/file.txt' + +fs.outputJson(file, {name: 'JP'}, function (err) { + console.log(err) // => null + + fs.readJson(file, function(err, data) { + console.log(data.name) // => JP + }) +}) +``` diff --git a/docs/readJson.md b/docs/readJson.md new file mode 100644 index 00000000..8d5e28c7 --- /dev/null +++ b/docs/readJson.md @@ -0,0 +1,33 @@ +# readJson(file, [options], callback) + +Reads a JSON file and then parses it into an object. `options` are the same +that you'd pass to [`jsonFile.readFile`](https://github.com/jprichardson/node-jsonfile#readfilefilename-options-callback). + +**Alias:** `readJSON()` + +**Sync:** `readJsonSync()`, `readJSONSync()` + + +## Example: + +```js +var fs = require('fs-extra') + +fs.readJson('./package.json', function (err, packageObj) { + console.log(packageObj.version) // => 0.1.3 +}) +``` + +--- + +`readJsonSync()` can take a `throws` option set to `false` and it won't throw if the JSON is invalid. Example: + +```js +var fs = require('fs-extra') +var file = path.join('/tmp/some-invalid.json') +var data = '{not valid JSON' +fs.writeFileSync(file, data) + +var obj = fs.readJsonSync(file, {throws: false}) +console.log(obj) // => null +``` diff --git a/docs/remove.md b/docs/remove.md new file mode 100644 index 00000000..785e808e --- /dev/null +++ b/docs/remove.md @@ -0,0 +1,20 @@ +# remove(dir, callback) + +Removes a file or directory. The directory can have contents. Like `rm -rf`. + +**Sync:** `removeSync()` + + +## Example: + +```js +var fs = require('fs-extra') + +fs.remove('/tmp/myfile', function (err) { + if (err) return console.error(err) + + console.log('success!') +}) + +fs.removeSync('/home/jprichardson') //I just deleted my entire HOME directory. +``` diff --git a/docs/writeJson.md b/docs/writeJson.md new file mode 100644 index 00000000..04b93457 --- /dev/null +++ b/docs/writeJson.md @@ -0,0 +1,21 @@ +# writeJson(file, object, [options], callback) + +Writes an object to a JSON file. `options` are the same that +you'd pass to [`jsonFile.writeFile()`](https://github.com/jprichardson/node-jsonfile#writefilefilename-options-callback). + +**Alias:** `writeJSON()` + +**Sync:** `writeJsonSync()`, `writeJSONSync()` + +## Example: + +```js +var fs = require('fs-extra') +fs.writeJson('./package.json', {name: 'fs-extra'}, function (err) { + console.log(err) +}) +``` + +--- + +**See also:** [`outputJson()`](outputJson.md)