pax_global_header 0000666 0000000 0000000 00000000064 14220416173 0014512 g ustar 00root root 0000000 0000000 52 comment=54452cfada7a690edb7e0fd4b6fabcef7ba1d567
gauge-4.0.4/ 0000775 0000000 0000000 00000000000 14220416173 0012607 5 ustar 00root root 0000000 0000000 gauge-4.0.4/.commitlintrc.js 0000664 0000000 0000000 00000000553 14220416173 0015732 0 ustar 00root root 0000000 0000000 /* This file is automatically added by @npmcli/template-oss. Do not edit. */
module.exports = {
extends: ['@commitlint/config-conventional'],
rules: {
'type-enum': [2, 'always', ['feat', 'fix', 'docs', 'deps', 'chore']],
'header-max-length': [2, 'always', 80],
'subject-case': [0, 'always', ['lower-case', 'sentence-case', 'start-case']],
},
}
gauge-4.0.4/.eslintrc.js 0000664 0000000 0000000 00000000511 14220416173 0015043 0 ustar 00root root 0000000 0000000 /* This file is automatically added by @npmcli/template-oss. Do not edit. */
const { readdirSync: readdir } = require('fs')
const localConfigs = readdir(__dirname)
.filter((file) => file.startsWith('.eslintrc.local.'))
.map((file) => `./${file}`)
module.exports = {
extends: [
'@npmcli',
...localConfigs,
],
}
gauge-4.0.4/.github/ 0000775 0000000 0000000 00000000000 14220416173 0014147 5 ustar 00root root 0000000 0000000 gauge-4.0.4/.github/CODEOWNERS 0000664 0000000 0000000 00000000132 14220416173 0015536 0 ustar 00root root 0000000 0000000 # This file is automatically added by @npmcli/template-oss. Do not edit.
* @npm/cli-team
gauge-4.0.4/.github/ISSUE_TEMPLATE/ 0000775 0000000 0000000 00000000000 14220416173 0016332 5 ustar 00root root 0000000 0000000 gauge-4.0.4/.github/ISSUE_TEMPLATE/bug.yml 0000664 0000000 0000000 00000002655 14220416173 0017642 0 ustar 00root root 0000000 0000000 # This file is automatically added by @npmcli/template-oss. Do not edit.
name: Bug
description: File a bug/issue
title: "[BUG]
"
labels: [ Bug, Needs Triage ]
body:
- type: checkboxes
attributes:
label: Is there an existing issue for this?
description: Please [search here](./issues) to see if an issue already exists for your problem.
options:
- label: I have searched the existing issues
required: true
- type: textarea
attributes:
label: Current Behavior
description: A clear & concise description of what you're experiencing.
validations:
required: false
- type: textarea
attributes:
label: Expected Behavior
description: A clear & concise description of what you expected to happen.
validations:
required: false
- type: textarea
attributes:
label: Steps To Reproduce
description: Steps to reproduce the behavior.
value: |
1. In this environment...
2. With this config...
3. Run '...'
4. See error...
validations:
required: false
- type: textarea
attributes:
label: Environment
description: |
examples:
- **npm**: 7.6.3
- **Node**: 13.14.0
- **OS**: Ubuntu 20.04
- **platform**: Macbook Pro
value: |
- npm:
- Node:
- OS:
- platform:
validations:
required: false
gauge-4.0.4/.github/ISSUE_TEMPLATE/config.yml 0000664 0000000 0000000 00000000145 14220416173 0020322 0 ustar 00root root 0000000 0000000 # This file is automatically added by @npmcli/template-oss. Do not edit.
blank_issues_enabled: true
gauge-4.0.4/.github/dependabot.yml 0000664 0000000 0000000 00000000565 14220416173 0017005 0 ustar 00root root 0000000 0000000 # This file is automatically added by @npmcli/template-oss. Do not edit.
version: 2
updates:
- package-ecosystem: npm
directory: "/"
schedule:
interval: daily
allow:
- dependency-type: direct
versioning-strategy: increase-if-necessary
commit-message:
prefix: deps
prefix-development: chore
labels:
- "Dependencies"
gauge-4.0.4/.github/settings.yml 0000664 0000000 0000000 00000000055 14220416173 0016532 0 ustar 00root root 0000000 0000000 ---
_extends: '.github:npm-cli/settings.yml'
gauge-4.0.4/.github/workflows/ 0000775 0000000 0000000 00000000000 14220416173 0016204 5 ustar 00root root 0000000 0000000 gauge-4.0.4/.github/workflows/audit.yml 0000664 0000000 0000000 00000001344 14220416173 0020037 0 ustar 00root root 0000000 0000000 # This file is automatically added by @npmcli/template-oss. Do not edit.
name: Audit
on:
workflow_dispatch:
schedule:
# "At 01:00 on Monday" https://crontab.guru/#0_1_*_*_1
- cron: "0 1 * * 1"
jobs:
audit:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- name: Setup git user
run: |
git config --global user.email "ops+npm-cli@npmjs.com"
git config --global user.name "npm cli ops bot"
- uses: actions/setup-node@v3
with:
node-version: 16.x
- name: Update npm to latest
run: npm i --prefer-online --no-fund --no-audit -g npm@latest
- run: npm -v
- run: npm i --ignore-scripts --package-lock
- run: npm audit
gauge-4.0.4/.github/workflows/ci.yml 0000664 0000000 0000000 00000005044 14220416173 0017325 0 ustar 00root root 0000000 0000000 # This file is automatically added by @npmcli/template-oss. Do not edit.
name: CI
on:
workflow_dispatch:
pull_request:
branches:
- '*'
push:
branches:
- main
- latest
schedule:
# "At 02:00 on Monday" https://crontab.guru/#0_2_*_*_1
- cron: "0 2 * * 1"
jobs:
lint:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- name: Setup git user
run: |
git config --global user.email "ops+npm-cli@npmjs.com"
git config --global user.name "npm cli ops bot"
- uses: actions/setup-node@v3
with:
node-version: 16.x
- name: Update npm to latest
run: npm i --prefer-online --no-fund --no-audit -g npm@latest
- run: npm -v
- run: npm i --ignore-scripts
- run: npm run lint
test:
strategy:
fail-fast: false
matrix:
node-version:
- 12.13.0
- 12.x
- 14.15.0
- 14.x
- 16.0.0
- 16.x
platform:
- os: ubuntu-latest
shell: bash
- os: macos-latest
shell: bash
- os: windows-latest
shell: cmd
runs-on: ${{ matrix.platform.os }}
defaults:
run:
shell: ${{ matrix.platform.shell }}
steps:
- uses: actions/checkout@v3
- name: Setup git user
run: |
git config --global user.email "ops+npm-cli@npmjs.com"
git config --global user.name "npm cli ops bot"
- uses: actions/setup-node@v3
with:
node-version: ${{ matrix.node-version }}
- name: Update to workable npm (windows)
# node 12 and 14 ship with npm@6, which is known to fail when updating itself in windows
if: matrix.platform.os == 'windows-latest' && (startsWith(matrix.node-version, '12.') || startsWith(matrix.node-version, '14.'))
run: |
curl -sO https://registry.npmjs.org/npm/-/npm-7.5.4.tgz
tar xf npm-7.5.4.tgz
cd package
node lib/npm.js install --no-fund --no-audit -g ..\npm-7.5.4.tgz
cd ..
rmdir /s /q package
- name: Update npm to 7
# If we do test on npm 10 it needs npm7
if: startsWith(matrix.node-version, '10.')
run: npm i --prefer-online --no-fund --no-audit -g npm@7
- name: Update npm to latest
if: ${{ !startsWith(matrix.node-version, '10.') }}
run: npm i --prefer-online --no-fund --no-audit -g npm@latest
- run: npm -v
- run: npm i --ignore-scripts
- run: npm test --ignore-scripts
gauge-4.0.4/.github/workflows/codeql-analysis.yml 0000664 0000000 0000000 00000002002 14220416173 0022011 0 ustar 00root root 0000000 0000000 # This file is automatically added by @npmcli/template-oss. Do not edit.
name: "CodeQL"
on:
push:
branches:
- main
- latest
pull_request:
# The branches below must be a subset of the branches above
branches:
- main
- latest
schedule:
# "At 03:00 on Monday" https://crontab.guru/#0_3_*_*_1
- cron: "0 3 * * 1"
jobs:
analyze:
name: Analyze
runs-on: ubuntu-latest
permissions:
actions: read
contents: read
security-events: write
strategy:
fail-fast: false
matrix:
language: [ javascript ]
steps:
- uses: actions/checkout@v3
- name: Setup git user
run: |
git config --global user.email "ops+npm-cli@npmjs.com"
git config --global user.name "npm cli ops bot"
- name: Initialize CodeQL
uses: github/codeql-action/init@v1
with:
languages: ${{ matrix.language }}
- name: Perform CodeQL Analysis
uses: github/codeql-action/analyze@v1
gauge-4.0.4/.github/workflows/post-dependabot.yml 0000664 0000000 0000000 00000002550 14220416173 0022021 0 ustar 00root root 0000000 0000000 # This file is automatically added by @npmcli/template-oss. Do not edit.
name: Post Dependabot Actions
on: pull_request
# https://docs.github.com/en/rest/overview/permissions-required-for-github-apps
permissions:
actions: write
contents: write
jobs:
Install:
runs-on: ubuntu-latest
if: github.actor == 'dependabot[bot]'
steps:
- uses: actions/checkout@v3
- name: Setup git user
run: |
git config --global user.email "ops+npm-cli@npmjs.com"
git config --global user.name "npm cli ops bot"
- uses: actions/setup-node@v3
with:
node-version: 16.x
- name: Update npm to latest
run: npm i --prefer-online --no-fund --no-audit -g npm@latest
- run: npm -v
- name: Dependabot metadata
id: metadata
uses: dependabot/fetch-metadata@v1.1.1
with:
github-token: "${{ secrets.GITHUB_TOKEN }}"
- name: npm install and commit
if: contains(steps.metadata.outputs.dependency-names, '@npmcli/template-oss')
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
run: |
gh pr checkout ${{ github.event.pull_request.number }}
npm install --ignore-scripts
npm run template-oss-apply
git add .
git commit -am "chore: postinstall for dependabot template-oss PR"
git push
gauge-4.0.4/.github/workflows/pull-request.yml 0000664 0000000 0000000 00000002144 14220416173 0021372 0 ustar 00root root 0000000 0000000 # This file is automatically added by @npmcli/template-oss. Do not edit.
name: Pull Request Linting
on:
pull_request:
types:
- opened
- reopened
- edited
- synchronize
jobs:
check:
name: Check PR Title or Commits
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
with:
fetch-depth: 0
- name: Setup git user
run: |
git config --global user.email "ops+npm-cli@npmjs.com"
git config --global user.name "npm cli ops bot"
- uses: actions/setup-node@v3
with:
node-version: 16.x
- name: Update npm to latest
run: npm i --prefer-online --no-fund --no-audit -g npm@latest
- run: npm -v
- name: Install deps
run: npm i -D @commitlint/cli @commitlint/config-conventional
- name: Check commits OR PR title
env:
PR_TITLE: ${{ github.event.pull_request.title }}
run: |
npx --offline commitlint -V --from origin/main --to ${{ github.event.pull_request.head.sha }} \
|| echo $PR_TITLE | npx --offline commitlint -V
gauge-4.0.4/.github/workflows/release-please.yml 0000664 0000000 0000000 00000001314 14220416173 0021615 0 ustar 00root root 0000000 0000000 # This file is automatically added by @npmcli/template-oss. Do not edit.
name: Release Please
on:
push:
branches:
- main
- latest
jobs:
release-please:
runs-on: ubuntu-latest
steps:
- uses: google-github-actions/release-please-action@v3
id: release
with:
release-type: node
changelog-types: >
[
{"type":"feat","section":"Features","hidden":false},
{"type":"fix","section":"Bug Fixes","hidden":false},
{"type":"docs","section":"Documentation","hidden":false},
{"type":"deps","section":"Dependencies","hidden":false},
{"type":"chore","hidden":true}
]
gauge-4.0.4/.gitignore 0000664 0000000 0000000 00000000543 14220416173 0014601 0 ustar 00root root 0000000 0000000 # This file is automatically added by @npmcli/template-oss. Do not edit.
# ignore everything in the root
/*
# keep these
!/.eslintrc.local.*
!**/.gitignore
!/docs/
!/tap-snapshots/
!/test/
!/map.js
!/scripts/
!/README*
!/LICENSE*
!/CHANGELOG*
!/.commitlintrc.js
!/.eslintrc.js
!/.github/
!/.gitignore
!/.npmrc
!/SECURITY.md
!/bin/
!/lib/
!/package.json
gauge-4.0.4/.npmrc 0000664 0000000 0000000 00000000135 14220416173 0013726 0 ustar 00root root 0000000 0000000 ; This file is automatically added by @npmcli/template-oss. Do not edit.
package-lock=false
gauge-4.0.4/CHANGELOG.md 0000664 0000000 0000000 00000020543 14220416173 0014424 0 ustar 00root root 0000000 0000000 # Changelog
### [4.0.4](https://github.com/npm/gauge/compare/v4.0.3...v4.0.4) (2022-03-28)
### Bug Fixes
* fix always true condition ([#160](https://github.com/npm/gauge/issues/160)) ([bebaf0b](https://github.com/npm/gauge/commit/bebaf0b0655f0bdc58a6548b04230cd420245e5e))
### v4.0.0
* BREAKING CHANGE: Drops support for Node v10 and non-LTS versions of v12 and v14
* feat: install template-oss
* fix: repository metadata
* fix: Typo in package.json
* fix: Remove remaining uses of object-assign
* fix: remove object-assign
### [4.0.3](https://www.github.com/npm/gauge/compare/v4.0.2...v4.0.3) (2022-03-10)
### Bug Fixes
* move demo.js to the docs folder ([#155](https://www.github.com/npm/gauge/issues/155)) ([1faf8cf](https://www.github.com/npm/gauge/commit/1faf8cf25c0bffb345f6657e20743d83c54d6695))
### Dependencies
* remove the unused direct ansi-regex dependency ([#156](https://www.github.com/npm/gauge/issues/156)) ([65be798](https://www.github.com/npm/gauge/commit/65be79895801433e02aef58cafb6f31a87287e59))
### [4.0.2](https://www.github.com/npm/gauge/compare/v4.0.1...v4.0.2) (2022-02-16)
### Dependencies
* update color-support requirement from ^1.1.2 to ^1.1.3 ([5921a0f](https://www.github.com/npm/gauge/commit/5921a0f89e6c4c10ea047a219230809fd4118409))
* update console-control-strings requirement from ^1.0.0 to ^1.1.0 ([a5ac787](https://www.github.com/npm/gauge/commit/a5ac787a3771e8882f9837fab08ca2985cad609f))
* update signal-exit requirement from ^3.0.0 to ^3.0.7 ([3e0d399](https://www.github.com/npm/gauge/commit/3e0d39917b10e0f94efd4a4c74a46fa8e21e768a))
* update wide-align requirement from ^1.1.2 to ^1.1.5 ([ddc9048](https://www.github.com/npm/gauge/commit/ddc90480a6c1caa8c176e0b65a9d8207be846f94))
### [4.0.1](https://www.github.com/npm/gauge/compare/v4.0.0...v4.0.1) (2022-02-15)
### Bug Fixes
* use more commonly available character for pre/post progressbar ([#141](https://www.github.com/npm/gauge/issues/141)) ([13d3046](https://www.github.com/npm/gauge/commit/13d30466b56015cb75df366371cf85234a8a517f))
### v3.0.1
* deps: object-assign@4.1.1
### v3.0.0
* BREAKING CHANGE: Drops support for Node v4, v6, v7 and v8
### v2.7.4
* Reset colors prior to ending a line, to eliminate flicker when a line
is trucated between start and end color sequences.
### v2.7.3
* Only create our onExit handler when we're enabled and remove it when we're
disabled. This stops us from creating multiple onExit handlers when
multiple gauge objects are being used.
* Fix bug where if a theme name were given instead of a theme object, it
would crash.
* Remove supports-color because it's not actually used. Uhm. Yes, I just
updated it. >.>
### v2.7.2
* Use supports-color instead of has-color (as the module has been renamed)
### v2.7.1
* Bug fix: Calls to show/pulse while the progress bar is disabled should still
update our internal representation of what would be shown should it be enabled.
### v2.7.0
* New feature: Add new `isEnabled` method to allow introspection of the gauge's
"enabledness" as controlled by `.enable()` and `.disable()`.
### v2.6.0
* Bug fix: Don't run the code associated with `enable`/`disable` if the gauge
is already enabled or disabled respectively. This prevents leaking event
listeners, amongst other weirdness.
* New feature: Template items can have default values that will be used if no
value was otherwise passed in.
### v2.5.3
* Default to `enabled` only if we have a tty. Users can always override
this by passing in the `enabled` option explicitly or by calling calling
`gauge.enable()`.
### v2.5.2
* Externalized `./console-strings.js` into `console-control-strings`.
### v2.5.1
* Update to `signal-exit@3.0.0`, which fixes a compatibility bug with the
node profiler.
* [#39](https://github.com/iarna/gauge/pull/39) Fix tests on 0.10 and add
a missing devDependency. ([@helloyou2012](https://github.com/helloyou2012))
### v2.5.0
* Add way to programmatically fetch a list of theme names in a themeset
(`Themeset.getThemeNames`).
### v2.4.0
* Add support for setting themesets on existing gauge objects.
* Add post-IO callback to `gauge.hide()` as it is somtetimes necessary when
your terminal is interleaving output from multiple filehandles (ie, stdout
& stderr).
### v2.3.1
* Fix a refactor bug in setTheme where it wasn't accepting the various types
of args it should.
### v2.3.0
#### FEATURES
* Add setTemplate & setTheme back in.
* Add support for named themes, you can now ask for things like 'colorASCII'
and 'brailleSpinner'. Of course, you can still pass in theme objects.
Additionally you can now pass in an object with `hasUnicode`, `hasColor` and
`platform` keys in order to override our guesses as to those values when
selecting a default theme from the themeset.
* Make the output stream optional (it defaults to `process.stderr` now).
* Add `setWriteTo(stream[, tty])` to change the output stream and,
optionally, tty.
#### BUG FIXES & REFACTORING
* Abort the display phase early if we're supposed to be hidden and we are.
* Stop printing a bunch of spaces at the end of lines, since we're already
using an erase-to-end-of-line code anyway.
* The unicode themes were missing the subsection separator.
### v2.2.1
* Fix image in readme
### v2.2.0
* All new themes API– reference themes by name and pass in custom themes and
themesets (themesets get platform support autodetection done on them to
select the best theme). Theme mixins let you add features to all existing
themes.
* Much, much improved test coverage.
### v2.1.0
* Got rid of ░ in the default platform, noUnicode, hasColor theme. Thanks
to @yongtw123 for pointing out this had snuck in.
* Fiddled with the demo output to make it easier to see the spinner spin. Also
added prints before each platforms test output.
* I forgot to include `signal-exit` in our deps. <.< Thank you @KenanY for
finding this. Then I was lazy and made a new commit instead of using his
PR. Again, thank you for your patience @KenenY.
* Drastically speed up travis testing.
* Add a small javascript demo (demo.js) for showing off the various themes
(and testing them on diff platforms).
* Change: The subsection separator from ⁄ and / (different chars) to >.
* Fix crasher: A show or pulse without a label would cause the template renderer
to complain about a missing value.
* New feature: Add the ability to disable the clean-up-on-exit behavior.
Not something I expect to be widely desirable, but important if you have
multiple distinct gauge instances in your app.
* Use our own color support detection.
The `has-color` module proved too magic for my needs, making assumptions
as to which stream we write to and reading command line arguments.
### v2.0.0
This is a major rewrite of the internals. Externally there are fewer
changes:
* On node>0.8 gauge object now prints updates at a fixed rate. This means
that when you call `show` it may wate up to `updateInterval` ms before it
actually prints an update. You override this behavior with the
`fixedFramerate` option.
* The gauge object now keeps the cursor hidden as long as it's enabled and
shown.
* The constructor's arguments have changed, now it takes a mandatory output
stream and an optional options object. The stream no longer needs to be
an `ansi`ified stream, although it can be if you want (but we won't make
use of its special features).
* Previously the gauge was disabled by default if `process.stdout` wasn't a
tty. Now it always defaults to enabled. If you want the previous
behavior set the `enabled` option to `process.stdout.isTTY`.
* The constructor's options have changed– see the docs for details.
* Themes are entirely different. If you were using a custom theme, or
referring to one directly (eg via `Gauge.unicode` or `Gauge.ascii`) then
you'll need to change your code. You can get the equivalent of the latter
with:
```
var themes = require('gauge/themes')
var unicodeTheme = themes(true, true) // returns the color unicode theme for your platform
```
The default themes no longer use any ambiguous width characters, so even
if you choose to display those as wide your progress bar should still
display correctly.
* Templates are entirely different and if you were using a custom one, you
should consult the documentation to learn how to recreate it. If you were
using the default, be aware that it has changed and the result looks quite
a bit different.
gauge-4.0.4/LICENSE.md 0000664 0000000 0000000 00000001436 14220416173 0014217 0 ustar 00root root 0000000 0000000
ISC License
Copyright npm, Inc.
Permission to use, copy, modify, and/or distribute this
software for any purpose with or without fee is hereby
granted, provided that the above copyright notice and this
permission notice appear in all copies.
THE SOFTWARE IS PROVIDED "AS IS" AND NPM DISCLAIMS ALL
WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO
EVENT SHALL NPM BE LIABLE FOR ANY SPECIAL, DIRECT,
INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS,
WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE
USE OR PERFORMANCE OF THIS SOFTWARE.
gauge-4.0.4/README.md 0000664 0000000 0000000 00000036077 14220416173 0014103 0 ustar 00root root 0000000 0000000 gauge
=====
A nearly stateless terminal based horizontal gauge / progress bar.
```javascript
var Gauge = require("gauge")
var gauge = new Gauge()
gauge.show("working…", 0)
setTimeout(() => { gauge.pulse(); gauge.show("working…", 0.25) }, 500)
setTimeout(() => { gauge.pulse(); gauge.show("working…", 0.50) }, 1000)
setTimeout(() => { gauge.pulse(); gauge.show("working…", 0.75) }, 1500)
setTimeout(() => { gauge.pulse(); gauge.show("working…", 0.99) }, 2000)
setTimeout(() => gauge.hide(), 2300)
```
See also the [demos](docs/demo.js):

### CHANGES FROM 1.x
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.
[changelog]: CHANGELOG.md
### THE GAUGE CLASS
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])
```
* **stream** – *(optional, default STDERR)* A stream that progress bar
updates are to be written to. Gauge honors backpressure and will pause
most writing if it is indicated.
* **options** – *(optional)* An option object.
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 versions 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 previously 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:
* **updateInterval**: How often gauge updates should be drawn, in milliseconds.
* **fixedFramerate**: Defaults to false on node 0.8, true on everything
else. When this is true a timer is created to trigger once every
`updateInterval` ms, when false, updates are printed as soon as they come
in but updates more often than `updateInterval` are ignored. The reason
0.8 doesn't have this set to true is that it can't `unref` its timer and
so it would stop your program from exiting– if you want to use this
feature with 0.8 just make sure you call `gauge.disable()` before you
expect your program to exit.
* **themes**: A themeset to use when selecting the theme to use. Defaults
to `gauge/themes`, see the [themes] documentation for details.
* **theme**: Select a theme for use, it can be a:
* Theme object, in which case the **themes** is not used.
* The name of a theme, which will be looked up in the current *themes*
object.
* A configuration object with any of `hasUnicode`, `hasColor` or
`platform` keys, which if will be used to override our guesses when making
a default theme selection.
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 ordinarily 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.
[has-unicode]: https://www.npmjs.com/package/has-unicode
[themes]: #themes
[documentation]: #templates
#### `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.
#### `gauge.hide([cb])`
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.
#### `gauge.pulse([subsection])`
* **subsection** – *(optional)* The specific thing that triggered this pulse
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`.
#### `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.isEnabled()`
Returns true if the gauge is enabled.
#### `gauge.setThemeset(themes)`
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.
#### `gauge.setTheme(theme)`
Change the active theme, will be displayed with the next show or pulse. This can be:
* Theme object, in which case the **themes** is not used.
* The name of a theme, which will be looked up in the current *themes*
object.
* A configuration object with any of `hasUnicode`, `hasColor` or
`platform` keys, which if will be used to override our guesses when making
a default theme selection.
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.
#### `gauge.setTemplate(template)`
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.
[are-we-there-yet]: https://www.npmjs.com/package/are-we-there-yet
### THEMES
```
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(themes({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
```
#### themes(opts)
#### themes.getDefault(opts)
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:
* **hasUnicode** - If true, fetch a unicode theme, if no unicode theme is
available then a non-unicode theme will be used.
* **hasColor** - If true, fetch a color theme, if no color theme is
available a non-color theme will be used.
* **platform** (optional) - Defaults to `process.platform`. If no
platform match is available then `fallback` is used instead.
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`.
#### themes.getThemeNames()
Return a list of all of the names of the themes in this themeset. Suitable
for use in `themes.getTheme(…)`.
#### themes.getTheme(name)
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.
* **platform** - Defaults to `'fallback'`. If your theme is platform
specific, specify that here with the platform from `process.platform`, eg,
`win32`, `darwin`, etc.
* **hasUnicode** - Defaults to `false`. If your theme uses unicode you
should set this to true.
* **hasColor** - Defaults to `false`. If your theme uses color you should
set this to true.
`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:
* **preProgressbar** - displayed prior to the progress bar, if the progress
bar is displayed.
* **postProgressbar** - displayed after the progress bar, if the progress bar
is displayed.
* **progressBarTheme** - The subtheme passed through to the progress bar
renderer, it's an object with `complete` and `remaining` properties
that are the strings you want repeated for those sections of the progress
bar.
* **activityIndicatorTheme** - The theme for the activity indicator (spinner),
this can either be a string, in which each character is a different step, or
an array of strings.
* **preSubsection** - Displayed as a separator between the `section` and
`subsection` when the latter is printed.
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:
* **strings & numbers** - They'll be included as is
* **function (values, theme, width)** - Should return what you want in your output.
*values* is an object with values provided via `gauge.show`,
*theme* is the theme specific to this item (see below) or this theme object,
and *width* is the number of characters wide your result should be.
There are a couple of special prefixes:
* **pre** - Is shown prior to the property, if its displayed.
* **post** - Is shown after the property, if its displayed.
And one special suffix:
* **Theme** - Its value is passed to a function-type item as the theme.
#### themes.addToAllThemes(theme)
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.
#### themes.newThemeSet()
Copy the current themeset into a new one. This allows you to easily inherit
one themeset from another.
### TEMPLATES
A template is an array of objects and strings that, after being evaluated,
will be turned into the gauge line. The default template is:
```javascript
[
{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:
* *type* can be any of the following plus any keys you pass into `gauge.show` plus
any keys you have on a custom theme.
* `section` – What big thing you're working on now.
* `subsection` – What component of that thing is currently working.
* `activityIndicator` – Shows a spinner using the `activityIndicatorTheme`
from your active theme.
* `progressbar` – A progress bar representing your current `completed`
using the `progressbarTheme` from your active theme.
* *kerning* – Number of spaces that must be between this item and other
items, if this item is displayed at all.
* *maxLength* – The maximum length for this element. If its value is longer it
will be truncated.
* *minLength* – The minimum length for this element. If its value is shorter it
will be padded according to the *align* value.
* *align* – (Default: left) Possible values "left", "right" and "center". Works
as you'd expect from word processors.
* *length* – Provides a single value for both *minLength* and *maxLength*. If both
*length* and *minLength or *maxLength* are specified then the latter take precedence.
* *value* – A literal value to use for this template item.
* *default* – A default value to use for this template item if a value
wasn't otherwise passed in.
### PLUMBING
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)
```
* **theme**: The theme to use.
* **template**: The template to use.
* **width**: How wide your gauge should be
#### `gauge.setTheme(theme)`
Change the active theme.
#### `gauge.setTemplate(template)`
Change the active template.
#### `gauge.setWidth(width)`
Change the width to render at.
#### `gauge.hide()`
Return the string necessary to hide the progress bar
#### `gauge.hideCursor()`
Return a string to hide the cursor.
#### `gauge.showCursor()`
Return a string to show the cursor.
#### `gauge.show(status)`
Using `status` for values, render the provided template with the theme and return
a string that is suitable for printing to update the gauge.
gauge-4.0.4/SECURITY.md 0000664 0000000 0000000 00000000246 14220416173 0014402 0 ustar 00root root 0000000 0000000
Please send vulnerability reports through [hackerone](https://hackerone.com/github).
gauge-4.0.4/docs/ 0000775 0000000 0000000 00000000000 14220416173 0013537 5 ustar 00root root 0000000 0000000 gauge-4.0.4/docs/demo.js 0000664 0000000 0000000 00000001631 14220416173 0015022 0 ustar 00root root 0000000 0000000 var Gauge = require('..')
var gaugeDefault = require('../lib/themes.js')
var onExit = require('signal-exit')
var activeGauge
onExit(function () {
activeGauge.disable()
})
var themes = gaugeDefault.getThemeNames()
nextBar()
function nextBar () {
var themeName = themes.shift()
console.log('Demoing output for ' + themeName)
var gt = new Gauge(process.stderr, {
updateInterval: 50,
theme: themeName,
cleanupOnExit: false,
})
activeGauge = gt
var progress = 0
var cnt = 0
var pulse = setInterval(function () {
gt.pulse('this is a thing that happened ' + (++cnt))
}, 110)
var prog = setInterval(function () {
progress += 0.04
gt.show(themeName + ':' + Math.round(progress * 1000), progress)
if (progress >= 1) {
clearInterval(prog)
clearInterval(pulse)
gt.disable()
if (themes.length) {
nextBar()
}
}
}, 100)
gt.show()
}
gauge-4.0.4/docs/gauge-demo.gif 0000664 0000000 0000000 00000671517 14220416173 0016261 0 ustar 00root root 0000000 0000000 GIF87a ):60:C@:3 ;U*;SB;-N;"4<;?'=h[=4M>16A]6Af[A'5BU9CK-EC+F^AFCDGLLGCSG93H~aI.9JYMMMOM/ZM=aM3hMMCNYLNdROMdPB:QgOQT[QLNRkOS\AT}BTkeT4hT<=UshUKUN8V