Chapter 7: HANDLING STRING DATA: "SYMBOLS"
Ferret offers a variety of tools for manipulating strings through the use of "symbols" (variables defined to be strings). The following are the relevant commands:
usage:
DEFINE SYMBOL symbol_name = string
SHOW SYMBOL
usage:
SHOW SYMBOL/ALL
SHOW SYMBOL symbol_name
SHOW SYMBOL partial_name
CANCEL SYMBOL
usage:
CANCEL SYMBOL/ALL
CANCEL SYMBOL symbol_name
Legal symbol names must begin with a letter and contain only letters, digits, underscores, and dollar signs.
To invoke symbol substitution—the replacement of the symbol name with its (text) value—within a Ferret command include the name of the symbol preceded by a dollar sign in parentheses.
For example,
yes? DEFINE SYMBOL hi = hello everyone
yes? MESSAGE ($hi) !
issues "hello everyone" msg
It is also possible to nest symbol definitions, as the following commands illustrate:
yes? DEFINE SYMBOL label_2 = My test label
yes? DEFINE SYMBOL number = 2
yes?
SAY ($label_($number))
My test label
Ch7 Sec1. AUTOMATICALLY GENERATED SYMBOLS
A number of useful symbols are automatically defined whenever Ferret sets up a plot. Following any plotting command issue the command SHOW SYMBOLS/ALL to see a list. Consult the PLOT PLUS for Ferret Users Guide (section "General Global Symbols") for detailed descriptions of the plot symbols. For example, if we wish to place a label "hello" at the upper right corner of a plot we might do the following
yes? PLOT/I=1:100 SIN(I/6)
yes? LABEL/NOUSER ($ppl$xlen) ($ppl$ylen) 1 0
.2 hello
This labeling procedure would work regardless of the aspect ratio of the plot. Use the command SHOW SYMBOL/ALL to see the symbols (and see "General Global Symbols" in the PLOT+ Users Guide).
Ch7 Sec2. USE WITH EMBEDDED EXPRESSIONS
When used together with Ferret embedded expressions symbols can be used to perform arithmetic on the plot geometry. For example, this command will locate the plot title in bold at the center of a plot regardless of the aspect ratio:
yes? LABEL/NOUSER `($ppl$xlen)/2` `($ppl$ylen)/2` 0 0 .2 @AC($labtit)
Ch7 Sec3. ORDER OF STRING SUBSTITUTIONS
The above example illustrates that the order in which Ferret performs string substitutions and evaluates immediate mode expressions in the command line is significant. The successful evaluation of the embedded expression `($ppl$xlen)/2` requires that ($ppl$xlen) is evaluated before attempting the divide by 2 operation. The order of Ferret string substitutions is as follows:
1. substitute "GO" command arguments of the form "$1", "$2", ...
2. substitute symbols of the form ($symbol_name) (discussed here)
3. substitute command aliases
4. substitute immediate mode mathematical expressions
For example, if the script snoopy.jnl contains
DEFINE SYMBOL fcn = $1
DEFINE ALIAS ANSWER LIST/NOHEAD/FORMAT=("Result is
",$2)
ANSWER `($fcn)(($3^2)/2)`+5
then the command
yes? GO snoopy EXP F5.2 2.25
would evaluate to
DEFINE SYMBOL fcn = EXP
DEFINE ALIAS ANSWER LIST/NOHEAD/FORMAT=("Result
is ",F5.2)
LIST/NOHEAD/FORMAT=("Result is ",F5.2) `EXP((2.25^2)/2)`+5
and would result in Ferret output of "Result is 17.57."
Ch7 Sec4. CUSTOMIZING THE POSITION AND STYLE OF PLOT LABELS
All of the plot labels generated by Ferret are automatically defined as symbols. This includes the title ($labtit), X and Y axis labels ($labx),($laby), as well as the position labels (latitude, longitude, depth, time), which are normally placed at the upper left on a plot (see "Labels," p. 138). Sometimes it is desirable to change the location, size or fonts of these labels. The symbol facility makes it possible to do this in a way that is independent of the particular label strings or plot aspect ratio. See the demonstration script symbol_demo.jnl for an example.
Ch7 Sec5. USING SYMBOLS IN COMMAND FILES
Often in Ferret command files the identical argument substitutions must be repeated at several points in the file. Using symbols it is possible to write "cleaner" Ferret scripts in which the argument substitution occurs only once—to define a symbol which is used in place of the argument thereafter. See the demonstration script symbol_demo.jnl for an example.
Ch7 Sec6. PLOT+ STRING EDITING TOOLS
The PLOT+ program provides a variety of tools for editing symbol strings. See the PLOT+ Users Guide for further information. A sample usage:
yes? DEFINE SYMBOL test = my string
yes? PPL SET upper_test $EDIT(test,UPCASE)
yes?
SHOW SYMBOL upper_test
UPPER_TEST = "MY STRING"
Symbols may be edited and checked using the same controls that apply to journal file arguments.
The section of this users guide entitled "Arguments to GO tools" (p 20) describes the syntax for checking and editing arguments. The identical syntax applies to symbols. As with the GO tool arguments (e.g., "$4"), all string manipulations are case insensitive.
In brief, the capabilities include:
default strings
If a symbol is undefined a default value may be provided using the pattern ($my_symbol%my default string%). For example,
($SHAPE%XY%)
check against list of acceptable values
A list of acceptable string values may be provided using the pattern
($my_symbol%|option
1|option 2|%). For example,
($SHAPE%|X|Y|Z|T|%)
will ensure that only 1-dimensional shapes (X, Y, Z, or T) are acceptable.
string substitution
Any of the optional string matches provided can invoke a substitution using the pattern ($my_symbol%|option 1>replacement|%). For example,
($SHAPE%|X>I|Y>J|Z>K|T>L|%)
will substitute I for X or J for Y, etc.
Asterisk ("*") provides default substitution
The asterisk character matches any string. For example,
($SHAPE%|X|Y|Z|T|*>other%)
will always result in "X," "Y," "Z," "T," or "other."
Asterisk ("*") provides limited string editing
The asterisk character, when used on the right hand side of a string substitution, inserts the original symbol contents
($SHAPE%|*>The shape is *|%)
An error message can be provided if the symbol is undefined or doesn't
match any options. The pattern for this is
($my_symbol%|option 1|option
2|<error message text %). For example,
($SHAPE%|X|Y|Z|T|<Not a 1-dimensional shape%)
There are a few symbols, generated automatically by plots, which are not documented in the PLOT PLUS for Ferret Users Guide. Those are shown like all symbols by SHOW SYMBOLS, but cannot be redefined by the user.
the number of pixels in the horizontal (X) and vertical (Y) size of the current Ferret output window. Note: these are "0" if there is no current window -- hence they can be used as a test of whether there is an open window.
gives "BIG" or "LITTLE" according to endianness of the CPU
gives the Ferret version
PPLUS defines a number of global symbols which are available to the user. They are documented in the PPLUS Users Guide, section 7.3, and listed in the chapter "Customizing Plots", section PPLUS special symbols (p. ).