* Ruby/GDChart 0.0.1

This is an extension library to use the GDCHART C library written by
Bruce Verderaime (http://www.fred.net/brv/chart/).  The extension
provides a the module 'GDChart'.  The following example spits a simple
200x200 PNG chart to standard output.

--
require 'GDChart'

GDChart.title = "A Chart"
GDChart.xtitle = "X-axis"
GDChart.ytitle = "Y-axis"
data = [1, 2, 3, 4, 5, 6]
# the wrong number of labels cause Ruby/GDChart to segfault!
labels = ["label 1", "label 2", "label 3", "label 4", "label 5", "label 6"]
numpoints = 6
numsets = 1
xsize = 200
ysize = 200
GDChart.image_type = GDChart::PNG;
GDChart.out_graph(xsize, ysize, $stdout, GDChart::LINE, numpoints, \
                  labels, numsets, data)
--

This is a first alpha-level version, which means that it works, but
that there has been practically no testing.  Also, no documentation
exists yet, but the extension has an almost 1-1 mapping with the C
library, so using that as a reference you can make charts pretty
quickly.

This extension was written on a Debian GNU/Linux 2.1 system using
ruby-1.6.1.

Basically, most of the code is auto-generated by a couple of scripts
just to get it working in a hurry.  I haven't had much experience with
writing Ruby extensions yet, so don't be surprised if the
implementation is contrived, slow or otherwise non-optimal.  It's not
OO, but the GDCHART C library isn't either.

I welcome questions, comments and suggestions to make this library
more well-designed and robust in the future.

* License

This extension is distributed under the same terms as Ruby (see
<http://www.ruby-lang.org/en/LICENSE.txt>.  The included gd-1.8.3
(needed by GDCHART) and gdchart0.951a libraries have their own license
terms.

* Implemented Functions and Variables

The following list are all the variables in the GDCHART C library
which have a mapping in the Ruby extension.  The (C) datatype after a
variable indicates its use.  Basically, use a number when integer or
float, and a string when string (obviously).

GDC_image_type          integer
GDC_ytitle              string
GDC_xtitle              string
GDC_ytitle2             string
GDC_title               string
GDC_ylabel_fmt          string
GDC_ylabel2_fmt         string
GDC_xlabel_ctl          string
GDC_xlabel_spacing      integer
GDC_ylabel_density      integer
GDC_interpolations      integer
GDC_requested_ymin      float
GDC_requested_ymax      float
GDC_requested_yinterval float
GDC_0Shelf              integer
GDC_grid                integer
GDC_ticks               integer
GDC_xaxis               integer
GDC_yaxis               integer
GDC_yaxis2              integer
GDC_yval_style          integer
GDC_stack_type          integer
GDC_3d_depth            float
GDC_3d_angle            integer
GDC_bar_width           integer
GDC_HLC_style           integer
GDC_HLC_cap_width       integer
GDC_thumbnail           integer
*GDC_thumblabel         string
GDC_thumbval            float
GDC_border              unsigned long integer
GDC_BGColor             unsigned long integer
GDC_GridColor           unsigned long integer
GDC_LineColor           unsigned long integer
GDC_PlotColor           unsigned long integer
GDC_VolColor            unsigned long integer
GDC_TitleColor          unsigned long integer
GDC_XTitleColor         unsigned long integer
GDC_YTitleColor         unsigned long integer
GDC_YTitle2Color        unsigned long integer
GDC_XLabelColor         unsigned long integer
GDC_YLabelColor         unsigned long integer
GDC_YLabel2Color        unsigned long integer
GDC_ExtVolColor         unsigned long integer (pointer)
GDC_SetColor            unsigned long integer (pointer)
GDC_ExtColor            unsigned long integer (pointer
GDC_BGImage             string

There is only one function, GDChart.out_graph, which actually outputs
a chart.

out_graph(xsize, ysize, outputfile, chart_type, num_points, labels, \
          num_sets, data)

The following constants (GDChart::CONSTANT) are defined.  Note about
the 'xxx3D' constants: these were originally of the form GDC_3Dxxx.
When using those constants, remember to move the `3D' to the end of
the name.  This is due to the naming rules of Ruby: a constants can't
begin with a number.

# Chart types
LINE
AREA
BAR
FLOATINGBAR
HILOCLOSE
COMBO_LINE_BAR
COMBO_HLC_BAR
COMBO_LINE_AREA
COMBO_LINE_LINE
COMBO_HLC_AREA
HILOCLOSE3D
COMBO_LINE_BAR3D
COMBO_LINE_AREA3D
COMBO_LINE_LINE3D
COMBO_HLC_BAR3D
COMBO_HLC_AREA3D
BAR3D
FLOATINGBAR3D
AREA3D
LINE3D
# Stack types
STACK_DEPTH
STACK_SUM
STACK_BESIDE
STACK_LAYER
# HiLoClose chart styles
HLC_DIAMOND
HLC_CLOSE_CONNECTED
HLC_CONNECTING
HLC_I_CAP
# Scatter indicators (XXX:?)
SCATTER_TRIANGLE_DOWN
SCATTER_TRIANGLE_UP
SCATTER_CIRCLE
# Axis tick types
TICK_LABELS
TICK_POINTS
TICK_NONE	
# Border types
BORDER_NONE
BORDER_ALL
BORDER_X
BORDER_Y
BORDER_Y2
BORDER_TOP
# Output types
PNG
JPEG
GIF
# Font sizes
TINY
SMALL
MEDBOLD
LARGE
GIANT

* Installation

Installation is pretty straightforward.  If you have the gd and
gdchart libraries, make sure they're versions >= 1.8.3 and >= 0.951,
respectively.  The libraries are included in the distribution, and
will be used if you don't already have them.

~$ ruby extconf.rb
~$ make
~$ make install			# as root


Questions, comments and suggestion are welcome.

Enjoy!


Arjen Laarhoven (arjen@aragorn.demon.nl)