GENERIC(1)

💖 GENERIC(1) — the IRAF commands era 💖

okay bestie, gather round, because this is generic, the generic preprocessor for IRAF, and she is literally the main character of datatype generation. no cap. 🦋

---

✨ NAME ✨

generic — generic preprocessor for IRAF 💅

---

🎀 SYNOPSIS 🎀

generic [options] files...

---

🌸 DESCRIPTION 🌸

so like. the generic preprocessor exists to translate generic source code — code written so it works for any datatype — into type dependent source code, aka code that's actually ready to be compiled and dropped into a library. ✨ it does this by translating the generic source once for each datatype, which gives you a type dependent copy of the source for every single datatype. it's giving "one source, many outputs" and honestly? obsessed.

there are two primary modes of operation:

1. the generic source is embedded inside a normal file, bracketed by $for and $endfor directives. one input file, one slightly chunkier output file — the generic code in the input gets replaced in the output by several copies of the enclosed source, one copy per datatype. this mode is most commonly used for modules that are going to be linked in their entirety into an applications package. you use the -o parameter to name the output file. 📝
2. the entire input file is generic. there can be multiple input files, and for each input file you get N output files generated, one for each datatype you specified with the -t parameter. the output filenames are generated automatically 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 works by token replacement (currently using a UNIX Lex lexical analyzer, iykyk). the input stream gets broken up into a stream of tokens, and each token is checked against the following list — if it matches, the indicated action happens. generic preprocessor directives have the form "$NAME", where $ marks a generic directive and 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 one 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 pass translates it to the actual type string. double the slay, double the pass. 💫
• $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. math but make it cute. 🧮
• $if (expression) — the conditional preprocessing facility. if the $IF tests false, the code that follows is skipped over and is not copied to the output file, and 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
  • > < >= <= — the other 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. (yes, every single one. don't test her.) 💅
• $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. (she will simply delete your old files and not feel bad about it, bestie 😭)
• -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 supposed to go into 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

---

🫶 SEE ALSO 🫶

xc(1), xyacc(1). go read those next bestie, they're part of the lore 💜

---

👑 AUTHOR 👑

this manual page was taken from the IRAF generic.hlp help file.

---

and that's the whole page, babe ✨ this one's from IRAF 2.17, dated June 2021, and it's GENERIC(1) all day long. slay, compile, and preprocess responsibly 💖🎀🦋