gchart

gchart.lua - Create charts using the Google Charts API

Google Charts API works on a very simple principle. You encode all the data about the chart you want 
to render into a URL, and when you request this URL you will receive a PNG image of your chart.

The API is very fussy about the format of the data you pass it, so this library abstracts all that away, 
and lets you create charts, manipulate them, and then build the URL when you are ready.

## Example

   gchart = require "gchart"
   gchart.default:set_color("C6D9FD");
   
   mychart = gchart.new("bar")
   mychart:add_series({ 100, 200, 100, 400 })
   
   print("Chart:", chart:url());
   --> Chart: http://chart.apis.google.com/chart?cht=bvs&chco=00CC00,CC0000&&chd=e:DwS0Dww7&chs=320x200

## Reference

### Defaults

gchart.lua exposes a default chart object. All charts will 'inherit' the properties from this chart unless you override them. For example:

   gchart.default:set_color("C6D9FD") -- All charts will now be this colour by default

### Core

 gchart.set_base_url(url): Set the base URL of the API. Default: "http://chart.apis.google.com/chart"
	For example if another provider supports an API compatible with Google Charts, you could use this to switch gchart.lua to using their service instead.

 gchart.new(type): Creates a new chart. Default type is "line".
	Returns the new chart object.

### Charts

All these functions assume that 'chart' is a chart object returned from gchart.new().

 chart:set_type(type): Set the type of chart.
	May be one of "line", "sparkline", "plot", "bar" or a type code straight from the Google API, like "bhs".

 chart:add_series(series): Add a new data series
	Takes an array of numbers, each represinting a data point. For example { 10, 20, 30 }.

 chart:set_scale(min, max): Set the minimum and maximum values for the chart
	The Google Chart API does not automatically scale input data. By default gchart.lua will attempt
	to scale the graph so that the base line is 25% lower than the lowest value on the graph, and the 
	top axis 25% higher than the highest value on the graph. Supply custom numbers for either or both of 
	min and max, or set to true for gchart.lua to auto-scale that value (default is to auto-scale both min 
	and max).

 chart:set_size(width, height): Set the width and height of the generated chart in pixels
 	Google Chart API limits the maximum size of generated charts, the default size is 320x200.

 chart:set_title(title): Set the title of the chart
 	The title will be displayed at the top of the chart. Both the '|' (pipe) and \n (newline) characters 
 	will start a new line (use for sub-titles).

 chart:set_legend(entries): Add a legend to a chart
	Set entries to a list of legend entries, in the same order as your data series were added. For example 
	{ "Temperature", "Rainfall", "Humidity" }.

 chart:set_legend_position(position, layout): Set the position of the legend
 	position may be one of "top", "bottom", "left" or "right". Default is "right".
 	layout may be one of "vertical" or "horizontal". Default is "vertical". When using 
 	the "horizontal" layout, the only valid positions are "top" and "bottom".

 chart:add_axis(location, options): Add an axis to the chart
	location may be one of "top", "bottom", "left" or "right".
	options is an (optional) table allowing you to configure how the axis is displayed. For more info see
	the 'Axes' section below.

 chart:add_marker(marker): Add a marker to one or more datapoints
 	'marker' is a table of options. For more info see the 'Markers' section below.

 chart:set_color(color): Set the colour of the graph lines
 	Colours are specified as hexidecimal values of red, green and blue, just as in HTML. An optional addition 
 	is appending 2 further digits to specify the opacity. For example 50% transparent blue would be: 0000FFCC.
 	It is possible to specify multiple colours, separated by commas, which will be used differently according 
 	to the chart type. For example "0000FFCC,FF0000CC".

 chart:url(): Return the URL to render the chart
 	Last but not least, call this function to retrieve the URL to generate the graph with all properties applied.

## Axes

Axes are extremely flexible in Google Charts API. Add an axis with chart:add_axis(location, options) as described above. The 'options'
table may contain any of the following options:

 options.range: Specify the range of the axis markers
 	For example: options.range = { min = 0, max = 500 }
 
 options.labels: Specify text labels along the axis instead of numbers
	For example: options.labels = { "Jan", "Feb", "Mar", "Apr" }
	or with positions: options.labels = { Jan = 10, Feb = 20, Mar = 30, May = 50 }

 options.style: Specify the style of an axis
 	Currently a string of the form: <axis color>,<font size>,<alignment>,<drawing control>,<tick mark color>
 	Only the colour is required, and further parameters are optional.
 	For example, a green axis: options.style = "00CC00"
 	and with 12pt text: options.style = "00CC00,12"
 	
 options.ticklength: Specify the length of the tickmarks on the axis
 	Must be a number. From the Google documentation:
 	"Positive values are drawn outside the chart area. The maximum positive value is 25."
 	"Negative values are drawn inside the chart area. Use this feature to draw gridlines on a chart."


## Markers
 
Markers can be used to draw attention to specific points on the chart. They can be added using chart:add_marker(marker), 
where 'marker' is a table of marker options, as described below:

  marker.label: Text label for the marker. Default is to use marker.index.
  
  marker.color: Colour for the marker. A simple hexadecimal value like 00FF00.
  
  marker.series: Which data series the marker should be on. Default is 0 (the first series)
  
  marker.index: The index of the data point to add the marker at. Default is 0 (the start of the series)
  
  marker.size: Text size of the marker's label. Default is 11 (for 11pt text)

  marker.priority: When to draw the marker
  	From the Google documentation:
  	 -1 specifies that the label is drawn before all other parts of the chart. The label will be 
  	    hidden if another chart element is drawn in the same place.
  	    
  	  0 specifies that the label is drawn after bars or lines, but before other labels. This is the default.
  	  
  	  1 specifies that the label is drawn after all other parts of the chart. If more than one label has this 
  	    value, the first one will be drawn first, the second one drawn second, and so on.