A. The Plotter Output Syntax

When used in plotter mode, the plugins write information about each plot which is generated to standard output. This output is designed to be parsed by some kind of wrapper which presents the plots in a more user friendly way.

A.1. Formal Syntax Definition

The formal syntax definition is written in ABNF ¹.

output    = 1*(imagedata)

imagedata = title start end-p image width height 1*(plotdata) end

plotdata  = dimension unit avg min max last

title     = "TITLE" ws string lf

start     = "START" ws integer lf

end-p     = "END" ws integer lf

image     = "IMAGE" ws string lf

width     = "WIDTH" ws integer lf

height    = "HEIGHT" ws integer lf

dimension = "DIMENSION" ws string lf

unit      = "UNIT" ws string lf

avg       = "AVG" ws float lf

min       = "MIN" ws float lf

max       = "MAX" ws float lf

last      = "LAST" ws float lf

end       = "END" lf

string    = chars-nb *chars-b
               ; a string is a concatenation of one non blank character
               ; and any number of characters including blanks.

chars-nb  = (%x21-FF)
               ; a non blank character is any character with an ASCII
               ; value greater 32 decimal.

chars-b   = (%x20-FF)
               ; a character including blank is any character with an
               ; ASCII value greater or equal 32 decimal.

integer   = ["-"] 1*(%x30-39)
               ; an integer is a optional minus followed by at least one
               ; decimal digit.

float     = ["-"] 1*(%x30-39) "." 1*(%x30-39)
               ; a float is a optional minus followed by at least one
               ; decimal digit followed by a dot followed by at least one
               ; decimal digit.

ws        = 1*(%d32)
               ; whitespace is one or more blank character (ASCII 32).

lf        = %d10
               ; line feed is one linefeed character (ASCII 10).

Notes about the syntax definition:

ABNF strings are case-insensitive by definition, the plugins however use only capital letters for keywords. Therefor a parser does not have to implement case insensitive keyword matching.
This definition does not rely on implicit white space, i. e. white space is only used inside string literals and where explicitly needed.
The definition allows characters between 7E_hex and FF_hex to be used within strings. The plugins never use any character from this range, they may however have been parsed from the command line using the “-I” parameter.

A.2. Convenient Description

While ABNF may be the perfect tool to define the syntax of the plotter output, describing it is a lot simplier.

The output consists of several blocks each describing one image. Each block consists of lines where each line in turn consists of a keyword and a value separated by one or more blanks. There is one exception to the keyword-value pair rule, which is the “END” line without value, which ends one image block.²

Within each image block there are several “plot” blocks, each containing information about one plot i. e. one curve.

The semantics of the lines—in order of apperance—are:

TITLE: descriptive title for the image. This is usually built from the name of the host, the indices a/o the additional information.
START: the time at the start of the plotted range as timestamp³.
END: the time at the end of the plotted range.
IMAGE: the basename of the image, i. e. the name of the image without leading directories.
WIDTH: the width of the image.
HEIGHT: the height of the image.
DIMENSION: the dimension of a plot. This is the first line of a plot block.
UNIT: the unit of the following values.
AVG: the average value during the time plotted.
MIN: the minimum value during the time plotted.
MAX: the maximum value during the time plotted.
LST: the last value in the archive. This is the last line of a plot block.
END: the last line of an image block.

¹c.f. ftp://ftp.rfc-editor.org/in-notes/rfc4234.txt

²Two different cases where “END” is used may be considered a design error.

³Seconds since 1970-01-01 00:00:00 UTC