resin-cli-visuals
Version:
362 lines (281 loc) • 10.3 kB
Markdown
resin-cli-visuals
-----------------
[](https://npmjs.com/package/resin-cli-visuals)
[](https://npmjs.com/package/resin-cli-visuals)
[](https://npmjs.com/package/resin-cli-visuals)
[](https://travis-ci.org/resin-io-modules/resin-cli-visuals/branches)
[](https://ci.appveyor.com/project/resin-io/resin-cli-visuals/branch/master)
[](https://david-dm.org/resin-io-modules/resin-cli-visuals)
Join our online chat at [](https://gitter.im/resin-io/chat)
Resin CLI UI widgets.
Role
----
The intention of this module is to provide a collection of command line widgets to be used by the Resin CLI and its plugins.
Installation
------------
Install `resin-cli-visuals` by running:
```sh
$ npm install --save resin-cli-visuals
```
Documentation
-------------
## Classes
<dl>
<dt><a href="#DriveScanner">DriveScanner</a></dt>
<dd></dd>
</dl>
## Objects
<dl>
<dt><a href="#visuals">visuals</a> : <code>object</code></dt>
<dd></dd>
</dl>
<a name="DriveScanner"></a>
## DriveScanner
**Kind**: global class
**Summary**: Dynamically detect changes of connected drives
**Access**: protected
* [DriveScanner](#DriveScanner)
* [new DriveScanner(driveFinder, [options])](#new_DriveScanner_new)
* [.stop()](#DriveScanner+stop)
<a name="new_DriveScanner_new"></a>
### new DriveScanner(driveFinder, [options])
| Param | Type | Default | Description |
| --- | --- | --- | --- |
| driveFinder | <code>function</code> | | drive finder |
| [options] | <code>Object</code> | | scan options |
| [options.interval] | <code>Number</code> | <code>1000</code> | interval |
| [options.drives] | <code>Array.<Object></code> | | current drives |
**Example**
```js
scanner = new DriveScanner driveFinder,
interval: 1000
drives: [
{ foo: 'bar' }
]
```
<a name="DriveScanner+stop"></a>
### driveScanner.stop()
**Kind**: instance method of [<code>DriveScanner</code>](#DriveScanner)
**Summary**: Stop the interval
**Access**: public
**Example**
```js
scanner = new DriveScanner(@driveFinder, interval: 1000)
scanner.stop()
```
<a name="visuals"></a>
## visuals : <code>object</code>
**Kind**: global namespace
* [visuals](#visuals) : <code>object</code>
* [.Spinner](#visuals.Spinner)
* [new Spinner(message)](#new_visuals.Spinner_new)
* [.start()](#visuals.Spinner+start)
* [.stop()](#visuals.Spinner+stop)
* [.Progress](#visuals.Progress)
* [new Progress(message)](#new_visuals.Progress_new)
* [.update(state)](#visuals.Progress+update)
* [.SpinnerPromise](#visuals.SpinnerPromise)
* [new SpinnerPromise(options)](#new_visuals.SpinnerPromise_new)
* [.table](#visuals.table) : <code>object</code>
* [.horizontal(data, ordering)](#visuals.table.horizontal)
* [.vertical(data, ordering)](#visuals.table.vertical)
* [.drive([message])](#visuals.drive) ⇒ <code>Promise.<String></code>
<a name="visuals.Spinner"></a>
### visuals.Spinner
**Kind**: static class of [<code>visuals</code>](#visuals)
**Summary**: Create a CLI Spinner
**Access**: public
* [.Spinner](#visuals.Spinner)
* [new Spinner(message)](#new_visuals.Spinner_new)
* [.start()](#visuals.Spinner+start)
* [.stop()](#visuals.Spinner+stop)
<a name="new_visuals.Spinner_new"></a>
#### new Spinner(message)
**Returns**: <code>Spinner</code> - spinner instance
**Throws**:
- Will throw if no message.
| Param | Type | Description |
| --- | --- | --- |
| message | <code>String</code> | message |
**Example**
```js
spinner = new visuals.Spinner('Hello World')
```
<a name="visuals.Spinner+start"></a>
#### spinner.start()
**Kind**: instance method of [<code>Spinner</code>](#visuals.Spinner)
**Summary**: Start the spinner
**Access**: public
**Example**
```js
spinner = new visuals.Spinner('Hello World')
spinner.start()
```
<a name="visuals.Spinner+stop"></a>
#### spinner.stop()
**Kind**: instance method of [<code>Spinner</code>](#visuals.Spinner)
**Summary**: Stop the spinner
**Access**: public
**Example**
```js
spinner = new visuals.Spinner('Hello World')
spinner.stop()
```
<a name="visuals.Progress"></a>
### visuals.Progress
**Kind**: static class of [<code>visuals</code>](#visuals)
**Summary**: Create a CLI Progress Bar
**Access**: public
* [.Progress](#visuals.Progress)
* [new Progress(message)](#new_visuals.Progress_new)
* [.update(state)](#visuals.Progress+update)
<a name="new_visuals.Progress_new"></a>
#### new Progress(message)
**Returns**: <code>Progress</code> - progress bar instance
**Throws**:
- Will throw if no message.
| Param | Type | Description |
| --- | --- | --- |
| message | <code>String</code> | message |
**Example**
```js
progress = new visuals.Progress('Hello World')
```
<a name="visuals.Progress+update"></a>
#### progress.update(state)
**Kind**: instance method of [<code>Progress</code>](#visuals.Progress)
**Summary**: Update the progress bar
**Access**: public
**Parm**: <code>String</code> [state.message] - message
| Param | Type | Description |
| --- | --- | --- |
| state | <code>Object</code> | progress state |
| state.percentage | <code>Number</code> | percentage |
| [state.eta] | <code>Number</code> | eta in seconds |
**Example**
```js
progress = new visuals.Progress('Hello World')
progress.update(percentage: 49, eta: 300)
```
<a name="visuals.SpinnerPromise"></a>
### visuals.SpinnerPromise
**Kind**: static class of [<code>visuals</code>](#visuals)
**Summary**: Create a CLI Spinner that spins on a promise
**Access**: public
**Fulfil**: <code>Object</code> value - resolved or rejected promise
<a name="new_visuals.SpinnerPromise_new"></a>
#### new SpinnerPromise(options)
This function will start a Spinner and stop it when the
passed promise is either fulfilled or rejected. The function
returns the passed promise which will be in either rejected or
resolved state.
| Param | Type | Description |
| --- | --- | --- |
| options | <code>Object</code> | spinner promise options |
| options.promise | <code>Promise</code> | promise to spin upon |
| options.startMessage | <code>String</code> | start spinner message |
| options.stopMessage | <code>String</code> | stop spinner message |
**Example**
```js
visuals.SpinnerPromise
promise: scanDevicesPromise
startMessage: "Scanning devices"
stopMessage: "Scanned devices"
.then (devices) ->
console.log devices
```
<a name="visuals.table"></a>
### visuals.table : <code>object</code>
**Kind**: static namespace of [<code>visuals</code>](#visuals)
* [.table](#visuals.table) : <code>object</code>
* [.horizontal(data, ordering)](#visuals.table.horizontal)
* [.vertical(data, ordering)](#visuals.table.vertical)
<a name="visuals.table.horizontal"></a>
#### table.horizontal(data, ordering)
Notice that you can rename columns by using the CURRENT => NEW syntax in the ordering configuration.
**Kind**: static method of [<code>table</code>](#visuals.table)
**Summary**: Make an horizontal table
**Access**: public
| Param | Type | Description |
| --- | --- | --- |
| data | <code>Array.<Object></code> | table data |
| ordering | <code>Array.<String></code> | display ordering |
**Example**
```js
console.log visuals.table.horizontal [
{ name: 'John Doe', age: 40 }
{ name: 'Jane Doe', age: 35 }
], [
'name => full name'
'age'
]
FULL NAME AGE
John Doe 40
Jane Doe 35
```
<a name="visuals.table.vertical"></a>
#### table.vertical(data, ordering)
Notice that you can rename columns by using the CURRENT => NEW syntax in the ordering configuration.
Vertical tables also accept separators and subtitles, which are represented in the ordering configuration as empty strings and strings surrounded by dollar signs respectively.
**Kind**: static method of [<code>table</code>](#visuals.table)
**Summary**: Make a vertical table
**Access**: public
| Param | Type | Description |
| --- | --- | --- |
| data | <code>Object</code> | table data |
| ordering | <code>Array.<String></code> | display ordering |
**Example**
```js
console.log visuals.table.vertical
name: 'John Doe'
age: 40
job: 'Developer'
, [
'$summary$'
'name => full name'
'age'
''
'$extras$'
'job'
]
== SUMMARY
FULL NAME: John Doe
AGE: 40
== EXTRAS
JOB: Developer
```
<a name="visuals.drive"></a>
### visuals.drive([message]) ⇒ <code>Promise.<String></code>
The dropdown detects and autorefreshes itself when the drive list changes.
**Kind**: static method of [<code>visuals</code>](#visuals)
**Summary**: Prompt the user to select a drive device
**Returns**: <code>Promise.<String></code> - device path
**Access**: public
| Param | Type | Default | Description |
| --- | --- | --- | --- |
| [message] | <code>String</code> | <code>'Select a drive'</code> | message |
**Example**
```js
visuals.drive('Please select a drive').then (drive) ->
console.log(drive)
```
Support
-------
If you're having any problem, please [raise an issue](https://github.com/resin-io/resin-cli-visuals/issues/new) on GitHub and the Resin.io team will be happy to help.
Tests
-----
Run the test suite by doing:
```sh
$ gulp test
```
Contribute
----------
- Issue Tracker: [github.com/resin-io/resin-cli-visuals/issues](https://github.com/resin-io/resin-cli-visuals/issues)
- Source Code: [github.com/resin-io/resin-cli-visuals](https://github.com/resin-io/resin-cli-visuals)
Before submitting a PR, please make sure that you include tests, and that [coffeelint](http://www.coffeelint.org/) runs without any warning:
```sh
$ gulp lint
```
License
-------
The project is licensed under the Apache 2.0 license.