top banner
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
navigate navigate navigate navigate navigate navigate

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.
bottom banner