-dvo: c -ambiguous command: c ( catalog cgrid clear create cursor ) -- -The shell is an interpretive programming language. -Variables are set as follows: - -
-dvo: $fred = 10 -- -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.
-
--! -- 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 command -- -Most 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). - -
-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. - -
-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 -- -
-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).
-Opihi is a program to manipulate and display 1-D (vector) and 2-D -(matrix) data. Opihi has a simple command-line interaction that -resembles the UNIX tcsh, but with many additional useful features. -Opihi consists of several, vaguely independant portions: the -command-line interpreter language (Opihi), the image display tool -(Kii), the graphing tool (Kapa), and the vector and matrix -manipulation commands. - -
Opihi is a generic command-line interpreter which has been used as the -front-end for Opihi, as well as other programs in the Elixir system. -The interpreter has a variety of features of shell-scripting +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. I have used the Opihi shell language for several -other user interface front ends, in addition to the Opihi data analysis -tool: a CCD controller interface and a variable star database in the -LONEOS project. The programming structure of the Opihi front-end -makes it very easy to add commands to the package; more about this -later. +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. + +
@@ -36,4 +32,27 @@ 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 @@ -48,17 +67,161 @@ 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. Also, 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. Variables can be numeric or character strings. If +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.
-Some of the programming functions are for loops and if (if else) -statements. There are no delimiting characters; ends of program -blocks are defined by the word 'end'. Syntax is rather simplistic at -the moment. For example: +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 +end ++ +will 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 test ++will 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:
@@ -66,4 +229,44 @@ echo $i end ++This 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 +end ++This would print all the elements of the list. + +
+for i 0 vector[] + echo vector[$i] +end ++This 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 @@ -82,5 +285,48 @@ 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 command ++ +Most 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 +
@@ -90,4 +336,66 @@ 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).
@@ -127,2 +435,6 @@ green, blue, and yellow overlays. +programming considerations
+The programming structure of the Opihi front-end +makes it very easy to add commands to the package; more about this +later.