NAME

vc — version control

SYNOPSIS

`vc`	[`-c` `ch`] [`-s`] [`-w`] [`variable=value ...`] [`file ...`]

DESCRIPTION

The vc command copies lines from the files named in the command line to the standard output, under control of its arguments. If no files are named on the command line, lines are read from the standard input. In the process of performing the copy operation, user declared variables may be replaced by their value when they appear in plain text lines.

The copying of lines from the input files is conditional, based upon tests of variable values defined in control statements or the vc command line.

A control statement is a single line beginning with a control character. The default control character is the percent sign ('%'), except as modified by the -c argument or the ctl statement. Input lines beginning with a backslash ('\') followed by a control character are not control lines and are copied to the standard output with the backslash removed. Lines beginning with a backslash, followed by a non-control character are copied in their entirety.

A variable name is composed on any number of alphanumeric or underscore characters, of which the first must be alphabetic. A variable value can either be an ASCII string, enclosed in double quotes ('"'), or an integer. To include double quote characters in a string, escape them with the backslash ('\') character.

Replacement of variables or expressions by their value is performed whenever a variable or bracketed expression, surrounded by control characters, is encountered on plain text lines, msg or err statements. Undeclared variables or unpaired control characters are silently passed through unchanged. See the -w option.

Options

-c ch: Specifies a control character to be used in place of the default.
-s: Silences warning messages (not error) that are normally printed on the standard error output.
-w: Issue a warning if an undeclared variable or an unpaired control character is encountered while processing plain text lines.
-x: Causes vc to issue a diagnostic trace. Not useful for normal usage.

Version Control Statements

set variable=expression

Used to assign a value to a variable. The assignment will override any value assigned in the vc command line or any preceeding set statement. An expression is an algebraic expression combining constants, variables and operators. Legal operators are:

*    multiply
/    divide
+    addition
-    subtraction
==   equal
!=   not equal
>=   greater than or equal
<=   less than or equal
>    greater than
<    less than
|    logical or
&    logical and
()   grouping expression components
!    not
=    assignment

Operator priorities are ranked as follows (highest first):

! (not) - (unary minus) + (unary plus)
* /
+ -
== != >= <= > <
| &
=

if expression, else, elif expression, end

These vc control statements may be used to conditionally skip lines in the input file. If the expression on the if statement evaluates to true, all lines between the if statement and the else statement (or, if not present, the end statement) will be copied to the standard output. If the expression evaluates as false, the lines between the else and end statements will be copied to the standard output. If the else statement has been omitted, no lines are copied.

The elif statement provides a more convenient way of handling multiple choice conditions.

Note that if groups may be nested.

Expressions are evaluated as for the set statement.

inc "filename"

Commence copying lines from the file named on the inc statement. The filename must be quoted. When the include file is exhausted, copying will restart from the original file, at the line following the inc statement. Include files may be nested up to 10 deep.

on, off

Turn on or off variable replacement in plain text lines.

ctl ch

Change the control character to ch

msg "message"

Prints the given message on the standard error output. The message must be quoted. If the message contains variables or bracketed expressions, quoted by control characters, the quoted text will be replaced by its value before the message is displayed.

err "message"

Behaves exactly as msg but the printed message is followed by text of the form:

ERROR: on line NNN (filename)

produced on the standard error output. vc halts execution and returns an exit code of 1.

Messages produced by err cannot be suppressed by the -s command argument.

NOTES

Maximum line length for input file (characters): 256

Maximum variable name size (characters): 72

The vc command is based (loosely) on the old System V UNIX vc.

EXAMPLES

%set debug=1
%set version="1.2"
%if debug>0
%msg "Debugging code is ON (debug value: %debug%)"
%else
%msg "Debugging code is OFF"
%end
%msg "Building for version %version%"
10    write(6,900) '%version%'
900   format(' FOO Version ', A3,' at your service.')
%set value=4
assert(cube(%value%), %(value*value*value)%)

AUTHORS

Mark Willson