14. Commands

Unlike formulas, which are stored and evaluated later, commands are not stored and are executed immediately.

Numeric expressions in command arguments are evaluated in dependency order.

SS commands are:

  byrows|bycols - set default direction
  copy [byrows|bycols] dest_range src_range
  Copy [byrows|bycols] dest_range Cell(c,r)
  debug [on|off|level]
  eval [byrows|bycols] [range|symbols] [number_of_iterations]
  exit
  fill [byrows|bycols] range - truth-table
  fill [byrows|bycols] range start_expr [,increment_expr] - linear scale
  Fill [byrows|bycols] range start_expr [,ratio_expr] - geometric scale
  fill [byrows|bycols] range { expr_list }
  fill [byrows|bycols] range "fmt", "start", increments... - date/time
  format A0|RC|CR - formula printing format
  format [cell|row|col|range|symbols] "fmt_string"
  headers on|off
  help - print list of operators, functions, commands and constants
  help ["what"] - print help matching string
  output "fname" - redirect output to a file
  plot|plot2d|plot3d ["fname"] [byrows|bycols] [range]
  print ["fname"] [byrows|bycols] [range] [all|constants|...
  ...|formats|formulas|functions|pointers|states|symbols|values]...
  quit
  reset [range|symbols] - set formulas to unevaluated state
  sort [byrows|bycols] range [uniq [count]] - sort values
  srand expr - initialize the pseudo-random number generator
  while(expr) { commands... } - repeat commands

Additional information:

copy [byrows|bycols] dest_range src_range

If the source range contains fewer elements than the destination it will be traversed more than once. If the source range contains too many elements a warning message will be displayed. A more general way of assigning a range is using a multiple assignment as discussed in the previous section, for example A1:A9 = { A0 };

Copy [byrows|bycols] dest_range Cell(r,c)

Copies formulas to the destination range dynamically from the specified cells. See the section on Dynamic Cell References for more information and examples.

eval [byrows|bycols] [range|symbols]

If the number of iterations is not specified, then the cells and/or symbols are evaluated in dependency order. This will fail and display an error message if any cyclic dependencies are encountered.

If no range or symbols options are specified, then all of the cells and symbols are evaluated. If range or symbols options are specified, then only that range and/or the symbols are evaluated, in dependency order, which can cause evaluations to occur outside of the specified range if there are dependencies outside of that range.

The cells and/or symbols which are evaluated in dependency order are set to the evaluated state. This means that their formulas will not be reevaluated by subsequent dependency evaluations unless they are first reset to the unevaluated state using the reset command.

eval [byrows|bycols] [range|symbols] number_of_iterations

If the number of iterations is specified, then the cells and/or symbols will be evaluated up to that number or iterations or until convergence. The state of formulas (evaluated or unevaluated) is ignored and not changed by this type of evaluation.

If no range or symbols options are specified, then each iteration will first evaluate the symbol table, then evaluate the cells twice: first starting at the top-left corner of the cells being used and traversing the range to the bottom-right corner of the cells being used; then again starting at the bottom-right corner and traversing to the top-left corner.

If only the symbols option is specified, then only the symbol table is evaluated.

If only a range is specified, then only that range is evaluated, in the default or specified direction (byrows or bycols), for the specified number of iterations.

If the symbols option and a range are both specified, then the symbol table and range are both evaluated, in the specified order, for the specified number of iterations. For example, eval a0:a1 symbols 2; is equivalent to eval a0:a1 1; eval symbols 1; eval a0:a1 1; eval symbols 1;

fill [byrows|bycols] range - truth-table

Fill a range with constant 0,1 values suitable as inputs for a truth-table. For example, fill a0:c7; produces 8 rows and 3 columns representing the 8 possible 3-bit values:

        A       B       C
0       0       0       0
1       0       0       1
2       0       1       0
3       0       1       1
4       1       0       0
5       1       0       1
6       1       1       0
7       1       1       1

fill [byrows|bycols] range start_expr [,increment_expr] - linear scale

Fill a range with constant values, starting with the start expression value, and increasing by the increment expression value for subsequent cells. The start and increment expressions are evaluated only once, before filling starts. If the increment is not specified it defaults to 0.

Fill [byrows|bycols] range start_expr [,ratio_expr] - geometric scale

Fill a range with constant values, starting with the start expression value, and multiplying by the ratio expression value for subsequent cells. The start and ratio expressions are evaluated only once, before filling starts. If the ratio is not specified it defaults to 1.

fill [byrows|bycols] range { expr_list }

Fill a range using a list of expressions. Unlike the range assignment statement, the fill command always uses each of the expressions in the list exactly once, so the extent of the range filled is determined by the length of the expression list rather than by the size of the specified range. The end cell of the range determines only the direction for traversing the range.

fill [byrows|bycols] range "fmt", "start", increments... - date/time

Fill a range with date/time strings, using strftime() with the specified format. The start value can be in the form "YYYY-MM-DD" or "HH:MM:SS" or "YYYY-MM-DD:HH:MM:SS". Defaults for omitted start date or time values are "2000-01-01" and "12:00:00".

Depending on the form of the start value, the increments are specified in years, months, days, or hours, minutes, seconds, or both:

"YYYY-MM-DD", year_inc[,month_inc[,day_inc]]
"HH:MM:SS", hour_inc[,min_inc[,sec_inc]]
"YYYY-MM-DD:HH:MM:SS", year_inc[,month_inc[,day_inc[hour_inc[,min_inc[,sec_inc]]]]]

The increment expressions are evaluated only once, before filling starts.

Examples (date_time.ss, date_time.out):

                                           // fill column with:
fill a0:a9 "%Y", "2012-01-01", 1;          //  years
fill b0:b15 "%Y-%m", "2011-11-01", 0, 1;   //  months "YYYY-MM"
fill c0:c9 "%m/%d", "2011-12-29", 0, 0, 1; //  days "MM/DD"
fill d0:d12 "%H:%M", "11:15:00", 0, 15;    //  time "HH:MM"

headers on|off

Display of row and column headers can be controlled by the headers command.

format A0|RC|CR - formula printing format

The format A0, RC, and CR options specify the format used for printing formulas.

format [cell|row|col|range|symbols] "fmt_string"

For printing spreadsheet values, the format can be set globally or for a specific cell, row, column or range. The default global format is "%.2f".

If a cell is not assigned a format, and evaluation is byrows (the default), printing will use the cell's row format, if set; otherwise it will use the cell's column format, if set; otherwise it will use the global format.

If a cell is not assigned a format, and evaluation is bycols, printing will use the cell's column format, if set; otherwise it will use the cell's row format, if set; otherwise it will use the global format.

The default format for printing symbol table values is "%g". This can be changed using the format symbols command.

plot|plot2d|plot3d ["fname"] [byrows|bycols] [range]

The plot commands do not actually plot anything, they simply display output in a form suitable for plotting to be used in conjunction with the plot command-line options.

print ...

print all; is equivalent to print symbols, formulas, values;

When printing formulas, indirect dependencies on symbol table formulas (due to use of multiple return values) are shown in parentheses, e.g. ($1), ($2), etc.

sort [byrows|bycols] range [uniq [count]] - sort values

Sort the values in the specified range in increasing order. Unused cells and cells containing strings are ignored.

Sort does not evaluate any cell formulas, so eval would normally be used before sorting. After sorting, the value in a cell will not necessarily correspond to the cell formula, since the values will be rearranged but the formulas are not moved or changed.

If the uniq option is specified, duplicate values are eliminated after sorting. For count, specify a cell or symbol which will be set to the number of values which remain after eliminating duplicates. If there are duplicates, the range will not be completely filled by the sorted values and the unused cells at the end of the range will be marked as undefined so they will not be printed when displaying the spreadsheet.

To sort in decreasing order specify a reverse range, e.g. a9:a1 instead of a1:a9.

while(expr) { commands... }

Repeat commands while a condition is true, i.e. while expr is non-zero. The condition is evaluated without dependency checking, so increment and decrement expressions (++, --) can be used without generating warnings about cyclic dependencies.

Any assignment statements (cell or symbol formulas) appearing in expr and commands will be stored but not evaluated unless a command indirectly causes evaluation or the eval command is explicitly used.

The body of the loop must not contain any '}' characters, and while loops may not be nested. The body is stored in a string and parsed for each loop iteration.

Example:

% cat loop.ss

n = 3; while( n-- > 0) { print symbols; }

% SS loop.ss

  n = 2
  n = 1
  n = 0