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

   1 # npmlog
   2
   3 The logger util that npm uses.
   4
   5 This logger is very basic.  It does the logging for npm.  It supports
   6 custom levels and colored output.
   7
   8 By default, logs are written to stderr.  If you want to send log messages
   9 to outputs other than streams, then you can change the `log.stream`
  10 member, or you can just listen to the events that it emits, and do
  11 whatever you want with them.
  12
  13 # Installation
  14
  15 ```console
  16 npm install npmlog --save
  17 ```
  18
  19 # Basic Usage
  20
  21 ```javascript
  22 var log = require('npmlog')
  23
  24 // additional stuff ---------------------------+
  25 // message ----------+                         |
  26 // prefix ----+      |                         |
  27 // level -+   |      |                         |
  28 //        v   v      v                         v
  29     log.info('fyi', 'I have a kitty cat: %j', myKittyCat)
  30 ```
  31
  32 ## log.level
  33
  34 * {String}
  35
  36 The level to display logs at.  Any logs at or above this level will be
  37 displayed.  The special level `silent` will prevent anything from being
  38 displayed ever.
  39
  40 ## log.record
  41
  42 * {Array}
  43
  44 An array of all the log messages that have been entered.
  45
  46 ## log.maxRecordSize
  47
  48 * {Number}
  49
  50 The maximum number of records to keep.  If log.record gets bigger than
  51 10% over this value, then it is sliced down to 90% of this value.
  52
  53 The reason for the 10% window is so that it doesn't have to resize a
  54 large array on every log entry.
  55
  56 ## log.prefixStyle
  57
  58 * {Object}
  59
  60 A style object that specifies how prefixes are styled.  (See below)
  61
  62 ## log.headingStyle
  63
  64 * {Object}
  65
  66 A style object that specifies how the heading is styled.  (See below)
  67
  68 ## log.heading
  69
  70 * {String} Default: ""
  71
  72 If set, a heading that is printed at the start of every line.
  73
  74 ## log.stream
  75
  76 * {Stream} Default: `process.stderr`
  77
  78 The stream where output is written.
  79
  80 ## log.enableColor()
  81
  82 Force colors to be used on all messages, regardless of the output
  83 stream.
  84
  85 ## log.disableColor()
  86
  87 Disable colors on all messages.
  88
  89 ## log.enableProgress()
  90
  91 Enable the display of log activity spinner and progress bar
  92
  93 ## log.disableProgress()
  94
  95 Disable the display of a progress bar
  96
  97 ## log.enableUnicode()
  98
  99 Force the unicode theme to be used for the progress bar.
 100
 101 ## log.disableUnicode()
 102
 103 Disable the use of unicode in the progress bar.
 104
 105 ## log.setGaugeTemplate(template)
 106
 107 Set a template for outputting the progress bar. See the [gauge documentation] for details.
 108
 109 [gauge documentation]: https://npmjs.com/package/gauge
 110
 111 ## log.setGaugeThemeset(themes)
 112
 113 Select a themeset to pick themes from for the progress bar. See the [gauge documentation] for details.
 114
 115 ## log.pause()
 116
 117 Stop emitting messages to the stream, but do not drop them.
 118
 119 ## log.resume()
 120
 121 Emit all buffered messages that were written while paused.
 122
 123 ## log.log(level, prefix, message, ...)
 124
 125 * `level` {String} The level to emit the message at
 126 * `prefix` {String} A string prefix.  Set to "" to skip.
 127 * `message...` Arguments to `util.format`
 128
 129 Emit a log message at the specified level.
 130
 131 ## log\[level](prefix, message, ...)
 132
 133 For example,
 134
 135 * log.silly(prefix, message, ...)
 136 * log.verbose(prefix, message, ...)
 137 * log.info(prefix, message, ...)
 138 * log.http(prefix, message, ...)
 139 * log.warn(prefix, message, ...)
 140 * log.error(prefix, message, ...)
 141
 142 Like `log.log(level, prefix, message, ...)`.  In this way, each level is
 143 given a shorthand, so you can do `log.info(prefix, message)`.
 144
 145 ## log.addLevel(level, n, style, disp)
 146
 147 * `level` {String} Level indicator
 148 * `n` {Number} The numeric level
 149 * `style` {Object} Object with fg, bg, inverse, etc.
 150 * `disp` {String} Optional replacement for `level` in the output.
 151
 152 Sets up a new level with a shorthand function and so forth.
 153
 154 Note that if the number is `Infinity`, then setting the level to that
 155 will cause all log messages to be suppressed.  If the number is
 156 `-Infinity`, then the only way to show it is to enable all log messages.
 157
 158 ## log.newItem(name, todo, weight)
 159
 160 * `name` {String} Optional; progress item name.
 161 * `todo` {Number} Optional; total amount of work to be done. Default 0.
 162 * `weight` {Number} Optional; the weight of this item relative to others. Default 1.
 163
 164 This adds a new `are-we-there-yet` item tracker to the progress tracker. The
 165 object returned has the `log[level]` methods but is otherwise an
 166 `are-we-there-yet` `Tracker` object.
 167
 168 ## log.newStream(name, todo, weight)
 169
 170 This adds a new `are-we-there-yet` stream tracker to the progress tracker. The
 171 object returned has the `log[level]` methods but is otherwise an
 172 `are-we-there-yet` `TrackerStream` object.
 173
 174 ## log.newGroup(name, weight)
 175
 176 This adds a new `are-we-there-yet` tracker group to the progress tracker. The
 177 object returned has the `log[level]` methods but is otherwise an
 178 `are-we-there-yet` `TrackerGroup` object.
 179
 180 # Events
 181
 182 Events are all emitted with the message object.
 183
 184 * `log` Emitted for all messages
 185 * `log.<level>` Emitted for all messages with the `<level>` level.
 186 * `<prefix>` Messages with prefixes also emit their prefix as an event.
 187
 188 # Style Objects
 189
 190 Style objects can have the following fields:
 191
 192 * `fg` {String} Color for the foreground text
 193 * `bg` {String} Color for the background
 194 * `bold`, `inverse`, `underline` {Boolean} Set the associated property
 195 * `bell` {Boolean} Make a noise (This is pretty annoying, probably.)
 196
 197 # Message Objects
 198
 199 Every log event is emitted with a message object, and the `log.record`
 200 list contains all of them that have been created.  They have the
 201 following fields:
 202
 203 * `id` {Number}
 204 * `level` {String}
 205 * `prefix` {String}
 206 * `message` {String} Result of `util.format()`
 207 * `messageRaw` {Array} Arguments to `util.format()`
 208
 209 # Blocking TTYs
 210
 211 We use [`set-blocking`](https://npmjs.com/package/set-blocking) to set
 212 stderr and stdout blocking if they are tty's and have the setBlocking call.
 213 This is a work around for an issue in early versions of Node.js 6.x, which
 214 made stderr and stdout non-blocking on OSX. (They are always blocking
 215 Windows and were never blocking on Linux.) `npmlog` needs them to be blocking
 216 so that it can allow output to stdout and stderr to be interlaced.