/****h* ROBODoc/Headers
 * FUNCTION
 *   This module contains a set of variables that define how headers
 *   start and how they end in various programming languages.
 * NOTES
 *   Added C++/ACM header option (David White)
 *   Enables documentation only comments (//!) to be extracted from C++ 
 *   and ACM files, rather than all comments.
 ******
 */

#include <assert.h>
#include <stdio.h>
#include <ctype.h>
#include <string.h>
#include "robodoc.h"
#include "headers.h"
#include "globals.h"
#include "util.h"

#define NO_MARKER_LOCKED -1
#define NO_MARKER        -2

static int locked_header_marker = NO_MARKER_LOCKED;
static int locked_end_marker    = NO_MARKER_LOCKED;
static int locked_remark_marker = NO_MARKER_LOCKED;


/****v* Headers/header_markers [3.0h]
 * NAME
 *   header_markers -- strings that mark the begin of a header.
 * FUNCTION
 *   These specify what robodoc recognizes as the beginning
 * NOTE
 *   The numbers at the beginning of the lines make it easier
 *   to keep them in sync with the src_constants
 *   of a header.
 * SOURCE
 */

char               *header_markers[] = {
    "/****",                    /* 0   C, C++ */
    "//!****",                  /* 1   C++, ACM */
    "//****",                   /* 2   C++ */
    "(****",                    /* 3   Pascal, Modula-2, B52 */
    "{****",                    /* 4   Pascal */
    ";;!****",                  /* 5   Aspen Plus */
    ";****",                    /* 6   M68K assembler */
    "****",                     /* 7   M68K assembler */
    "C     ****",               /* 8   Fortran */
    "REM ****",                 /* 9   BASIC */
    "%****",                    /* 10  LaTeX, TeX, Postscript */
    "#****",                    /* 11  Tcl/Tk */
    "      ****",               /* 12  COBOL */
    "--****",                   /* 13  Occam */
    "<!--****",                 /* 14  HTML Code */
    "<!---****",                /* 15  HTML Code,  the three-dashed comment
                                 * tells the [server] pre-processor not
                                 * to send that comment with the HTML 
                                 */
    "|****",                    /* 16  GNU Assembler */
    "!****",                    /* 17  FORTRAN 90 */
    "!!****",                   /* 18  FORTRAN 90 */
    "$!****",                   /* 19  DCL */
    "'****",                    /* 20  VB, LotusScript */
    ".****",                    /* 21  DB/C */
    NULL
};

/****/

/****v* Headers/robo_header [3.0h]
 * NAME
 *   robo_header -- the distinct robodoc header - 
 *                  alternative to using header_markers
 * FUNCTION
 *   This is an alternative to using header_markers - sometimes
 *   ROBODOC confuses asterisks commonly used in comments as a header.
 *   To use this header instead of header_markers use the -rh switch.
 * NOTE
 *   Added by David Druffner.
 * SOURCE
 */

char               *robo_header = "/*ROBODOC*";

/****/


/****v* Headers/remark_markers [3.0h]
 * NAME
 *   remark_markers
 * FUNCTION
 *   These specify what robodoc recognizes as a comment marker.
 * TODO
 *   (1) All the markers that start with one or more spaces are
 *   never recognized, and should be removed.
 *   (2) The numbers at the beginning of the lines make it easier
 *   to keep them in sync with the src_remark_constants
 * SOURCE
 */

char               *remark_markers[] = {

    " *",                       /* 0  C, C++, Pascal, Modula-2 */
    "//!",                      /* 1  C++, ACM */  /* MUST CHECK BEFORE C++ */
    "//",                       /* 2  C++ */
    "*",                        /* 3  C, C++, M68K assembler, Pascal,  Modula-2 */
    ";;!",                      /* 4  Aspen Plus */   /* MUST CHECK BEFORE M68K */
    ";*",                       /* 5  M68K assembler */
    ";",                        /* 6  M68K assembler */
    "C",                        /* 7  Fortran */
    "REM",                      /* 8  BASIC */
    "%",                        /* 9  LaTeX, TeX, Postscript */
    "#",                        /* 10 Tcl/Tk */
    "      *",                  /* 11 COBOL */
    "--",                       /* 12 Occam */
    "|",                        /* 13 GNU Assembler */
    "!!",                       /* 14 FORTRAN 90 */
    "!",                        /* 15 FORTRAN 90 */
    "$!",                       /* 16 DCL */
    "'*",                       /* 17 VB */
    ".*",                       /* 18 DB/C */
    NULL
};

/****/


/****v* Headers/end_markers [3.0h]
 * NAME
 *   end_markers -- strings that mark the end of a header.
 * FUNCTION
 *   These specify what robodoc recognizes as the end of a 
 *   documentation header. In most cases this will be
 *   "***" or " ***". If the header contains a SOURCE item
 *   then the end of the source has to be marked, which
 *   is when the other strings in this array are used.
 * NOTE
 *   The numbers at the beginning of the lines make it easier
 *   to find a special index-number.
 * SOURCE
 */

char               *end_markers[] = {
    "/***",                     /* 0  C, C++ */
    "//!***",                   /* 1  C++, ACM */  /* Must check before C++ */
    "//***",                    /* 2  C++ */
    " ***",                     /* 3  C, C++, Pascal, Modula-2 */
    "{***",                     /* 4  Pascal */
    "(***",                     /* 5  Pascal, Modula-2, B52 */
    ";;!***",                   /* 6  Aspen Plus */  /* Must check before M68K */
    ";***",                     /* 7  M68K assembler */
    "***",                      /* 8  M68K assembler */
    "C     ***",                /* 9  Fortran */
    "REM ***",                  /* 10 BASIC */
    "%***",                     /* 11 LaTeX, TeX, Postscript */
    "#***",                     /* 12 Tcl/Tk */
    "      ***",                /* 13 COBOL */
    "--***",                    /* 14 Occam */
    "<!--***",                  /* 15 HTML */
    "<!---***",                 /* 16 HTML */
    "|***",                     /* 17 GNU Assembler */
    "!!***",                    /* 18 FORTRAN 90 */
    "!***",                     /* 19 FORTRAN 90 */
    "$!***",                    /* 20 DCL */
    "'***",                     /* 21 VB, LotusScript */
    ".***",                     /* 22 DB/C */
    NULL
};

/****/

/****v* Headers/end_remark_markers
 * NAME
 *   end_remark_markers -- strings that mark the end of a comment.
 * NOTE
 *   The numbers at the beginning of the lines make it easier
 *   to keep them in sync with the end_remark_constants
 * SOURCE
 */

char               *end_remark_markers[] = {
    "*/",                       /* 0   C, C++ */
    ( char * ) NULL,            /* 1   C++, ACM */
    ( char * ) NULL,            /* 2   C++ */
    ( char * ) NULL,            /* 3   C, C++, Pascal, Modula-2 */
    "***}",                     /* 5   Pascal */
    "***)",                     /* 6   Pascal, Modula-2, B52 */
    ( char * ) NULL,            /* 7   M68K assembler */
    ( char * ) NULL,            /* 8   M68K assembler */
    ( char * ) NULL,            /* 9   Fortran */
    ( char * ) NULL,            /* 10  BASIC */
    ( char * ) NULL,            /* 11  LaTeX, TeX, Postscript */
    ( char * ) NULL,            /* 12  Tcl/Tk */
    ( char * ) NULL,            /* 13  COBOL */
    ( char * ) NULL,            /* 14  Occam */
    "-->",                      /* 15  HTML */
    "--->",                     /* 16  HTML */
    ( char * ) NULL,            /* 17  GNU Assembler */
    ( char * ) NULL,            /* 18  FORTRAN 90 !! */
    ( char * ) NULL,            /* 19  FORTRAN 90 !*/
    ( char * ) NULL,            /* 20  VB */
    ( char * ) NULL             /* 21  Aspen Plus */
};

/****/


/****v* Headers/robo_end [3.0h]
 * NAME
 *   robo_end[] -- the distinct robodoc end marker - 
 *                 alternative to using end_markers
 * FUNCTION
 *   This is an alternative to using end_markers - sometimes ROBODOC
 *   confuses asterisks commonly used in comments as an end marker. To
 *   use this footer instead of end_markers use the -rh switch.
 * NOTE
 *   Added by David Druffner.
 * SOURCE
 */

char               *robo_end[] = { "/*ROBODOC_END*", "*ROBODOC_END*", NULL };

/****/


/*x**v* Headers/RB_header_typenames
 * NAME
 *   RB_header_typename
 * FUNCTION
 *   Handy table to translate a header type number (see RB_header_types)
 *   to an ascii string.
 *
 *   OBSOLETE
 *
 *****
 */

char               *RB_header_type_names[] = {
    "none",
    "main",
    "generic",
    "function",
    "struct",
    "class",
    "method",
    "constant",
    "variable",
    "blank",
    "procedure",
    "type",
    "exception"
};

/*x**v* Headers/RB_internal_header_type_names
 * NAME
 *   RB_internal_header_type_names
 * FUNCTION
 *   Handy table to translate a header type number (see RB_header_types)
 *   to an ascii string.
 * NOTES
 *   (RB_header.type & ~INTERNAL_HEADER) should be used as the index
 *   into this array.  
 *    
 *    OBSOLETE
 *
 *****
 */

char               *RB_internal_header_type_names[] = {
    "none",
    "main (internal)",
    "generic (internal)",
    "function (internal)",
    "struct (internal)",
    "class (internal)",
    "method (internal)",
    "constant (internal)",
    "variable (internal)",
    "blank (internal)",
    "procedure (internal)",
    "type (internal)",
    "exception (internal)"
};


/***f* Headers/RB_Is_Begin_Marker
 * FUNCTION
 *   Scan a line and see if any of the begin of a header markers 
 *   defined in header_markers can be found.
 * SYNOPSIS
 *   static int RB_Is_Begin_Marker( char* cur_line, char** type )
 * INPUTS
 *   cur_line -- line to be searched.
 * OUTPUT
 *   type     -- the kind of header
 * RESULT
 *   TRUE  -- a begin header was found
 *   FALSE -- no begin header was found.
 * SOURCE
 */

int
RB_Is_Begin_Marker( char *cur_line, char **type )
{
    int                 found = FALSE;
    int                 marker = NO_MARKER;  /* for the assert */
    char               *cur_mchar = NULL;
    char               *cur_char = NULL;

    if ( !( course_of_action & DO_ROBO_HEAD ) 
         &&
         ( ( ( course_of_action & DO_LOCKHEADER ) &&
             ( locked_header_marker == NO_MARKER_LOCKED ) 
           )
           ||
           !( course_of_action & DO_LOCKHEADER ) 
         )
       )
    {
        for ( marker = 0;
              ( ( cur_mchar = header_markers[ marker ] ) != NULL )
              && !found; marker++ )
        {
            for ( found = TRUE, cur_char = RB_Skip_Whitespace( cur_line );
                  *cur_mchar && *cur_char && found; cur_mchar++, cur_char++ )
            {
                if ( tolower( *cur_mchar ) != tolower( *cur_char ) )
                    found = FALSE;
            }
        }
    }
    else if ( ( course_of_action & DO_LOCKHEADER ) &&
              ( locked_header_marker != NO_MARKER_LOCKED ) )
    {
        cur_mchar = header_markers[ locked_header_marker ];
        for ( found = TRUE, cur_char = RB_Skip_Whitespace( cur_line );
                *cur_mchar && *cur_char && found; cur_mchar++, cur_char++ )
        {
            if ( tolower( *cur_mchar ) != tolower( *cur_char ) )
            {
                found = FALSE;
            }
        }
    }
    else
    {
        /* use robo_header instead if -rh command line switch */
        if ( ( ( cur_mchar = robo_header ) != NULL ) )
        {
            for ( found = TRUE, cur_char = line_buffer;
                  *cur_mchar && *cur_char && found; cur_mchar++, cur_char++ )
            {
                if ( tolower( *cur_mchar ) != tolower( *cur_char ) )
                {
                    found = FALSE;
                }
            }
        }
    }                           /* end of DO_ROBO_HEAD else */

    if ( found && cur_char )
    {
        *type = cur_char;
        /* Do some additional checks to make sure it is
         * really a begin marker and not an end marker.
         */
        found = FALSE;
        /* It should contain a '/' and some non * characters. */
        for ( ; *cur_char && *cur_char != '/'; ++cur_char )
        {
            if ( *cur_char != '*' )
            {
                found = TRUE;
            }
        }
        found = found && ( *cur_char == '/' ) && ( *( cur_char - 1 ) != '*' );
    }

    if ( found && 
         ( course_of_action & DO_LOCKHEADER ) && 
         ( locked_header_marker == NO_MARKER_LOCKED ) ) 
    {
        assert( marker != NO_MARKER );
        locked_header_marker = marker - 1;
        RB_Say( "header marker locked on %s\n", header_markers[ locked_header_marker ] );
    }
    return found;
}

/******/


/****f* Headers/RB_Is_End_Marker
 * FUNCTION
 *   Scan a line and see if any of the end of a header markers 
 *   defined in header_markers can be found.
 * SYNOPSIS
 *   static int RB_Is_End_Marker( char* cur_line, char** type )
 * INPUTS
 *   cur_line -- line to be searched.
 * OUTPUT
 *   none
 * RESULT
 *   TRUE  -- an end header was found
 *   FALSE -- none was found.
 * SOURCE
 */

int
RB_Is_End_Marker( char *cur_line )
{
    int                 found = FALSE;
    int                 marker = NO_MARKER; /* For the assert */
    char               *cur_mchar;
    char               *cur_char;

    if ( !( course_of_action & DO_ROBO_HEAD ) 
         &&
         ( ( ( course_of_action & DO_LOCKHEADER ) &&
             ( locked_end_marker == NO_MARKER_LOCKED ) 
           )
           ||
           !( course_of_action & DO_LOCKHEADER ) 
         )
       )
    {
        for ( marker = 0;
              ( ( cur_mchar = end_markers[marker] ) != NULL ) && !found;
              marker++ )
        {
            for ( found = TRUE, cur_char = RB_Skip_Whitespace( cur_line );
                  *cur_mchar && *cur_char && found; cur_mchar++, cur_char++ )
            {
                if ( tolower( *cur_mchar ) != tolower( *cur_char ) )
                {
                    found = FALSE;
                }
            }
        }
    }
    else if ( ( course_of_action & DO_LOCKHEADER ) &&
              ( locked_end_marker != NO_MARKER_LOCKED ) )
    {
        cur_mchar = end_markers[ locked_end_marker ];
        for ( found = TRUE, cur_char = RB_Skip_Whitespace( cur_line );
              *cur_mchar && *cur_char && found; 
              cur_mchar++, cur_char++ )
        {
            if ( tolower( *cur_mchar ) != tolower( *cur_char ) )
            {
                found = FALSE;
            }
        }
    }
    else
    {
        /*use robo_end if using -rh switch */
        for ( marker = 0;
              ( ( cur_mchar = robo_end[marker] ) != NULL ) && !found;
              marker++ )
        {
            for ( found = TRUE, cur_char = cur_line;
                  *cur_mchar && *cur_char && found; cur_mchar++, cur_char++ )
            {
                if ( tolower( *cur_mchar ) != tolower( *cur_char ) )
                {
                    found = FALSE;
                }
            }
        }
    }

    /* Locking on end markers does not work at the moment,
     * because there can be more than one end marker for
     * a given language.
     */
#if 0
    if ( found &&
         ( course_of_action & DO_LOCKHEADER ) && 
         ( locked_end_marker == NO_MARKER_LOCKED ) ) 
    {
        assert( marker != NO_MARKER );
        locked_end_marker = marker - 1;
        RB_Say( "end marker locked on %s\n", end_markers[ locked_end_marker ] );
    }
#endif
    return found;
}

/*****/


/****f* Headers/RB_Has_Remark_Marker
 * FUNCTION
 *   Check if a line starts with a remark marker.  This function
 *   assumes that the remark marker starts on the first character of
 *   the line.
 * INPUTS
 *   o lline_buffer -- the line of text.
 * RESULT
 *   o TRUE -- it starts with a remark marker
 *   o FALSE -- it does not.
 * SOURCE
 */

int RB_Has_Remark_Marker( char* lline_buffer )
{
    int                 marker       = NO_MARKER; 
    int                 marker_found = NO_MARKER;
    int                 found  = FALSE;
    char*               space_pos = NULL;

    space_pos = strchr( lline_buffer, ' ' );

    /* Replace the first space on the line with a '\0'
     * this makes the comparison with the remark markers
     * much easier.
     */
    if ( space_pos )
    {
        *space_pos = '\0';
    }

    if ( ( ( course_of_action & DO_LOCKHEADER ) &&
           ( locked_remark_marker == NO_MARKER_LOCKED ) )
            ||
           !( course_of_action & DO_LOCKHEADER ) 
       )
    {
        for ( marker = 0; remark_markers[ marker ] != NULL; marker++ )
        {
            if ( RB_Str_Case_Cmp( lline_buffer, remark_markers[ marker ] ) == 0 ) 
            {
                marker_found = marker;
                found = TRUE;
            }
        }
    }
    else
    {
        if ( RB_Str_Case_Cmp( lline_buffer, remark_markers[ locked_remark_marker ] ) == 0 ) 
        {
            marker_found = marker;
            found = TRUE;
        }
    }

    if ( found && 
         ( locked_remark_marker == NO_MARKER_LOCKED ) 
         &&
         ( course_of_action & DO_LOCKHEADER )
       ) 
    {
        assert( marker_found != NO_MARKER );
        locked_remark_marker = marker_found;
        RB_Say( "remark marker locked on %s\n", remark_markers[ locked_remark_marker ] );
    }

    /* Restore the space we replaced with a '\0' */
    if ( space_pos )
    {
        *space_pos = ' ';
    }

    return found;
}

/******/


/****f* Headers/RB_Skip_Remark_Marker [2.0e]
 * NAME
 *    RB_Skip_Remark_Marker
 * SYNOPSIS
 *    text  = RB_Skip_Remark_Marker (line_buffer)
 *    char *                            char *
 * FUNCTION
 *    Scan and search for a recognized remark marker; skip past the
 *    marker to the body of the text
 * SOURCE
 */

char*
RB_Skip_Remark_Marker( char *lline_buffer )
{
    int                 marker, found;
    char               *cur_char, *cur_mchar;

    found = FALSE;
    cur_char = NULL;
    for ( marker = 0;
          ( ( cur_mchar = remark_markers[ marker ] ) != NULL ) && !found;
          marker++ )
    {
        for ( found = TRUE, cur_char = lline_buffer;
                *cur_mchar && *cur_char && found; cur_mchar++, cur_char++ )
        {
            if ( tolower( *cur_mchar ) != tolower( *cur_char ) )
            {
                found = FALSE;
            }
        }
    }
    return ( cur_char );
}

/**************/


void RB_Header_Lock_Reset( void )
{
    locked_header_marker = NO_MARKER_LOCKED;
    locked_end_marker    = NO_MARKER_LOCKED;
    locked_remark_marker = NO_MARKER_LOCKED;
}