The PREPR library — API documentation

TMC Suite package. A static library — a preprocessor of the input text template files (.tpl) for the compute kernels. All signatures are taken from the sources in src/libs/PREPR/ and the shared header src/Include/Prepr1.h.

1. Purpose of the library

PREPR is a static library (StaticLibrary, toolset v145, built for Win32 and x64) — a preprocessor of the input text template files (.tpl) for the package's compute kernels (PlanarRT_H / PlanarRT_X).

Important: PREPR is NOT a C/C++ language preprocessor. Even though the syntax of the directives outwardly resembles the C-preprocessor directives (#define, #include), PREPR processes text computation input files (.tpl templates) and has no relation to C++ compilation.

The library performs the following transformations on the input template:

• processing of #define NAME@BODY directives — the definition of text macros, including ones with formal parameters (the @ separator, parameters separated by ;);
• processing of #include file_name directives — the substitution of the included file's contents in place of the #include line;
• removal of comments — everything after the ! character is discarded; the \\ marker is processed as a line join;
• substitution of macros with actual parameters — recursively, from the last #define to the first;
• saving all the #define definitions into a temporary file $$vr$$s.prc.

The result of the work is an expanded text file, which is then read by the compute kernel as an ordinary computation input file.

The entry point is the MainPrepr1() function. It is called from the wrapper MainPrepr() (in the TMCIndan library), which in turn is called from the compute kernel. This is the only call site of PREPR.

2. Location of the sources in the build

Sources: src/libs/PREPR/. Header: src/Include/Prepr1.h (in the project it is included as ..\..\INCLUDE\Prepr1.h).

The build project is Prepr.vcxproj (toolset v145, Win32/x64 configurations, type StaticLibrary). The build contains 9 .cpp files:

Files outside the build (legacy / dead code)

The following files are present in the directory but are not included in Prepr.vcxproj and are therefore not described:

3. Data structures

Declared in Prepr1.h.

3.1. BUFFER — a linked character buffer

The main working buffer of the preprocessor. It is implemented as a doubly linked list of characters through two fixed-size arrays NMAX. Insertion and deletion of characters are performed by operations on the list (changing indices) without a physical memory shift.

typedef struct
{
  char  *lsplex;      // character buffer (as a linked list)
  int   *ilex;        // index of the "next" element (list links)
  int    inp_p;       // current reading position
  int    inp_p_nul;   // start of the free-cell list
} BUFFER;

The size of the arrays is set by the NMAX macro (by default 30,000,000, see Prepr1.h).

3.2. MACROS — the description of one macro definition

Stores a parsed #define definition: the name, the formal parameters, and the body split into alternating fragments (a "mask").

typedef struct
{
  char   mac[ BUF_STR_N_MAX ];    // the #define body string
  char  *m[ BUF_PAR_MAX ];        // m[0] — the name; m[1..j1] — the formal parameter names
  char  *m1[ BUF_MASKA_MAX ];     // the body pieces between the parameters (the "mask")
  int    im1[ BUF_MASKA_MAX ];    // the index of the formal parameter before the m1[i] piece, or -1
  int    j1;                      // the number of formal parameters
  int    i2;                      // the number of mask elements
} MACROS;

The macro body is stored split into alternating text fragments (m1) with the indices of the formal parameters bound to them (im1). During substitution the fragments are output in sequence, and the actual values are inserted in place of the parameters.

3.3. Size constants and names (Prepr1.h)

Note: DEF_SEPARATOR is mentioned in the code as the separator character '@'; in Prepr1.h itself it may be defined elsewhere — when in doubt, rely on the DEF_MACR.CPP sources.

4. Syntax of the input-file directives

4.1. #define — a macro definition

#define NAME par1; par2; ... @ BODY

• Both forms of the directive start are recognized: #define (with a space) and #define (with a tab).
• The separator @ (DEF_SEPARATOR = '@') separates the "name + list of formal parameters" from the macro body.
• The formal parameters are listed after the name and separated by the ; (semicolon).
• If there are no parameters, the directive has the form:

#define NAME@BODY

• The body may span several lines (a \\ join marker is used for continuation, see below).

4.2. #include — file inclusion

#include file_name

• Both forms are recognized: #include (with a space) and #include (with a tab).
• The full path to the included file is formed as <GetCurrentPath()>\<file_name> — that is, the name is treated relative to the current directory (see MainPrepr1, the csCurrentPath parameter).
• The contents of the included file are substituted in place of the #include line.

4.3. Comments and line joining

4.4. Calling (using) a macro

NAME(param1; param2; ...)

• The actual parameters are listed in parentheses and separated by the ;.
• If an actual parameter is entirely enclosed in parentheses, those parentheses are replaced with spaces during substitution.
• Substitution is performed recursively by the def_main_macro function — the definitions are traversed from the last #define to the first.
• All the #define definitions are additionally saved into the temporary file $$vr$$s.prc (the load_vr_file function).

5. Public functions

About the _near, _fortran macros. These are memory-model and calling-convention attributes from old 16/32-bit code. In the modern build they do not affect the semantics. They are omitted from the signatures below. Where a function is declared with such attributes, this is noted in the description.

5.1. The main entry point

void MainPrepr1(char *csTplFileNamePrepr, char *csTplFileName, char *csCurrentPath, char *csError)

The main entry point into the preprocessor. It allocates the internal buffers (szError, szPathName), runs the main processing main_preproc, then frees the buffer (unload_prep_buf) and deletes the temporary file (dest_prep).

• Parameters:
• csTplFileNamePrepr (char*) — the name of the output (expanded, processed) file;
• csTplFileName (char*) — the name of the source template file .tpl;
• csCurrentPath (char*) — the current directory (used to resolve relative paths in #include);
• csError (char*) — output: the error string. An empty string ("") on success, otherwise the text of the error that occurred.
• Return: void (the result is reported through csError).

char* main_preproc(char *szTargetFileName, char *szSourceFileName)

The main processing procedure. It reads the source file line by line, removes comments (DeleteComment), loads the text into the buffer, then sequentially performs:

1. def_include — the expansion of #include;
2. load_vr_file — saving all #defines into the temporary file;
3. def_err_dec — checking for re-definitions;
4. def_main_macro — the recursive substitution of macros;

and writes the result into the target file szTargetFileName.

• Parameters:
• szTargetFileName (char*) — the name of the output (expanded) file;
• szSourceFileName (char*) — the name of the source template file.
• Return: a pointer to the global error string szError (the value "" on success, otherwise the error text).

5.2. Lifecycle and memory management

int unload_prep_buf(void)

Frees the memory of the working buffer: the arrays buf.lsplex and buf.ilex.

• Return: always 0.

int load_preproc_buff(void)

• Status: the function is declared in Prepr1.h, but there is no implementation in the library. The only external reference to it is in the unused file DR_BUF.CPP (outside the build).
• Return: undefined (no body).

int dest_prep(void)

Deletes the temporary file <CurrentPath>\$$vr$$s.prc (by calling remove).

• Return: the return code of remove() (0 on successful deletion).

int buf_init(BUFFER *buf, int n)

Initializes the buffer: allocates the arrays lsplex (char[n]) and ilex (int[n]) via alloc_mem_err, builds the initial free-cell list.

• Parameters:
• buf (BUFFER*) — the buffer being initialized;
• n (int) — the buffer size (the number of cells), usually NMAX.
• Return: BUF_NULL (0) on success; ERROR_INIT (-11) on out of memory.

int InitCharArray(char **ch, int n)

Initializes a character array: if *ch is not NULL, frees it, then allocates malloc(n).

• Parameters:
• ch (char**) — the address of the pointer to the array;
• n (int) — the size of the allocated block (bytes).
• Return: 0 on success; -1 on allocation error.

int FreeCharArray(char **ch)

Frees a character array (free(*ch)) and nulls the pointer (*ch = NULL).

• Parameters: ch (char**) — the address of the pointer to the array.
• Return: 0.

5.3. Processing #include and macros

int def_include(BUFFER *buf)

Finds #include directives, substitutes the contents of the included file in place of the #include line, then performs line-join processing (def_sl).

• Parameters: buf (BUFFER*) — the working buffer.
• Return: 0 on success; -1, DEF_ERROR_INFILE (-7) on an error opening the included file; DEF_ERROR_MEMORY (-8) on out of memory.

int def_sl(BUFFER *buf)

Replaces the line-join marker \\ with " \n" (a line break in a macro body).

• Parameters: buf (BUFFER*) — the working buffer.
• Return: 0 on success; -1 on error.

int def_macro(BUFFER *buf)

Finds the next #define / #define directive in the buffer without shifting the current position inp_p.

• Parameters: buf (BUFFER*) — the working buffer.
• Return: the position of the found directive (>= 0) or -1 if #define was not found.

int def_main_macro(BUFFER *buf)

Recursively substitutes all macro definitions: the traversal goes from the last #define to the first (for the correct expansion of macros that use other macros).

• Parameters: buf (BUFFER*) — the working buffer.
• Return: BUF_NULL (0) on success; a negative error code (< 0) on failure.

int def_main_macdef(BUFFER *buf)

Substitutes one macro definition: parses the header (def_separ_mac_name), forms the body mask (def_set_formal_param), removes the #define line from the buffer, performs the substitution (def_subst_mac).

• Parameters: buf (BUFFER*) — the working buffer.
• Return: BUF_NULL (0) on success; a negative error code on failure.
• Note: declared with the _near fortran attributes, but is actually exported and used.

int def_subst_mac(BUFFER *buf, MACROS *mac)

Finds in the buffer calls of the macro mac->m[0] with actual parameters (read via def_buf_gets_param) and substitutes the macro body, replacing the formal parameters with the actual ones.

• Parameters:
• buf (BUFFER*) — the working buffer;
• mac (MACROS*) — the parsed macro definition.
• Return: BUF_NULL (0) on success; a negative error code on failure.

int def_set_formal_param(BUFFER *buf, MACROS *mac, int i)

Parses the macro body, filling the mask arrays mac->m1[] (text fragments) and mac->im1[] (formal-parameter indices).

• Parameters:
• buf (BUFFER*) — the working buffer;
• mac (MACROS*) — the definition being filled;
• i (int) — the start position (of the body) in the buffer.
• Return: the position of the end of the body (>= 0) or -1 on error.

int def_separ_mac_name(BUFFER *buf, MACROS *mac)

Parses the header #define NAME par1; par2; ... @ BODY: writes the name into mac->m[0], the formal parameters into mac->m[1..], the number of parameters into mac->j1, and finds the @ separator.

• Parameters:
• buf (BUFFER*) — the working buffer;
• mac (MACROS*) — the definition being filled.
• Return: the position of the @ separator (>= 0) or an error code: BUF_ERROR_NO_SEP (-6), BUF_ERROR_NO_FORMAL_PARAM (-9).

int def_err_dec(BUFFER *buf)

Checks for the re-definition of a macro name (the same name in two #defines).

• Parameters: buf (BUFFER*) — the working buffer.
• Return: BUF_NULL (0) if there are no repeats; BUF_ERROR_REDEC (-10) if a re-definition is detected.

int load_vr_file(BUFFER *buf)

Saves all the #define definitions into the temporary file $$vr$$s.prc (VR_MAC_FILE_NAME). Multi-line definitions are split with the join marker \\.

• Parameters: buf (BUFFER*) — the working buffer.
• Return: BUF_NULL (0) on success; -1 on a file error; -11 (ERROR_INIT) on out of memory.

5.4. Low-level operations on the linked buffer (DEF_STR.CPP)

int buf_gets(char *str, int n, BUFFER *buf)

Reads a string from the linked buffer into str (up to the terminating \0), but no more than n characters.

• Parameters: str (char*) — the receiving buffer; n (int) — the character limit; buf (BUFFER*) — the working buffer.
• Return: BUF_NULL / BUF_EOF / BUF_ABN (see section 6).

int read_buf(char *str, int n, BUFFER *buf)

Similar to buf_gets, but reading ends at \0 or at \n (reads one line).

• Parameters: as in buf_gets.
• Return: BUF_NULL / BUF_EOF / BUF_ABN.

int buf_puts(char *str, BUFFER *buf)

Inserts the string str (together with the terminating \0) at the current buffer position without shifting the pointer.

• Parameters: str (char*) — the string to insert; buf (BUFFER*) — the working buffer.
• Return: the result code (BUF_NULL on success).

int buf_puts1(char *str, BUFFER *buf)

Like buf_puts, but without the terminating \0; the pointer is not shifted.

int buf_puts2(char *str, BUFFER *buf)

Without the terminating \0; the pointer is shifted to the end of the inserted fragment.

int buf_puts3(char *str, BUFFER *buf)

With the terminating \0; the pointer is shifted to the end of the inserted fragment. Used when reading a file into the buffer line by line.

A summary of the buf_puts* variants:

Function	Terminating \0	Pointer shift
buf_puts	yes	no
buf_puts1	no	no
buf_puts2	no	yes
buf_puts3	yes	yes

int buf_dels(BUFFER *buf, int n)

Deletes n elements starting from the current position (the deleted cells are returned to the free list).

• Parameters: buf (BUFFER*) — the working buffer; n (int) — the number of elements to delete.
• Return: the result code.

void def_gets(char *mac1, char *ch)

Copies from ch into mac1 an identifier (the characters A-Z a-z 0-9 _) up to the first character that is not part of the identifier.

• Parameters: mac1 (char*) — the identifier receiver; ch (char*) — the source string.

int def_buf_gets_mac(BUFFER *buf, char *mac1)

Reads an identifier from the buffer (the macro name when searching for a call) into mac1.

• Parameters: buf (BUFFER*) — the working buffer; mac1 (char*) — the name receiver.
• Return: 0 on success; BUF_EOF at the end of the buffer.

int def_buf_gets_param(BUFFER *buf, char *mac1)

Reads one actual parameter of a macro call up to a ; character (taking nested parentheses into account). If the parameter is entirely in parentheses, the parentheses are replaced with spaces.

• Parameters: buf (BUFFER*) — the working buffer; mac1 (char*) — the parameter receiver.
• Return: BUF_NULL / BUF_EOF / BUF_ERROR_FACT_PARAM (-5).

int buf_cmpn(BUFFER *buf, int n, char *mac)

Compares n characters of the buffer (from the current position) with the string mac.

• Parameters: buf (BUFFER*) — the working buffer; n (int) — the number of characters; mac (char*) — the pattern.
• Return: BUF_NULL (matched) / BUF_EOF (not matched or end).

int buf_cmpn2(BUFFER *buf, int n, char *mac1, char *mac2)

Compares n characters of the buffer with one of two strings mac1 / mac2. Used to recognize the pairs of directive forms: #define / #define and #include / #include.

• Parameters: buf (BUFFER*) — the working buffer; n (int) — the number of characters; mac1, mac2 (char*) — the two patterns.
• Return: BUF_NULL (matched one of them) / BUF_EOF.

5.5. Errors and auxiliary functions

char* def_err_get(int i_err)

Returns the text of an error message by its code (the internal array error[], indexed as error[-i_err]).

• Parameters: i_err (int) — the error code (0..-11, see section 6).
• Return: a pointer to the error description string.

char* DefineIncludeName(char *str, char *str1)

• Status: the implementation in DEFMIS.CPP is in fact empty (the code is commented out); the function returns str unchanged.
• Parameters: str, str1 (char*).
• Return: str (without processing).

char* GetCurrentPath(void)

Returns the current directory — the global string szPathName (set in MainPrepr1 from csCurrentPath). Used when forming #include paths.

• Return: a pointer to the current-directory string.

void DeleteComment(char *pszStr)

Truncates the string at the ! character: everything from ! onward is replaced with " \n" (comment removal).

• Parameters: pszStr (char*) — the string being processed (modified in place).

int put_error_messege(char *szError1)

Copies the error text szError1 into the global string szError.

• Parameters: szError1 (char*) — the error text.
• Return: the result code.
• Note: not declared in Prepr1.h; implemented in PREP_MN.CPP and used inside the library.

6. Error codes

Defined in Prepr1.h. The texts are returned by the def_err_get function (the DEF_ER.CPP file).

A note on the accuracy of the codes. On a memory-allocation error some functions return a "raw" -1, which by the table corresponds to BUF_EOF with the text very small memory. The text does not always accurately reflect the real cause of the failure — when diagnosing, take the call context into account, not just the code itself.

7. Dependencies

• The exprint and complex libraries are NOT used. PREPR works only with text, without expression evaluation and complex arithmetic.
• The TMCLibError library is mentioned only in commented-out code. In the working MainPrepr1, instead of the CTmcLibError class, a simple parameter char *csError is used.
• The calling side: PREPR is called from the TMCIndan library — the wrapper MainPrepr() (TmcRTH_Indan.cpp:846) over MainPrepr1 (with a transition from CString / CTmcLibError& to char*). This is the only call site of PREPR.

The shared headers (src/Include/) that appear in the PREPR sources: Prepr1.h, typedef.h, error1.h, tmclimit.h, mainwndw.h, tpl_file.h, tmc_lib.h (provides alloc_mem_err / free_mem), run_flag.h, listing.h, indan.h, descrptr.h.