Go directly to Introduction to coco
Go directly to The coco setfile
Go directly to Extensions to the Standard coco
Go directly to An Example of Using coco
The program coco provides preprocessing as per Part 3 of the Fortran Standard (coco stands for "conditional compilation"). It implements the auxiliary third part of ISO/IEC 1539-1:1997 (better known as Fortran 95). (Part 2 is the ISO_VARYING_STRINGS standard, which is sometimes
The Fortran source code for coco may be found at http://users.erols.com/dnagle. It is not F conformant, but is standard Fortran 95, except that it uses two extensions from Fortran 2003. These are the get_command_count() procedure to retrieve the number of command line arguments and the get_command_argument() procedure to retrieve the command line arguments themselves. You will have to find a replacement for these routines if your processor does not support them. These procedures are available from I.S.S. Ltd. via the free F2KCLI Module implemented as a module.) You don't need the source code to use coco with an F program.
Generally, coco programs are interpreted line by line. A line is either a coco directive or a source line. The coco directives start with the characters "??" in columns 1 and 2. Lines are continued by placing an "&" as the last character of the line to be continued. Except for the "??" characters in columns 1 and 2, coco lines follow the same rules as free format lines in Fortran source code. A coco comment is any text following a "!" following the "??" characters. A coco comment may not follow the "&" at the end of a line containing a continued string.
A coco program consists of coco lines and source lines. A coco program may have an optional setfile associated with it. The setfile may be used to control what coco does with coco lines or with source lines which are not intended to be effective in the output source file. The setfile may define coco variables, if so, the setfile definitions override the value contained in the program itself. The definitions must match, however, as far as type and whether the symbol is a constant (this keeps a coco program self contained and consistent).
The standard coco directives are integer and logical declarations and assignments, if/elseif/else/endif directives, and message and stop directives. An integer or logical variable may be given a value where declared, and may be declared to be a constant. As extensions to the standard, a macro capability is provided, as is the ability to specify directories to be searched for include files not found in the current directory (see below). A further extension is the text & copy mechanism, which is a block of text which may be copied to several places within the source program. A text block may have dummy arguments associated with it, which may be replaced by actual arguments when the text block is copied.
The standard coco directives may appear in upper or lower case interchangeably and are summarized on the list below:
?? INCLUDE 'filename'
The filename may appear in single quotes or double quotes. The include directive may not be continued onto subsequent lines.
?? INTEGER :: name [, name] ...
?? INTEGER :: name=value [, name=value] ...
The name and name=value forms may be mixed.
?? INTEGER, PARAMETER :: name=value [, name=value] ...
?? LOGICAL :: name [, name] ...
?? LOGICAL :: name=value [, name=value] ...
The name and name=value forms may be mixed.
?? LOGICAL, PARAMETER :: name=value [, name=value] ...
?? IF( logical-expression )THEN
?? ELSEIF( logical-expression )THEN
?? ELSE
?? ENDIF
?? MESSAGE [ item [, item ]...]
The items may be coco variables or expressions, or a string enclosed in single quotes or double quotes.
?? STOP
?? name=value
The value may be a literal value (e.g., 42 or .true.), a coco variable, or a coco expression using coco operators (+, -, *, / with integers; .and., .or., .eqv., .neqv., .not. with logicals; .eq.,==, .ne., /=, .lt., <, .le., <=, .ge., >=, and .gt., > produce a logical result from integer operands). The usual Fortran precedence rules apply. Parentheses are honored.
The name and name=value forms of the integer and logical declarations may be mixed, a name declared to be a constant, of ocurse, must be supplied with a value.
The programmer may use a separate file, called a setfile, which permits the programmer to change the values of variables and constants outside the coco program, and to specify what happens to elided source text and coco directives. Within the setfile, variable and constant declarations may appear, the values supplied override those (of the same name) appearing in the coco program proper. There must be a definition of the same variable within the coco program proper, only the value may be changed by the setfile. The setfile is appended to the end of the coco program's output (depending on the value of the ALTER directive, see the following).
The setfile is named according to the output file name, any ".fpp" or ".f90" suffix is discarded and ".set" is appended to make the setfile name. If a file with that name is not found, a file with the default name of "coco.set" is sought. This allows a programmer to have a default setfile for a project or directory, or to control the output on a file-by-file basis. There is only one setfile read for a multi input file invocation of coco. See Using coco for more on the command line.
The fate of source lines not appearing in the coco output and of coco directives is controlled by the ALTER directive. At most one alter directive may appear in a setfile. The -a command line option overrides the alter directive. Examples of alter directives and their effects are described in the following:
All coco lines and source lines not selected for output are deleted from the output file. Of course, these lines will not be seen by the compiler at all.
All coco lines and source lines not selected for output are replaced by blank lines in the output file. Of course, these lines will be seen by the compiler as comments.
All coco lines are printed with the leading "?" replaced by a "!". Source lines not selected for output are printed with a "!" in place of the character in column one. Of course, these lines will be seen by the compiler as comments.
All coco lines are printed with a leading "!" before the leading "?". Source lines not selected for output are printed with a "!" preceding the leading character, coco issues a warning if a line so extended exceeds 132 characters. Of course, these lines will be seen by the compiler as comments.
All coco lines are printed with a leading "!?>" before the leading "?". Source lines not selected for output are printed with "!?>" preceding the leading character, coco issues a warning if a line so extended exceeds 132 characters. Of course, these lines will be seen by the compiler as comments. The leading "!?>" makes it easy to write a program to undo the effects of the coco preprocessor (at least so long as the use of coco conforms to the standard and doesn't use any extensions). See the restore program available in the Downloads section.
coco -V
coco -h
coco [[options] [--]] [ basename | output input [...]]
The coco program reads its input on stdin and writes its output to stdout if it finds no filename arguments on its command line. The coco program responds to "-V" option by printing its version information and quitting. The coco program responds to the "-h" option by printing a short help message and quitting. Any single filename command line argument has ".fpp" appended to it and used as the single input filename, ".f90" is appended and used as the output filename. If more than one filename argument appears on the command line the first is taken to be the output filename, the rest are treated, in the order of occurrence, as input filenames. Examples follow:
causes coco to read the file input.f and write the file output.f90. A setfile named "coco.set" is sought.
causes coco to print its version information to stderr and stop.
causes coco to print short summary of its command line options to stderr and stop.
causes coco to read source.fpp and write source.f90. The filename source.set is checked to see if it exists, if so, it is processed as the setfile. If source.set is not found, coco.set is checked to see if it exists, if so, it is processed as the setfile.
causes coco to read input1.f90, input2.f90, input3.f90 in that order and to write output.f90. The filename output.set is checked to see if it exists, if so, it is processed as the setfile. If output.set is not found, coco.set is checked to see if it exists, if so, it is processed as the setfile. If coco.set is not found, no setfile is processed.
A good default setfile contains the line ?? ALIGN: DELETE, which overrides the standard specified default of SHIFT3.
Options coco recognizes the following command line options:
-D rules The following rule applies to the -D option: if the "=" is present, it must be followed by an integer literal and name is defined to be an integer constant with the value specified. There should be an integer constant with the same name defined within the source file. If no "=" is present, then name is defined to be a logical constant with a value of ".true.". There should be a logical constant with the same name defined within the source file.
The search rule for directories specified by the -I argument and ??directory directive is that the directories specified by the -I argument are searched first. This way, the command line may override the setfile. Directory directives may not appear in the coco program proper so all include files with the same name are known to come from the same directory, and thus each occurance of any one named include file will be the same file. Since coco doesn't know what kind of operating system is in use, the user must append the appropriate separator (i.e., "/", "\" or ":") after the directory name, whether it appears in the -I argument, or the ??directory directive (see below).
This program supports some extensions to standard coco. The string ?file? is replaced in source code by the current input file name and the string ?line? is replaced by the current input file line number. This editing is prevented by the -f or -e command line options. The strings ?date? is replaced by the date of the preprocessing and the string ?time? is replaced by the time of the preprocessing. This editing is prevented by the -d or -e options. The string ?coco? is replaced by the coco version and may be prevented by the -e option. These strings are internally defined and may not be changed. They may appear in either case. If they appear in an assert condition or within a text block, the line number is that of the directive.
The string ?name? is checked to see if name is the name of a coco integer or logical. If it is, it is replaced by the value of the coco integer or logical name. The name may be in either case. This editing is prevented by the -i or -e command line options.
A directive has been added to allow macro definition. If a ?name? is found which is not an integer or a logical, it is checked to see if it is the name of a macro. If so, it is replaced with the value of the macro. Arguments may be present, if so, they are substituted in the value.
This causes code to be written to the output Fortran source to verify that the logical condition is true during program execution, and to halt execution with an error message written to error_unit if it is false. The error message includes the file name and line number where the assert directive was found. The assert directive should be placed only where executable Fortran code is allowed, and the condition should refer to only those Fortran symbols in scope at that location in the source file. The condition may be delimited with single quotes or double quotes. This directive uses quotes around the condition in order to preserve the programmer's case and spacing.
?? ASSERTIF( logical expression ) " condition " acts similarly to the assert above, except that it is only active if the logical expression evaluates to true. It acts like an IF, ASSERT, ENDIF sequence.
Causes coco to write to the logfile a summary of all symbols (integers, logicals, macros and text blocks) known at the point where the directive is encountered.
Causes coco to act as if the end of the current input file has been encountered. The file is closed and the next input file is opened. If there is no next input file, processing is terminated and normal end of input actions occur.
This causes subsequent strings of the form ?NAME? to be replaced by STRING in the source code. This processing is prevented by the -m or -e command line options. There must not be an "(" immediately following ?NAME? (including white space). A macro definition must appear in the coco program proper, not in the setfile. A macro may not be redefined.
This causes subsequent strings of the form ?NAME?( str[, str]... ) to be replaced by STRING in the source code, with strs substituted for the corresponding ?arg? within STRING. A macro definition must appear in the coco program proper, not in the setfile. A macro may not be redefined. If a macro NAME definition has args, the ?name? must also (it must be followed by an "(" immediately, without any white space).
Causes coco to print its end of processing report to the logfile, with data current as of the position where the directive is encountered.
Defines the lines which follow, up to the next end text directive, as being the text block named NAME. The name must not be the name of an integer, logical, macro or another text block. This text may be copied into the coco output by using the copy directive (see below). See below for information about which directives may appear between the text directive and the matching end text directive.
Marks the end of the text block which started with the previous text directive. The name, if present, must match the name on the preceeding text directive.
Defines the lines which follow, up to the next end text directive, as being the text block named NAME. The name must be unique. This text may be copied into the coco output by using the copy directive, see below. See below for information about which directives may appear between the text directive and the matching end text directive. Each arg will be substituted for ?arg when the text is copied, see the copy directive below.
Copies the text block named by NAME into the output.
Copies the text block named by NAME into the output. The strs are substituted for the corresponding ?args within the text block definition during the copy. The copy directive may have args only if the text directive with the same name had args. Each arg on the copy directive is substituted for the corresponding arg on the text directive wherever ?arg appears within the text block.
?? COPYIF( logical expression ) NAME acts similarly to the copy directives above, except it is only active if the logical expression evaluates to true. The argument list is optional, and must match the corresponding TEXT directive.
?? IFDEF( symbol )THEN introduces an if-block which is active if the symbol is defined. It must be followed by an ?? ENDIF statement, no ELSEIF or ELSE directives are allowed.
?? IFNDEF( symbol )THEN introduces an if-block which is active if the symbol is not defined. It must be followed by an ?? ENDIF statement, no ELSEIF or ELSE directives are allowed.
Causes coco to remove the definition of the named symbol(s). An error occurs if the symbol is not defined as an integer, logical, macro or text symbol.
Causes coco to divert lines of text, with editing, to the documentation file named on the docfile directive in the setfile. It is an error to have an active DOC ... END DOC sequence if no DOCFILE directive opened a documentation file. No assumption is made regarding the format of the documentation text, it may be man format, HTML, LaTex, plain text, or any other text lines.
Ends the text diverted to the documentation file. Further lines are treated as source lines and processed to the output file.
There is one name space for all integers, logicals, macros and text blocks. They are processed in the following order: file, line, date, time, integers and logicals, and lastly, macros. Also, to avoid ambiguity, dummy arguments (to macro or to text blocks) may not have the same name as variables, macros or text blocks.
Only the following directives may appear between the text and end text directives: the assert, if, elseif, else, endif, message, stop and assignment directives. While a text block may appear in an include file, an include directive may not appear within a text block. Declaration directives may not appear because each declaration may only occur once per program. Text blocks may not be nested.
If coco is being used as part of The Portability Project, the coco.inc file can be used to define coco symbols for the compiler targeted by the coco.inc file. The definitions contained in the coco.inc file match those in the standard_types module, these two files must both refer to the same processor, otherwise, suboptimal or incorrect results may occur.
Other directives may appear in the setfile, and are intended to allow the programmer to access extensions to the standard coco otherwise controlled from the command line (in case the program was compiled without the f2kcli module, or other access to the command line). These directives are listed below.
The directory dirname is searched if an include file is not found in the current directory. Several DIRECTORY directives may each specify a dirname, they are searched in the order they are declared. A directory directive must appear in the setfile so each include file is known to come from the same directory, and thus be the same file. See also the -I command line option.
Turns on of off the editing of integers, logicals and macros. Only one EDIT directive may occur in a setfile. See also the -e command line option.
The logfile is set to the named file. The file is created. Only one LOGFILE directives may occur in a setfile. See also the -l command line option.
Causes coco to open a documentation file to receive lines of text found between ?? DOC and ?? END DOC directives in the source file(s). See also the -F command line option.
Turns on of off the numbering of source lines. If on, source lines appearing in the output as active source lines have the input file name and line number appearing as a Fortran comment starting in column 75. See also the -n command line option.
Turns on of off the reporting of actual arguments to macros and text blocks which may require enclosing parenthesis to have the effect intended. Only one PARENS directives may occur in a setfile. For exmaple, an actual argument of a+b may result in a+b*a+b when (a+b)*(a+b) was intended. This warning is based on the argument alone, without regard to the text of the macro or text block. See also the -p command line option.
Turns on of off the reporting of file openings and closings. Note that the opening of the setfile cannot be reported this way, because the setfile is already being read when this directive is executed. Only one VERBOSE directives may occur in a setfile. See also the -v command line option.
Turns on or off the reporting of integers and logicals declared in the setfile, but not in any source file. Only one WARN directives may occur in a setfile. See also the -u command line option.
The integer n is taken as the new value of the wrapping length, if possible. A wrap directive must appear in the setfile. Only one WRAP directives may occur in a setfile. See also the -w command line option.
Statement of the problem to be solved: A Fortran program needs to use full path names for file names. The separator in the file names should be "/" if the system is not Windows and "\" if it is Windows.
A file slash.inc contains the following, which
indicates whether the system is Windows or not.
?? logical, parameter :: windows = .false.Then the following program will produce the correct character.module slash ?? include "slash.inc" character, parameter, public :: & ?? if (windows) then slash = "\" ?? else slash = "/" ?? end if end module slash program p use slash print *, "Path is usr" // slash // "local" end program pThe COCO preprocessor is run with
coco < slash.f90 > new_slash.f95which produces the filenew_slash.f95:module slash !?>?? include "slash.inc" !?>??! INCLUDE slash.inc !?>?? logical, parameter :: WINDOWS = .false. !?>??! END INCLUDE slash.inc character, parameter, public :: & !?>?? if (windows) then !?> slash = "\" !?>?? else slash = "/" !?>?? end if end module slash program p use slash print *, "Path is usr" // slash // "local" end program pCompiling and running the program produces the output:
Path is usr/local