Gri: variables

Chapters:
  1: Introduction
  2: Simple example
  3: Invocation
  4: Finer Control
  5: X-Y Plots
  6: Contour Plots
  7: Image Plots
  8: Examples
  9: Gri Commands
  10: Programming
  11: Environment
  12: Emacs Mode
  13: History
  14: Installation
  15: Gri Bugs
  16: Test Suite
  17: Gri in Press
  18: Acknowledgments
  19: License

Indices:
  Concepts
  Commands
  Variables

10.4: Variables

About Variables: What variables are used for, and how
User Variables: Defining your own variables
Built-in Variables: Variables pre-defined by Gri

10.4.1: About variables

Variables store numbers. As it reads your program, Gri substitutes variable values any place a variable appears where a number normally would. For example, in the code below `.number.' is a variable storing the value 10, so the two `read' statements have the same effect:

.number. = 10 read columns .number. x y read columns 10 x y

Variable names begin and end with a single period (example: `.num.'). (Gri uses this odd notation to distinguish variable names from ``normal'' words, which is necessary because Gri does not have a limited list of keywords as other languages do. Thus, the C programming language is happy to let you use a variable name like `latitude', since it is not a keyword, but Gri is not, since it might like to use that word itself in a new command.)

You should not use names beginning and ending with double periods, because Gri uses names like that to store built-in variables for its own use (e.g., `..xsize..' saves the width of the plot).

To store a number into a variable, use a command like

.time. = 10

.time. = {rpn 10 sin}

Storage is automatically set aside when you assign into a nonexistent variable; no ``declaration'' statements are required as in the C language.

The Gri command, `new' (see New), allows you to have several ``versions'' of a variable. This is useful for local storage in new commands, inside `if' statements, etc, since it lets you use temporary variables without worrying about overwriting values outside the local block of code. The syntax is `new .variable. = value' (where, as usual, `value' may be an rpn expression (see rpn Mathematics). Here is an example:

`foo bar' { new .a. # Get storage .a. = 10 # Store a local value show "Locally, .a.=" .a. " (expect 10)" delete .a. # Delete this local one } .a. = 1 show "Global version has .a.=" .a. " (expect 1)" foo bar

To see if a given named variable (or synonym) exists, use the RPN operator `defined' (see rpn Mathematics).

10.4.2: User variables

You can get Gri to read values for variables from your file. Here's how to read a number from a header line and then read that many lines of columnar data:

open file.dat read .num. read columns .num. x y

You can define variables within the Gri program:

.num. = 10 read columns .num. x y

You can get variables interactively from the user, using the `query' command. (If the user types carriage-return, or if the command-line flag `-y' was specified when invoking Gri, the value 100 will be assigned to `.num.'). For example,

query .num. "Number of rows to read?" (100) read columns .num. x y

Gri allows you to use a previous value of the variable in the default string, as in this example:

.start. = 8 # default .stop. = 2 # default query .start. "Start time? " (.start.) query .stop. "Stop time? " (.stop.)

Variables can be manipulated using reverse polish notation (RPN) mathematical operations (see rpn Mathematics).

Variables are often useful in `if' statements. Here are some examples:

read .num_pts. if .num_pts. show "There are some data" read columns .num_pts. x y else show "There are no data" end if # ... read .latitude. if {rpn .latitude. 10 <} read .num. read .num. x y draw curve else show "Skipping data North of 10deg N" read .num. skip .num. end if

10.4.3: Built-in variables

Built-in variables (see Index of Builtins) have names which begin and end with two periods. For example, `..xsize..' is the width of the x-axis in centimetres. You may use these variables as you wish (example: `..xsize.. = 4' is an alternative to `set x size 4'), but you must be aware that these are not ``free'' variables for you to use for arbitrary purposes. You can find out what the built-in variables are by the command `show variables'.

There are two types of variables

Startup variables, which are created by Gri at startup time. These variables can be relied upon to exist (barring changes in Gri itself), unless you `delete' them.
Spontaneous variables (which are created by certain Gri commands, and only exist if these commands have been executed). For example, the `regress' command defines `..coeff0..' (the intercept of the fitted line), `..coeff1..' (the slope of the fitted line), `..R2..' (the correlation coefficient).

To see the values of the built-in variables (along with the user variables), use `show variables'. Here are some useful builtin variables:

`..arrowsize..' Stores either a positive number representing the halfwidth of arrowheads measured in centimetres, or a negative number giving the negative of the ratio of arrowhead halfwidth to arrow length (see Set Arrow Size).
`..batch..' Flag used for batch mode.
`..debug..' Equal to 1 if the `-debug' command-line flag was set. Flag used for debugging (see Invoking Gri). The `..debug..' built-in variable is useful in isolating code to use only in test runs. For example, you might use
if ..debug.. show "Following are the column data" show columns end if
When you run the program with command-line `gri -debug file.gri' the code in the `if' block will print out the columnar data, but when you run it with `gri file.gri' these lines are not printed.
`..eof..' Flag indicating whether an end-of-file was encountered on the last `read columns'.

`..words_in_dataline..' Number of words on last dataline. This is useful in constructs like

open tmp.dat .num. = 0 while 1 read .a. .b. if !..words_in_dataline.. show "Got empty line or EOF, so break loop" break end if show "a=" .a. "b=" .b. show "; words in line=" ..words_in_dataline.. .num. += 1 end while show "Got " .num. "data lines."

`..fontsize..' Size of letters, measured in points; there are 72.27 points in an inch and 28.45 points in a centimetre. The mathematical operators `pttocm' and `cmtopt', which do conversion between points and centimetres, are often useful in labelling data curves (see rpn Mathematics).
`..graylevel..' Graylevel to use in drawing lines, text, etc. Black ink is 0; white paper is 1. See also `..red..' etc.
`..image_height..' Height of image, or 0 if no image defined yet.
`..image_width..' Width of image, or 0 if no image defined yet.
`..length_dash..' Length in cm of dashes in dashed lines.
`..length_blank..' Length in cm of blanks in dashed lines.
`..linewidth..' Width of lines for data curves (see Set Line Width).
`..linewidthaxis..' Width of lines on axes (see Set Line Width).
`..linewidthsymbol..' Width of lines in symbols (see Set Line Width).
`..missingvalue..' Missing value code, also stored in the synonym `\.missingvalue.'; (see Set Missing Value).
`..num_col_data..' Number of column data that exist. You might want to use this after `read columns' to see if a data file actually had any data in it, or use it in accessing individual elements of columns (see rpn Mathematics).
`..publication..' Flag for final copy of plot. The command-line option `-p' sets the value of `..publication..' to 1. A typical, and highly recommended, code fragment is
if !..publication.. draw time stamp end if
`..red..', `..green..', `..blue..' Description of present color. The values are between 0 and 1, with (0,0,0) being black and (1,1,1) being white. If color is gray, all these will be equal. You may assign to these, but it will not change the color.
`..symbolsize..' Size of symbols in centimetres.
`..superuser..' Equal to 0 if the flag was not set, or equal to the flag if it was.
`..tic_direction..' Direction of axis tics, 1 for inside or 0 for outside.
`..tic_size..' Size of axis tics in centimetres.
`..trace..' Equal to 1 if the `-trace' command-line flag was set. Used for tracing program execution.
`..xinc..' x increment on axes.
`..xleft..' x value at left of plot.
`..xmargin..' Left margin, in centimetres.
`..xright..' x value at right of plot.
`..xsize..' x-axis length in centimetres.
`..ybottom..' y value at bottom of plot.
`..yinc..' y increment on axes.
`..ymargin..' Bottom margin in centimetres.
`..ysize..' y-axis length in centimetres.
`..ytop..' y value at top of plot
`..exit_status..' The exit status from the most recent `system' call (or 0 if no system calls have been done yet).

You may use any of these built-in variables anywhere. For example, here's how to stack 3 graphs vertically on the page:

.offset. = {rpn ..ysize.. 3 + } open file1 read columns x y close draw axes draw curve
..ymargin.. += .offset. open file2 read columns x y draw axes draw curve close
..ymargin.. += .offset. open file3 read columns x y draw axes draw curve close

The first line needs a bit of explanation. It is a reverse-polish expression. The format is `{' followed by `rpn' followed by an expression followed by `}'. Within the expression, spaces must separate operands. This makes `.offset.' equal to the height of y-axis plus 3 cm, so plots are separated by 3 cm. To learn more about `{rpn ... }' (see rpn Mathematics).

Another possibly unfamiliar thing is the code `+='. It means take the thing on the left hand side, and add to it the thing on the right hand side. (In this case, it is used to increase the y margin by the value of `.offset.'.)