node-fs-extra/params.json

{"name":"Node-fs-extra","tagline":"Node.js: extra methods for the fs object.","body":"\r\nNode.js: fs-extra\r\n=================\r\n\r\n[![build status](https://secure.travis-ci.org/jprichardson/node-fs-extra.png)](http://travis-ci.org/jprichardson/node-fs-extra)\r\n\r\nThis module adds a few extra file system methods that aren't included in the native `fs` module. It is a drop in replacement for `fs`.\r\n\r\n\r\n\r\nWhy?\r\n----\r\n\r\nI got tired of including `mkdirp`, `rimraf`, and `cp -r` in most of my projects. \r\n\r\n\r\n\r\n\r\nInstallation\r\n------------\r\n\r\n    npm install --save fs-extra\r\n\r\n\r\n\r\nUsage\r\n-----\r\n\r\n`fs-extra` is a drop in replacement for native `fs`. All methods in `fs` are unmodified and attached to `fs-extra`.\r\n\r\nYou don't ever need to include the original `fs` module again:\r\n\r\n```javascript\r\nvar fs = require('fs') //this is no longer necessary\r\n```\r\n\r\nyou can now do this:\r\n\r\n```javascript\r\nvar fs = require('fs-extra'); //var fs = require('fs')\r\n```\r\n\r\nor if you prefer to make it clear that you're using `fs-extra` and not `fs`, you may want \r\nto do this:\r\n\r\n```javascript\r\n//var fs = require('fs')\r\nvar fse = require('fs-extra')\r\n```\r\n\r\nyou can also keep, both, but it's redundant:\r\n\r\n```javascript\r\nvar fs = require('fs')\r\n  , fse = require('fs-extra')\r\n```\r\n\r\n\r\n\r\nMethods\r\n-------\r\n\r\n**NOTE:** You can still use the native Node.js methods. They are copied over to `fs-extra`.\r\n\r\n\r\n### copy(src, dest, callback)\r\n\r\nCopy a file or directory. The directory can have contents. Like `cp -r`. There isn't a synchronous version implemented yet.\r\n\r\nSync: (none)\r\n\r\n\r\nExamples:\r\n\r\n```javascript\r\nvar fs = require('fs-extra');\r\n\r\nfs.copy('/tmp/myfile', '/tmp/mynewfile', function(err){\r\n  if (err) return console.error(err);\r\n\r\n  console.log(\"success!\")\r\n}); //copies file\r\n\r\nfs.copy('/tmp/mydir', '/tmp/mynewdir', function(err){\r\n  if (err) return console.error(err);\r\n  \r\n  console.log(\"success!\")\r\n}); //copies directory, even if it has subdirectories or files\r\n```\r\n\r\n\r\n### createFile(file, callback) \r\n\r\nCreates a file. 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**.\r\n\r\nSync: `createFileSync()`\r\n\r\n\r\nExample:\r\n\r\n```javascript\r\nvar fs = require('fs-extra')\r\n\r\nvar file = '/tmp/this/path/does/not/exist/file.txt'\r\n\r\nfs.createFile(file, function(err) {\r\n  console.log(err); //null\r\n  //file has now been created, including the directory it is to be placed in\r\n})\r\n```\r\n\r\n\r\n\r\n### mkdirs(dir, callback) \r\n\r\nCreates a directory. If the parent hierarchy doesn't exist, it's created. Like `mkdir -p`.\r\n\r\nAlias: `mkdirp()`\r\n\r\nSync: `mkdirsSync()` / `mkdirpSync()`\r\n\r\n\r\nExamples:\r\n\r\n```javascript\r\nvar fs = require('fs-extra');\r\n\r\nfs.mkdirs('/tmp/some/long/path/that/prob/doesnt/exist', function(err){\r\n  if (err) return console.error(err);\r\n  \r\n  console.log(\"success!\")\r\n});\r\n\r\nfs.mkdirsSync('/tmp/another/path');\r\n```\r\n\r\n\r\n### outputFile(file, data, callback)\r\n\r\nAlmost the same as `writeFile`, except that if the directory does not exist, it's created.\r\n\r\nSync: `outputFileSync()`\r\n\r\n\r\nExample:\r\n\r\n```javascript\r\nvar fs = require('fs-extra')\r\nvar file = '/tmp/this/path/does/not/exist/file.txt'\r\n\r\nfs.outputFile(file, 'hello!', function(err) {\r\n  console.log(err); //null\r\n\r\n  fs.readFile(file, 'utf8', function(err, data) {\r\n    console.log(data); //hello!\r\n  })\r\n})\r\n```\r\n\r\n\r\n\r\n### outputJson(file, data, callback)\r\n\r\nAlmost the same as `writeJson`, except that if the directory does not exist, it's created.\r\n\r\nAlias: `outputJSON()\r\n\r\nSync: `outputJsonSync()`, `outputJSONSync()`\r\n\r\n\r\nExample:\r\n\r\n```javascript\r\nvar fs = require('fs-extra')\r\nvar file = '/tmp/this/path/does/not/exist/file.txt'\r\n\r\nfs.outputJson(file, {name: 'JP'}, function(err) {\r\n  console.log(err); //null\r\n\r\n  fs.readJson(file, function(err, data) {\r\n    console.log(data.name); //'JP\r\n  })\r\n})\r\n```\r\n\r\n\r\n\r\n### readJson(file, callback) \r\n\r\nReads a JSON file and then parses it into an object.\r\n\r\nAlias: `readJSON()`\r\n\r\nSync: `readJsonSync()`, `readJSONSync()`\r\n\r\n\r\nExample:\r\n\r\n```javascript\r\nvar fs = require('fs-extra');\r\n\r\nfs.readJson('./package.json', function(err, packageObj) {\r\n  console.log(packageObj.version); //0.1.3\r\n});\r\n```\r\n\r\n\r\n### remove(dir, callback)\r\n\r\nRemoves a file or directory. The directory can have contents. Like `rm -rf`.\r\n\r\nAlias: `delete()`\r\n\r\nSync: `removeSync()` / `deleteSync()`\r\n\r\n\r\nExamples:\r\n\r\n```javascript\r\nvar fs = require('fs-extra');\r\n\r\nfs.remove('/tmp/myfile', function(err){\r\n  if (err) return console.error(err);\r\n  \r\n  console.log(\"success!\")\r\n});\r\n\r\nfs.removeSync('/home/jprichardson'); //I just deleted my entire HOME directory. \r\n```\r\n\r\n\r\n\r\n### writeJson(file, object, callback) \r\n\r\nWrites an object to a JSON file.\r\n\r\nAlias: `writeJSON()`\r\n\r\nSync: `writeJsonSync()`, `writeJSONSync()`\r\n\r\nExample:\r\n\r\n```javascript\r\nvar fs = require('fs-extra');\r\nfs.writeJson('./package.json', {name: 'fs-extra'}, function(err){\r\n  console.log(err);\r\n});\r\n```\r\n\r\n\r\n\r\nRoadmap to 1.0.0\r\n-----------------\r\n\r\nThis contains items that I'm considering doing. I'd love community feedback.\r\n\r\n* File system walker. I really like this one: https://github.com/daaku/nodejs-walker ... this might be adding too much. Thoughts?\r\n* File/directory tree watcher. There are quite a few. ... this also might be adding too much. Thoughts?\r\n* Method to move files.\r\n* Copy sync.\r\n* Thinking about moving `rimraf`, `ncp`, and `mkdirps` code into this library. I'd like fs-extra to be a stable library that module authors\r\ncan depend upon. A bunch of other dependencies kinda sucks for modules/libraries. (I'm leaning against this now.)\r\n* Change documentation to use the `fse` prefix instead of `fs`. This may encourage people to start using `fse` as a prefix and hence make their code clearer that they're not using the native `fs`. I'm very undecided on this one since `fs-extra` is a drop in replacement for the native `fs`. (I'm leaning against this now.)\r\n\r\n\r\n\r\nNaming\r\n------\r\n\r\nI put a lot of thought into the naming of these functions. Inspired by @coolaj86's request. So he deserves much of the credit for raising the issue. See discussion(s) here:\r\n\r\n* https://github.com/jprichardson/node-fs-extra/issues/2\r\n* https://github.com/flatiron/utile/issues/11\r\n* https://github.com/ryanmcgrath/wrench-js/issues/29\r\n* https://github.com/substack/node-mkdirp/issues/17\r\n\r\nFirst, I believe that in as many cases as possible, the [Node.js naming schemes](http://nodejs.org/api/fs.html) should be chosen. However, there are problems with the Node.js own naming schemes.\r\n\r\nFor example, `fs.readFile()` and `fs.readdir()`: the **F** is capitalized in *File* and the **d** is not capitalized in *dir*. Perhaps a bit pedantic, but they should still be consistent. Also, Node.js has chosen a lot of POSIX naming schemes, which I believe is great. See: `fs.mkdir()`, `fs.rmdir()`, `fs.chown()`, etc.\r\n\r\nWe have a dilemma though. How do you consistently name methods that perform the following POSIX commands: `cp`, `cp -r`, `mkdir -p`, and `rm -rf`?\r\n\r\nMy perspective: when in doubt, err on the side of simplicity. A directory is just a hierarchical grouping of directories and files. Consider that for a moment. So when you want to copy it or remove it, in most cases you'll want to copy or remove all of its contents. When you want to create a directory, if the directory that it's suppose to be contained in does not exist, then in most cases you'll want to create that too. \r\n\r\nSo, if you want to remove a file or a directory regardless of whether it has contents, just call `fs.remove(path)` or its alias `fs.delete(path)`. If you want to copy a file or a directory whether it has contents, just call `fs.copy(source, destination)`. If you want to create a directory regardless of whether its parent directories exist, just call `fs.mkdirs(path)` or `fs.mkdirp(path)`. \r\n\r\n\r\n\r\nContributors\r\n-------------\r\n- [JP Richardson](https://github.com/jprichardson)\r\n- [Mike McNeil](https://github.com/mikermcneil)\r\n- [Ian Crowther](https://github.com/iancrowther)\r\n- [Stephen Mathieson](https://github.com/stephenmathieson)\r\n- `<your name here>`\r\n\r\n\r\n\r\n\r\nLicense\r\n-------\r\n\r\n\r\nLicensed under MIT\r\n\r\nCopyright (c) 2011-2013 JP Richardson\r\n\r\n[1]: http://nodejs.org/docs/latest/api/fs.html \r\n\r\n\r\n[jsonfile]: https://github.com/jprichardson/node-jsonfile\r\n\r\n\r\n[aboutjp]: http://about.me/jprichardson\r\n[twitter]: http://twitter.com/jprichardson\r\n[procbits]: http://procbits.com\r\n[gitpilot]: http://gitpilot.com\r\n\r\n\r\n\r\n","google":"UA-35285930-1","note":"Don't delete this file! It's used internally to help with page regeneration."}