<commit_before># TTY::ProgressBar [![Gitter](https://badges.gitter.im/Join%20Chat.svg)][gitter]
[![Gem Version](https://badge.fury.io/rb/tty-progressbar.svg)][gem]
[![Build Status](https://secure.travis-ci.org/piotrmurach/tty-progressbar.svg?branch=master)][travis]
[![Build status](https://ci.appveyor.com/api/projects/status/w3jafjeatt1ulufa?svg=true)][appveyor]
[![Code Climate](https://codeclimate.com/github/piotrmurach/tty-progressbar/badges/gpa.svg)][codeclimate]
[![Coverage Status](https://coveralls.io/repos/github/piotrmurach/tty-progressbar/badge.svg)][coverage]
[![Inline docs](http://inch-ci.org/github/piotrmurach/tty-progressbar.svg?branch=master)][inchpages]

[gitter]: https://gitter.im/piotrmurach/tty
[gem]: http://badge.fury.io/rb/tty-progressbar
[travis]: http://travis-ci.org/piotrmurach/tty-progressbar
[appveyor]: https://ci.appveyor.com/project/piotrmurach/tty-progressbar
[codeclimate]: https://codeclimate.com/github/piotrmurach/tty-progressbar
[coverage]: https://coveralls.io/github/piotrmurach/tty-progressbar
[inchpages]: http://inch-ci.org/github/piotrmurach/tty-progressbar

> A flexible progress bars drawing in terminal emulators.

**TTY::ProgressBar** provides independent progress bars component for [TTY](https://github.com/piotrmurach/tty) toolkit.

## Features

* Fully [configurable](#2-configuration)
* Extremly flexible progress display [formatting](#3-formatting)
* Ability to define your custom format [tokens](#31-tokens)
* Works on all ECMA-48 compatible terminals

## Installation

Add this line to your application's Gemfile:

```ruby
gem 'tty-progressbar'
```

And then execute:

    $ bundle

Or install it yourself as:

    $ gem install tty-progressbar

## Contents

* [1. Usage](#1-usage)
  * [1.1 advance](#11-advance)
  * [1.2 current=](#12-current)
  * [1.3 ratio=](#13-ratio)
  * [1.4 width=](#14-width)
  * [1.5 start](#15-start)
  * [1.6 update](#16-update)
  * [1.7 finish](#17-finish)
  * [1.8 complete?](#18-complete)
  * [1.9 reset](#19-reset)
  * [1.10 resize](#110-resize)
* [2. Configuration](#2-configuration)
  * [2.1 :head](#21-head)
  * [2.2 :frequency](#22-interval)
  * [2.3 :interval](#23-interval)
* [3. Formatting](#3-formatting)
  * [3.1 Tokens](#31-tokens)
  * [3.2 Custom Formatters](#32-custom-formatters)
  * [3.3 Custom Tokens](#33-custom-tokens)
* [4. Logging](#4-logging)
* [5. Examples](#5-examples)
  * [5.1 Color](#51-color)

## 1. Usage

**TTY::ProgressBar** requires only format string and total number of steps to completion. Once initialized, use `advance` method to indicated the progress like so:

```ruby
bar = TTY::ProgressBar.new("downloading [:bar]", total: 30)
30.times do
  sleep(0.1)
  bar.advance(1)
end
```

This would produce animation in your terminal:

```ruby
# downloading [=======================       ]
```

### 1.1 advance

Once you have **TTY::ProgressBar** instance, you can progress the display by calling `advance` method. By default it will increase by `1` but you can pass any number of steps, for instance, when used to advance number of bytes of downloaded file.

```ruby
bar.advance(1000)
```

You can also pass negative steps if you wish to backtrack the progress:

```ruby
bar.advance(-1)
```

Note: If a progress bar has already finished then negative steps will not set it back to desired value.

### 1.2 current=

**TTY::ProgressBar** allows you to set progress to a given value by calling `current=` method.

```ruby
bar.current = 50
```

Note: If a progress bar has already finished then negative steps will not set it back to desired value.

### 1.3 ratio=

In order to update overall completion of a progress bar as an exact percentage use the `ratio=` method. The method accepts values between `0` and `1` inclusive. For example, a ratio of 0.5 will attempt to set the progress bar halfway:

```ruby
bar.ratio = 0.5
```

### 1.4 width=

You can set how many terminal columns will the `:bar` actually span excluding any other tokens and/or text. For example if you need the bar to be always 20 columns wwide do:

```ruby
bar.width = 20
```

or with configuration options:

```ruby
bar = TTY::ProgressBar.new("[:bar]", width: 20)
```

### 1.5 start

By default the timer for internal time esitamation is started automatically when the `advance` method is called. However, if you require control on when the progression timer is started use `start` call:

```ruby
bar.start  # => sets timer and draws initial progress bar
```

### 1.6 update

Once the progress bar has been started you can change its configuration option(s) by calling `update`:

```ruby
bar.update(complete: '+', frequency: 10)
```

### 1.7 finish

In order to immediately stop and finish the progress call `finish`. This will finish drawing the progress and return to new line.

```ruby
bar.finish
```

### 1.8 complete?

During progresion you can check if bar is finished or not by calling `complete?`.

```ruby
bar.complete? # => false
```

### 1.9 reset

In order to reset currently running or finished progress bar to its original configuration and initial position use `reset` like so:

```ruby
bar.reset
```

After resetting the bar if you wish to draw and start the bar and its timers use `start` call.

### 1.10 resize

If you wish for a progress bar to change it's current width, you can use `resize` by passing in a new desired length. However, if you don't provide any width the `resize` will use terminal current width as its base for scaling.

```ruby
bar.resize      # => determine terminal width and scale accordingly
bar.resize(50)  # => will resize bar proportionately from this point onwards
```

To handle automatic resizing you can trap `:WINCH` signal:

```ruby
trap(:WINCH) { bar.resize }
```

## 2. Configuration

There are number of configuration options that can be provided:
<commit_msg>Add docs for #stop api<commit_after># TTY::ProgressBar [![Gitter](https://badges.gitter.im/Join%20Chat.svg)][gitter]
[![Gem Version](https://badge.fury.io/rb/tty-progressbar.svg)][gem]
[![Build Status](https://secure.travis-ci.org/piotrmurach/tty-progressbar.svg?branch=master)][travis]
[![Build status](https://ci.appveyor.com/api/projects/status/w3jafjeatt1ulufa?svg=true)][appveyor]
[![Code Climate](https://codeclimate.com/github/piotrmurach/tty-progressbar/badges/gpa.svg)][codeclimate]
[![Coverage Status](https://coveralls.io/repos/github/piotrmurach/tty-progressbar/badge.svg)][coverage]
[![Inline docs](http://inch-ci.org/github/piotrmurach/tty-progressbar.svg?branch=master)][inchpages]

[gitter]: https://gitter.im/piotrmurach/tty
[gem]: http://badge.fury.io/rb/tty-progressbar
[travis]: http://travis-ci.org/piotrmurach/tty-progressbar
[appveyor]: https://ci.appveyor.com/project/piotrmurach/tty-progressbar
[codeclimate]: https://codeclimate.com/github/piotrmurach/tty-progressbar
[coverage]: https://coveralls.io/github/piotrmurach/tty-progressbar
[inchpages]: http://inch-ci.org/github/piotrmurach/tty-progressbar

> A flexible progress bars drawing in terminal emulators.

**TTY::ProgressBar** provides independent progress bars component for [TTY](https://github.com/piotrmurach/tty) toolkit.

## Features

* Fully [configurable](#2-configuration)
* Extremly flexible progress display [formatting](#3-formatting)
* Ability to define your custom format [tokens](#31-tokens)
* Works on all ECMA-48 compatible terminals

## Installation

Add this line to your application's Gemfile:

```ruby
gem 'tty-progressbar'
```

And then execute:

    $ bundle

Or install it yourself as:

    $ gem install tty-progressbar

## Contents

* [1. Usage](#1-usage)
  * [1.1 advance](#11-advance)
  * [1.2 current=](#12-current)
  * [1.3 ratio=](#13-ratio)
  * [1.4 width=](#14-width)
  * [1.5 start](#15-start)
  * [1.6 update](#16-update)
  * [1.7 finish](#17-finish)
  * [1.8 stop](#18-stop)
  * [1.9 reset](#19-reset)
  * [1.10 complete?](#110-complete)
  * [1.11 resize](#111-resize)
* [2. Configuration](#2-configuration)
  * [2.1 :head](#21-head)
  * [2.2 :frequency](#22-interval)
  * [2.3 :interval](#23-interval)
* [3. Formatting](#3-formatting)
  * [3.1 Tokens](#31-tokens)
  * [3.2 Custom Formatters](#32-custom-formatters)
  * [3.3 Custom Tokens](#33-custom-tokens)
* [4. Logging](#4-logging)
* [5. Examples](#5-examples)
  * [5.1 Color](#51-color)

## 1. Usage

**TTY::ProgressBar** requires only format string and total number of steps to completion. Once initialized, use `advance` method to indicated the progress like so:

```ruby
bar = TTY::ProgressBar.new("downloading [:bar]", total: 30)
30.times do
  sleep(0.1)
  bar.advance(1)
end
```

This would produce animation in your terminal:

```ruby
# downloading [=======================       ]
```

### 1.1 advance

Once you have **TTY::ProgressBar** instance, you can progress the display by calling `advance` method. By default it will increase by `1` but you can pass any number of steps, for instance, when used to advance number of bytes of downloaded file.

```ruby
bar.advance(1000)
```

You can also pass negative steps if you wish to backtrack the progress:

```ruby
bar.advance(-1)
```

Note: If a progress bar has already finished then negative steps will not set it back to desired value.

### 1.2 current=

**TTY::ProgressBar** allows you to set progress to a given value by calling `current=` method.

```ruby
bar.current = 50
```

Note: If a progress bar has already finished then negative steps will not set it back to desired value.

### 1.3 ratio=

In order to update overall completion of a progress bar as an exact percentage use the `ratio=` method. The method accepts values between `0` and `1` inclusive. For example, a ratio of 0.5 will attempt to set the progress bar halfway:

```ruby
bar.ratio = 0.5
```

### 1.4 width=

You can set how many terminal columns will the `:bar` actually span excluding any other tokens and/or text. For example if you need the bar to be always 20 columns wwide do:

```ruby
bar.width = 20
```

or with configuration options:

```ruby
bar = TTY::ProgressBar.new("[:bar]", width: 20)
```

### 1.5 start

By default the timer for internal time esitamation is started automatically when the `advance` method is called. However, if you require control on when the progression timer is started use `start` call:

```ruby
bar.start  # => sets timer and draws initial progress bar
```

### 1.6 update

Once the progress bar has been started you can change its configuration option(s) by calling `update`:

```ruby
bar.update(complete: '+', frequency: 10)
```

### 1.7 finish

In order to immediately stop and finish the progress call `finish`. This will finish drawing the progress and return to new line.

```ruby
bar.finish
```

### 1.8 stop

In order to immediately stop the bar in the current position and thus finish any further progress use `stop`:

```ruby
bar.stop
```

### 1.9 reset

In order to reset currently running or finished progress bar to its original configuration and initial position use `reset` like so:

```ruby
bar.reset
```

After resetting the bar if you wish to draw and start the bar and its timers use `start` call.

### 1.10 complete?

During progresion you can check if a bar is finished or not by calling `complete?`. The bar will only return `true` if the progression finished successfuly, otherwise `false` will be returned.

```ruby
bar.complete? # => false
```

### 1.11 resize

If you wish for a progress bar to change it's current width, you can use `resize` by passing in a new desired length. However, if you don't provide any width the `resize` will use terminal current width as its base for scaling.

```ruby
bar.resize      # => determine terminal width and scale accordingly
bar.resize(50)  # => will resize bar proportionately from this point onwards
```

To handle automatic resizing you can trap `:WINCH` signal:

```ruby
trap(:WINCH) { bar.resize }
```

## 2. Configuration

There are number of configuration options that can be provided:

{'fraction_non_alphanumeric': 0.14007553503986572, 'fraction_numerical': 0.02492656315568611, 'mean_word_length': 4.537174721189591, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 13, 'https://': 22, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 6, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '695307', 'n_tokens_mistral': 4054, 'n_tokens_neox': 3735, 'n_words': 1306}