cli-progress - npm Package Compare versions

Comparing version 1.5.1 to 1.6.0

CHANGES.md

@@ -0,1 +1,4 @@
+### 1.6.0 ###
+* Added: Additional payload data which can be used as **custom-tokens** within the bar - thanks to [tobiasps on GitHub](https://github.com/AndiDittrich/Node.CLI-Progress/pull/15) #15
+
 ### 1.5.1 ###
@@ -2,0 +5,0 @@ * Bugifx: Progressbar cannot be initialized to 0% - thanks to [erikkallen on GitHub](https://github.com/AndiDittrich/Node.CLI-Progress/pull/14) #13

example.js

@@ -8,3 +8,5 @@ var _progress = require('./main');
             Example4(function(){
-                console.log('\nDemo finished!');
+                Example5(function(){
+                    console.log('\nDemo finished!');
+                });
             });
@@ -126,1 +128,46 @@ });
 }
+
+function Example5(onComplete){
+    // EXAMPLE 5 ---------------------------------------------
+    console.log('\nExample 5 - Custom Payload');
+    // create new progress bar
+    var b1 = new _progress.Bar({
+        format: 'progress [{bar}] {percentage}% | ETA: {eta}s | {value}/{total} | Speed: {speed}'
+    });
+
+    // initialize the bar -  defining payload token "speed" with the default value "N/A"
+    b1.start(200, 0, {
+        speed: "N/A"
+    });
+
+    // the bar value - will be linear incremented
+    var value = 0;
+
+    var speedData = [];
+
+    // 20ms update rate
+    var timer = setInterval(function(){
+        // increment value
+        value++;
+
+        // example speed data
+        speedData.push(Math.random()*2+5);
+        var currentSpeedData = speedData.splice(-10);
+
+        // update the bar value
+        b1.update(value, {
+            speed: (currentSpeedData.reduce(function(a, b) { return a + b; }, 0) / currentSpeedData.length).toFixed(2) + "mb/s"
+        });
+
+        // set limit
+        if (value >= b1.getTotal()){
+            // stop timer
+            clearInterval(timer);
+
+            b1.stop();
+
+            // run complete callback
+            onComplete.apply(this);
+        }
+    }, 20);
+}

lib/Bar.js

@@ -64,2 +64,5 @@ var _readline = require('readline');
     this.eta = {};
+
+    // payload data
+    this.payload = {};
 };
@@ -113,2 +116,8 @@
 
+    // assign payload placeholder tokens
+    for (var key in this.payload) {
+        var pattern = RegExp('{'+key+'}', 'gi');
+        s = s.replace(pattern, this.payload[key]);
+    }
+
     // string changed ? only trigger redraw on change!
@@ -157,6 +166,7 @@ if (this.lastDrawnString != s){
 // start the progress bar
-Bar.prototype.start = function(total, startValue){
+Bar.prototype.start = function(total, startValue, payload){
     // set initial values
     this.value = startValue || 0;
     this.total = (typeof total !== 'undefined' && total >= 0) ? total : 100;
+    this.payload = payload || {};
 
@@ -217,3 +227,3 @@ this.startTime = Date.now();
 // update the bar value
-Bar.prototype.update = function(current){
+Bar.prototype.update = function(current, payload){
     // update value
@@ -231,2 +241,7 @@ this.value = current;
 
+    var payloadData = payload || {};
+    for (var key in payloadData){
+        this.payload[key] = payloadData[key];
+    }
+
     // throttle the update or force update ?
@@ -233,0 +248,0 @@ if (this.lastRedraw + this.throttleTime < Date.now()){

package.json

 {
   "name": "cli-progress",
-  "version": "1.5.1",
+  "version": "1.6.0",
   "description": "Easy to use Progress-Bar for Command-Line/Terminal Applications",
@@ -5,0 +5,0 @@ "keywords": [

README.md

@@ -5,12 +5,14 @@ CLI-Progress
 
+![Demo](assets/cli-progress.gif)
+
+![Demo](assets/presets.png)
+
+Install
+--------
+
 ```bash
-$ npm install cli-progress
+$ npm install cli-progress --save
+$ yarn add cli-progress --save
 ```
 
-![Demo](assets/video.gif)
-
-Presets
--------
-![Demo](assets/presets.png)
-
 Features
@@ -24,2 +26,3 @@ --------
 * ETA calculation based on elapsed time
+* Custom Tokens to display additional data (payload) within the bar
 * Only visible in TTY environments
@@ -30,29 +33,8 @@ * No callbacks required - designed as pure, external controlled UI widget
 
-*Successful tested on Windows10, Debian 8 and Ubuntu 14,15,16*
 
-Installation
+Usage
 ------------
 
-You can install cli-progress with [NPM](http://www.npmjs.com/package/cli-progress)
+Multiple examples are available e.g. [example.js](https://github.com/AndiDittrich/Node.CLI-Progress/blob/master/example.js) - just try it `$ node example.js` 
 
-```bash
-$ npm install cli-progress
-$ yarn add cli-progress
-```
-
-Or manually from the [GitHub Repository](https://github.com/AndiDittrich/Node.CLI-Progress/releases/latest)
-
-```bash
-$ wget https://github.com/AndiDittrich/Node.CLI-Progress/archive/v1.4.0.tar.gz
-```
-
-Progress-Bar
-------------
-
-### Getting Started ###
-
-You can find some basic examples in [example.js](https://github.com/AndiDittrich/Node.CLI-Progress/blob/master/example.js) - just run the file with `$ node example.js` 
-
-### Usage ###
-
 ```js
@@ -74,5 +56,6 @@ var _progress = require('cli-progress');
 
-### Methods/Syntax ###
+Methods/Syntax
+-----------------------------------
 
-#### Constructor ####
+### Constructor ###
 
@@ -82,22 +65,35 @@ Initialize a new Progress bar. An instance can be used **multiple** times! it's not required to re-create it!
 ```js
-var <instance> = new namespace.Bar(options:object, preset:object);
+var <instance> = new namespace.Bar(options:object [, preset:object]);
 ```
 
-#### start() ####
+#### Options ####
 
+- `format` (type:string) - progress bar output format @see format section
+- `fps` (type:float) - the maximum update rate (default: 10)
+- `stream` (type:stream) - output stream to use (default: `process.stderr`)
+- `stopOnComplete` (type:boolean) - automatically call `stop()` when the value reaches the total (default: false)
+- `clearOnComplete` (type:boolean) - clear the progress bar on complete / `stop()` call (default: false)
+- `barsize` (type:int) - the length of the progress bar in chars (default: 40)
+- `barCompleteString` (type:char) - character to use as "complete" indicator in the bar (default: "=")
+- `barIncompleteString` (type:char) - character to use as "incomplete" indicator in the bar (default: "-")
+- `hideCursor` (type:boolean) - hide the cursor during progress operation; restored on complete (default: false)
+- `etaBuffer` (type:int) - number of updates with which to calculate the eta; higher numbers give a more stable eta (default: 10)
+
+### ::start() ###
+
 Starts the progress bar and set the total and initial value
 
 ```js
-<instance>.start(totalValue:int, startValue:int);
+<instance>.start(totalValue:int, startValue:int [, payload:object = {}]);
 ```
 
-#### update() ####
+### ::update() ###
 
-Sets the current progress value
+Sets the current progress value and optionally the payload with values of custom tokens as a second parameter
 
 ```js
-<instance>.update(currentValue:int);
+<instance>.update(currentValue:int [, payload:object = {}]);
 ```
 
-#### increment() ####
+### ::increment() ###
 
@@ -110,3 +106,3 @@ Increases the current progress value by a specified amount (default +1)
 
-#### stop() ####
+### ::stop() ###
 
@@ -120,3 +116,4 @@ Stops the progress bar and go to next line
 
-### Bar Formatting ###
+Bar Formatting
+-----------------------------------
 
@@ -134,3 +131,3 @@ The progressbar can be customized by using the following build-in placeholders. They can be combined in any order.
 
-#### Example ####
+### Example ###
 
@@ -147,17 +144,7 @@ ```
 
-### Options ###
+Examples
+---------------------------------------------
 
-- `format` (type:string) - progress bar output format @see format section
-- `fps` (type:float) - the maximum update rate (default: 10)
-- `stream` (type:stream) - output stream to use (default: `process.stderr`)
-- `stopOnComplete` (type:boolean) - automatically call `stop()` when the value reaches the total (default: false)
-- `clearOnComplete` (type:boolean) - clear the progress bar on complete / `stop()` call (default: false)
-- `barsize` (type:int) - the length of the progress bar in chars (default: 40)
-- `barCompleteString` (type:char) - character to use as "complete" indicator in the bar (default: "=")
-- `barIncompleteString` (type:char) - character to use as "incomplete" indicator in the bar (default: "-")
-- `hideCursor` (type:boolean) - hide the cursor during progress operation; restored on complete (default: false)
-- `etaBuffer` (type:int) - number of updates with which to calculate the eta; higher numbers give a more stable eta (default: 10)
+### Example 1 - Set Options ###
 
-#### Example ####
-
 ```js
@@ -167,3 +154,3 @@ // change the progress characters
 // change the output stream and barsize
-var b2 = new _progress.Bar({
+var bar = new _progress.Bar({
     barCompleteChar: '#',
@@ -177,2 +164,62 @@ barIncompleteChar: '.',
 
+### Example 2 - Change Styles defined by Preset ###
+
+```js
+// uee shades preset
+// change the barsize
+var bar = new _progress.Bar({
+    barsize: 65
+}, _progress.Presets.shades_grey);
+```
+
+### Example 3 - Custom Payload ###
+
+```js
+// create new progress bar with custom token "speed"
+var bar = new _progress.Bar({
+    format: 'progress [{bar}] {percentage}% | ETA: {eta}s | {value}/{total} | Speed: {speed} kbit'
+});
+
+// initialize the bar - set payload token "speed" with the default value "N/A"
+bar.start(200, 0, {
+    speed: "N/A"
+});
+
+// some code/update loop
+// ...
+
+// update bar value. set custom token "speed" to 125
+bar.update(5, {
+    speed: '125'
+});
+
+// process finished
+bar.stop();
+```
+
+### Example 4 - Custom Presets ###
+
+**File** `mypreset.js`
+
+```js
+var _colors = require('colors');
+
+module.exports = {
+    format: _colors.red(' {bar}') + ' {percentage}% | ETA: {eta}s | {value}/{total} | Speed: {speed} kbit',
+    barCompleteChar: '\u2588',
+    barIncompleteChar: '\u2591'
+};
+```
+
+**Application**
+
+```js
+var _mypreset = require('./mypreset.js');
+
+var bar = new _progress.Bar({
+    barsize: 65
+}, _mypreset);
+```
+
+
 Presets/Themes
@@ -179,0 +226,0 @@ ---------------------------------------------

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

25913

increased by12.58%

Lines of code

441

increased by12.5%

Number of lines in readme file

236

increased by24.87%

No dependency changes