HELP VCALC updated Aaron Sloman July 1986
LIB VED_VCALC: A VED-BASED 'SPREADSHEET'
=================================
CONTENTS - (Use g to access desired sections)
-- Introduction
-- Using VCALC
-- Example: declarations of invars and outvars
-- Example equations
-- Setting up the table with initial values for invars
-- Constraints
-- Running VCALC
-- NOTES
-- Format of the table
-- Location of output values
-- Format for equations
-- Initialising VCALC
-- Interactive alterations
-- Manipulating non-numerical structures
-- Printing out results
-- Abbreviating Utilities
-- Additional VED Utilities
-- SHOWING and CHATTY
-- Possible further developments:
-- Introduction -------------------------------------------------------
LIB VED_VCALC allows collections of values of variables to be
manipulated, with consequences of any change automatically computed and
displayed on the screen. Constraints can be specfied, and if violated
will cause an error message.
E.g. you could have an array of numbers, and after changing one number
the relevant row and column totals, averages, etc. could be
automatically re-computed. Constraints on their bounds can be set, to
ensure that reasonable values are given. VCALC makes it easy to
experiment with different combinations of numbers, automatically
checking that user-defined constraints are not violated. E.g. it has
been used to draft a grant application subject to a specified upper
bound on the total funding requested.
Since July 1986 negative numbers, decimals, ratios or complex numbers
can all be handled.
It is also possible to manipulate non-numeric objects, such as strings,
words or lists. Since all the resources of POP-11 and VED are available
to the user of VCALC, it is potentially an extremely powerful tool.
The program can be autoloaded by using VCALC as below, or
explicitly loaded with the command:
lib ved_vcalc;
WARNING: this program is experimental, and may be withdrawn or changed
later. If you wish to ensure that you can go on using it, make a copy.
-- Using VCALC --------------------------------------------------------
To use it on a new file called FOO type, to VED
vcalc foo
This will autoload the library program initialise records, put you in
the file FOO and put the following reminder into the file, inviting you
to specify some input variables, some output variables, some equations
(more strictly, assignments), a 'table' and some constraints:
invars ;
outvars ;
EQS
;
TABLE
;
;;; constraint [ ];
-- Example: declarations of invars and outvars ------------------------
If you wished to have a two by three array of numbers, using VCALC to
add up rows, columns, row totals and column totals, then you might fill
in the blanks thus (the first two lines are optional, and merely provide
a consistency check):
invars a1 a2 b1 b2 c1 c2;
outvars row1 row2 row3 col1 col2 Rowtotal Coltotal;
-- Example equations --------------------------------------------------
Now provide a set of equations specifying how the output variables are
to get their values from input variables or other output variables:
EQS
row1 = a1 + a2;
row2 = b1 + b2;
row3 = c1 + c2;
col1 = a1 + b1 + c1;
col2 = a2 + b2 + c2;
Rowtotal = sumof row; ;;; 'sumof' is explained below
Coltotal = sumof col;
;
-- Setting up the table with initial values for invars ----------------
Set up a table with input variables indicated by ":" and output
variables by "::". Give the initial values for the input variables, and
use a dot (or 0) for initial values of output variables. ( row,
explained below, can simplify this task.)
TABLE
| a1:20 | a2:-15.3 | row1::.
| b1:24 | b2:3 | row2::.
| c1:-14.3 | c2:17 | row3::.
| col1::. | col2::. | Rowtotal::. | Coltotal::.
;
The table can include optional vertical bars "|" to improve readability.
These will be ignored by VCALC. The terminating semicolon is required.
Note that in the TABLE, a dot has been used to indicate unknown output
values. You could use "0" or "?" or some other character instead. When
VCALC runs the character will be replaced with the appropriate entry.
-- Constraints --------------------------------------------------------
You may wish the entries in the first row to add up to less than 20 and
the sum of entries in the second row to exceed those in the third row.
The following two constraints specify these restrictions on permitted
values.
constraint cr1 [ row1 < 20 ];
constraint cr2 [ row2 > row3 ];
A third constraint can be given specifying that the sum of row totals
and sum of colum totals should be the same. If decimal numbers are used,
equality can't be relied on, owing to rounding errors so a threshold on
difference should be used instead.
constraint cr3 [ abs(Rowtotal - Coltotal) < 0.001];
A constraint can perform any computation, alter a database, write files,
etc., so long as it returns a boolean result, which should be TRUE if
processing is to continue.
-- Running VCALC ------------------------------------------------------
There are several ways of getting the output values calculated and
entered into the tables. Initially you need all the declarations,
equations, initial values and constraints to be processed, i.e. the
whole file. This can be done using the command:
run
Provided you have given enough information, the unknown values in the
table will be filled in. E.g.
TABLE
| a1:20 | a2:-15.3 | row1::4.7
| b1:24 | b2:3 | row2::27
| c1:-14.3 | c2:17 | row3::2.7
| col1::29.7 | col2::4.7 | Rowtotal::34.4 | Coltotal::34.4
;
VCALC will not change the format unless an output value will not fit
into the space provided.
If you have inadvertently declared the same thing as both an input and an
output variable you will get an error message.
If a constraint is violated the name of the offending constraint will be
reported on the status line and VED will go to the constraint.
-- NOTES --------------------------------------------------------------
Because the file will be altered by run, and other commands
explained below, it is as well to make a copy before giving the command
in case you want to get back to the original state.
The 'invars' and 'outvars' declarations are not strictly necessary,
since they are implied by the use of ':' and '::' in the table,
respectively. However, the declarations are useful as a consistency
check.
The variables may be any legitimate POP identifiers, not system words,
e.g.
a43 fred_salary_1985a_* etc
-- Format of the table ------------------------------------------------
The input variables are ones for which you have to specify numerical
values in the table, using the format
:
e.g.
a3:99 fred_salary:66500
(you may add extra spaces, tabs or vertical bars if you wish).
The output variables are ones which you specify in the table by means
of the format
::
e.g.
total::0 total::.
The 'table' starts with the word 'TABLE' (in capitals) followed by a
sequence of specifications of input variables and output variables,
separated by spaces tabs, new lines, or vertical bars, in any format you
like, and terminated with a semi colon.
-- Location of output values ------------------------------------------
Note that it is not necessary for the output values to be between TABLE
and the semi-colon. VCALC will search for an entry of the form 'total::.'
anywhere in the file when it has computed a value for the output
variable total. Sometimes it is convenient to keep the output values in
a separate part of the file.
-- Format for equations -----------------------------------------------
The equations are introduced by the keyword EQS, and each is of the form