Opihi is a generic command-line interpreter which has been used as the front-end for Mana, DVO, and other high-level programs in the Elixir system. The interpreter has a variety of features of shell-scripting languages: if statements, for loops, macros with command-line arguments, and so forth. The shell also allows for variables, arithmetic on variables, input from source files, and a variety of other useful tools. Opihi has a simple command-line interaction that resembles the UNIX tcsh, but with many additional useful features. It can also be used as a scripting language much like #sh/# or perl.
Opihi includes tools to manipulate and display 1-D (vector) and 2-D (matrix) data. Two external programs are used to graphical display. These are the image display tool (Kii), the graphing tool (Kapa), and the vector and matrix manipulation commands. Various functions are available to perform math, statistical, and other operations on vectors and images.
The command-line interaction is based on the readline libraries and behaves like tcsh. Arrows can be used for editing. There is both command and file completion with the TAB key. Multiple commands can generally be placed on one line with semi-colons as separators. The interface has an interaction similar to tcsh. The arrows allow editing of previous commands. You can also use emacs-like commands such as cntl-a to reach the beginning of the line and cntl-e to reach the end. There is command and file completion: if you type part of a command (as the first thing on a line) and then type tab, it will fill in as much as possible, until the word is not unique. Typing tab twice at that point will list the possible endings. For any but the first word on a line, the same thing will happen for the files in the current directory. It is also possible to type just a fraction of a command, as long as it is unique. An ambiguous command will list the possible alternatives. For example:
dvo: c ambiguous command: c ( catalog cgrid clear create cursor )The shell is an interpretive programming language.
Scalar variables in Opihi are proceeded with a dollar sign ($). A variable may be created and the value assigned by a line which looks like:
$var = (expression)
where (expression) is some math expression. The math expression may consist of the standard math operators (+,-,*,/) as well as any already-defined variables and the functions log(), ln(), sqrt(), exp(), ten() ($10^x$), sin(), cos(), etc. Variables can be numeric or character strings. If the shell does not understand the syntax of the line as a math expression, it is assumed to be a string.If there is a pair of curly brackets {} anywhere on a command line, whatever is inside is assumed to be a math expression and evaluated as well. This later feature allows functions of variables to be passed as arguments to Opihi functions. (see also the discussion below about temporary vectors and images). Any expression within curly brackets {} is assumed to be an arithmetical expression and is evaluated before the line is executed. For example:
echo {$fred*dcos(45)}
would give the response 7.07107. There are math functions cos, sin,
and tan, which operate on radian expressions, and also dcos, dsin,
dtan, which operate on degree expressions. There are also the
equivalent inverse functions: eg., asin and dasin return radians and
degrees, respectively. The help section on Math defines all of the
available math functions.
list sample value 0 value 1 test line endwill define the variables #$sample:0 - $sample:2/#, and #$sample:n/#, with value of 3.
The list command may also construct a list from the output of a UNIX command:
list sample -x "ls /tmp"will result in a list consisting of one entry for each file in the listing.
The list command may also be used to split a string by whitespace:
list sample -split this is a testwill result in a list with 4 elements, one for each word.
The #queuepush/# commands allows for additional options which modify how the data is pushed on the queue. The #-uniq/# flag specifies that the queue should be search for an existing match and not add the new data item if a matching item already exists. The #-replace/# flag is similar to the #-uniq/# flag, but instead the new item will replace the existing match, if a match is found. These two options have identical results if the match is made based on the entire line. However, they may be more usefully distinguished by specifying a restriction on the match with the #-key/# flag. This flag specified which whitespace-separated element of the line to use for the match, with the first element being element 0.
Numerical vectors and images (matrices) are discussed later in this document.
break -- escape from function for -- loops if -- logical cases input -- read command lines from a file macro -- deal with the macros
There are several options for programming in status. First, a file which contains a series of commands can be executed with input (filename). It is also possible to define macros which will behave much like regular commands. A macro is defined by typing macro name or macro create name followed by the commands. Arguments to the macro are assigned to the variables $1 .. $N and the number of arguments is given by $0. Macros may be defined in input files, and in fact when status is started, it loads the file ~/.statusrc which may contain default macros. Simple loops and if statements can be performed, and are quite useful for complex macros.
'If' statements are similar in syntax to C if statements. Math expresions in the if statement must be contained in curly braces, as elsewhere. Variables with string values may use the logical == operator to test if two strings are the same. 'For' loops are quite simplistic. The form is:
for var first last delta (commands) end
The value of $var will start at the value first and increment by delta after each loop. The loop will stop after $var is greater than stop. The value delta is optional, with 1 assumed. The value of $var may be changed during the loop, and if set beyong the value of last will end the loop early.
Opihi has several types of flow-control features. These include for-loops, while-loops, if-else blocks. These blocks are defined by the corresponding command (#for/#, #while/#, #if/#) and are terminated with by a line with the single word #end/#.
The for loop syntax is simplistic. The #for/# command specifies the loop variable, the starting value, the ending value, and optionally the delta for each loop. The implicit loop test is always to check if the loop variable is still less than the end value (or greater than if the delta value is negative). The definitions of this loop syntax and the value of the list length (#$list:n/#) and the vector length (#vector[]/#) make for natural loops over all elements of a list or vector. Below are a few examples:
for i 1 10 0.1 echo $i endThis runs the loop with the variable #$i/# running from 1.0, 1.1, up to 9.9 (inclusive).
for i 0 $list:n echo $list:$i endThis would print all the elements of the list.
for i 0 vector[] echo vector[$i] endThis would print all the elements of the vector.
The if-block begins with a line of the form: #if (condition)/# and ends with a single #end/#. A line with a single #else/# specifies the optional else portion of the block. The conditional expression is a valid math inequality with approximately C-syntax: ## (($i < 10) && ($i > 4)) /## The elements of the inequality may also be string comparisons. The only valid string comparisons are #==/# and #!=/#.
The while loop begins with a line of the form #while (condition)/# and ends with a single #end/#. The conditions follow the same rules as the if conditional statements.
*continue, break, auto-break concepts/* macro test echo "this is a macro" echo "number of arguments $0" echo "first argument $1" if ($1 = 10) echo first argument is 10 end end
Some of the other useful programming features are the ability to run files as scripts (input (filename)) and the option of performing unix system calls (exec (command)).
! -- system call ? -- list commands ?? -- list variables echo -- type this line exec -- system call exit -- exit program help -- get help on a function output -- redirect output to file quit -- exit program scan -- scan line from keyboard or file to variable wait -- wait until return is typed which -- show commandMost of these are self-explanatory. The command ?? prints the system variables. The help command will provide help on a single command or, without any arguments, will list all available help files (this includes general help not associated with a specific command).
box -- draw a box on the plot clear -- erase plot create -- create a new vector cursor -- get coords from cursor grid -- plot cartesian grid hist -- create histogram from a vector labels -- define labels for plot limits -- define plot limits plot -- plot a pair of vectors print -- write vectors to file ps -- define labels for plot set -- vector math style -- set the style for graph plots vectors -- list vectors zplot -- plot scaled points
Opihi has a variety of commands to manipulate 1-D data (vectors). Vectors can be loaded from a data file or created with uniform spacing. New vectors can be defined as the arithmetical combinations of other vectors. For example, we could create a sine wave with the following two lines:
In addition to scalar variables, status can manipulate and display 1-D vector variables. Many of the commands which extract data from the photometry database place the data in vectors as well as plotting them. A vector can also be created based on a number sequence with the command create name Nelements start delta. The resulting vector has $Nelements$ entries, starting at a value of $start$ and running until $start + delta*Nelements$. If $delta$ is 0.0, all elements will have the value of $start$. A histogram of a vector may be made with the command hist, which creates a new vector containing the histogram of the first vector. The data range and bin size of the histogram are defined in same way as with create. This makes it easy to create the index vector that goes with a histogram vector:
hist y Ny 1 100 0.1 create dx 1 100 0.1
The above will create a histogram of y in Ny and the index in dx. Plotting this with plot dx Ny will show the histogram.
Vector math is performed with a command of the form set new = (expression). The expression is some math function employing vectors and scalars. A complete listing of the math operators available in set can be found in the help for set.
Once vectors are defined, they may be plotted. A pair of vectors can be plotted against each other if they have the same number of entries. The plotting is performed on the graphics window, Kapa. There are actually several graphics windows available to status, any of which may be used to plot at any time. Some of the more complex operations default to either graphics window 0 or 1, depending on the context. Except for those functions with a pre-defined window, all plotting functions apply to the current graphics window unless an option -n N is given to specify a different window. The plotting style is determined by the command style which can set the line width, the line type (solid, dashed, dotted, etc), the point type (box, cross, etc), the point size, the color, and whether a pair of vectors is plotted as a sequence of points, a set of connected lines, or a histogram. Some functions which make plots use their own styles, as discussed below. The function limits lets the user set the range of the plot axes, or check the current setting. The command plot will plot a pair of vectors on the current graphics window using the current plotting style for that window. The command zplot will plot a pair of vectors with the point size scaled by a third vector, with maximum and minimum point sizes representing specified values. The cursor command goes the other way: this command puts the Kapa window in cursor mode and waits for input from Kapa. The user can then type any alphanumeric key on the graphics windows and will be told both the pointer location (in the graphics coordinates) and will have the coordinates stored in status variables. For example, by typing ``1'' in the sky display window, the RA and DEC of the pointer are stored in the variables $R1 and $D1. This command can be used to let the user define locations or regions of interest on the Kapa window. (Future addition: button, which does the same with the mouse buttons).
create x 1 20 0.01 set y = sin(x)We can plot this pair of vectors on the Kapa graphing window:
limit x y plot x y boxThe Kapa window has a variety of style options to change the plotting type (line, histogram, point), point type, line color, weight and style, and the errorbar style (if errorbars are plotted).
Opihi has many commands to manipulate 2-D data (images). Images can be loaded from FITS files and mathematical operations applied to them. Various other operations, such as rebinning, shifting, rotating, and so forth are also available. Images can be displayed using the Kii image window. In an 8-bit visual, the image window has a dynamic colormap to allow the user to change the relationship between pixel value and the displayed color. There are three colormaps which can be selected by pressing the middle three buttons on the bottom row. The PS button produces a PostScript file from the image. The user can change the magnification and the position of the image with the mouse (left - recenter at cursor; middle - zoom out; right - zoom in). There are four color overlays which the user can draw objects of different shapes (circles, boxes, lines) or draw a contour. The four buttons labeled R, G, B, Y turn on or off the display of the red, green, blue, and yellow overlays.