www.aleph1.co.uk Git - yaffs-website/blob - node_modules/jsonfile/README.md

   1 Node.js - jsonfile
   2 ================
   3
   4 Easily read/write JSON files.
   5
   6 [![npm Package](https://img.shields.io/npm/v/jsonfile.svg?style=flat-square)](https://www.npmjs.org/package/jsonfile)
   7 [![build status](https://secure.travis-ci.org/jprichardson/node-jsonfile.svg)](http://travis-ci.org/jprichardson/node-jsonfile)
   8 [![windows Build status](https://img.shields.io/appveyor/ci/jprichardson/node-jsonfile/master.svg?label=windows%20build)](https://ci.appveyor.com/project/jprichardson/node-jsonfile/branch/master)
   9
  10 <a href="https://github.com/feross/standard"><img src="https://cdn.rawgit.com/feross/standard/master/sticker.svg" alt="Standard JavaScript" width="100"></a>
  11
  12 Why?
  13 ----
  14
  15 Writing `JSON.stringify()` and then `fs.writeFile()` and `JSON.parse()` with `fs.readFile()` enclosed in `try/catch` blocks became annoying.
  16
  17
  18
  19 Installation
  20 ------------
  21
  22     npm install --save jsonfile
  23
  24
  25
  26 API
  27 ---
  28
  29 ### readFile(filename, [options], callback)
  30
  31 `options` (`object`, default `undefined`): Pass in any `fs.readFile` options or set `reviver` for a [JSON reviver](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/parse).
  32   - `throws` (`boolean`, default: `true`). If `JSON.parse` throws an error, pass this error to the callback.
  33   If `false`, returns `null` for the object.
  34
  35
  36 ```js
  37 var jsonfile = require('jsonfile')
  38 var file = '/tmp/data.json'
  39 jsonfile.readFile(file, function(err, obj) {
  40   console.dir(obj)
  41 })
  42 ```
  43
  44
  45 ### readFileSync(filename, [options])
  46
  47 `options` (`object`, default `undefined`): Pass in any `fs.readFileSync` options or set `reviver` for a [JSON reviver](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/parse).
  48 - `throws` (`boolean`, default: `true`). If `JSON.parse` throws an error, throw the error.
  49 If `false`, returns `null` for the object.
  50
  51 ```js
  52 var jsonfile = require('jsonfile')
  53 var file = '/tmp/data.json'
  54
  55 console.dir(jsonfile.readFileSync(file))
  56 ```
  57
  58
  59 ### writeFile(filename, obj, [options], callback)
  60
  61 `options`: Pass in any `fs.writeFile` options or set `replacer` for a [JSON replacer](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify). Can also pass in `spaces`.
  62
  63
  64 ```js
  65 var jsonfile = require('jsonfile')
  66
  67 var file = '/tmp/data.json'
  68 var obj = {name: 'JP'}
  69
  70 jsonfile.writeFile(file, obj, function (err) {
  71   console.error(err)
  72 })
  73 ```
  74
  75 **formatting with spaces:**
  76
  77 ```js
  78 var jsonfile = require('jsonfile')
  79
  80 var file = '/tmp/data.json'
  81 var obj = {name: 'JP'}
  82
  83 jsonfile.writeFile(file, obj, {spaces: 2}, function(err) {
  84   console.error(err)
  85 })
  86 ```
  87
  88
  89 ### writeFileSync(filename, obj, [options])
  90
  91 `options`: Pass in any `fs.writeFileSync` options or set `replacer` for a [JSON replacer](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify). Can also pass in `spaces`.
  92
  93 ```js
  94 var jsonfile = require('jsonfile')
  95
  96 var file = '/tmp/data.json'
  97 var obj = {name: 'JP'}
  98
  99 jsonfile.writeFileSync(file, obj)
 100 ```
 101
 102 **formatting with spaces:**
 103
 104 ```js
 105 var jsonfile = require('jsonfile')
 106
 107 var file = '/tmp/data.json'
 108 var obj = {name: 'JP'}
 109
 110 jsonfile.writeFileSync(file, obj, {spaces: 2})
 111 ```
 112
 113
 114
 115 ### spaces
 116
 117 Global configuration to set spaces to indent JSON files.
 118
 119 **default:** `null`
 120
 121 ```js
 122 var jsonfile = require('jsonfile')
 123
 124 jsonfile.spaces = 4
 125
 126 var file = '/tmp/data.json'
 127 var obj = {name: 'JP'}
 128
 129 // json file has four space indenting now
 130 jsonfile.writeFile(file, obj, function (err) {
 131   console.error(err)
 132 })
 133 ```
 134
 135 Note, it's bound to `this.spaces`. So, if you do this:
 136
 137 ```js
 138 var myObj = {}
 139 myObj.writeJsonSync = jsonfile.writeFileSync
 140 // => this.spaces = null
 141 ```
 142
 143 Could do the following:
 144
 145 ```js
 146 var jsonfile = require('jsonfile')
 147 jsonfile.spaces = 4
 148 jsonfile.writeFileSync(file, obj) // will have 4 spaces indentation
 149
 150 var myCrazyObj = {spaces: 32}
 151 myCrazyObj.writeJsonSync = jsonfile.writeFileSync
 152 myCrazyObj.writeJsonSync(file, obj) // will have 32 space indentation
 153 myCrazyObj.writeJsonSync(file, obj, {spaces: 2}) // will have only 2
 154 ```
 155
 156
 157 License
 158 -------
 159
 160 (MIT License)
 161
 162 Copyright 2012-2016, JP Richardson  <jprichardson@gmail.com>