TextBarGraph v0.1alpha

Preface

As you might consider from the version number this is definitely alpha software. So far it has been only tested by a small amount of people and can contain buckets of bugs.

Overview

This module generates text bar graphs based on data sent to it in a list. It was inspired by the Perl module “Text::BarGraph” by Kirk Baucom.

Parameters overview

name	default	meaning	Possible values
dot	“#”	character used to create bars	any ASCII character
num	0	display the numerical values	0, 1
numAlign	“left”Alignment of numerical values	left, right, block
xsize	80	maximum horizontal size of graph	any positive integer
highlight	[]	name(s) of bar(s) to be highlighted	key names defined in list
highlightDot	“*”	character used to create an optional	any ASCII character hightlighted bar
highlightColor	None	color used for optional highlighted bar	any defined ANSI color
highlightLabels	1	also hightlight labels and values	0, 1
labelAlign	“right”	Alignment for labels	left, right, center

The parameters in detail:

dot:

Defines the parameter which is used to create the bar itself. Common characters used are “#”, “*” or “=” but you can use any character which can be displayed on the target system.
Possible value: any displayable character
Default value: “#”

num:

You can display a value in front or behind the bar (defined by “numAlign”). The value is always displayed as an integer. If you defined a float in the list the value is rounded to an integer. (This will be changed in future
versions.)
Possible value: 0, 1
Default value: 0 (off)

numAlign:

You can align the value display in three ways:

* left: The value will be display the label and the bar itself.

Example:

 alpha (11) #######
 beta  (40) #########################
 gamma (25) ################

* right: The value will be displayed right after each bar.

Example:

 alpha ####### (11)
 beta  ######################### (40)
 gamma ################ (25)

* block: All the values will be right aligned. (There’s still a bug which extends the bars over xsize. This has to be fixed!)

Example:

 alpha #######                      (11)
  beta  #########################    (40)
  gamma ################             (25)

Possible values: “left”, “right”, “center”
Default value: “left”

xsize:

xsize defines the maximum size of the bars in characters. (This will be changed in the future, so that you can decide if this value defines the size of the _whole_ diagramm or behaves like it does now.)

Example 1: xsize = 20

alpha (11) ######
beta  (40) ####################
gamma (25) #############

Example 2: xsize = 40

alpha (11) ###########
beta  (40) ########################################
gamma (25) #########################

Possible values: any positive integer
Default value: 80

highlight:

You can define one or more bars to be highlighted. This is done by passing a string or a list of strings to the graph instance. By default the bar(s) will be displayed using the “*” char and be coloured in red.
Using the parameters “highlightDot” and “highlightColor” you can change these defaults.

Example (using the defaults values)

alpha (11) ###########
beta  (40) ****************************************
gamma (25) #########################

Possible values: any defined bar name(s)
Default value: None

highlightDot:

Defines the character used to display a highlighted bar. You can only use one highlight character for the complete graph.

Possible values: any character
Default value: “*”

highlightColor:

Defines the color used to display a highlighted bar. The colour can be one of the predefined ANSI colors (black, red, green, yellow, blue, magenta, cyan, white). You can only use one highlightColor for the complete graph.

Possible values: any predefined ANSI color
Default value: “red”

highlightLabels:

You can decide if you which to labels together with the bars or not.

Possible values: 1 (on), 0 (off)
Default value: 1

labelAlign:

Example 1: labelAlign = “left”

alpha     (11) ###########
beta      (40) ########################################
thesaurus (25) #########################

Example 2: labelAlign = “right”

    alpha (11) ###########
     beta (40) ########################################
thesaurus (25) #########################

Possible values: “left”, “right”
Default value: “left”

ToDo:

Parameter for defining the behaviour of xsize. There are two possibilities: xsize defines only the maximum size of the bars in characters or it defines the size of the whole diagram.
New parameter behaviour: if xsize=0 the graph size will represent the actual values.
Possibility to define more than one highlight character.
Possibility to define more than one highlight color.
Create an online demo with user definable parameters.

Download:

TextBarGraph.zip

Contacting the author:

If you have some new ideas, found some errors, or want to donate me a better Internet access, please write to dev@elektrolch.de