A nearly stateless terminal based horizontal gauge / progress bar.
var Gauge = require("gauge") var gauge = new Gauge() gauge.show("test", 0.20) gauge.pulse("this") gauge.hide()
var gauge = new Gauge([options], [ansiStream])
Constructs a new gauge. Gauges are drawn on a single line, and are not drawn if the current terminal isn't a tty.
If you resize your terminal in a way that can be detected then the gauge will be drawn at the new size. As a general rule, growing your terminal will be clean, but shrinking your terminal will result in cruft as we don't have enough information to know where what we wrote previously is now located.
The options object can have the following properties, all of which are optional:
show
and pulse
calls, but if you hide
and then show
the gauge it will draw it regardless of time since last draw.if the terminal supports unicode according to [has-unicode], otherwise it defaults to
Gauge.ascii`. Details on the theme object are documented elsewhere.If ansiStream isn't passed in, then one will be constructed from stderr with ansi(process.stderr)
.
gauge.show([name, [completed]])
If process.stdout.isTTY
is false then this does nothing. If completed is 0 and gauge.pulse
has never been called, then similarly nothing will be printed.
If maxUpdateFrequency
msec haven't passed since the last call to show
or pulse
then similarly, nothing will be printed. (Actually, the update is deferred until maxUpdateFrequency
msec have passed and if nothing else has happened, the gauge update will happen.)
gauge.hide()
Removes the gauge from the terminal.
gauge.pulse([name])
Spins the spinner in the gauge to show output. If name is included then it will be combined with the last name passed to gauge.show
using the subsection property of the theme (typically a right facing arrow).
gauge.disable()
Hides the gauge and ignores further calls to show
or pulse
.
gauge.enable()
Shows the gauge and resumes updating when show
or pulse
is called.
gauge.setTheme(theme)
Change the active theme, will be displayed with the next show or pulse
gauge.setTemplate(template)
Change the active template, will be displayed with the next show or pulse
There are two theme objects available as a part of the module, Gauge.unicode
and Gauge.ascii
. Theme objects have the follow properties:
Property | Unicode | ASCII |
---|---|---|
startgroup | ╢ | | |
endgroup | ╟ | | |
complete | █ | # |
incomplete | ░ | - |
spinner | ▀▐▄▌ | -\|/ |
subsection | → | -> |
startgroup, endgroup and subsection can be as many characters as you want.
complete and incomplete should be a single character width each.
spinner is a list of characters to use in turn when displaying an activity spinner. The Gauge will spin as many characters as you give here.
A template is an array of objects and strings that, after being evaluated, will be turned into the gauge line. The default template is:
[ {type: "name", separated: true, maxLength: 25, minLength: 25, align: "left"}, {type: "spinner", separated: true}, {type: "startgroup"}, {type: "completionbar"}, {type: "endgroup"} ]
The various template elements can either be plain strings, in which case they will be be included verbatum in the output.
If the template element is an object, it can have the following keys:
name
– The most recent name passed to show
; if this is in response to a pulse
then the name passed to pulse
will be appended along with the subsection property from the theme.spinner
– If you've ever called pulse
this will be one of the characters from the spinner property of the theme.startgroup
– The startgroup
property from the theme.completionbar
– This progress bar itselfendgroup
– The endgroup
property from the theme.If you have more than one thing going on that you want to track completion of, you may find the related are-we-there-yet helpful. It's change
event can be wired up to the show
method to get a more traditional progress bar interface.