Moth

A 2D Graphing Application

Documentation

XML

Each XML file describes how to generate one or more images. This is done by specifying one or more sources of data, and one or more images. The drawing layers of the images then use the data in the columns to figure out where to draw.

Since the contents of a data source are interpretted as XML, special care must be taken when the contents contain certain characters. The following table lists alternatives for the characters that have special meaning in XML:

& &

< <

Alternately, you can use the CDATA method of guarding against XML interpretation. A chunk of text that starts with <![CDATA[ and ends with ]]> will not be interpretted by the XML parser.

The fact that the contents of a data source is interpretted as XML allows you to use XML comments to hide part of the contents from the data source.  is the end. They may not be nested.

The image tags which actually draw data (<area>, <grid>, <line>, <points>, and <segments>) are drawn in layers in order that they appear in the image, bottom to top.

Top-Level Tag

<moth>

Attributes:

name	type	default
draw	boolean	`true`
dump-columns	boolean	`false`
draw-nan	boolean	`false`
dump-xml	boolean	`false`

Contents: <mysql>
<rpn>
<rrd>
<textfile>
<image>

Data Source Tags

<mysql>

Attributes:

name	type	default
columns	column list
host	text	"`localhost`"
database	text
username	text
password	text

Contents: SQL

<rpn>

Attributes:

name	type	default
columns	column list

Contents:

reverse polish notation

<rrd>

Attributes:

name	type	default
columns	column list
filename	filename
cf	"`AVERAGE`" or "`MIN`" or "`MAX`" or "`LAST`"
start	text	see '`man rrdfetch`'
end	text	see '`man rrdfetch`'
resolution	integer seconds	see '`man rrdfetch`'

Contents: A whitespace-separated list of ds-names, used to fill the columns. The columns are filled in the same order as the ds-names are given.
Note: The first column is filled with the timestamps pulled out of the rrd file.

Attributes:

name	type	default
columns	column list
filename	filename
skip	integer	`0`
delimiter	text	tab

Image Tags

<image>

Attributes:

name	type	default
filename	filename
fileformat	text
width	integer pixels
height	integer pixels
size-type	"`image`" or "`canvas`"	"`canvas`"
title	text
background	color	"`white`"
canvas	color	"`white`"
border-color	color	"`#CCCCCC`"
border-size	integer pixels	`1`

Contents: <axis>
<area>
<grid>
<line>
<points>
<segments>

<axis>

Attributes:

name	type	default
location	"`left`" or "`top`" or "`right`" or "`bottom`"
scaling	"`linear`" or "`log2`" or "`loge`" or "`log10`"	"`linear`"
clip-min	double
clip-max	double
clip-force	boolean	`false`
snap-to	double
title	text
color	color	"`black`"

Contents: <label>

<label>

Attributes:

name	type	default
color	color	"color" attribute of parent axis
modulus	double	"snap-to" attribute of parent axis if it exists
offset	double	`0.0`

Contents: value template
default is "%1.0#"

Drawing Layer Tags

<area>

Attributes:

name	type	default
title	text
color	color	"`black`"
x0	column	"`x0`" or "`x`"
y0	column	"`y0`" or "`y`"
x1	column	"`x1`" or "`x`"
y1	column	"`y1`" or "`y`"
x-axis	"`left`" or "`right`"	"`left`"
y-axis	"`top`" or "`bottom`"	"`bottom`"

<grid>

Attributes:

name	type	default
color	color	"`black`"
x-modulus	double
y-modulus	double
x-offset	double	`0.0`
y-offset	double	`0.0`
x-axis	"`left`" or "`right`"	"`left`"
y-axis	"`top`" or "`bottom`"	"`bottom`"

<line>

Attributes:

name	type	default
title	text
color	color	"`black`"
x	column	"`x`"
y	column	"`y`"
x-axis	"`left`" or "`right`"	"`left`"
y-axis	"`top`" or "`bottom`"	"`bottom`"
width	pixels or column	`1.0`

Attributes:

name	type	default
title	text
color	color	"`black`"
x	column	"`x`"
y	column	"`y`"
x-axis	"`left`" or "`right`"	"`left`"
y-axis	"`top`" or "`bottom`"	"`bottom`"
radius	pixels or column	`0.5`
filled	boolean	`false`

Attributes:

name	type	default
title	text
color	color	"`black`"
x0	column	"`x0`" or "`x`"
y0	column	"`y0`" or "`y`"
x1	column	"`x1`" or "`x`"
y1	column	"`y1`" or "`y`"
x-axis	"`left`" or "`right`"	"`left`"
y-axis	"`top`" or "`bottom`"	"`bottom`"
width	pixels or column	`1.0`

Attribute Types

boolean: A boolean value indicates a condition that is either true or false. "on", "yes", "true", or 1.0 are interpretted as true, everything else is interpretted as false.
color: See the colors documentation page.
column: The name of a column, which must have already been created by a datasource. (It must have been specified in a column list.)
column list: A column list is a comma-separated list of column names. The name of each column must start with a letter and must not be all UPPERCASE.
double: A double is a real number -- a number that has a whole and decimal part. (The name "double" comes from Computer Science and refers to how accurate a number can be represented.)
filename: A filename is the name of a file. If an relative path is used, it is usually interpretted in relation to where the moth program is run.
integer: An integer is a whole number -- a number without a decimal part.
text: A chunk of text. Some attributes may also have restrictions on what constitutes a valid value. For example, <mysql>'s attribute database must be a valid database on the specified host.