next up previous contents index
Next: Commands and Scripts Up: The WRspice Shell Previous: Semicolon Termination   Contents   Index

Variables and Variable Substitution

Shell variables can be set with the set command, or graphically with some of the tools available in the Tools menu of the Tool Control window. In particular, the Shell button in the Tools menu brings up a panel which allows those variables which control shell behavior to be set. Both methods of setting and unsetting the shell variables are equivalent. The Variables tool in the Tools menu provides a listing of the variables currently set, and is updated dynamically when variables are set and unset. A variable with any alphanumeric name can be set, though there are quite a number of predefined variable names which have significance to WRspice.

Shell variables have boolean type if they are defined without assigning any text to them. Otherwise, the variables take a single text token as their defining value, or a list of text tokens if the assigned value consists of a list of tokens surrounded by space-separated parentheses. See 4.4.9 for details of the syntax of the set command.

The values of variables previously set can be accessed in commands, circuit descriptions, or elsewhere by writing $varname where the value of the variable is to appear. However, if a backslash ( \ ) precedes $, the variable substitution is not performed. The special variable references $$ and $< are replaced by the process ID of the program and a line of input which is read from the terminal when the variable is evaluated, respectively. Also, the notation $?foo evaluates to 1 if the variable foo is defined, 0 otherwise, and $#foo evaluates to the number of elements in foo if it is a list, 1 if it is a number or string, and 0 if it is a boolean variable. If foo is a valid variable, and is of type list, then the expression $foo[low-high] represents a range of elements. The values in the range specification [...] can also be shell variable references. Either the upper index or the lower may be left out, and the reverse of a list may be obtained with $foo[len-0].

In releases 4.2.12 and later, the independent token $? is replaced by the current value of the ``global return value''. The global return value is an internal constant accessible from all scripts, and can be used to pass data between scripts and return data from scripts. It is a global variable so one must make sure that its value can not be changed unexpectedly before use. The initial value is zero, and it retains its most recent value indefinitely.

The global return value is set by the string comparison commands strcmp and friends, and can be set directly with the retval command. This can be called within a script to set a value that the caller can access after the script returns.

If a variable reference has the form $&word, then word is assumed to be a vector, and its value is used to satisfy the reference. Vectors consist of one or more real or complex numbers, and are produced, among other ways, during simulation, in which case they represent simulation output. The shell variable substitution mechanism allows reference to all of the vectors in scope. The reference can be followed by range specifiers in square brackets, consistent with the dimensionality and size of the vector. The range specifier can itself contain shell variable references. The complete information on vectors and vector expressions is presented in 3.16.

The sequences $?&vector and $#&vector are accepted. The first expands to 1 if vector is defined with the let command or otherwise, 0 if not. The second expands to the vector length or 0 if vector is undefined. This is analogous to $?variable and $#variable for shell variables.

The notation $&(expression) is replaced by the value of the vector expression. A range specification can be added, for example

echo $&(a+1)[2]
prints the third entry in vector a+1, or 0 if out of range.

When a real number is converted into text during expansion, up to 14 significant figures may be used to avoid loss of precision. Trailing zeroes are omitted. However, in releases 4.2.4 and earlier, and Spice3, only six significant digits were used.

When a circuit file is sourced into WRspice, each line of the circuit description has variable substitution performed by the shell. Thus, shell variables can be used to define circuit parameters, if within the circuit description the parameter is specified in the form of a variable reference. The variable substitution in a SPICE deck allows a concatenation character `%'. This is used between a variable and other text, which would otherwise mask the variable. For example

set value = 10
v1 1 0 pulse(0 $value%m 5p 10p)
expands to
v1 1 0 pulse(0 10m 5p 10p).
Without the %, the pattern match would fail.

next up previous contents index
Next: Commands and Scripts Up: The WRspice Shell Previous: Semicolon Termination   Contents   Index
Stephen R. Whiteley 2022-09-18