Introduction to gpdiagram

What it does

The perl script "gpdiagram" is a pre-processor for the gnuplot program, allowing anyone to easily produce diagrams from text input. For example, it will convert the string

;triangle (0,0)(4,0)(4,3) ;label (0,0)"_A" ;(4,0)"_B" ;(4,3)">C"

into the picture:

;triangle (0,0)(4,0)(4,3) ;label (0,0)"_A" ;(4,0)"_B" ;(4,3)">C"

More examples can be found on the gpdiagram examples page.


Installation and use

Requirements

This script requires perl ( http://www.perl.com/pub/a/language/info/software.html) and gnuplot ( ftp://ftp.gnuplot.info/pub/gnuplot/ - see the README file for what it all means).

Installation

Use

To have gpdiagram read commands from infile and write an image into outfile, run gpdiagram infile outfile. The image type will depend on outfile's extension (postscript for .ps, png for .png). Leaving off outfile entirely will result in a screen image. To read from standard input, use - for infile. To write to standard output, use -.ps or -.png for outfile.


Syntax

General syntax

Gpdiagram reads all its input into a single string, and then processes that string. The first non-whitespace character in the string is the "parsing character", which separates the string into "objects". (I will use "#" as the parsing character throughout this section, but you are free to choose any otherwise-unused character from !@#%&=;:) Each object has a "type", given by the word at its beginning (if there is none, the previous type is used). The rest of the object are its "parameters". For example, the string

#Line (0,1) (2,3) #Label (4,5)"A" #(6,7)"B"

has an object of type "line" with parameters (0,1) (2,3), and two objects of type "label": the first with parameters (4,5) "A", and the second with parameters (6,7) "B".

Gpdiagram takes only numbers and quoted strings as parameters. In particular, it will ignore any punctuation (including newlines) except for the parsing character and (non-parsing-character) punctuation inside a quoted string. For example, the string #Line (0,1) (2,3) is equivalent to the string #Line 0 1 2 3. This means that you are free to punctuate as you wish.

Type syntax

Type names are case-insensitive. For simplicity, I will demonstrate the syntax of each type by example.

Arrow (1,2) (3,4) Draws an arrow from (1,2) to (3,4)
Bezier (1,2) (4,3) (5,6) Plots a bezier curve with these points as "control points"
Circle (0,1) 2 Draws a circle with center (0,1) and radius 2
Circle (0,1) 2 {0,90} Draws the part of the circle with center (0,1) and radius 2 that has (polar) angle between 0 and 90 degrees
Color "red" Sets the color (options are black, red, green, blue and varies)
Comment "Hello world" This is ignored
Dimensions 10 8 Indicates that the diagram will be about 8 units wide by 10 units high (used only to calculate label offsets)
Ellipse (0,1) [2,3] Draws an ellipse with center (0,1), x-radius 2 and y-radius 3
Ellipse (0,1) [2,3] {0,90} Draws the part of the ellipse with center (0,1), x-radius 2 and y-radius 3 that has (polar) angle between 0 and 90 degrees
Font "Courier" 24 Sets the font to 24-point Courier (used only for postscript output)
Graph 1:2 "ln(x)" Plots the graph of ln(x) from x=1 to x=2???
Label(1,2)"A" Centers the label A at the point (1,2)
Line (1,2) (4,3) (5,6) Plots a polygonal line through the three points
Point (1,2) Plots a point at (1,2)
Rectangle (0,1) (2,3) Draws the rectangle with diagonally opposite corners (0,1) and (2,3)
Set "bmargin 1" Runs the gnuplot command "set bmargin 1" (this sets the bottom margin to be 1 character wide)
Spline (1,2) (4,3) (5,6) Plots a cubic spline through the three points
Title "Hello World" Writes a diagram title
Triangle (1,2) (3,4) (5,6) Draws a triangle with the given vertices


License and disclaimers

License

Gpdiagram is copyright (C) 2003 Michael J Miller

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

Stability and feedback

I am releasing this software under the "release early and often" mantra. Among other things, this means that this is currently beta software, that its specifications are not yet completed, and that it is likely to have bugs. While I will try to maintain backward compatibility, future versions may drift in ways as yet unpredictable.

I'd very much appreciate bug reports (and suggested solutions if you have them), requests for features, and notes of appreciation. While the script suits my needs, I am sure that there are many ways it can be improved, and your feedback will help that process greatly. I can be reached at millermj.mail.lemoyne.edu (replace the first dot with an @).


Improvements

To do - new features

To do - fix bugs