Ubuntu Manpage: generic - generic preprocessor for IRAF

Provided by: iraf-dev_2.18.1~rc1-2_amd64

NAME

       generic - generic preprocessor for IRAF

SYNOPSIS

       generic [options] files...

DESCRIPTION

       The generic preprocessor is used to translate generic source code (code written to work for any datatype)
       into  type  dependent  source  code,  suitable for compilation and insertion into a library.  The generic
       source is translated for each datatype, producing a type dependent copy  of  the  source  code  for  each
       datatype.  There are two primary modes of operation:

       [1]    The  generic source is embedded in a normal file, bracketed by $for and $endfor directives.  There
              is one input file and one somewhat larger output file, with the generic code  in  the  input  file
              being replaced in the output file by several copies of the enclosed source, one for each datatype.
              This  mode  is  most commonly used for modules to be linked in their entirety into an applications
              package.  The -o parameter is used to specify the output filename.

       [2]    The entire input file is generic.  There may be multiple input files, and for each  input  file  N
              output  files  are  generated,  one for each datatype specified with the -t parameter.  The output
              filenames are automatically generated by appending the type character to the root filename of  the
              input file.  This mode is most commonly used for object libraries.

       The  generic  preprocessor  operates  by token replacement (currently using a UNIX Lex lexical analyzer).
       The input stream is broken up into a stream of tokens.  Each token is examined to see if  it  is  in  the
       following  list,  and  the  indicated  action is taken if the token is matched.  The generic preprocessor
       directives have the form "$NAME", where $ marks a generic directive, and where NAME is the  name  of  the
       directive.

       PIXEL  Replaced by the current type name, e.g., "int", "real", etc.

       XPIXEL Replaced  by  the  current  type name in upper case, preceded by an X, e.g., "XINT", "XREAL", etc.
              This is used for generic C procedures meant to be called from SPP or Fortran.

       INDEF  Replaced by the numeric constant denoting indefinite for the current datatype.

       INDEF[SILRDX]
              These strings are not replaced, since the "INDEF" in this case is not generic.

       SZ_PIXEL
              Replaced by "SZ_INT", "SZ_REAL", etc.

       TY_PIXEL
              Replaced by "TY_INT", "TY_REAL", etc.

       $PIXEL Replaced by the string "PIXEL".  This is used in doubly generic  sources,  where  the  first  pass
              translates $PIXEL to PIXEL, and the second to the actual type string.

       $INDEF Replaced by the string "INDEF".

       $t     Replaced by one of the characters [ubcsilrdx].

       $T     Replaced by one of the characters [UBCSILRDX].

       $/.../ Replaced by the string "...", i.e., whatever is within the // delimiters.  Used to disable generic
              preprocessing of arbitrary text.

       [0-9]+("$f"|"$F")
              Replaced by the corresponding real or double constant.  For example, "1$f" translates as "1.0" for
              type real, but as "1.0D0" for type double.

       $if (expression)
              The  conditional preprocessing facility.  If the $IF tests false the code which follows is skipped
              over, and is not copied to the output file.  Control transfers to the matching  $ELSE  or  $ENDIF.
              The following may be used in the boolean expression:

              "datatype"      denotes the current type
              ubcsilrdx       any subset of these characters
                                denotes the corresponding datatype
              sizeof()        the size of the specified type,
                                e.g., for comparisons
              != ==           the relational operators
               >  <  >= <=

              Examples:

                      $if (datatype != dx)
                          (code to be compiled if type not d or x)

                      $if (sizeof(i) <= sizeof(r))
                          (code to be compiled if size int <= real)

              $IF constructs may be nested.  The directive may appear anywhere on a line.

       $else  Marks the else clause of a $IF.

       $endif Marks the end of a $IF.  One is required for every $IF.

       $for (types)
              For  each  of  the  listed  types,  output  a translated copy of the code between the $FOR and the
              matching $ENDFOR.  Nesting is permitted.

              Example:
                      $for (silrd)
                      (any amount of generic code)
                      $endfor

       $endfor
              Marks the end of a $FOR statement.

       $$     Replaced by a single $.

       /*...*/
              C comments are not preprocessed.

       ...    Quoted strings are not preprocessed.

       #...(EOL)
              SPP comments are not preprocessed.

       %...(EOL)
              SPP Fortran escapes are not preprocessed.

OPTIONS

-k Allow the output files generated by generic to clobber any existing files.

-o ofile
The name of the output file. If this option is selected, only a single file can be processed.

-p prefix
A prefix to be prepended to the output filenames. This is useful when the output files are to be
placed in a different directory.

-t types
The datatypes for which output is desired. One output file will be generated for each type
specified, with generic automatically generating the output filename by appending the type
character to the root filename of the input file. The types string is some subset of [ubscilrdx],
where the type characters are as follows:

u - C unsigned short
b - C byte (char)
c - SPP character
s - SPP short
i - SPP int
l - SPP long
r - SPP real
d - SPP double
x - SPP complex

This option cannot be used in combination with the -o option, and should not be used when generic
code is expanded inline, rather than written into multiple output files.

files The input file or files to be processed. Generic input files should have the extension ".gx" or
".gc", although this is not required. Only a single input file can be given if the -o option is
specified.

EXAMPLES

       1. Translate the generic source "aadd.gx" to produce the six output files "aadds.x", "aaddi.x", etc.,  in
       the  subdirectory  "ak",  clobbering any existing files therein.  The generic task is a bootstrap utility
       written in C and is implemented as a CL foreign task, hence the UNIX command syntax.

               cl> generic -k -p ak/ -t silrdx aadd.gx

       2. Perform an inline transformation ($FOR directive) of the source file "imsum.gx", producing the  single
       file "imsum.x" as output.

               cl> generic -k -o imsum.x imsum.gx

       3.  The following is a simple example of a typical generic source file.  For additional examples, see the
       ".gx" sources in the VOPS, IMIO, IMAGES and other directories.

       # ALIM -- Compute the limits (minimum and maximum values)
       #         of a vector.
       # (this is a copy of the file vops$alim.gx).

       procedure alim$t (a, npix, minval, maxval)

       PIXEL   a[ARB], minval, maxval, value
       int     npix, i

       begin
               minval = a[1]
               maxval = a[1]

               do i = 1, npix {
                   value = a[i]
                   $if (datatype == x)
                       if (abs(value) < abs(minval))
                           minval = value
                       else if (abs(value) > abs(maxval))
                           maxval = value
                   $else
                       if (value < minval)
                           minval = value
                       else if (value > maxval)
                           maxval = value
                   $endif
               }
       end

AUTHOR