org.simantics.maps.server/node/node-v4.8.0-win-x64/node_modules/npm/node_modules/npmlog/node_modules/gauge/README.md

   1 gauge
   2 =====
   3
   4 A nearly stateless terminal based horizontal gauge / progress bar.
   5
   6 ```javascript
   7 var Gauge = require("gauge")
   8
   9 var gauge = new Gauge()
  10
  11 gauge.show("test", 0.20)
  12
  13 gauge.pulse("this")
  14
  15 gauge.hide()
  16 ```
  17
  18 ![](example.png)
  19
  20
  21 ### `var gauge = new Gauge([options], [ansiStream])`
  22
  23 * **options** – *(optional)* An option object. (See [below] for details.)
  24 * **ansiStream** – *(optional)* A stream that's been blessed by the [ansi]
  25   module to include various commands for controlling the cursor in a terminal.
  26
  27 [ansi]: https://www.npmjs.com/package/ansi
  28 [below]: #theme-objects
  29
  30 Constructs a new gauge. Gauges are drawn on a single line, and are not drawn
  31 if the current terminal isn't a tty.
  32
  33 If you resize your terminal in a way that can be detected then the gauge
  34 will be drawn at the new size. As a general rule, growing your terminal will
  35 be clean, but shrinking your terminal will result in cruft as we don't have
  36 enough information to know where what we wrote previously is now located.
  37
  38 The **options** object can have the following properties, all of which are
  39 optional:
  40
  41 * maxUpdateFrequency: defaults to 50 msec, the gauge will not be drawn more
  42   than once in this period of time. This applies to `show` and `pulse`
  43   calls, but if you `hide` and then `show` the gauge it will draw it
  44   regardless of time since last draw.
  45 * theme: defaults to Gauge.unicode` if the terminal supports
  46   unicode according to [has-unicode], otherwise it defaults to `Gauge.ascii`.
  47   Details on the [theme object](#theme-objects) are documented elsewhere.
  48 * template: see [documentation elsewhere](#template-objects) for
  49   defaults and details.
  50
  51 [has-unicode]: https://www.npmjs.com/package/has-unicode
  52
  53 If **ansiStream** isn't passed in, then one will be constructed from stderr
  54 with `ansi(process.stderr)`.
  55
  56 ### `gauge.show([name, [completed]])`
  57
  58 * **name** – *(optional)* The name of the current thing contributing to progress. Defaults to the last value used, or "".
  59 * **completed** – *(optional)* The portion completed as a value between 0 and 1. Defaults to the last value used, or 0.
  60
  61 If `process.stdout.isTTY` is false then this does nothing. If completed is 0
  62 and `gauge.pulse` has never been called, then similarly nothing will be printed.
  63
  64 If `maxUpdateFrequency` msec haven't passed since the last call to `show` or
  65 `pulse` then similarly, nothing will be printed.  (Actually, the update is
  66 deferred until `maxUpdateFrequency` msec have passed and if nothing else has
  67 happened, the gauge update will happen.)
  68
  69 ### `gauge.hide()`
  70
  71 Removes the gauge from the terminal.
  72
  73 ### `gauge.pulse([name])`
  74
  75 * **name** – *(optional)* The specific thing that triggered this pulse
  76
  77 Spins the spinner in the gauge to show output. If **name** is included then
  78 it will be combined with the last name passed to `gauge.show` using the
  79 subsection property of the theme (typically a right facing arrow).
  80
  81 ### `gauge.disable()`
  82
  83 Hides the gauge and ignores further calls to `show` or `pulse`.
  84
  85 ### `gauge.enable()`
  86
  87 Shows the gauge and resumes updating when `show` or `pulse` is called.
  88
  89 ### `gauge.setTheme(theme)`
  90
  91 Change the active theme, will be displayed with the next show or pulse
  92
  93 ### `gauge.setTemplate(template)`
  94
  95 Change the active template, will be displayed with the next show or pulse
  96
  97 ### Theme Objects
  98
  99 There are two theme objects available as a part of the module, `Gauge.unicode` and `Gauge.ascii`.
 100 Theme objects have the follow properties:
 101
 102 | Property   | Unicode | ASCII |
 103 | ---------- | ------- | ----- |
 104 | startgroup | ╢       | \|    |
 105 | endgroup   | ╟       | \|    |
 106 | complete   | █       | #     |
 107 | incomplete | ░       | -     |
 108 | spinner    | ▀▐▄▌    | -\\\|/ |
 109 | subsection | →       | ->    |
 110
 111 *startgroup*, *endgroup* and *subsection* can be as many characters as you want.
 112
 113 *complete* and *incomplete* should be a single character width each.
 114
 115 *spinner* is a list of characters to use in turn when displaying an activity
 116 spinner.  The Gauge will spin as many characters as you give here.
 117
 118 ### Template Objects
 119
 120 A template is an array of objects and strings that, after being evaluated,
 121 will be turned into the gauge line.  The default template is:
 122
 123 ```javascript
 124 [
 125     {type: "name", separated: true, maxLength: 25, minLength: 25, align: "left"},
 126     {type: "spinner", separated: true},
 127     {type: "startgroup"},
 128     {type: "completionbar"},
 129     {type: "endgroup"}
 130 ]
 131 ```
 132
 133 The various template elements can either be **plain strings**, in which case they will
 134 be be included verbatum in the output.
 135
 136 If the template element is an object, it can have the following keys:
 137
 138 * *type* can be:
 139   * `name` – The most recent name passed to `show`; if this is in response to a
 140     `pulse` then the name passed to `pulse` will be appended along with the
 141     subsection property from the theme.
 142   * `spinner` – If you've ever called `pulse` this will be one of the characters
 143     from the spinner property of the theme.
 144   * `startgroup` – The `startgroup` property from the theme.
 145   * `completionbar` – This progress bar itself
 146   * `endgroup` – The `endgroup` property from the theme.
 147 * *separated* – If true, the element will be separated with spaces from things on
 148   either side (and margins count as space, so it won't be indented), but only
 149   if its included.
 150 * *maxLength* – The maximum length for this element. If its value is longer it
 151   will be truncated.
 152 * *minLength* – The minimum length for this element. If its value is shorter it
 153   will be padded according to the *align* value.
 154 * *align* – (Default: left) Possible values "left", "right" and "center". Works
 155   as you'd expect from word processors.
 156 * *length* – Provides a single value for both *minLength* and *maxLength*. If both
 157   *length* and *minLength or *maxLength* are specifed then the latter take precedence.
 158
 159 ### Tracking Completion
 160
 161 If you have more than one thing going on that you want to track completion
 162 of, you may find the related [are-we-there-yet] helpful.  It's `change`
 163 event can be wired up to the `show` method to get a more traditional
 164 progress bar interface.
 165
 166 [are-we-there-yet]: https://www.npmjs.com/package/are-we-there-yet