The Perl and Raku Conference 2025: Greenville, South Carolina - June 27-29 Learn more

 / 
Text-Graph-0.83
River stage zero No dependents
/ Text::Graph

NAME

Text::Graph - Perl module for generating simple text-based graphs.

VERSION

This document describes "Text::Graph" version 0.82.

SYNOPSIS


            

              
              
use Text::Graph;
my $graph = Text::Graph->new( 'Bar' );
print $graph->to_string( $dataset, labels => $labels );

DESCRIPTION

Some data is easier to analyze graphically than in its raw form. In many cases, however, a full-blown multicolor graphic representation is overkill. In these cases, a simple graph can provide an appropriate graphical representation.

The Text::Graph module provides a simple text-based graph of a dataset. Although this approach is not appropriate for all data analysis, it can be useful in some cases.

Functions

new

The list below describes the parameters.

  • minval - Minimum value cutoff. All values below minval are considered equal to minval. The default value for minval is 0. Setting the minval to undef causes Text::Graph to use the minimum of values as minval.

  • maxval - Maximum value cutoff. All values above maxval are considered equal to maxval. The default value for maxval is undef which causes Text::Graph to use the maximum of values as maxval.

  • maxlen - Maximum length of a histogram bar. This parameter is used to scale the histogram to a particular size. The default value for maxlen is (maxval - minval + 1).

  • marker - Character to be used for the highest point on each bar of the histogram. The default value for marker is '*'.

  • fill - Character to be used for drawing the bar of the histogram, except the highest point. The default value for fill is the value of marker.

  • log - Flag determining if the graph is logarithmic or linear. The default value for log is 0 for a linear histogram.

  • showval - Flag determining if the value of each bar is displayed to the right of the bar. The default value for showval is 0, which does not display the value.

  • separator - String which separates the labels from the histogram bars. The default value of separator is ' :'.

  • right - Flag which specifies the labels should be right-justified. By default, this flag is 0, specifying that the labels are left justified.

get_marker

The get_marker method returns the marker associated with this graph.

get_fill

The get_fill method returns the fill character used for this graph.

is_log

The is_log method returns a flag telling whether this is a logarithmic graph (true) or linear graph (false).

get_maxlen

The get_maxlen method returns the maximum length of the graph this value is used to scale the graph.

get_maxval

The get_maxval method returns the maximum value cutoff defined for this graph. A value of undef means the graph is not cut off.

get_minval

The get_minval method returns the minimum value cutoff defined for this graph. A value of undef means the graph is not cut off.

get_separator

The get_separator method returns the string used to separate the labels from the graph.

is_right_justified

The get_separator method returns true if the labels are right justified, false otherwise.

show_value

The show_value method returns true if the actual values are shown next to the bars, false otherwise.

make_lines

The make_lines method converts a dataset into a list of strings representing the dataset. The make_lines takes either a Text::Graph::DataSet object or the parameters needed to construct such an object. If used in array context, it returns an array of bars. If used in scalar context, it returns a reference to an array of bars.

make_labelled_lines

The make_lines method converts a dataset into a list of strings representing the dataset. The make_lines takes either a Text::Graph::DataSet object or the parameters needed to construct such an object. Unlike make_lines, each line in this returned list is labelled as described in the Text::Graph::DataSet object. If used in array context, it returns an array of bars. If used in scalar context, it returns a reference to an array of bars.

to_string

The to_string method creates a displayable Graph for the supplied dataset. The Graph is labelled as specified in the DataSet. The to_string method accepts all of the same parameters as make_lines.

Examples

Bar Graph of an Array


            

              
              
use Text::Graph;
my $graph = Text::Graph->new( 'Bar' );
print $graph->to_string( [1,2,4,5,10,3,5],
                         labels => [ qw/aaaa bb ccc dddddd ee f ghi/ ],
                       );

Generates the following output:


            

              
              
aaaa   :
bb     :*
ccc    :***
dddddd :****
ee     :*********
f      :**
ghi    :****

Line Graph of an Array


            

              
              
use Text::Graph;
my $graph = Text::Graph->new( 'Line' );
print $graph->to_string( [1,2,4,5,10,3,5],
                         labels => [ qw/aaaa bb ccc dddddd ee f ghi/ ],
                       );

Generates the following output:


            

              
              
aaaa   :
bb     :*
ccc    :  *
dddddd :   *
ee     :        *
f      : *
ghi    :   *

Bar Graph of an Anonymous Hash


            

              
              
use Text::Graph;
my $graph = Text::Graph->new( 'Bar' );
print $graph->to_string( { a=>1, b=>5, c=>20, d=>10, e=>17 } );

Generates the following output:


            

              
              
a :
b :****
c :*******************
d :*********
e :****************

Bar Graph of an Anonymous Hash in Reverse Order


            

              
              
use Text::Graph;
use Text::Graph::DataSet;
my $graph = Text::Graph->new( 'Bar' );
my $dataset = Text::Graph::DataSet->new ({ a=>1, b=>5, c=>20, d=>10, e=>17 },
                                      sort => sub { sort { $b cmp $a } @_ });
print $graph->to_string( $dataset );

Generates the following output:


            

              
              
e :****************
d :*********
c :*******************
b :****
a :

Bar Graph of Part of an Anonymous Hash


            

              
              
use Text::Graph;
use Text::Graph::DataSet;
my $graph = Text::Graph->new( 'Bar' );
my $dataset = Text::Graph::DataSet->new ({ a=>1, b=>5, c=>20, d=>10, e=>17 },
                                      labels => [ qw(e b a d) ]);
print $graph->to_string( $dataset );

Generates the following output:


            

              
              
e :****************
b :****
a :
d :*********

Filled Line Graph With Advanced Formatting


            

              
              
use Text::Graph;
use Text::Graph::DataSet;
my $dataset = Text::Graph::DataSet->new ([1,22,43,500,1000,300,50],
                                      [ qw/aaaa bb ccc dddddd ee f ghi/ ]);
my $graph = Text::Graph->new( 'Line',
                              right  => 1,    # right-justify labels
                              fill => '.',    # change fill-marker
                              log => 1,       # logarithmic graph
                              showval => 1    # show actual values
                            );
print $graph->to_string( $dataset );

Generates the following output:


            

              
              
  aaaa :        (1)
    bb :.*      (22)
   ccc :..*     (43)
dddddd :....*   (500)
    ee :.....*  (1000)
     f :....*   (300)
   ghi :..*     (50)

SEE ALSO

perl(1).

ACKNOWLEDMENTS

Thanks to Jerry D. Hedden for pointing out a few inconsistencies in the code. Sorry for taking so long to get back to the module to fix it.

AUTHOR

G. Wade Johnson, gwadej@cpan.org

COPYRIGHT

Copyright 2002-2014 G. Wade Johnson

This module is free software; you can distribute it and/or modify it under the same terms as Perl itself.

perl(1).