SVG::T...ph::XY(3pm)

💖 SVG::TT::Graph::XY 💖

okay bestie, sit down, hydrate, because today we're talking about SVG::TT::Graph::XY and it is literally the moment. it makes presentation quality SVG line graphs of XY data points and it does it easily. no cap. 🦋✨

---

🌸 NAME 🌸

SVG::TT::Graph::XY — Create presentation quality SVG line graphs of XY data points easily 💅

---

🎀 SYNOPSIS 🎀

here's the vibe, bestie, copy-paste and go:

use SVG::TT::Graph::XY;

my @data_cpu  = (0.3, 23, 0.5, 54, 1.0, 67, 1.8, 12);
my @data_disk = (0.45, 12, 0.51, 26, 0.53, 23);

my $graph = SVG::TT::Graph::XY->new({
  'height' => '500',
  'width'  => '300',
});

$graph->add_data({
  'data'  => \@data_cpu,
  'title' => 'CPU',
});

$graph->add_data({
  'data'  => \@data_disk,
  'title' => 'Disk',
});

print "Content-type: image/svg+xml\n\n";
print $graph->burn();

like??? that's it. that's the whole thing. iconic. 🎀

---

💜 DESCRIPTION 💜

so the whole point of this object is to let you easily create high quality SVG line graphs of XY data. periodt. ✨

you've got options, bestie. you can either roll with the default style sheet, or you can supply your own. either way there are so many options you can configure to control how the graph gets generated — with or without a key, data elements at each point, title, subtitle, etc. etc. the whole main character lineup. 💅

---

🧚 METHODS 🧚

🍓 new()

use SVG::TT::Graph::XY;

my $graph = SVG::TT::Graph::XY->new({

  # Optional - defaults shown
  'height'              => 500,
  'width'               => 300,

  'show_y_labels'       => 1,
  'yscale_divisions'    => '',
  'min_yscale_value'    => 0,
  'max_yscale_value'    => '',

  'show_x_labels'       => 1,
  'xscale_divisions'    => '',
  'min_xscale_value'    => '',
  'max_xscale_value'    => '',
  'stagger_x_labels'    => 0,
  'rotate_x_labels'     => 0,
  'y_label_formatter'   => sub { return @_ },
  'x_label_formatter'   => sub { return @_ },

  'show_data_points'    => 1,
  'show_data_values'    => 1,
  'rollover_values'     => 0,

  'area_fill'           => 0,

  'show_x_title'        => 0,
  'x_title'             => 'X Field names',

  'show_y_title'        => 0,
  'y_title'             => 'Y Scale',

  'show_graph_title'    => 0,
  'graph_title'         => 'Graph Title',
  'show_graph_subtitle' => 0,
  'graph_subtitle'      => 'Graph Sub Title',
  'key'                 => 0,
  'key_position'        => 'right',

  # Stylesheet defaults
  'style_sheet'         => '/includes/graph.css', # internal stylesheet
  'random_colors'       => 0,
});

so the constructor takes a hash reference, and all the values default to exactly what's shown up there 👆 — except for style_sheet, which defaults to using the internal style sheet. iykyk. 💖

🌈 add_data()

my @data_cpu  = (0.3, 23, 0.5, 54, 1.0, 67, 1.8, 12);
or
my @data_cpu = ([0.3,23], [0.5,54], [1.0,67], [1.8,12]);
or
my @data_cpu = ([0.3,23,'23%'], [0.5,54,'54%'], [1.0,67,'67%'], [1.8,12,'12%']);

$graph->add_data({
  'data' => \@data_cpu,
  'title' => 'CPU',
});

this method is how you feed data into the graph object, bestie. the data can be either:

• a list of scalars — in which case pairs of elements are taken to be X,Y pairs 🫶
• a list of array references — in which case the first two elements in each referenced array are taken to be X and Y, and the optional third element (if it's there) is used as the text to display for that point for show_data_values and rollover_values; otherwise the Y value itself gets displayed ✨

and the best part? you can call it several times to add more data sets in. stack 'em up, queen. 👑

🦋 clear_data()

my $graph->clear_data();

this one removes all data from the object, so you can reuse it to create a new graph but with the same config options. lowkey the most efficient thing ever. 💅

💀 burn()

print $graph->burn();

this method processes the template with the data and config that's been set, and returns the resulting SVG. 🔥

⚠️ heads up bestie: this method will croak unless at least one data set has been added to the graph object. no data, no graph, no mercy. 😭

👑 config methods

my $value = $graph->method();
my $confirmed_new_value = $graph->method($value);

here's the list of methods you can use to change the config of the graph object after it's been created. go wild. 🎀

⭐ height()

Set the height of the graph box — this is the total height of the SVG box created, not the graph itself, which auto scales to fix the space. 🦋

⭐ width()

Set the width of the graph box — this is the total width of the SVG box created, not the graph itself, which auto scales to fix the space. 🦋

⭐ compress()

Whether or not to compress the content of the SVG file. (Compress::Zlib required.) 🗜️

⭐ tidy()

Whether or not to tidy the content of the SVG file. (XML::Tidy required.) 🧹

⭐ style_sheet()

Set the path to an external stylesheet. set it to '' if you want to revert back to using the default internal version.

set it to "inline:<style>...</style>" with your CSS in between the tags. that way you can override the default style without requiring an external URL. 💅

the default stylesheet handles up to 12 data sets. all data series over the 12th will have no style and be in black. if you have over 12 data sets you can assign them all random colors (see the random_color() method) or create your own stylesheet and add the additional settings for the extra data sets.

to create an external stylesheet, create a graph using the default internal version, copy the stylesheet section to an external file, and edit from there. 🎀

⭐ random_colors()

Use random colors in the internal stylesheet. 🌈

⭐ show_data_values()

Show the value of each element of data on the graph — or optionally a user-defined label; see add_data. ✨

⭐ show_data_points()

Show a small circle on the graph where the line goes from one point to the next. ⚪

⭐ rollover_values()

Shows data values and data points when the mouse is over the point. used in combination with show_data_values and/or show_data_points. 🖱️

⭐ data_value_format()

Format specifier to for data values (as per printf). 🍓

⭐ max_x_span()

Maximum span for a line between data points on the X-axis. if this span is exceeded, the points are not connected. this is useful for skipping missing data sections. if you set this value to something smaller than 0 (e.g. -1), you will get an XY scatter plot with no line joining the data points. 💅

⭐ stacked()

Accumulates each data set. (i.e. Each point increased by sum of all previous series at same point.) default is 0, set to '1' to show. 📚

⭐ min_yscale_value()

The point at which the Y axis starts, defaults to '0', if set to '' it will default to the minimum data value. 📉

⭐ max_yscale_value()

The point at which the Y axis ends, if set to '' it will default to the maximum data value. 📈

⭐ yscale_divisions()

This defines the gap between markers on the Y axis, default is a 10th of the range, e.g. you will have 10 markers on the Y axis.

😭 NOTE: do not set this too low — you are limited to 999 markers, after that the graph won't generate.

⭐ show_x_labels()

Whether to show labels on the X axis or not, defaults to 1, set to '0' if you want to turn them off. 🏷️

⭐ show_y_labels()

Whether to show labels on the Y axis or not, defaults to 1, set to '0' if you want to turn them off. 🏷️

⭐ y_label_format()

Format string for presenting the Y axis labels (as per printf). 🍓

⭐ xscale_divisions()

This defines the gap between markers on the X axis. default is the entire range (only start and end axis labels). 📏

⭐ stagger_x_labels()

This puts the labels at alternative levels, so if they are long field names they will not overlap so easily. default it '0', to turn on set to '1'. 🪜

⭐ rotate_x_labels()

This turns the X axis labels by 90 degrees. default it '0', to turn on set to '1'. 🔄

⭐ min_xscale_value()

This sets the minimum X value. any data points before this value will not be shown. ✂️

⭐ max_xscale_value()

This sets the maximum X value. any data points after this value will not be shown. ✂️

⭐ show_x_title()

Whether to show the title under the X axis labels, default is 0, set to '1' to show. 🏷️

⭐ x_title()

What the title under X axis should be, e.g. 'Parameter X'. ✍️

⭐ show_y_title()

Whether to show the title under the Y axis labels, default is 0, set to '1' to show. 🏷️

⭐ y_title()

What the title under Y axis should be, e.g. 'Sales in thousands'. ✍️

⭐ show_graph_title()

Whether to show a title on the graph, default is 0, set to '1' to show. 🏷️

⭐ graph_title()

What the title on the graph should be. ✍️

⭐ show_graph_subtitle()

Whether to show a subtitle on the graph, default is 0, set to '1' to show. 🏷️

⭐ graph_subtitle()

What the subtitle on the graph should be. ✍️

⭐ key()

Whether to show a key, defaults to 0, set to '1' if you want to show it. 🔑

⭐ key_position()

Where the key should be positioned, defaults to 'right', set to 'bottom' if you want to move it. 📍

⭐ x_label_formatter ()

A callback subroutine which will format a label on the x axis. for example:

$graph->x_label_formatter( sub { return '$' . $_[0] } );

💅

⭐ y_label_formatter()

A callback subroutine which will format a label on the y axis. for example:

$graph->y_label_formatter( sub { return '$' . $_[0] } );

💅

---

🌟 EXAMPLES 🌟

for examples, look at the project home page: http://leo.cuckoo.org/projects/SVG-TT-Graph/ 🦋

---

✨ EXPORT ✨

None by default. (yeah, nothing. it's giving minimalist. 💅)

---

🫶 SEE ALSO 🫶

• SVG::TT::Graph
• SVG::TT::Graph::Line
• SVG::TT::Graph::Bar
• SVG::TT::Graph::BarHorizontal
• SVG::TT::Graph::BarLine
• SVG::TT::Graph::Pie
• Compress::Zlib
• XML::Tidy

---

and that's the whole page bestie!! 🎀✨ this was perl v5.36.0, documented back on 2022-11-19, and it's all in the user contributed perl documentation section. go make some graphs, you absolute icon. 👑💖