TTY:Pie 
Draw pie charts in your terminal window
TTY::Pie provides pie chart drawing component for TTY toolkit.
Installation
Add this line to your application's Gemfile:
gem "tty-pie"
And then execute:
$ bundle
Or install it yourself as:
$ gem install tty-pie
Contents
1. Usage
To render a pie chart you need to provide an array of data items:
data = [
{ name: "BTC", value: 5977, color: :bright_yellow, fill: "*" },
{ name: "BCH", value: 3045, color: :bright_green, fill: "x" },
{ name: "LTC", value: 2030, color: :bright_magenta, fill: "@" },
{ name: "ETH", value: 2350, color: :bright_cyan, fill: "+" }
]
Then pass data to TTY::Pie instance with a given radius:
pie_chart = TTY::Pie.new(data: data, radius: 5)
and print the pie chart in your terminal window:
print pie_chart
# =>
# ++***
# ++++++******* * BTC 44.60%
# @@@+++++*********
# @@@@@@+++********** x BCH 22.72%
# @@@@@@@@@+***********
# @@@@@@@@@@x********** @ LTC 15.15%
# @@@@@@@@@xx**********
# @@@@@@xxxx********* + ETH 17.53%
# @@@xxxxxxx*******
# xxxxxxxx*****
# xxxx*
#
2. Interface
2.1 data
To render a pie chart you need to provide data. A single data item is just a Ruby hash that can contain the following keys:
:name- used for setting the entry name in legend:value- used for calculating actual pie slice size:color- used to color a pie slice corresponding with a value:fill- used as a character to fill in a pie slice
At the very minimum you need to provide a :value in order for a pie to calculate slice sizes. If you wish to have a legend then add the :name key as well.
For example, the following will result in four slices in a pie chart:
data = [
{ name: "BTC", value: 5977 },
{ name: "BCH", value: 3045 },
{ name: "LTC", value: 2030 },
{ name: "ETH", value: 2350 }
]
However, the above data slices will be displayed without any color. Use :color out of supported colors:
data = [
{ name: "BTC", value: 5977, color: :bright_yellow },
{ name: "BCH", value: 3045, color: :bright_green },
{ name: "LTC", value: 2030, color: :bright_magenta },
{ name: "ETH", value: 2350, color: :bright_cyan }
]
To further make your chart readable consider making pie chart slices visible by channging the displayed characters using :fill key:
data = [
{ name: "BTC", value: 5977, color: :bright_yellow, fill: "*" },
{ name: "BCH", value: 3045, color: :bright_green, fill: "x" },
{ name: "LTC", value: 2030, color: :bright_magenta, fill: "@" },
{ name: "ETH", value: 2350, color: :bright_cyan, fill: "+" }
]
There is no limit to the amount of data you can present, however there is a point of scale and legibility to be considered when printing in the terminals.
You can add data to pie chart during initialization using :data keyword:
pie_chart = TTY::Pie.new(data: data)
Alternatively, you can delay adding data later with add or << methods:
pie_chart = TTY::Pie.new
pie_chart << { name: "BTC", value: 5977, color: :bright_yellow, fill: "*" }
pie_chart << { name: "BCH", value: 3045, color: :bright_green, fill: "x" }
pie_chart << { name: "LTC", value: 2030, color: :bright_magenta, fill: "@" }
pie_chart << { name: "ETH", value: 2350, color: :bright_cyan, fill: "+" }
2.2 add
You can also set data for the pie chart using the add or << method calls. Once a pie chart is initialized, you can add data items:
pie_chart = TTY::Pie.new
pie_chart << { name: "BTC", value: 5977, color: :bright_yellow, fill: "*" }
pie_chart << { name: "BCH", value: 3045, color: :bright_green, fill: "x" }
...
2.3 update
To replace current data completely with the new use update:
data = [
{ name: "BTC", value: 5977, color: :bright_yellow, fill: "*" },
{ name: "BCH", value: 3045, color: :bright_green, fill: "x" }
]
pie_chart = TTY::Pie.new(data: data)
new_data = [
{ name: "BTC", value: 3400, color: :bright_yellow, fill: "*" },
{ name: "BCH", value: 1200, color: :bright_green, fill: "x" },
]
pie_chart.update(new_data)
2.4 render
Once a pie chart has been initialized use the render or to_s method to return a string representation of the chart.
To actually show it in a terminal, you need to print it:
print pie_chart.render
# => this will render chart in terminal
You can skip calling any method and simply print:
print pie_chart
# => this will render chart in terminal
2.5 position
If you don't provide location for you pie chart it will be printed at the current cursor location. In order to absolutely position the chart use :left and :top keyword arguments. For example, if you wanted to position the pie chart at 50thcolumn and 10th row:
TTY::Pie.new(data: data, left: 50, top: 10)
2.6 radius
By default, a pie chart is rendered with a radius of 10, you can change this using the :radius keyword:
TTY::Pie.new(data: data, radius: 5)
2.7 legend
Provided the following data:
data = [
{ name: "BTC", value: 5977, fill: "*" },
{ name: "BCH", value: 3045, fill: "+" },
{ name: "LTC", value: 2030, fill: "x" }
]
You can control how the legend is displayed using the :legend keyword and hash as value with the following keys:
:left- used to determine spacing between a chart and a legend, defaults to4columns:line- used to determine spacing between legend labels, defaults to1line:format- used to format a display label using template named strings:precision- used to determine currency display decimal places, defaults to2:delimiter- used to set thousands delimiter in currency format
For example, to place a legend 10 columns away from the pie chart and separate each label by 2 lines do:
pie_chart = TTY::Pie.new(data: data, radius: 3, legend: {left: 10, line: 2})
And printing in a terminal will produce:
print pie_chart
# =>
# x** * BTC 54.08%
# xxxx*****
# ++++xx*******
# ++++++******* + BCH 27.55%
# ++++++*******
# ++++*****
# +** x LTC 18.37%
2.7.1 format
The :format uses Ruby's format sequences and named strings placeholders:
<label>- the icon matching pie chart display<name>- the label name provided in data<value>- the label value provided in data, by default not displayed<currency>- the label value formatted as currency<percent>- the percent automatically calculated from data
By default the label is formatted according to the following pattern with named strings:
"%<label>s %<name>s %<percent>.2f%%"
Given data items:
data = [
{ name: "BTC", value: 5977.12345, fill: "*" },
{ name: "BCH", value: 3045.2, fill: "+" },
{ name: "LTC", value: 2030.444, fill: "x" }
]
The legend will show:
# =>
# x** * BTC 54.08%
# xxxx*****
# ++++xx*******
# ++++++******* + BCH 27.55%
# ++++++*******
# ++++*****
# +** x LTC 18.37%
To display value together with percent, use <value> named string in the format:
legend: {
format: "%<label>s %<name>s %<value>d (%<percent>.2f%%)"
}
The legend will show:
# =>
# x** * BTC 5977 (54.08%)
# xxxx*****
# ++++xx*******
# ++++++******* + BCH 3045 (27.55%)
# ++++++*******
# ++++*****
# +** x LTC 2030 (18.37%)
To display value as currency use <currency> name string in the format:
legend: {
format: "%<label>s %<name>s $%<currency>s (%<percent>.0f%%)"
}
The legend will show:
# =>
# x** * BTC $5,977 (54%)
# xxxx*****
# ++++xx*******
# ++++++******* + BCH $3,045 (28%)
# ++++++*******
# ++++*****
# +** x LTC $2,030 (18%)
The currency can be further customised using :precision and :delimiter keys:
legend: {
format: "%<label>s %<name>s $%<currency>s (%<percent>.0f%%)",
precision: 3,
delimiter: "*"
}
The legend will show:
# =>
# x** * BTC $5*977.123 (54%)
# xxxx*****
# ++++xx*******
# ++++++******* + BCH $3*045.200 (28%)
# ++++++*******
# ++++*****
# +** x LTC $2*030.444 (18%)
Development
After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.
To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org.
Contributing
Bug reports and pull requests are welcome on GitHub at https://github.com/piotrmurach/tty-pie. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.
License
The gem is available as open source under the terms of the MIT License.
Code of Conduct
Everyone interacting in the TTY::Pie project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.
Copyright
Copyright (c) 2018 Piotr Murach. See LICENSE.txt for further details.