org.simantics.maps.server/node/node-v4.8.0-win-x64/node_modules/npm/node_modules/read-package-json/README.md

   1 # read-package-json
   2
   3 This is the thing that npm uses to read package.json files.  It
   4 validates some stuff, and loads some default things.
   5
   6 It keeps a cache of the files you've read, so that you don't end
   7 up reading the same package.json file multiple times.
   8
   9 Note that if you just want to see what's literally in the package.json
  10 file, you can usually do `var data = require('some-module/package.json')`.
  11
  12 This module is basically only needed by npm, but it's handy to see what
  13 npm will see when it looks at your package.
  14
  15 ## Usage
  16
  17 ```javascript
  18 var readJson = require('read-package-json')
  19
  20 // readJson(filename, [logFunction=noop], [strict=false], cb)
  21 readJson('/path/to/package.json', console.error, false, function (er, data) {
  22   if (er) {
  23     console.error("There was an error reading the file")
  24     return
  25   }
  26
  27   console.error('the package data is', data)
  28 });
  29 ```
  30
  31 ## readJson(file, [logFn = noop], [strict = false], cb)
  32
  33 * `file` {String} The path to the package.json file
  34 * `logFn` {Function} Function to handle logging.  Defaults to a noop.
  35 * `strict` {Boolean} True to enforce SemVer 2.0 version strings, and
  36   other strict requirements.
  37 * `cb` {Function} Gets called with `(er, data)`, as is The Node Way.
  38
  39 Reads the JSON file and does the things.
  40
  41 ## `package.json` Fields
  42
  43 See `man 5 package.json` or `npm help json`.
  44
  45 ## readJson.log
  46
  47 By default this is a reference to the `npmlog` module.  But if that
  48 module can't be found, then it'll be set to just a dummy thing that does
  49 nothing.
  50
  51 Replace with your own `{log,warn,error}` object for fun loggy time.
  52
  53 ## readJson.extras(file, data, cb)
  54
  55 Run all the extra stuff relative to the file, with the parsed data.
  56
  57 Modifies the data as it does stuff.  Calls the cb when it's done.
  58
  59 ## readJson.extraSet = [fn, fn, ...]
  60
  61 Array of functions that are called by `extras`.  Each one receives the
  62 arguments `fn(file, data, cb)` and is expected to call `cb(er, data)`
  63 when done or when an error occurs.
  64
  65 Order is indeterminate, so each function should be completely
  66 independent.
  67
  68 Mix and match!
  69
  70 ## readJson.cache
  71
  72 The `lru-cache` object that readJson uses to not read the same file over
  73 and over again.  See
  74 [lru-cache](https://github.com/isaacs/node-lru-cache) for details.
  75
  76 ## Other Relevant Files Besides `package.json`
  77
  78 Some other files have an effect on the resulting data object, in the
  79 following ways:
  80
  81 ### `README?(.*)`
  82
  83 If there is a `README` or `README.*` file present, then npm will attach
  84 a `readme` field to the data with the contents of this file.
  85
  86 Owing to the fact that roughly 100% of existing node modules have
  87 Markdown README files, it will generally be assumed to be Markdown,
  88 regardless of the extension.  Please plan accordingly.
  89
  90 ### `server.js`
  91
  92 If there is a `server.js` file, and there is not already a
  93 `scripts.start` field, then `scripts.start` will be set to `node
  94 server.js`.
  95
  96 ### `AUTHORS`
  97
  98 If there is not already a `contributors` field, then the `contributors`
  99 field will be set to the contents of the `AUTHORS` file, split by lines,
 100 and parsed.
 101
 102 ### `bindings.gyp`
 103
 104 If a bindings.gyp file exists, and there is not already a
 105 `scripts.install` field, then the `scripts.install` field will be set to
 106 `node-gyp rebuild`.
 107
 108 ### `index.js`
 109
 110 If the json file does not exist, but there is a `index.js` file
 111 present instead, and that file has a package comment, then it will try
 112 to parse the package comment, and use that as the data instead.
 113
 114 A package comment looks like this:
 115
 116 ```javascript
 117 /**package
 118  * { "name": "my-bare-module"
 119  * , "version": "1.2.3"
 120  * , "description": "etc...." }
 121  **/
 122
 123 // or...
 124
 125 /**package
 126 { "name": "my-bare-module"
 127 , "version": "1.2.3"
 128 , "description": "etc...." }
 129 **/
 130 ```
 131
 132 The important thing is that it starts with `/**package`, and ends with
 133 `**/`.  If the package.json file exists, then the index.js is not
 134 parsed.
 135
 136 ### `{directories.man}/*.[0-9]`
 137
 138 If there is not already a `man` field defined as an array of files or a
 139 single file, and
 140 there is a `directories.man` field defined, then that directory will
 141 be searched for manpages.
 142
 143 Any valid manpages found in that directory will be assigned to the `man`
 144 array, and installed in the appropriate man directory at package install
 145 time, when installed globally on a Unix system.
 146
 147 ### `{directories.bin}/*`
 148
 149 If there is not already a `bin` field defined as a string filename or a
 150 hash of `<name> : <filename>` pairs, then the `directories.bin`
 151 directory will be searched and all the files within it will be linked as
 152 executables at install time.
 153
 154 When installing locally, npm links bins into `node_modules/.bin`, which
 155 is in the `PATH` environ when npm runs scripts.  When
 156 installing globally, they are linked into `{prefix}/bin`, which is
 157 presumably in the `PATH` environment variable.