parsevar.h
=============================================================================

    This module provides several functions that do some heavy-duty
    text parsing (macros, text codes, and *-codes). While the
    routines look deceptively simple, their task is formidable. I
    hesitated for a long time before actually writing them as the
    complexity involved is taxing (not as programming effort, but
    as figuring out how they are supposed to behave). The current
    implemetnation is the third generation of the interface.


    PARSE_TOKEN
    -------------------------------------------------------------------------

       Synopsis  Create a string based on a token

       Syntax    char* parse_token(char *dest, int token, int style, int len);

       Remarks   This function will create a string whith content based on
                 the 'token' parameter. You can use the constants defined in
                 the PARSEDEF.H file as the value of the token (except the
                 PDEF_ERROR, PDEF_DEAD, PDEF_JUST_???, and PDEF_ACTION_???)
                 which are reserved for other use. You will notice that the
                 tokens correspond to the textcode macros available in
                 ProBoard. Each constant has a brief description the header
                 file that you can read to determine its nature.

                 The 'dest' parameter is the buffer where the result will be
                 placed by the function. If an invalid token is requested,
                 this will be set to "" (empty string). Note that this area
                 should be large enough to accomodate the anticipated result.

                 The 'style' parameter determines the justification of the
                 text in the buffer (padding is always done with blanks).
                 The styles that are available are as follows:

                           JUST_LEFT   - left justification
                           JUST_RIGHT  - right justification
                           JUST_CENTER - text is centered

                 The 'len' argument controls the width of the buffer. This
                 is the maximum width that the buffer can hold. The caller
                 is guaranteed that this number will not be exceeded (you
                 should allow 'len+1' characters in buffer size in order to
                 accomodate the terminating NUL). If the text is longer than
                 'len' characters, it will be truncated on the left.

       Return    dest


    PARSE_ACTION
    -------------------------------------------------------------------------

       Synopsis  Execute a command based on a token

       Syntax    Boolean parse_action(int token, char *data = 0);

       Remarks   This function is primarily intended for internal use. The
                 'token' parameter specifies the action to be performed
                 (you must use one of the PDEF_ACTION_??? constants), and
                 'data' is an optional argument which can be used, depending
                 on the action, to pass additional data to the function.
                 Refer to the source code for further information.

       Return    On success, returns True; False otherwise


    PARSE_MACRO
    -------------------------------------------------------------------------

       Synopsis  Parse a ProBoard-style macro

       Syntax    int parse_macro(char *result, char *source);

       Remarks   This function is used to parse @<MACRO>@ (ProBoard style).
                 It assumes that the 'source' string contains the text of
                 the macro (with the "@<" and ">@" delimeters stripped).
                 All ProBoard macros are supported (but some are faked).
                 Also, the justification specifiers can be used as well.
                 For more information, refer to the user manual. Note that
                 the 'result' buffer must be large enough to accomodate the
                 resulting text string.

       Return    0 - error (unknown macro)
                 1 - string formatted in 'result'
                 2 - macro specified an action (performed 'result' undefined)

    PARSE_STARS
    -------------------------------------------------------------------------

       Synopsis  Parse the '*' (star) codes

       Syntax    void parse_stars(char *result, char *source, int maxlen);

       Remarks   This function can parse the star macros used by ProBoard's
                 function 7 (Shell). The 'source' argument contains one or
                 more '*x' codes (refer to ProBoard's manual) which are to
                 be parsed. All other text remains unchanged. The 'result'
                 string will contain the text with the macros replaced by
                 relevant data. The 'maxlen' parameter determines the maximum
                 number of characters that can be placed in the buffer.
                 While all star macros will be processed, only some will be
                 replaced with data (the ones that do require a caller
                 online, such as the FOSSIL-disable macro, will be ignored).

       Return    Nothing

