TTY::Pie

The :format key in the legend configuration uses Ruby's format sequences and specific named placeholders to build labels:

• <label>: The icon matching the pie chart display.
• <name>: The :name provided in the data.
• <value>: The :value provided in the data.
• <currency>: The value formatted as currency.
• <percent>: The automatically calculated percentage.

Default format: "%<label>s %<name>s %<percent>.2f%%"

# Example: Displaying value and percent
legend: {
  format: "%<label>s %<name>s %<value>d (%<percent>.2f%%)"
}

# Example: Displaying as currency
legend: {
  format: "%<label>s %<name>s $%<currency>s (%<percent>.0f%%)",
  precision: 3,
  delimiter: "*"
}

To render a pie chart, provide an array of hashes containing data items and initialize TTY::Pie with a radius. You can then print the instance directly to the terminal.

Each data item hash can include:

• :name: Label for the legend.
• :value: Numeric value used to calculate slice size (required).
• :color: A color symbol (e.g., :bright_yellow) from supported colors.
• :fill: A character used to fill the slice (e.g., *, x, @).

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: "+" }
]

pie_chart = TTY::Pie.new(data: data, radius: 5)
print pie_chart

To use TTY::Pie in your Ruby application, add it to your Gemfile:

gem "tty-pie"

Then run bundle. Alternatively, you can install it directly via the command line:

gem install tty-pie

The :legend option accepts a hash to customize the display of labels alongside the chart. Available keys include:

• :left: Spacing between the chart and legend (defaults to 4 columns).
• :line: Spacing between legend labels (defaults to 1 line).
• :precision: Decimal places for currency/percent display (defaults to 2).
• :delimiter: Thousands delimiter for currency format.
• :format: A string template for the legend label.

pie_chart = TTY::Pie.new(data: data, radius: 3, legend: {left: 10, line: 2})

When initializing TTY::Pie.new, you can use the following keyword arguments:

• :radius: Sets the chart radius (defaults to 10).
• :left: The column position for absolute positioning.
• :top: The row position for absolute positioning.

# Position at 50th column and 10th row with radius 5
TTY::Pie.new(data: data, left: 50, top: 10, radius: 5)

The :enable_color option controls whether ANSI colors are applied to the output. Valid values are:

• true: Force color output.
• false: Disable color output.
• nil (default): Automatically detect terminal color support.

TTY::Pie.new(data: data, enable_color: true)

You can initialize a pie chart without data and add items later using the add method or the << shovel operator. To replace all existing data with a new set, use the update method.

# Adding data after initialization
pie_chart = TTY::Pie.new
pie_chart << { name: "BTC", value: 5977, color: :bright_yellow, fill: "*" }

# Replacing all data
new_data = [{ name: "BTC", value: 3400, color: :bright_yellow, fill: "*" }]
pie_chart.update(new_data)

The legend option in TTY::Pie.new accepts a hash to control the position and formatting of the legend labels.

Legend Configuration Keys:

• :left: Integer representing the horizontal spacing (offset) between the pie chart and the legend (default: 4).
• :line: Integer representing the vertical spacing between legend lines (default: 1).

legend = { left: 10, line: 2 }
pie = TTY::Pie.new(data: data, legend: legend)

You can add new data slices to an existing TTY::Pie instance using the add method or the << shovel operator. This returns the Pie instance, allowing for method chaining.

pie.add({name: "BTC", value: 5977, color: :yellow, fill: "*"})
# OR
pie << {name: "ETH", value: 3045, color: :green, fill: "+"}

Once a DataItem is initialized, you can access or modify its properties using the following attributes:

• name: The name for the legend label.
• value: The numeric value for the legend label.
• percent: The percentage size of the pie slice.
• angle: The start angle for the pie slice (writable via angle=).
• color: The color used to mark the pie slice.
• fill: The symbol used to mark the pie slice.

To modify the data currently held by a TTY::Pie instance:

• update(data): Replaces the current data set with a new array of hashes.
• clear (or reset): Removes all data items from the chart.

Both methods return the Pie instance for chaining.

pie.update([
  {name: "BTC", value: 5977, color: :yellow, fill: "*"},
  {name: "ETH", value: 3045, color: :green, fill: "+"}
])

pie.clear