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:

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:

  1. any headers specified with -V (in the order given), then
  2. any -D or -U options (in the order given), then
  3. any headers specified with -H (in the order given), then
  4. 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".