"Fossies" - the Fresh Open Source Software Archive

Member "Atom/resources/app/apm/node_modules/gauge/README.md" (7 Feb 2017, 15008 Bytes) of archive /windows/misc/atom-windows.zip:

As a special service "Fossies" has tried to format the requested source page into HTML format (assuming markdown format). Alternatively you can here view or download the uninterpreted source code file. A member file download can also be achieved by clicking within a package contents listing on the according byte size field.


A nearly stateless terminal based horizontal gauge / progress bar.

var Gauge = require("gauge")

var gauge = new Gauge()

gauge.show("test", 0.20)




Gauge 2.x is breaking release, please see the changelog for details on what's changed if you were previously a user of this module.


This is the typical interface to the module– it provides a pretty fire-and-forget interface to displaying your status information.

var Gauge = require("gauge")

var gauge = new Gauge([stream], [options])

Constructs a new gauge. Gauges are drawn on a single line, and are not drawn if stream isn't a tty and a tty isn't explicitly provided.

If stream is a terminal or if you pass in tty to options then we will detect terminal resizes and redraw to fit. We do this by watching for resize events on the tty. (To work around a bug in verisons of Node prior to 2.5.0, we watch for them on stdout if the tty is stderr.) Resizes to larger window sizes will be clean, but shrinking the window will always result in some cruft.

IMPORTANT: If you prevously were passing in a non-tty stream but you still want output (for example, a stream wrapped by the ansi module) then you need to pass in the tty option below, as gauge needs access to the underlying tty in order to do things like terminal resizes and terminal width detection.

The options object can have the following properties, all of which are optional:

If no theme is selected then a default is picked using a combination of our best guesses at your OS, color support and unicode support. * template: Describes what you want your gauge to look like. The default is what npm uses. Detailed documentation is later in this document. * hideCursor: Defaults to true. If true, then the cursor will be hidden while the gauge is displayed. * tty: The tty that you're ultimately writing to. Defaults to the same as stream. This is used for detecting the width of the terminal and resizes. The width used is tty.columns - 1. If no tty is available then a width of 79 is assumed. * enabled: Defaults to true if tty is a TTY, false otherwise. If true the gauge starts enabled. If disabled then all update commands are ignored and no gauge will be printed until you call .enable(). * Plumbing: The class to use to actually generate the gauge for printing. This defaults to require('gauge/plumbing') and ordinarly you shouldn't need to override this. * cleanupOnExit: Defaults to true. Ordinarily we register an exit handler to make sure your cursor is turned back on and the progress bar erased when your process exits, even if you Ctrl-C out or otherwise exit unexpectedly. You can disable this and it won't register the exit handler.

gauge.show(section | status, [completed])

The first argument is either the section, the name of the current thing contributing to progress, or an object with keys like section, subsection & completed (or any others you have types for in a custom template). If you don't want to update or set any of these you can pass null and it will be ignored.

The second argument is the percent completed as a value between 0 and 1. Without it, completion is just not updated. You'll also note that completion can be passed in as part of a status object as the first argument. If both it and the completed argument are passed in, the completed argument wins.


Removes the gauge from the terminal. Optionally, callback cb after IO has had an opportunity to happen (currently this just means after setImmediate has called back.)

It turns out this is important when you're pausing the progress bar on one filehandle and printing to another– otherwise (with a big enough print) node can end up printing the "end progress bar" bits to the progress bar filehandle while other stuff is printing to another filehandle. These getting interleaved can cause corruption in some terminals.


Spins the spinner in the gauge to show output. If subsection is included then it will be combined with the last name passed to gauge.show.


Hides the gauge and ignores further calls to show or pulse.


Shows the gauge and resumes updating when show or pulse is called.


Change the themeset to select a theme from. The same as the themes option used in the constructor. The theme will be reselected from this themeset.


Change the active theme, will be displayed with the next show or pulse. This can be:

If no theme is selected then a default is picked using a combination of our best guesses at your OS, color support and unicode support.


Change the active template, will be displayed with the next show or pulse

Tracking Completion

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.


var themes = require('gauge/themes')

// fetch the default color unicode theme for this platform
var ourTheme = themes({hasUnicode: true, hasColor: true})

// fetch the default non-color unicode theme for osx
var ourTheme = themes({hasUnicode: true, hasColor: false, platform: 'darwin'})

// create a new theme based on the color ascii theme for this platform
// that brackets the progress bar with arrows
var ourTheme = themes.newTheme(theme(hasUnicode: false, hasColor: true}), {
  preProgressbar: '→',
  postProgressbar: '←'

The object returned by gauge/themes is an instance of the ThemeSet class.

var ThemeSet = require('gauge/theme-set')
var themes = new ThemeSet()
// or
var themes = require('gauge/themes')
var mythemes = themes.newThemeset() // creates a new themeset based on the default themes



Theme objects are a function that fetches the default theme based on platform, unicode and color support.

Options is an object with the following properties:

If no compatible theme can be found then an error will be thrown with a code of EMISSINGTHEME.

themes.addTheme(themeName, themeObj)

themes.addTheme(themeName, [parentTheme], newTheme)

Adds a named theme to the themeset. You can pass in either a theme object, as returned by themes.newTheme or the arguments you'd pass to themes.newTheme.


Return a list of all of the names of the themes in this themeset. Suitable for use in themes.getTheme(…).


Returns the theme object from this theme set named name.

If name does not exist in this themeset an error will be thrown with a code of EMISSINGTHEME.

themes.setDefault([opts], themeName)

opts is an object with the following properties.

themeName is the name of the theme (as given to addTheme) to use for this set of opts.

themes.newTheme([parentTheme,] newTheme)

Create a new theme object based on parentTheme. If no parentTheme is provided then a minimal parentTheme that defines functions for rendering the activity indicator (spinner) and progress bar will be defined. (This fallback parent is defined in gauge/base-theme.)

newTheme should be a bare object– we'll start by discussing the properties defined by the default themes:

More generally, themes can have any value that would be a valid value when rendering templates. The properties in the theme are used when their name matches a type in the template. Their values can be:

There are a couple of special prefixes:

And one special suffix:


This mixes-in theme into all themes currently defined. It also adds it to the default parent theme for this themeset, so future themes added to this themeset will get the values from theme by default.


Copy the current themeset into a new one. This allows you to easily inherit one themeset from another.


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: 'progressbar', length: 20},
    {type: 'activityIndicator', kerning: 1, length: 1},
    {type: 'section', kerning: 1, default: ''},
    {type: 'subsection', kerning: 1, default: ''}

The various template elements can either be plain strings, in which case they will be be included verbatum in the output, or objects with the following properties:


This is the super simple, assume nothing, do no magic internals used by gauge to implement its ordinary interface.

var Plumbing = require('gauge/plumbing')
var gauge = new Plumbing(theme, template, width)


Change the active theme.


Change the active template.


Change the width to render at.


Return the string necessary to hide the progress bar


Return a string to hide the cursor.


Return a string to show the cursor.


Using status for values, render the provided template with the theme and return a string that is suitable for printing to update the gauge.