{"id":13394891,"url":"https://github.com/piotrmurach/tty-pie","last_synced_at":"2025-06-12T13:09:24.722Z","repository":{"id":59158178,"uuid":"142683318","full_name":"piotrmurach/tty-pie","owner":"piotrmurach","description":"Draw pie charts in your terminal window","archived":false,"fork":false,"pushed_at":"2024-02-21T21:30:06.000Z","size":126,"stargazers_count":143,"open_issues_count":0,"forks_count":3,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-06-01T06:36:52.813Z","etag":null,"topics":["ascii-art","console","pie-chart","piechart","ruby-gem","terminal"],"latest_commit_sha":null,"homepage":"http://ttytoolkit.org","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/piotrmurach.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE.txt","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":"piotrmurach"}},"created_at":"2018-07-28T14:22:51.000Z","updated_at":"2025-02-19T18:52:50.000Z","dependencies_parsed_at":"2022-09-13T17:50:50.631Z","dependency_job_id":"0cf37bbc-43fd-46a0-af59-cdd280f2c49f","html_url":"https://github.com/piotrmurach/tty-pie","commit_stats":{"total_commits":104,"total_committers":2,"mean_commits":52.0,"dds":0.009615384615384581,"last_synced_commit":"b7b17087c9702434a7f124b6fd582c3e34fa0415"},"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/piotrmurach/tty-pie","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/piotrmurach%2Ftty-pie","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/piotrmurach%2Ftty-pie/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/piotrmurach%2Ftty-pie/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/piotrmurach%2Ftty-pie/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/piotrmurach","download_url":"https://codeload.github.com/piotrmurach/tty-pie/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/piotrmurach%2Ftty-pie/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":259470951,"owners_count":22862999,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ascii-art","console","pie-chart","piechart","ruby-gem","terminal"],"created_at":"2024-07-30T17:01:35.270Z","updated_at":"2025-06-12T13:09:24.701Z","avatar_url":"https://github.com/piotrmurach.png","language":"Ruby","funding_links":["https://github.com/sponsors/piotrmurach"],"categories":["Happy Exploring 🤘","Ruby"],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n  \u003ca href=\"https://piotrmurach.github.io/tty\" target=\"_blank\"\u003e\u003cimg width=\"130\" src=\"https://github.com/piotrmurach/tty/raw/master/images/tty.png\" alt=\"tty logo\" /\u003e\u003c/a\u003e\n\u003c/div\u003e\n\n# TTY:Pie [![Gitter](https://badges.gitter.im/Join%20Chat.svg)][gitter]\n\n[![Gem Version](https://badge.fury.io/rb/tty-pie.svg)][gem]\n[![Actions CI](https://github.com/piotrmurach/tty-pie/actions/workflows/ci.yml/badge.svg)][gh_actions_ci]\n[![Build status](https://ci.appveyor.com/api/projects/status/9n69xpw64sylqh2y?svg=true)][appveyor]\n[![Maintainability](https://api.codeclimate.com/v1/badges/dfac05073e1549e9dbb6/maintainability)][codeclimate]\n[![Coverage Status](https://coveralls.io/repos/github/piotrmurach/tty-pie/badge.svg)][coverage]\n\n[gitter]: https://gitter.im/piotrmurach/tty\n[gem]: https://badge.fury.io/rb/tty-pie\n[gh_actions_ci]: https://github.com/piotrmurach/tty-pie/actions/workflows/ci.yml\n[appveyor]: https://ci.appveyor.com/project/piotrmurach/tty-pie\n[codeclimate]: https://codeclimate.com/github/piotrmurach/tty-pie/maintainability\n[coverage]: https://coveralls.io/github/piotrmurach/tty-pie\n\n\u003e Draw pie charts in your terminal window\n\n**TTY::Pie** provides pie chart drawing component for [TTY](https://github.com/piotrmurach/tty) toolkit.\n\n![Pie chart drawing](https://github.com/piotrmurach/tty-pie/blob/master/assets/tty-pie_chart_drawing_crypto.png)\n\n## Installation\n\nAdd this line to your application's Gemfile:\n\n```ruby\ngem \"tty-pie\"\n```\n\nAnd then execute:\n\n    $ bundle\n\nOr install it yourself as:\n\n    $ gem install tty-pie\n\n## Contents\n\n* [1. Usage](#1-usage)\n* [2. Interface](#2-interface)\n  * [2.1 data](#21-data)\n  * [2.2 add](#22-add)\n  * [2.3 update](#23-update)\n  * [2.4 render](#24-render)\n  * [2.5 position](#25-position)\n  * [2.6 radius](#26-radius)\n  * [2.7 legend](#27-legend)\n    * [2.7.1 format](#271-format)\n  * [2.8 enable_color](#28-enable_color)\n\n## 1. Usage\n\nTo render a pie chart you need to provide an array of data items:\n\n```ruby\ndata = [\n  { name: \"BTC\", value: 5977, color: :bright_yellow, fill: \"*\" },\n  { name: \"BCH\", value: 3045, color: :bright_green, fill: \"x\" },\n  { name: \"LTC\", value: 2030, color: :bright_magenta, fill: \"@\" },\n  { name: \"ETH\", value: 2350, color: :bright_cyan, fill: \"+\" }\n]\n```\n\nThen pass data to **TTY::Pie** instance with a given radius:\n\n```ruby\npie_chart = TTY::Pie.new(data: data, radius: 5)\n```\n\nand print the pie chart in your terminal window:\n\n```ruby\nprint pie_chart\n# =\u003e\n#         ++***\n#     ++++++*******        * BTC 44.60%\n#   @@@+++++*********\n#  @@@@@@+++**********     x BCH 22.72%\n# @@@@@@@@@+***********\n# @@@@@@@@@@x**********    @ LTC 15.15%\n# @@@@@@@@@xx**********\n#  @@@@@@xxxx*********     + ETH 17.53%\n#   @@@xxxxxxx*******\n#     xxxxxxxx*****\n#         xxxx*\n# \n```\n\n## 2. Interface\n\n### 2.1 data\n\nTo render a pie chart you need to provide data. A single data item is just a Ruby hash that can contain the following keys:\n\n* `:name` - used for setting the entry name in legend\n* `:value` - used for calculating actual pie slice size\n* `:color` - used to color a pie slice corresponding with a value\n* `:fill` - used as a character to fill in a pie slice\n\nAt 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.\n\nFor example, the following will result in four slices in a pie chart:\n\n```ruby\ndata = [\n  { name: \"BTC\", value: 5977 },\n  { name: \"BCH\", value: 3045 },\n  { name: \"LTC\", value: 2030 },\n  { name: \"ETH\", value: 2350 }\n]\n```\n\nHowever, the above data slices will be displayed without any color. Use `:color` out of [supported colors](https://github.com/piotrmurach/pastel#3-supported-colors):\n\n```ruby\ndata = [\n  { name: \"BTC\", value: 5977, color: :bright_yellow },\n  { name: \"BCH\", value: 3045, color: :bright_green },\n  { name: \"LTC\", value: 2030, color: :bright_magenta },\n  { name: \"ETH\", value: 2350, color: :bright_cyan }\n]\n```\n\nTo further make your chart readable consider making pie chart slices visible by channging the displayed characters using `:fill` key:\n\n```ruby\ndata = [\n  { name: \"BTC\", value: 5977, color: :bright_yellow, fill: \"*\" },\n  { name: \"BCH\", value: 3045, color: :bright_green, fill: \"x\" },\n  { name: \"LTC\", value: 2030, color: :bright_magenta, fill: \"@\" },\n  { name: \"ETH\", value: 2350, color: :bright_cyan, fill: \"+\" }\n]\n```\n\nThere 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.\n\nYou can add data to pie chart during initialization using `:data` keyword:\n\n```ruby\npie_chart = TTY::Pie.new(data: data)\n```\n\nAlternatively, you can delay adding data later with `add` or `\u003c\u003c` methods:\n\n```ruby\npie_chart = TTY::Pie.new\npie_chart \u003c\u003c { name: \"BTC\", value: 5977, color: :bright_yellow, fill: \"*\" }\npie_chart \u003c\u003c { name: \"BCH\", value: 3045, color: :bright_green, fill: \"x\" }\npie_chart \u003c\u003c { name: \"LTC\", value: 2030, color: :bright_magenta, fill: \"@\" }\npie_chart \u003c\u003c { name: \"ETH\", value: 2350, color: :bright_cyan, fill: \"+\" }\n```\n\n### 2.2 add\n\nYou can also set data for the pie chart using the `add` or `\u003c\u003c` method calls. Once a pie chart is initialized, you can add data items:\n\n```ruby\npie_chart = TTY::Pie.new\npie_chart \u003c\u003c { name: \"BTC\", value: 5977, color: :bright_yellow, fill: \"*\" }\npie_chart \u003c\u003c { name: \"BCH\", value: 3045, color: :bright_green, fill: \"x\" }\n...\n```\n\n### 2.3 update\n\nTo replace current data completely with the new use `update`:\n\n```ruby\ndata = [\n  { name: \"BTC\", value: 5977, color: :bright_yellow, fill: \"*\" },\n  { name: \"BCH\", value: 3045, color: :bright_green, fill: \"x\" }\n]\npie_chart = TTY::Pie.new(data: data)\n\nnew_data = [\n  { name: \"BTC\", value: 3400, color: :bright_yellow, fill: \"*\" },\n  { name: \"BCH\", value: 1200, color: :bright_green, fill: \"x\" },\n]\n\npie_chart.update(new_data)\n```\n\n### 2.4 render\n\nOnce a pie chart has been initialized use the `render` or `to_s` method to return a string representation of the chart.\n\nTo actually show it in a terminal, you need to print it:\n\n```ruby\nprint pie_chart.render\n# =\u003e this will render chart in terminal\n```\n\nYou can skip calling any method and simply print:\n\n```ruby\nprint pie_chart\n# =\u003e this will render chart in terminal\n```\n\n### 2.5 position\n\nIf 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 `50th`column and `10th` row:\n\n```ruby\nTTY::Pie.new(data: data, left: 50, top: 10)\n```\n\n### 2.6 radius\n\nBy default, a pie chart is rendered with a radius of `10`, you can change this using the `:radius` keyword:\n\n```ruby\nTTY::Pie.new(data: data, radius: 5)\n```\n\n### 2.7 legend\n\nProvided the following data:\n\n```ruby\ndata = [\n  { name: \"BTC\", value: 5977, fill: \"*\" },\n  { name: \"BCH\", value: 3045, fill: \"+\" },\n  { name: \"LTC\", value: 2030, fill: \"x\" }\n]\n```\n\nYou can control how the legend is displayed using the `:legend` keyword and hash as value with the following keys:\n\n* `:left` - used to determine spacing between a chart and a legend, defaults to `4` columns\n* `:line` - used to determine spacing between legend labels, defaults to `1` line\n* `:format` - used to format a display label using template named strings\n* `:precision` - used to determine currency display decimal places, defaults to `2`\n* `:delimiter` - used to set thousands delimiter in currency format\n\nFor example, to place a legend `10` columns away from the pie chart and separate each label by `2` lines do:\n\n```ruby\npie_chart = TTY::Pie.new(data: data, radius: 3, legend: {left: 10, line: 2})\n```\n\nAnd printing in a terminal will produce:\n\n```ruby\nprint pie_chart\n# =\u003e\n#      x**               * BTC 54.08%\n#   xxxx*****\n# ++++xx*******\n# ++++++*******          + BCH 27.55%\n# ++++++*******\n#   ++++*****\n#      +**               x LTC 18.37%\n```\n\n#### 2.7.1 format\n\nThe `:format` uses Ruby's [format sequences](https://ruby-doc.org/core-2.5.0/Kernel.html#method-i-format) and named strings placeholders:\n\n* `\u003clabel\u003e` - the icon matching pie chart display\n* `\u003cname\u003e` - the label name provided in data\n* `\u003cvalue\u003e` - the label value provided in data, by default not displayed\n* `\u003ccurrency\u003e` - the label value formatted as currency\n* `\u003cpercent\u003e` - the percent automatically calculated from data\n\nBy default the label is formatted according to the following pattern with named strings:\n\n```ruby\n\"%\u003clabel\u003es %\u003cname\u003es %\u003cpercent\u003e.2f%%\"\n```\n\nGiven data items:\n\n```ruby\ndata = [\n  { name: \"BTC\", value: 5977.12345, fill: \"*\" },\n  { name: \"BCH\", value: 3045.2, fill: \"+\" },\n  { name: \"LTC\", value: 2030.444, fill: \"x\" }\n]\n```\n\nThe legend will show:\n\n```ruby\n# =\u003e\n#      x**       * BTC 54.08%\n#   xxxx*****\n# ++++xx*******\n# ++++++*******  + BCH 27.55%\n# ++++++*******\n#   ++++*****\n#      +**       x LTC 18.37%\n```\n\nTo display value together with percent, use `\u003cvalue\u003e` named string in the format:\n\n```ruby\nlegend: {\n  format: \"%\u003clabel\u003es %\u003cname\u003es %\u003cvalue\u003ed (%\u003cpercent\u003e.2f%%)\"\n}\n```\n\nThe legend will show:\n\n```ruby\n# =\u003e\n#      x**       * BTC 5977 (54.08%)\n#   xxxx*****\n# ++++xx*******\n# ++++++*******  + BCH 3045 (27.55%)\n# ++++++*******\n#   ++++*****\n#      +**       x LTC 2030 (18.37%)\n```\n\nTo display value as currency use `\u003ccurrency\u003e` name string in the format:\n\n```ruby\nlegend: {\n  format: \"%\u003clabel\u003es %\u003cname\u003es $%\u003ccurrency\u003es (%\u003cpercent\u003e.0f%%)\"\n}\n```\n\nThe legend will show:\n\n```ruby\n# =\u003e\n#      x**       * BTC $5,977 (54%)\n#   xxxx*****\n# ++++xx*******\n# ++++++*******  + BCH $3,045 (28%)\n# ++++++*******\n#   ++++*****\n#      +**       x LTC $2,030 (18%)\n```\n\nThe currency can be further customised using `:precision` and `:delimiter` keys:\n\n```ruby\nlegend: {\n  format: \"%\u003clabel\u003es %\u003cname\u003es $%\u003ccurrency\u003es (%\u003cpercent\u003e.0f%%)\",\n  precision: 3,\n  delimiter: \"*\"\n}\n```\n\nThe legend will show:\n\n```ruby\n# =\u003e\n#      x**       * BTC $5*977.123 (54%)\n#   xxxx*****\n# ++++xx*******\n# ++++++*******  + BCH $3*045.200 (28%)\n# ++++++*******\n#   ++++*****\n#      +**       x LTC $2*030.444 (18%)\n```\n\n### 2.8 enable_color\n\nYou can control when to apply colouring to a pie chart output with `:enable_color` option.\n\nValid values are `true`, `false` or `nil`. By default `:enable_color` is set to `nil` which performs automatic terminal colour support detection. Setting `:enable_color` to `false` will disable coloured output. To force the output to be always coloured set `:enable_color` to `true` like so:\n\n```ruby\n TTY::Pie.new(data: data, enable_color: true)\n```\n\n## Development\n\nAfter 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.\n\nTo 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](https://rubygems.org).\n\n## Contributing\n\nBug 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 [code of conduct](https://github.com/piotrmurach/tty-pie/blob/master/CODE_OF_CONDUCT.md).\n\n## License\n\nThe gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).\n\n## Code of Conduct\n\nEveryone interacting in the TTY::Pie project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/piotrmurach/tty-pie/blob/master/CODE_OF_CONDUCT.md).\n\n## Copyright\n\nCopyright (c) 2018 Piotr Murach. See [LICENSE.txt](https://github.com/piotrmurach/tty-pie_chart/blob/master/LICENSE.txt) for further details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpiotrmurach%2Ftty-pie","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpiotrmurach%2Ftty-pie","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpiotrmurach%2Ftty-pie/lists"}