Programming Gri
1: Introduction
2: Simple example
3: Fancy example
4: Running Gri
5: Programming Gri
6: General Issues
7: X-Y Plots
8: Contour Plots
9: Image Plots
10: Examples
11: Handling Data
12: Gri Commands
13: Gri Extras
14: Evolution of Gri
15: Installing Gri
16: Gri Bugs
17: System Tools
18: Acknowledgments
19: License
20: Newsgroup
21: Concept Index
|
5.4: Synonyms
Synonyms are used by Gri to store character strings. Gri denotes
synonyms with words beginning with backslash (e.g., `\syn '),
following the TeX convention. You may use any name you like for
synonyms, but it's a bad idea to use names that begin and end with
period (since that's what Gri uses for it's own synonyms), or synonyms
with names like `\n ', `\t ', etc, since you might want to use
such items in system calls (where they may be intended to mean NEWLINE
and TAB).
There are two types of synonyms: user synonyms which are defined
by the user and Builtin synonyms which are pre-defined by Gri.
5.4.1: About synonyms
5.4.1.1: Synonym names
Synonym names begin with a backslash (e.g., `\filename '). Names
normally end with a space or a punctuation character (e.g. `, ').
It is also possible to use punctuation characters (but not blanks or
tabs) in synonym names, provided that the second character in the name
is an opening brace and the last character is a closing brace,
`\{foo.bar} = "Foo bar" '). This is used particularly for files
in the netCDF format, for reading variable attributes, which by netCDF
convention use a colon (`: ') to separate variable name and
attribute name see Read Synonym or Variable.
For more information on netCDF format, see
`http://www.unidata.ucar.edu/packages/netcdf/index.html '
here .
Synonyms may be freely embedded in strings (a common example is
`draw title "Data from file `\datafile'" '. They may also appear
anywhere in commands (e.g., `open \filename '). The exception to
this rule is that Gri ignores your synonyms within math mode, in order
to prevent clashes (e.g. you might define `\alpha ' as a synonym
storing the value `"foo bar" ', but Gri will ignore this within
math-mode, so that `$\alpha$ ' will still mean the Greek letter
alpha).
To get a backslash in a string without Gri thinking it is part of a
synonym, use two backslashes (e.g.,
`show "The backslash character \\ is used for synonyms." '). This
may sometimes be required in
`system ' commands (see System.), to prevent Gri from converting
substrings like `\n ' (which many system commands use to represent
the newline character). For example, the command
`system perl -e 'print "foo\nbar";' ' will be mangled if Gri has
already been told that
`\nbar ' is a synonym. (There will be no problem if `\nbar ' is
not an existing synonym, since Gri will then just leave it in place.)
To be sure that no mangling can occur, replace each backslash with two
backslashes. This tells Gri not to try to substitute a synonym at that
location. In the example below, the first system call prints
`fooled you! ' on one line line, because Gri substituted for what it
thought was a synonym called `\nbar '; the second (correctly) prints
`foo ' on one line and `bar ' on the next.
\nbar = "led you!"
system perl -e 'print "foo\nbar\n";'
system perl -e 'print "foo\\nbar\\n";'
|
5.4.1.2: Dot naming convention for builtin synonyms
Built-in synonyms have special names, as builtin variables do: the first
and last character is a period. Thus, `\.time. ' is a synonym for
the date. Do not use names like this for your own synonyms, or
you may confuse Gri.
5.4.1.3: Displaying synonyms
To display a particular synonym, do `show "\name" '. To display all
known synonyms, do `show synonyms '.
5.4.1.4: Accessing individual words within synonyms
Individual words of synonyms may be accessed by prefixing the synonym
name with the index number of the word (starting at 0) enclosed in
square brackets. If the number is negative or exceeds the number of
words less 1, then the first or last word is retrieved. If no number
appears in the brackets, the result is the number of words in a synonym.
\syn = "This has 4 words"
show "\[0]syn ... gives 'This'"
show "\[1]syn ... gives 'has'"
show "\[]syn ... gives '4', i.e. number of words"
|
5.4.1.5: Testing for existence of synonyms
To see if a given named synonym (or variable) exists, use the RPN
operator `defined ' see rpn Mathematics.
5.4.1.6: Using synonyms in `if ' statements
Here are some examples of using strings in `if ' statements. Note
that synonyms must be enclosed in quotes if they are to be compared with
strings.
query \item "Item to plot?" ("S")
if {"\item" == "S"}
show "Plotting S"
# ...
else if {"\item" == "T"}
show "Plotting T"
# ...
else
show "Don't know what to plot"
quit
end if
|
Here the strings are compared with the `== ' operator. Inequality
is tested with `!= '. One can do string comparisons in `rpn '
expressions, e.g `if {rpn "\item" "S"==} ' (for more information,
see rpn Mathematics.)
5.4.2: User synonyms
5.4.2.1: Simple Assignment
\filename = "columns.dat"
open \filename
|
5.4.2.2: System Output Stored Into Synonyms
# Show the date.
\date = system date
show "Time is \date"
# Show the command file name, then use the system
# to construct a filename with the same beginning
# but ".dat" as the ending instead of ".gri".
show "The commandfile name is \.command_file."
\fn = system echo `basename \.command_file. .gri`.dat
show "A filename constructed from this is \fn"
|
This example uses the Unix system commands `echo ' and
`basename ' to construct a filename ending in `.dat', from the
command file name (stored in the builtin string `\.command_file. '),
assuming that the command file name ends in `.gri'.
NOTE: As usual, if the system command contains the Gri comment
designator (the string `# '), protect it with double-quotes;
see System.
5.4.2.3: Assignment by Extraction of Words from Strings:
This is an adjunct to the `[] ' syntax for synonyms.
\sentence = "This sentence has five words"
\first_word = word 0 of "\sentence"
\last_word = word 4 of "This sentence has five words"
|
Note: this is often used together with `read \synonym ', to allow
the Gri program to access individual words in a data file.
5.4.2.4: Interactively User-supplied Strings
You can ask the user for the contents of strings:
query \filename "What's the data file?" ("file.dat")
|
The prompt `What's the name of the data file? ' is typed to the
terminal, and whatever string the user types is inserted into the
synonym `\filename '. If the user types nothing, but simply presses
carriage return, the (optional) default string (which must be enclosed
in parentheses as shown) is put into `\filename '. Note that the
default is ignored if it is not written properly: it must be enclosed in
double quotes enclosed in braces, with no intervening spaces.
5.4.2.5: Reading Synonyms From a File
You can read the contents of synonyms from a file:
open \directory_file
read \file_name
close
open \file_name
read columns x y
|
Note that the entire line is read into the synonym; if you need
individual words, see the item above about extracting words.
5.4.3: Built-in synonyms
There are two types of built-in synonyms: local and global.
5.4.3.1: Local synonyms
Local synonyms are created by Gri upon entry to a Gri command. You use
them to parse the command line that was used in calling the new command,
to look for options, gather filenames, etc. Local synonyms are known
only from within the local Gri command. They are not listed by
`show synonyms ', but they can be used freely in commands like
`show "Number of words is \.words." '.
-
Within any new Gri command, the number of words in the line that called
the command is available in `
\.words. '.
-
The first word in the calling line is `
\.word0. ', the second
`\.word1. ', etc. (Note that this is the C convention, not the
FORTRAN convention. If `\.words. ' is 2, then `\.word0. ' and
`\.word1. ' are defined, but `\.word2. ', which FORTRAN programmers
expect, will not be defined.)
-
Within any new Gri command, the proper calling usage is available in
`
\.proper_usage. '. This is useful in tests of syntax
(see New Commands.):
`draw depths from \file'
Draw depth data stored in indicated file. If the
filename contains periods or slashes, you'll
have to enclose it in double quotes, as
in the second example:
draw depths from file upper_cove
draw depths from file ../old_data/upper_cove
{
if {rpn \.words. 4 !=}
show "FATAL ERROR in `\.proper_usage.':"
show " Need 4 or 5 words; got \.words. words."
quit
end if
# Right number of words, so continue onward...
}
|
These synonyms help you scan for optional words in commands. Suppose
you have defined a new command `New Thing [option] '. If you call
it with `New Thing ', then (within `New Thing ') `\.words. '
will be `"2" ', `\.word1. ' will be `"New" ' and `\.word2. '
will be `"Thing" '. On the other hand, if you call it with
`New Thing 22.3 ' then `\.words. ' will be `"3 ',
`\.word1. ' will be `"New" ', `\.word2. ' will be
`"Thing" ', and `\.word3. ' will be `"22.3" '.
EXAMPLE Here is a new command to label lines drawn by
`draw curve ':
`Draw Label For Last Curve "label"'
Draw a label for the last curve drawn, using
..lastx.. and ..lasty.. built-in variables.
{
.draw_label_for_last_curve_graylevel. = ..graylevel..
set graylevel 0
draw label "\.word5." at \
{rpn ..lastx.. xusertocm 0.1 + xcmtouser} \
{rpn ..lasty.. yusertocm \
..fontsize.. pttocm 2 / -
ycmtouser}
set graylevel .draw_label_for_last_curve_graylevel.
delete .draw_label_for_last_curve_graylevel.
}
open file.dat
read columns x y
draw curve
\label = "Illustration"
Draw Label For Last Curve "\label"
|
(Note that Gri has a built-in command
`draw label for last curve "\label" ' written much as above, so
there is no need for you to enter
this new command into your `.grirc' file. But you might want to
check `gri.cmd' to see how a full
command does checking of the calling syntax
see Options On Command Line.
5.4.3.2: Global synonyms
Within mathematics mode (portions of strings enclosed within
dollar-signs), Gri stores the definitions of many Greek letters and
mathematical symbols as math-mode synonyms; see Mathematical Text.
Global synonyms are shared amoung commands. To see the built-in global
synonyms (see Index of Builtins.)
use `show synonyms ':
gri: Synonyms...
\.missingvalue.="10000000000000000000000.000000"
\.return_value.=""
\.awk.="gawk"
\.version.="2.2.6"
\.pid.="13644"
\.wd.="/autofs/users/dek/kelley/src/gri/src"
\.time.="Thu Jan 14 15:30:51 AST 1999"
\.user.="kelley"
\.host.="Kelley"
\.system.="unix"
\.home.="/users/dek/kelley"
\.lib_dir.="/users/dek/kelley/src/gri/src"
\.command_file.="stdin"
\.readfrom_file.="stdin"
\.ps_file.="gri-??.ps"
|
The meanings of these things will be obvious to unix users; for example
`\.pid. ' is the process ID of the job (often used in names for
temporary files), and `\.wd. ' is the working directory (often used
in `draw title ' commands to indicate in which directory the gri job
was run. Some commands set `\.return_value. ' to non-blank; the
meaning of the return value varies from command to command.
|