source: trip-planner-front/node_modules/gauge/README.md@ 6a3a178

Last change on this file since 6a3a178 was 6a3a178, checked in by Ema <ema_spirova@…>, 3 years ago

initial commit

  • Property mode set to 100644
File size: 14.7 KB
Line 
1gauge
2=====
3
4A nearly stateless terminal based horizontal gauge / progress bar.
5
6```javascript
7var Gauge = require("gauge")
8
9var gauge = new Gauge()
10
11gauge.show("test", 0.20)
12
13gauge.pulse("this")
14
15gauge.hide()
16```
17
18![](gauge-demo.gif)
19
20
21### CHANGES FROM 1.x
22
23Gauge 2.x is breaking release, please see the [changelog] for details on
24what's changed if you were previously a user of this module.
25
26[changelog]: CHANGELOG.md
27
28### THE GAUGE CLASS
29
30This is the typical interface to the module– it provides a pretty
31fire-and-forget interface to displaying your status information.
32
33```
34var Gauge = require("gauge")
35
36var gauge = new Gauge([stream], [options])
37```
38
39* **stream** – *(optional, default STDERR)* A stream that progress bar
40 updates are to be written to. Gauge honors backpressure and will pause
41 most writing if it is indicated.
42* **options** – *(optional)* An option object.
43
44Constructs a new gauge. Gauges are drawn on a single line, and are not drawn
45if **stream** isn't a tty and a tty isn't explicitly provided.
46
47If **stream** is a terminal or if you pass in **tty** to **options** then we
48will detect terminal resizes and redraw to fit. We do this by watching for
49`resize` events on the tty. (To work around a bug in verisons of Node prior
50to 2.5.0, we watch for them on stdout if the tty is stderr.) Resizes to
51larger window sizes will be clean, but shrinking the window will always
52result in some cruft.
53
54**IMPORTANT:** If you prevously were passing in a non-tty stream but you still
55want output (for example, a stream wrapped by the `ansi` module) then you
56need to pass in the **tty** option below, as `gauge` needs access to
57the underlying tty in order to do things like terminal resizes and terminal
58width detection.
59
60The **options** object can have the following properties, all of which are
61optional:
62
63* **updateInterval**: How often gauge updates should be drawn, in miliseconds.
64* **fixedFramerate**: Defaults to false on node 0.8, true on everything
65 else. When this is true a timer is created to trigger once every
66 `updateInterval` ms, when false, updates are printed as soon as they come
67 in but updates more often than `updateInterval` are ignored. The reason
68 0.8 doesn't have this set to true is that it can't `unref` its timer and
69 so it would stop your program from exiting– if you want to use this
70 feature with 0.8 just make sure you call `gauge.disable()` before you
71 expect your program to exit.
72* **themes**: A themeset to use when selecting the theme to use. Defaults
73 to `gauge/themes`, see the [themes] documentation for details.
74* **theme**: Select a theme for use, it can be a:
75 * Theme object, in which case the **themes** is not used.
76 * The name of a theme, which will be looked up in the current *themes*
77 object.
78 * A configuration object with any of `hasUnicode`, `hasColor` or
79 `platform` keys, which if wlll be used to override our guesses when making
80 a default theme selection.
81
82 If no theme is selected then a default is picked using a combination of our
83 best guesses at your OS, color support and unicode support.
84* **template**: Describes what you want your gauge to look like. The
85 default is what npm uses. Detailed [documentation] is later in this
86 document.
87* **hideCursor**: Defaults to true. If true, then the cursor will be hidden
88 while the gauge is displayed.
89* **tty**: The tty that you're ultimately writing to. Defaults to the same
90 as **stream**. This is used for detecting the width of the terminal and
91 resizes. The width used is `tty.columns - 1`. If no tty is available then
92 a width of `79` is assumed.
93* **enabled**: Defaults to true if `tty` is a TTY, false otherwise. If true
94 the gauge starts enabled. If disabled then all update commands are
95 ignored and no gauge will be printed until you call `.enable()`.
96* **Plumbing**: The class to use to actually generate the gauge for
97 printing. This defaults to `require('gauge/plumbing')` and ordinarly you
98 shouldn't need to override this.
99* **cleanupOnExit**: Defaults to true. Ordinarily we register an exit
100 handler to make sure your cursor is turned back on and the progress bar
101 erased when your process exits, even if you Ctrl-C out or otherwise exit
102 unexpectedly. You can disable this and it won't register the exit handler.
103
104[has-unicode]: https://www.npmjs.com/package/has-unicode
105[themes]: #themes
106[documentation]: #templates
107
108#### `gauge.show(section | status, [completed])`
109
110The first argument is either the section, the name of the current thing
111contributing to progress, or an object with keys like **section**,
112**subsection** & **completed** (or any others you have types for in a custom
113template). If you don't want to update or set any of these you can pass
114`null` and it will be ignored.
115
116The second argument is the percent completed as a value between 0 and 1.
117Without it, completion is just not updated. You'll also note that completion
118can be passed in as part of a status object as the first argument. If both
119it and the completed argument are passed in, the completed argument wins.
120
121#### `gauge.hide([cb])`
122
123Removes the gauge from the terminal. Optionally, callback `cb` after IO has
124had an opportunity to happen (currently this just means after `setImmediate`
125has called back.)
126
127It turns out this is important when you're pausing the progress bar on one
128filehandle and printing to another– otherwise (with a big enough print) node
129can end up printing the "end progress bar" bits to the progress bar filehandle
130while other stuff is printing to another filehandle. These getting interleaved
131can cause corruption in some terminals.
132
133#### `gauge.pulse([subsection])`
134
135* **subsection** – *(optional)* The specific thing that triggered this pulse
136
137Spins the spinner in the gauge to show output. If **subsection** is
138included then it will be combined with the last name passed to `gauge.show`.
139
140#### `gauge.disable()`
141
142Hides the gauge and ignores further calls to `show` or `pulse`.
143
144#### `gauge.enable()`
145
146Shows the gauge and resumes updating when `show` or `pulse` is called.
147
148#### `gauge.isEnabled()`
149
150Returns true if the gauge is enabled.
151
152#### `gauge.setThemeset(themes)`
153
154Change the themeset to select a theme from. The same as the `themes` option
155used in the constructor. The theme will be reselected from this themeset.
156
157#### `gauge.setTheme(theme)`
158
159Change the active theme, will be displayed with the next show or pulse. This can be:
160
161* Theme object, in which case the **themes** is not used.
162* The name of a theme, which will be looked up in the current *themes*
163 object.
164* A configuration object with any of `hasUnicode`, `hasColor` or
165 `platform` keys, which if wlll be used to override our guesses when making
166 a default theme selection.
167
168If no theme is selected then a default is picked using a combination of our
169best guesses at your OS, color support and unicode support.
170
171#### `gauge.setTemplate(template)`
172
173Change the active template, will be displayed with the next show or pulse
174
175### Tracking Completion
176
177If you have more than one thing going on that you want to track completion
178of, you may find the related [are-we-there-yet] helpful. It's `change`
179event can be wired up to the `show` method to get a more traditional
180progress bar interface.
181
182[are-we-there-yet]: https://www.npmjs.com/package/are-we-there-yet
183
184### THEMES
185
186```
187var themes = require('gauge/themes')
188
189// fetch the default color unicode theme for this platform
190var ourTheme = themes({hasUnicode: true, hasColor: true})
191
192// fetch the default non-color unicode theme for osx
193var ourTheme = themes({hasUnicode: true, hasColor: false, platform: 'darwin'})
194
195// create a new theme based on the color ascii theme for this platform
196// that brackets the progress bar with arrows
197var ourTheme = themes.newTheme(theme(hasUnicode: false, hasColor: true}), {
198 preProgressbar: '→',
199 postProgressbar: '←'
200})
201```
202
203The object returned by `gauge/themes` is an instance of the `ThemeSet` class.
204
205```
206var ThemeSet = require('gauge/theme-set')
207var themes = new ThemeSet()
208// or
209var themes = require('gauge/themes')
210var mythemes = themes.newThemeset() // creates a new themeset based on the default themes
211```
212
213#### themes(opts)
214#### themes.getDefault(opts)
215
216Theme objects are a function that fetches the default theme based on
217platform, unicode and color support.
218
219Options is an object with the following properties:
220
221* **hasUnicode** - If true, fetch a unicode theme, if no unicode theme is
222 available then a non-unicode theme will be used.
223* **hasColor** - If true, fetch a color theme, if no color theme is
224 available a non-color theme will be used.
225* **platform** (optional) - Defaults to `process.platform`. If no
226 platform match is available then `fallback` is used instead.
227
228If no compatible theme can be found then an error will be thrown with a
229`code` of `EMISSINGTHEME`.
230
231#### themes.addTheme(themeName, themeObj)
232#### themes.addTheme(themeName, [parentTheme], newTheme)
233
234Adds a named theme to the themeset. You can pass in either a theme object,
235as returned by `themes.newTheme` or the arguments you'd pass to
236`themes.newTheme`.
237
238#### themes.getThemeNames()
239
240Return a list of all of the names of the themes in this themeset. Suitable
241for use in `themes.getTheme(…)`.
242
243#### themes.getTheme(name)
244
245Returns the theme object from this theme set named `name`.
246
247If `name` does not exist in this themeset an error will be thrown with
248a `code` of `EMISSINGTHEME`.
249
250#### themes.setDefault([opts], themeName)
251
252`opts` is an object with the following properties.
253
254* **platform** - Defaults to `'fallback'`. If your theme is platform
255 specific, specify that here with the platform from `process.platform`, eg,
256 `win32`, `darwin`, etc.
257* **hasUnicode** - Defaults to `false`. If your theme uses unicode you
258 should set this to true.
259* **hasColor** - Defaults to `false`. If your theme uses color you should
260 set this to true.
261
262`themeName` is the name of the theme (as given to `addTheme`) to use for
263this set of `opts`.
264
265#### themes.newTheme([parentTheme,] newTheme)
266
267Create a new theme object based on `parentTheme`. If no `parentTheme` is
268provided then a minimal parentTheme that defines functions for rendering the
269activity indicator (spinner) and progress bar will be defined. (This
270fallback parent is defined in `gauge/base-theme`.)
271
272newTheme should be a bare object– we'll start by discussing the properties
273defined by the default themes:
274
275* **preProgressbar** - displayed prior to the progress bar, if the progress
276 bar is displayed.
277* **postProgressbar** - displayed after the progress bar, if the progress bar
278 is displayed.
279* **progressBarTheme** - The subtheme passed through to the progress bar
280 renderer, it's an object with `complete` and `remaining` properties
281 that are the strings you want repeated for those sections of the progress
282 bar.
283* **activityIndicatorTheme** - The theme for the activity indicator (spinner),
284 this can either be a string, in which each character is a different step, or
285 an array of strings.
286* **preSubsection** - Displayed as a separator between the `section` and
287 `subsection` when the latter is printed.
288
289More generally, themes can have any value that would be a valid value when rendering
290templates. The properties in the theme are used when their name matches a type in
291the template. Their values can be:
292
293* **strings & numbers** - They'll be included as is
294* **function (values, theme, width)** - Should return what you want in your output.
295 *values* is an object with values provided via `gauge.show`,
296 *theme* is the theme specific to this item (see below) or this theme object,
297 and *width* is the number of characters wide your result should be.
298
299There are a couple of special prefixes:
300
301* **pre** - Is shown prior to the property, if its displayed.
302* **post** - Is shown after the property, if its displayed.
303
304And one special suffix:
305
306* **Theme** - Its value is passed to a function-type item as the theme.
307
308#### themes.addToAllThemes(theme)
309
310This *mixes-in* `theme` into all themes currently defined. It also adds it
311to the default parent theme for this themeset, so future themes added to
312this themeset will get the values from `theme` by default.
313
314#### themes.newThemeset()
315
316Copy the current themeset into a new one. This allows you to easily inherit
317one themeset from another.
318
319### TEMPLATES
320
321A template is an array of objects and strings that, after being evaluated,
322will be turned into the gauge line. The default template is:
323
324```javascript
325[
326 {type: 'progressbar', length: 20},
327 {type: 'activityIndicator', kerning: 1, length: 1},
328 {type: 'section', kerning: 1, default: ''},
329 {type: 'subsection', kerning: 1, default: ''}
330]
331```
332
333The various template elements can either be **plain strings**, in which case they will
334be be included verbatum in the output, or objects with the following properties:
335
336* *type* can be any of the following plus any keys you pass into `gauge.show` plus
337 any keys you have on a custom theme.
338 * `section` – What big thing you're working on now.
339 * `subsection` – What component of that thing is currently working.
340 * `activityIndicator` – Shows a spinner using the `activityIndicatorTheme`
341 from your active theme.
342 * `progressbar` – A progress bar representing your current `completed`
343 using the `progressbarTheme` from your active theme.
344* *kerning* – Number of spaces that must be between this item and other
345 items, if this item is displayed at all.
346* *maxLength* – The maximum length for this element. If its value is longer it
347 will be truncated.
348* *minLength* – The minimum length for this element. If its value is shorter it
349 will be padded according to the *align* value.
350* *align* – (Default: left) Possible values "left", "right" and "center". Works
351 as you'd expect from word processors.
352* *length* – Provides a single value for both *minLength* and *maxLength*. If both
353 *length* and *minLength or *maxLength* are specifed then the latter take precedence.
354* *value* – A literal value to use for this template item.
355* *default* – A default value to use for this template item if a value
356 wasn't otherwise passed in.
357
358### PLUMBING
359
360This is the super simple, assume nothing, do no magic internals used by gauge to
361implement its ordinary interface.
362
363```
364var Plumbing = require('gauge/plumbing')
365var gauge = new Plumbing(theme, template, width)
366```
367
368* **theme**: The theme to use.
369* **template**: The template to use.
370* **width**: How wide your gauge should be
371
372#### `gauge.setTheme(theme)`
373
374Change the active theme.
375
376#### `gauge.setTemplate(template)`
377
378Change the active template.
379
380#### `gauge.setWidth(width)`
381
382Change the width to render at.
383
384#### `gauge.hide()`
385
386Return the string necessary to hide the progress bar
387
388#### `gauge.hideCursor()`
389
390Return a string to hide the cursor.
391
392#### `gauge.showCursor()`
393
394Return a string to show the cursor.
395
396#### `gauge.show(status)`
397
398Using `status` for values, render the provided template with the theme and return
399a string that is suitable for printing to update the gauge.
Note: See TracBrowser for help on using the repository browser.