Chart::...Methods(3)

💖 NAME 💖

Okay bestie, this is the Chart::...Methods(3) page, aka Chart::Manual::Methods — the user API page from the User Contributed Perl Documentation. It is literally the whole method menu for chart users. ✨

🌸 OVERVIEW 🌸

These are all the methods for the chart user. No secret menu, no cap. 💅

✨ ALPHABETICALLY ✨

🎀 add_datafile 🎀

Loads all data of a chart (one or more data sets) from a file. Fr fr, it only works if no data has been added yet. You have to either provide a filename or filehandle (OLD_SCHOOL or $scalar).

The doc's own snippets use add_dataset here — keeping them exactly as-is, bestie:

$graph->add_dataset( 'file.tsv' );
$graph->add_dataset( $file_handle );
$graph->add_dataset( FILE_HANDLE );

An optional second argument defaults to 'set' and can change the file format if set to 'pt'. In 'set' mode every row of the file content is fed to add_dataset; in 'pt' every row gets loaded like via add_pt. In other words: 'pt' transposes the data table.

$graph->add_dataset( 'file.tsv', 'pt'  );

The arbitrary named text files have to contain one or several rows of numbers. The numbers need to be separated by spaces or tabs (\t) (mixing allowed). Perl style comments or empty lines will be ignored, but rows containing different amount of numbers will cause problems. 😭

🦋 add_dataset 🦋

Adding a list of values as one data set. That is one row in the overall data table. The first data set are usually x-axis labels (domain set). Make sure all sets have the same length.

$graph->add_dataset(  1, 2, 3, ...  );
$graph->add_dataset( [1, 2, 3, ...] );

For instances with Points, Lines or Bars one data set is represented by a set of graphic items (points, bars or line) of one color. 💅

🌼 add_pt 🌼

Adds (appends) to each already existing data set one value. That is a column in the overall data table. In this example it adds to set 0 the value 3, to set 1 the 6 and so forth. Make sure that the list lengths matches the number of already existing data sets.

$graph->add_pt(  3, 6, 9, ...  );
$graph->add_pt( [3, 6, 9, ...] );

💀 cgi_jpeg 💀

Creates same JPEG image as jpeg, but outputs to STDOUT. Since no file name or handle needed, only the optional data argument is acceptable.

$graph->cgi_jpeg( );

my @data = ([1, 2, 3],   # data set 0
            [3, 4, 5]);  # data set 1
$graph->cgi_jpeg( \@data );

🫶 cgi_png 🫶

Creates same PNG image as png, but outputs to STDOUT. Since no file name or handle needed, only the optional data argument is acceptable.

$graph->cgi_png( );

my $data = [[1, 2, 3],   # data set 0
            [3, 4, 5] ]; # data set 1
$graph->cgi_png( $data );

🧹 clear_data 🧹

Needs no arguments and deletes all so far added data. Poof, gone. 💨

🍓 get_data 🍓

Return all data (array of arrays) given to a graph.

🗺️ imagemap_dump 🗺️

So when you're creating a chart for web purposes by cgi_jpeg or cgi_png, you maybe want the information where the areas of interests in the image are located — the spots that should react to a user's click. (HTML tag map.) These areas are bounding boxes around the drawn bars or points. You will get per box the values: x1, y1, x2, y2 in one array. These arrays are again in an Array holding all boxes from one data set. The highest level array again holds all arrays of all data sets, beginning with index 1.

This method can only be called if the functionality is activated by setting the property: imagemap to 'true'.

$graph->set( imagemap => 'true');
my $image_map = $graph->imagemap_dump();

say "coordinates of first bar, first data set:";
say for @{$image_map->[1][0]};

🖼️ jpeg 🖼️

Creates an JPEG image from given data and properties. Accepts a file name or a file handle (raw or in a SCALAR). The method closes the file handle.

$graph->jpeg( 'image.jpg' );
$graph->jpeg( $file_handle );
$graph->jpeg( FILE_HANDLE );

$graph->jpeg( 'image.jpg', $data );
$graph->jpeg( 'image.jpg', 'data_file.tsv' );
$graph->jpeg( 'image.jpg', $file_handle );
$graph->jpeg( 'image.jpg', FILE_HANDLE );

The second, optional argument is the data in form of an array of arrays reference. This only works if there is no data already given to the object. Alternatively the data can also be loaded from a file, just provide the filename or filehandle (modern in SCALAR or old school). Read more about the file format at add_datafile and note that this method has another option for loading transposed data tables. ✨

👑 new 👑

Creates a new chart object. Takes two optional arguments, which are the width and height of the to be produced image in pixels. Defaults for that are 400 x 300.

my $graph = Chart::Bars->new ( );
my $graph = Chart::Bars->new (600, 700);

Instead of Bars, you can also use: Composite, Direction, ErrorBars, HorizontalBars, Lines, LinesPoints, Mountain, Pareto, Pie, Points, Split and StackedBars. To know more about them read Chart::Manual::Types. 🌈

🌸 png 🌸

Creates an PNG image from given data and properties. Accepts a file name or a file handle (raw or in a SCALAR). The method closes the file handle.

$graph->png( 'image.png' );
$graph->png( $file_handle );
$graph->png( FILE_HANDLE );

$graph->png( 'image.png', $data );
$graph->png( 'image.png', 'data_file.tsv' );
$graph->png( 'image.png', $file_handle );
$graph->png( 'image.png', FILE_HANDLE );

The second, optional argument is the data in form of an array of arrays reference. This only works if there is no data already given to the object. Alternatively the data can also be loaded from a file, just provide the filename or filehandle (modern in SCALAR or old school). Read more about the file format at add_datafile and note that this method has another option for loading transposed data tables. 💅

🎀 scalar_jpeg 🎀

Creates same JPEG image as jpeg but returns the image binary into a variable, not to STDOUT or a file.

my $image_binary = $graph->scalar_jpeg();
my $image_binary = $graph->scalar_jpeg( $data );

🦋 scalar_png 🦋

Creates same PNG image as png but returns the image binary into a variable, not to STDOUT or a file.

my $image_binary = $graph->scalar_png();
my $image_binary = $graph->scalar_png( $data );

💜 set 💜

Method to change one or more chart properties in hash form.

$chart->set ( property_name => 'new value', ... );
$chart->set ( %properties );

Different chart types react to different properties, which are all listed and explained under Chart::Manual::Properties. 🔥

💜 COPYRIGHT & LICENSE 💜

Copyright 2022 Herbert Breunung.

This program is free software; you can redistribute it and/or modify it under same terms as Perl itself.

👑 AUTHOR 👑

Herbert Breunung, <lichtkind@cpan.org>

---

That's the whole page, bestie! 💅 This one is from perl v5.42.0, dated 2022-11-29, and it's the Chart::...Methods(3) page. Go make a chart that eats. 🎀