CCF Reference Manual
CCF takes a strictly line-oriented view of your files.
Any lines CCF finds uninteresting are simply copied to
its output (except, of course, in the case of header files).
Initialisation
The first line to catch CCF's attention will be the
"init" line. This consists of the word CCF:init,
commented out according to the style of your source language.
From this line CCF will deduce your comment
conventions:
- The text before CCF:init is how comments
should start.
- Any text after CCF:init indicates that
comments need to be explicitly terminated (rather than
extending to the end of the line).
- If the word nested follows CCF:init it
indicates that comments can be nested one within another.
You can (and, indeed, should) include some distinctive sequence
in the "comment start" string for CCF, in order to
differentiate CCF lines from normal comments. You are
strongly advised against such trickery in the "comment
end" sequence.
Commands
Once initialised, any properly commented-out line will be
treated as a CCF command. The following commands are
understood:
- case expression
- The expression is evaluated and its value saved for
comparison in later when clauses. The following line
must be a when clause.
- date anything
- The remainder of the line is deleted and replaced with the
current date and time.
- default var expression
- If the named variable is not currently defined, it is
initialised to the given value, otherwise it is left
unchanged.
- else
- If no preceding conditional blocks in the enclosing
if or case were successful then subsequent
lines are passed through un-commented, otherwise they are
commented out. An alternative spelling is
otherwise.
- else-if expression then
- If the preceding if and all corresponding
else-if expressions evaluated to zero or less, the
expression is evaluated and, if it is found to be
greater than zero, subsequent lines of the source are passed
through without comment markers being added. The word
then is optional. Alternative spellings of
elsif, elif, else if, and even
otherwise if are accepted.
- end-case
- Ends the range of an case. Alternative spellings
of endcase, end case, and esac
are accepted.
- end-if
- Ends the range of an if. Alternative spellings of
endif, end if, and fi are
accepted.
- enum var1 ...
- Assigns consecutive integer values to the named variables.
It is an error to use enum on a variable which is
already set.
- error message
- The message is printed to the standard error file, preceded
by the current source file and line number, and processing
will then terminate. A non-zero exit status will be returned
to the operating system.
- hide char
- Changes the "hide this line" marker CCF uses when
creating comments from the default value of "!" to
the given char.
- if expression then
- The expression is evaluated and, if it is found to
be greater than zero, subsequent lines of the source are
passed through without comment markers being added. The word
then is optional.
- report var1 ...
- The given variable names, together with their associated
values (if any) are printed to the standard error file. If no
variable names are supplied the complete list of symbols known
to CCF is printed.
- say message
- The message is printed to the standard error file.
- set var expression
- Assigns an integer value to a variable, losing any previous
setting.
- settings var1 val1 ...
- The remainder of the line is scanned for variable names and
then replaced with a list of (name,value) pairs. Variables
with no current setting are indicated by the value
"-".
- unset var1 ...
- Removes the named variables' values. It is an error to
attempt to unset a variable which is not set.
- unset! var1 ...
- Removes the named variables' values. It is an not
error to attempt to unset! a variable which is not set. The
spelling unsetXX is available as an alternative to
unset!.
- warning message
- The message is printed to the standard error file, preceded
by the current source file and line number. A non-zero exit
status will be returned to the operating system.
- when expression
- The expression is evaluated and compared with that
remembered by the enclosing case. If they are equal,
the subsequent lines are output without comment markers. It
is an error for a case to have two successful
when clauses. A contiguous sequence of
when clauses (ie, ones with no intervening
non-when lines) act as "alternatives": if any of them
are successful the following lines are output
un-commented.
Expressions
The following operators may be used in expressions (given in
order of decreasing priority):
- not |
unary minus, logical not |
* / |
multiplication and division |
+ - |
addition and subtraction |
< <= > >= |
ordering relations |
= or == /=,
<>, or != |
equality relations |
and or |
logical operators |
The following "function" may also be used:
ccf:defined(var) |
returns 1 if the given variable is set, 0 otherwise |
The following variables are pre-defined:
one of
MSDOS Unix Win32 |
set to 1 depending on the operating system, |
CCF:version |
the version number of CCF that's running |
CCF:header |
1 if the current file is being processed as a "header
file" only, 0 otherwise |
CCF:mode |
1 if the -a command-line option was given 2 if
the -n command-line option was given otherwise 0 |
The CCF Command Line
CCF is implemented as a shell
script calling a helper program (ccfbin) to do the
hard work.
The calling sequence is:
ccf [options] files ...
The options understood are:
- -a
- Comment out all lines controlled by an if
or case, regardless of the success of the
condition
- -b
- Apply a "commented out" marker to all appropriate lines,
even blanks.
- -B
- Do not apply a "commented out" marker to a blank line.
- -n
- Comment out nothing.
- -s
- Undoes the effects of a previous -a or
-n
- -v
- Causes the program's version number to be printed
- -w
- Copyright, author info, and a (lack of) warranty
statement.
- -D var
- Execute a "set var 1" before processing the
files
- -D var=val (Unix only)
- Execute a "set var val" before
processing the files
- -U var
- Execute an "unset var" before
processing the files
- -H hdr
- Process the file hdr as a "header file"
(but after any -D or -U options)
- -V hdr
- Process the file hdr as a "header file"
(but before any -D or -U options)
Note the order of processing:
- any headers specified with -V (in the order given),
then
- any -D or -U options (in the order given),
then
- any headers specified with -H (in the order given),
then
- other files
If the current directory contains a file defaults.ccf
then this is processed first. This of this as a sort
of "super -V option".