From owner-sc22wg5@dkuug.dk Thu Apr 29 15:18:47 2004 Received: (from majordom@localhost) by dkuug.dk (8.12.10/8.9.2) id i3TDIltM048945 for sc22wg5-domo; Thu, 29 Apr 2004 15:18:47 +0200 (CEST) (envelope-from owner-sc22wg5@dkuug.dk) X-Authentication-Warning: ptah.dkuug.dk: majordom set sender to owner-sc22wg5@dkuug.dk using -f Received: from smtp01.mrf.mail.rcn.net (smtp01.mrf.mail.rcn.net [207.172.4.60]) by dkuug.dk (8.12.10/8.9.2) with ESMTP id i3TDIZE7048933 for ; Thu, 29 Apr 2004 15:18:40 +0200 (CEST) (envelope-from dnagle@erols.com) Received: from 66-44-90-178.s559.tnt3.lnhva.md.dialup.rcn.com ([66.44.90.178]) by smtp01.mrf.mail.rcn.net with smtp (Exim 3.35 #7) id 1BJBRA-0005CH-00 for sc22wg5@dkuug.dk; Thu, 29 Apr 2004 09:18:49 -0400 From: Dan Nagle To: sc22wg5@dkuug.dk Subject: Future of coco Date: Thu, 29 Apr 2004 09:13:44 -0400 Organization: Purple Sage Computing Solutions, Inc. Message-ID: <98v1905kpqpk2go4qav9h4l11g25p24oaa@4ax.com> X-Mailer: Forte Agent 2.0/32.652 MIME-Version: 1.0 Content-Type: multipart/mixed; boundary="--=_8sv19018vp5khkrb8mrjef3qd9p1cgciud.MFSBCHJLHS" X-Spam-Score: 1.588 (*) CLICK_BELOW,HTML_20_30,HTML_FONT_FACE_ODD,HTML_MESSAGE,LINK_TO_NO_SCHEME Sender: owner-sc22wg5@dkuug.dk Precedence: bulk ----=_8sv19018vp5khkrb8mrjef3qd9p1cgciud.MFSBCHJLHS Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: quoted-printable Hello, Attached is a draft of n1596 for discussion next week. I do not intend that this be the final version. (It would be nice to answer the questions.) ;-) =46or reference, I am also attaching the page from my web site which discusses coco, hopefully this will provide some context. The paper contains a series of straw vote topics, we can modify the list in Vegas. The underlying issue is "how big should coco be?" I hope to see you in Vegas. --=20 Cheers! Dan Nagle Purple Sage Computing Solutions, Inc. ----=_8sv19018vp5khkrb8mrjef3qd9p1cgciud.MFSBCHJLHS Content-Type: text/plain; charset=us-ascii; name=n1596.txt Content-Transfer-Encoding: quoted-printable Content-Disposition: attachment; filename=n1596.txt ISO/IEC JTC1/SC22/WG5 = N1596 Topics within a Discussion of Extensions to CoCo Dan Nagle I do not want to discuss command line, methods of invocation or other "outside the source file" issues. I do want to require that extensions made which may be controlled via command line options also be controllable via set file directives. An f90 or f95 implementation might not have access to the command line, or a particular processor might not have the concept of command lines. Should coco apply file-by-file, or should multi-file invocations be allowed? One input file gives one output file may be simpler, but multi-file invocation may have an ease-of-use advantage. My coco allows, but does not require, multi-file invocation. If a multifile invocation is allowed, do coco definitions propagate from file to file? The advantage of multi-file propagation is that it allows a single "definitions" file to be the first file processed. This effect may be obtained via an include file read into each separate file. Should coco provide that the values of coco integers and coco logicals should be available in the source as text? That is, should ?? integer :: what =3D 4 expand when real( ?what?) :: foo is seen? integer, parameter :: isize =3D 3 type :: vector real, dimension( isize) :: elements end type vector character( len=3D *), parameter :: vector_fmt =3D '( es16.8 )' Should coco support any further macro (text substitution) capability? Many folks view a preprocessor without a general macro ability as severely wanting. If macros are supported, should coco wrap lines? I think so, otherwise macros are a trap. If coco supports macros, should file/line/date/time and coco version be predefined? I think so, these are minimal services which a compiler, working with the output of the preprocessor, will not be able to supply. If macros are supported, should macros support arguments? I think so, something as simple as a "preprocessor statement function" is useless without arguments. Should arguments be protected from "improper" expansion? That is, should coco wrap parenthesis around macro arguments so ?a?*?a? works with x+y as a? (so one doesn't have the result x+y*x+y, which is almost certainly not what is intended). Should the text/copy mechanism be supported? On the one hand, these may be viewed as a poor man's generic feature, on the other, they are more general, if lower level. I invented text/copy to make a "file scope include file" mechanism, originally aimed towards f77 common blocks. Nowadays, I use it more for repeating function definitions with different kind values in modules. YMMV, I suppose. I believe the value of text/copy is greatly enhanced by arguments, but strictly, arguments are a separate question. Should the doc/docfile mechanism be supported? How valuable is documentation within the source file? That is, does anyone write LaTex or Unix man page source within their Fortran source? Should the assert mechanism be supported? Preprocessor asserts are a poor man's assert mechanism, but we presently have no other. Should the diagnostic mechanisms (dump, options, report) be supported? These directives allow documentation of coco's expanded state, they are useful if the results of using coco aren't what is expected. Should the file control mechanisms (endfile, output) be supported? These provide a basic file control capability. Does anyone want to be able to (probably conditionally) truncate the current input file or to change the output file? Should the symbol control mechanisms (ifdef, ifndef, undefine) be supported? I don't especially like the spellings (from cpp) but they are the traditional spellings. I believe the capability is useful. ----=_8sv19018vp5khkrb8mrjef3qd9p1cgciud.MFSBCHJLHS Content-Type: text/html; charset=us-ascii; name=coco.html Content-Transfer-Encoding: quoted-printable Content-Disposition: attachment; filename=coco.html =20 =20 Fortran 95 Program coco =20 =20 =20 =20 =20 =20 =20 =20 =20
=20

goto

Home

Free Source Code=

Program coco =

Fact Sheet

Email us

= 		=20

Purple Sage = Computing Solutions, Inc.

=20

Program coco

Home --> Fact Sheet --> Free Source Code --> coco

About the Program coco

=20

Go directly to = Downloads

=20

Go directly to Introduction to coco

=20

Go directly to The coco setfile

=20

Go directly to Using coco =

=20

Go directly to Extensions= to the Standard coco

=20

Go directly to An Example of Using coco

=20

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 implemented as a module.) A restore = program, similar to that described in the standard, is also available for download.

=20

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.

=20

The make_processor_model program optionally = creates a file of symbol definitions which may be used by coco to control the = conditional compilation according to which kinds are present on a particular = processor. The programmer may then write programs with code supporting all kinds = available on all processors of interest, and use coco and the other software of = the Portability Project to = select source code suitable for each processor. The coco.inc file contains the = symbol definitions written by make_processor_model and may be included in = the Fortran source file via the coco include directive, or the programmer may = manually copy-and-paste it into the Fortran source. This means that a = programmer may base coco's preprocessing decisions automaticly on the processor = dependent kinds actually supported by the processor being used.

Back to the Top

Introduction to coco

=20

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).

=20

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.

=20

The standard coco directives may appear in upper or lower case interchangeably and are summarized on the list below:

= =20
    =20
  • INCLUDE Directive=20

    ?? INCLUDE 'filename'

    =20

    The filename may appear in single quotes or double quotes. The include directive may not be continued = onto subsequent lines.

    • =20
  • Simple Integer Declaration:=20

    ?? INTEGER :: name [, name] ...

    • =20
  • Integer Declaration with Initial Value=20

    ?? INTEGER :: name=3Dvalue [, name=3Dvalue] = ...

    =20

    The name and name=3Dvalue forms may be mixed. =

    • =20
  • Integer Constant Declaration=20

    ?? INTEGER, PARAMETER :: name=3Dvalue [, name=3Dvalue] ...

    • =20
  • Simple Logical Declaration:=20

    ?? LOGICAL :: name [, name] ...

    • =20
  • Logical Declaration with Initial Value=20

    ?? LOGICAL :: name=3Dvalue [, name=3Dvalue] = ...

    =20

    The name and name=3Dvalue forms may be mixed. =

    • =20
  • Logical Constant Declaration=20

    ?? LOGICAL, PARAMETER :: name=3Dvalue [, name=3Dvalue] ...

    • =20
  • IF Directive=20

    ?? IF( logical-expression )THEN

    • =20
  • ELSEIF Directive=20

    ?? ELSEIF( logical-expression )THEN

    • =20
  • ELSE Directive=20

    ?? ELSE

    • =20
  • ENDIF Directive=20

    ?? ENDIF

    • =20
  • MESSAGE Directive=20

    ?? MESSAGE [ item [, item ]...]

    =20

    The items may be coco variables or expressions, or a string enclosed in single quotes or double quotes.

    • =20
  • STOP Directive=20

    ?? STOP

    • =20
  • Assignment Directive=20

    ?? name=3Dvalue

    =20

    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.,=3D=3D, .ne., /=3D, .lt., <, .le., <=3D, .ge., >=3D, and .gt., > = produce a logical result from integer operands). The usual Fortran precedence rules = apply. Parentheses are honored.

    • =20
=20

The name and name=3Dvalue 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.

Back to the Top

The coco setfile

=20

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). =

=20

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.

=20

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:

=20
    =20
  • ?? ALTER: DELETE=20

    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.

    • =20
  • ?? ALTER: BLANK=20

    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.

    • =20
  • ?? ALTER: SHIFT0=20

    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.

    • =20
  • ?? ALTER: SHIFT1=20

    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.

    • =20
  • ?? ALTER: SHIFT3=20

    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.

    • =20
=20

Using coco

=20

The coco program is written in standard Fortran 95, using 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 for a very wide variety of compilers.

=20

SYNOPSIS:

=20

coco -V

=20

coco -h

=20

coco [[options] [--]] [ basename | output input [...]]

=20

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:

=20
    =20
  • coco <input.f >output.f90=20

    causes coco to read the file input.f and write the file output.f90. A setfile named "coco.set" is sought.

    =
    • =20
  • coco -V=20

    causes coco to print its version information to stderr and stop.

    • =20
  • coco -h=20

    causes coco to print short summary of its command line options to stderr and stop.

    • =20
  • coco source=20

    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.

    • = =20
  • coco output.f90 input1.f90 input2.f90 input3.f90=20

    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.

    • =20
=20

A good default setfile contains the line ?? ALIGN: DELETE, which overrides the standard specified = default of SHIFT3.

=20

Options coco recognizes the following command line options:

=20
    =20
  • -a? sets the alter state, with ? being one of d (delete), b (blank), 0 (shift0),= 1 (shift1), 3 (shift3). The -a option overrides an ALTER = directive in the setfile.
    • =20
  • -d turns off date and time editing (see below).
    • =20
  • -Dname[=3Dval] defines a logical or integer constant, as if in the setfile (see = below for rules).
    • =20
  • -e turns off all source editing (see below) (equivalent to -d, -f,= -i, -m).
    • =20
  • -f turns off file name and line number editing (see below).
    • =20
  • -Ffile names a file to receive documentation output (contained between ??doc and ??end doc directives (see below).
    • =20
  • -h makes coco print a short summary of coco's options to stderr and quit.
    • =20
  • -i turns off integer and logical editing (see below).
    • =20
  • -Idir causes coco to search dir for include files not found in the current = directory (see below).
    • =20
  • -lfile names a file to receive coco's reports, stderr is the default (see below).
    • =20
  • -m turns off macro editing (see below).
    • =20
  • -n turns on source line numbering (see below).
    • =20
  • -p turns on reporting of actual arguments to macros and text blocks which may need = enclosing parenthesis (see below).
    • =20
  • -r turns on reporting of extensions to the coco standard in the = logfile (stderr by default).
    • =20
  • -s makes coco work silently, suppressing all reports, including the default report, made at the end of = preprocessing (overrides -p, -r, -u, -v).
    • =20
  • -u makes coco report symbols declared in the setfile or on the command line, but not = declared in any source file (see below).
    • =20
  • -v makes coco work verbosely, reporting all file opening and closing, and a few other = events, to the logfile See below.
    • =20
  • -V makes coco print its version information to stderr and quit.
    • =20
  • -wn controls the wrapping of lines which exceed n characters in length. The = default is 132. It may be desirable to leave line wrapping on if macros are being = expanded. The number n is an unsigned integer which sets the width. Set n to zero= to disable wrapping of source lines. Setting n to 72 causes the continuation = character to be placed beyond column 72 for fixed format source code, and the = continued line is indented to column 7 with a continuation character in column 6 = (for fixed format files) (see below).
    • =20
=20

-D rules = The following rule applies to the -D option: if the "=3D" 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 "=3D" 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.

=20

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).

Extensions to Standard coco

=20

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.

= =20

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.

=20

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.

=20
    =20
  • ?? ASSERT "condition"=20

    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.

    • =20
  • ?? ASSERTIF( expression ) "condition"=20

    ?? ASSERTIF( logical expression ) " condition " acts similarly to the assert above, except that it is = only active if the logical expression evaluates to true. This directive acts = like an IF, ASSERT, ENDIF sequence.

    • =20
  • ?? DUMP=20

    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.

    • =20
  • ?? ENDFILE=20

    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.

    • =20
  • ?? MACRO :: NAME=3DSTRING=20

    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.

    • =09
  • ?? MACRO :: NAME( arg[, arg]... )=3DSTRING=20

    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 a "(" immediately, without any white = space).

    • =20
  • ?? OPTIONS=20

    Causes coco to print the currently in effect options to the logfile, or to stderr.

    • =20
  • ?? OUTPUT "filename"=20

    Causes coco to use the named file as the new output file. The current output file is closed. This may be useful,= for example, when one wants to write an include file using the = particular set of variables, macros and text that was used to write a source file. If= enabled, an end of file report is also written to the logfile, or stderr. The = setfile is copied to the end of each output file.

    • =20
  • ?? REPORT=20

    Causes coco to print its end of processing report to the logfile, with data current as of the position where the = directive is encountered.

    • =20
  • ?? TEXT :: NAME=20

    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.

    • =20
  • ?? END TEXT [NAME]=20

    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.

    • =20
  • ?? TEXT :: NAME( arg[, arg]... )=20

    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.

    • =20
  • ?? COPY :: NAME =20

    Copies the text block named by NAME into the output.

    • =20
  • ?? COPY :: NAME( str[, str]... )=20

    Copies the text block named by NAME into the output. The strs are substituted for the corresponding = ?arg? 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.

    • =20
  • ?? COPYIF ( expression ) NAME [(...)]=20

    ?? 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.

    • =20
  • ?? IFDEF ( symbol )THEN=20

    ?? 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.

    • =20
  • ?? IFNDEF ( symbol )THEN=20

    ?? 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.

    =
    • =20
  • ?? UNDEFINE :: NAME [,NAME]...=20

    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.

    • =20
  • ?? DOC =20

    Causes coco to divert lines of text, with editing if enabled, 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.

    • =20
  • ?? END DOC=20

    Ends the text diverted to the documentation file. Further lines are treated as source lines and processed to the = output file.

    • =20
=20

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.

=20

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.

=20

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.

=20

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.

=20
    =20
  • ?? DIRECTORY "dirname" =20

    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.

    • =20
  • ?? EDIT: [ON|OFF]=20

    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.

    • =20
  • ?? LOGFILE "filename"=20

    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.

    • =20
  • ?? DOCFILE "filename" =20

    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.

    • =20
  • ?? NUMBER: [ON|OFF]=20

    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. =

    • =20
  • ?? PARENS: [ON|OFF]=20

    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.

    • =20
  • ?? VERBOSE: [ON|OFF]=20

    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.

    • =20
  • ?? WARN: [ON|OFF]=20

    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.

    • =20
  • ?? WRAP: n=20

    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.

    • =20
=09

Back to the Top

An Example of Using coco

=20

Statement of the problem to be solved: A single source file is to be prepared which will specify a Fortran 95 Module = containing a cube root function to support all kinds of reals on any processor = at a computer center. Using the programs of the Portability Project, specifically, the standard_types module to provide kind = parameters and the coco.inc include file, this module may be written as follows: =

=20 
?? include 'coco.inc'
		=09
module cube_root
		=09
use standard_types
		=09
implicit none

private
		=09
public cbrt
		=09
interface cbrt
?? if( single_k )then
   module procedure single_cbrt
?? endif
?? if( double_k )then
   module procedure double_cbrt
?? endif
?? if( quad_k )then
   module procedure quad_cbrt
?? endif
end interface
		=09
contains
		=09
?? if( single_k )then
elemental real( kind=3D single_k) function single_cbrt( x)
real( kind=3D single_k), intent( in) :: x
=09
   single_cbrt =3D sign( exp( log( abs( x)) / 3.0_single_k), x)
		=09
end function single_cbrt
?? endif
		=09
?? if( double_k )then
elemental real( kind=3D double_k) function double_cbrt( x)
real( kind=3D double_k), intent( in) :: x
		=09
   double_cbrt =3D sign( exp( log( abs( x)) / 3.0_double_k), x)
		=09
end function double_cbrt
?? endif
		=09
?? if( quad_k )then
elemental real( kind=3D quad_k) function quad_cbrt( x)
real( kind=3D quad_k), intent( in) :: x
		=09
   quad_cbrt =3D sign( exp( log( abs( x)) / 3.0_quad_k), x)
		=09
end function quad_cbrt
?? endif
		=09
end module cube_root
=20

Note that the single_k, double_k, and quad_k which appear in the Fortran source proper are the three kind parameters = which are defined in the module standard_types. The single_k, double_k and = quad_k which appear in the coco if directives are coco logical variables which are= defined in the coco.inc coco include file. Both coco.inc and the source code = for standard_types are made (semi-)automatically by the make_processor_model = program of the Portability Project = All the Fortran kind parameters are valid on any processor, because if the = kind isn't supported, the corresponding coco logical variable is set to false, = thereby preventing the code from being present in the verison of the source = for that processor.

=20

Solving the same problem, but this time using the text-copy mechanism, is shown below:

=20 
?? include 'coco.inc'
		=09
module cube_root

?? text :: cbrt( kind)
elemental real( kind=3D ?kind?_k) function ?kind?_cbrt( x)
real( kind=3D ?kind?_k), intent( in) :: x
=09
   ?kind?_cbrt =3D exp( log( abs( x)) / 3.0_?kind?_k)
		=09
end function ?kind?_cbrt
?? end text cbrt
		=09
use standard_types
		=09
implicit none
		=09
public cbrt
		=09
interface cbrt
?? if( single_k )then
   module procedure single_cbrt
?? endif
?? if( double_k )then
   module procedure double_cbrt
?? endif
?? if( quad_k )then
   module procedure quad_cbrt
?? endif
end interface
		=09
contains
		=09
?? if( single_k )then
?? copy :: cbrt( single)
?? endif
		=09
?? if( double_k )then
?? copy :: cbrt( double)
?? endif
		=09
?? if( quad_k )then
?? copy :: cbrt( quad)
?? endif
		=09
end module cube_root
=20

Note that this time, the source for the cbrt() function need be specified only once, the text-copy mechanism = performs the copy-paste-substitute operation on demand. A further simplification = is to replace the if ... copy ... endif sequences with copyif directives, = as shown below:

=20 
?? include 'coco.inc'
		=09
module cube_root

?? text :: cbrt( kind)
elemental real( kind=3D ?kind?_k) function ?kind?_cbrt( x)
real( kind=3D ?kind?_k), intent( in) :: x
=09
   ?kind?_cbrt =3D exp( log( abs( x)) / 3.0_?kind?_k)
		=09
end function ?kind?_cbrt
?? end text cbrt
		=09
use standard_types
		=09
implicit none
		=09
public cbrt
		=09
interface cbrt
?? if( single_k )then
   module procedure single_cbrt
?? endif
?? if( double_k )then
   module procedure double_cbrt
?? endif
?? if( quad_k )then
   module procedure quad_cbrt
?? endif
end interface
		=09
contains
		=09
?? copyif( single_k) cbrt( single)
		=09
?? copyif( double_k) cbrt( double)
		=09
?? copyif( quad_k) cbrt( quad)
		=09
end module cube_root
=20 =20

Back to the Top

Downloads

=20

To download a source code for the coco program, = click coco preprocessor. = You will need the free F2KCLI Module from I.S.S. to compile coco program if your compiler doesn"t support the Fortran 2003 command= line access intrinsic procedures. Download the restore program = which can un-do coco processing under certain circumstances. Coco no longer needs a standard_types module.

=20

For more information about the standard_types = module, click here.

Back to the Top

Please see our Fact Sheet, or E-mail us for more = information.

Home - Fact Sheet - Free Source Code - Fortran Links - Email us

Back to the Top

----=_8sv19018vp5khkrb8mrjef3qd9p1cgciud.MFSBCHJLHS--