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).