Apg.h

Go to the documentation of this file.

/*******************************************************************************
  APG Version 6.3
  Copyright (C) 2005 - 2012 Lowell D. Thomas, all rights reserved
 
  author:  Lowell D. Thomas
  email:   lowell@coasttocoastresearch.com
  website: http://www.coasttocoastresearch.com
 
  This program is free software: you can redistribute it and/or modify
  it under the terms of the GNU General Public License as published by
  the Free Software Foundation, either version 2 of the License, or
  (at your option) any later version.
 
  This program is distributed in the hope that it will be useful,
  but WITHOUT ANY WARRANTY; without even the implied warranty of
  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  GNU General Public License for more details.
 
  You should have received a copy of the GNU General Public License
  along with this program.  If not, see
  <http://www.gnu.org/licenses/old-licenses/gpl-2.0.html>
  or write to the Free Software Foundation, Inc.,
  51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
*******************************************************************************/
#ifndef APG_H_6_3
#define APG_H_6_3
//static int testing = 0; /**! member comment */
 
#include <stdlib.h>
#include <string.h>
 
// Begin C-language linkage specification
#if defined(__cplusplus)
extern "C"
{
#endif
 
// BASIC INTEGER TYPES
// APG integer apg_uint, default = unsigned int
#if defined _APG_CFG_UINT && _APG_CFG_UINT == 1
    typedef unsigned char apg_uint;
#elif defined _APG_CFG_UINT && _APG_CFG_UINT == 2
    typedef unsigned short int apg_uint;
#elif defined _APG_CFG_UINT && _APG_CFG_UINT == 4
    typedef unsigned int apg_uint;
#elif defined _APG_CFG_UINT && _APG_CFG_UINT == 8
    typedef unsigned long int apg_uint;
#else
    typedef unsigned int apg_uint;
#endif
 
// APG alphabet character apg_achar, default = unsigned char
#if defined _APG_CFG_ACHAR && _APG_CFG_ACHAR == 1
        typedef unsigned char apg_achar;
#elif defined _APG_CFG_ACHAR && _APG_CFG_ACHAR == 2
        typedef unsigned short int apg_achar;
#elif defined _APG_CFG_ACHAR && _APG_CFG_ACHAR == 4
        typedef unsigned int apg_achar;
#elif defined _APG_CFG_ACHAR && _APG_CFG_ACHAR == 8
        typedef unsigned long int apg_achar;
#else
        typedef unsigned char apg_achar;
#endif
 
#define APG_TRUE       1        // apg_uint true value
 
#define APG_FALSE      0        // apg_uint false value
 
#define APG_UNDEFINED -1    // often used to represent an undefined integer
 
#define APG_INFINITE  -1    // often used to represent an infinite integer
 
// NOTE: on Hungarian notation
// prefix - type
// c      - char
// cp     - char*
// ac     - apg_achar
// acp    - apg_achar*
// ui     - apg_uint
// uip    - apg_uint*
// v      - void
// vp     - void*
// s      - struct/union
// sp     - pointer to struct/union
 
// CONFIGURATION CONTROL
// Control of debugging, statistics and tracing information is designed
// through macros so that when not needed, they generate no code.
//
// Debug information
// _APG_CFG_DEBUG - if defined:
//                  - automatically defines _APG_CFG_STATS
//                  - automatically defines _APG_CFG_TRACE
//
 
// these macros generate no code unless otherwise defined
#if defined(_APG_CFG_DEBUG)
  // debug implies defines tracing & statistics gathering
  #undef  _APG_CFG_TRACE
  #define _APG_CFG_TRACE
 
  #undef  _APG_CFG_STATS
  #define _APG_CFG_STATS
#endif
 
#if defined(_APG_CFG_TRACE)
  // tracing macros (requires run-time set up in addition to _APG_CFG_TRACE)
  #define APG_TRACE_ADMIN(ctx, a, i, e, c) vTraceAdmin((ctx), (a), (i), (e), (c));
  #define APG_TRACE(ctx, op, a, i, off, pl) if((ctx)->vpTraceCtx){vTrace((ctx), (op), (a), (i), (off), (pl));}
#else
  #define APG_TRACE_ADMIN(ctx, a, i, e, c)
  #define APG_TRACE(ctx, op, a, i, off, pl)
#endif
 
#if defined(_APG_CFG_STATS)
        #define APG_STATS_ADMIN(ctx, a, s, r, cfg) vStatsAdmin((ctx), (a), (s), (r), (cfg))
        #define APG_STATS(ctx, a, s, o, r) vStats((ctx), (a), (s), (o), (r))
#else
        #define APG_STATS_ADMIN(ctx, a, s, r, cfg)
        #define  APG_STATS(ctx, a, s, o, r)
#endif
 
// Configurable default values
#undef APG_VEC_ELEMENT
#undef APG_VEC_ALLOC
 
#define APG_VEC_ELEMENT   ((apg_uint)1)     // default vector element size (bytes)
 
#define APG_VEC_ALLOC     ((apg_uint)100)   // default initial number of vector elements allocated
 
#define APG_DISPLAY_MAX_LINE    128
 
// ALERT HANDLING
 
typedef void (*PFN_ALERT)(unsigned int uiLine, const char* cpFile);
typedef void (*PFN_ALERT_MSG)(unsigned int uiLine, const char* cpFile, const char* cpMsg);
void vDefaultAlertHandler(unsigned int uiLine, const char* cpFile);
 
// TOOLS
// non-ANSI minimum/maximum macros
#undef min
#undef max
 
#define min(a,b) (((a) < (b)) ? (a) : (b))
 
#define max(a,b) (((a) > (b)) ? (a) : (b))
 
// stricmp is non-ANSI - not all CRTs support it
int apg_stricmp(const char* cpLhs, const char* cpRhs);
void vCharToAChar(apg_achar* acpAChars, const char* cpChars, apg_uint uiLen);
apg_uint uiACharToStringSize(const apg_achar* acpAChars, apg_uint uiALen);
apg_uint uiACharToString(char* cpChars, apg_uint uiCLen, const apg_achar* acpAChars, apg_uint uiALen);
 
// APG INFORMATION
char* cpApgVersion();
char* cpApgAuthor();
char* cpApgDescription();
char* cpApgCopyright();
char* cpApgEmail();
char* cpApgWebsite();
char* cpApgGPLNotice();
// MEMORY MANAGEMENT COMPONENT
// A container for all parser & parser-related memory allocations.
// Intended for initial set ups, not for dynamic allocation during parsing.
 
typedef struct{
  apg_uint uiAllocations;   
  apg_uint uiReAllocations; 
  apg_uint uiFrees; 
  apg_uint uiCells; 
  apg_uint uiMaxCells; 
  apg_uint uiHeapBytes; 
  apg_uint uiMaxHeapBytes; 
} APG_MEM_STATS;
 
typedef void* (*PFN_ALLOCATOR)(size_t);
typedef void  (*PFN_DEALLOCATOR)(void*);
void*           vpMemCtorA(PFN_ALLOCATOR pfnAllocator, PFN_DEALLOCATOR pfnDeAllocator);
void*           vpMemCtor();
void            vMemDtor(void* vpCtx);
apg_uint        uiMemValidate(void* vpCtx);
void*           vpMemAlloc(void* vpCtx, apg_uint uiBytes);
void*           vpMemRealloc(void* vpCtx, void* vpData, apg_uint uiBytes);
void            vMemFree(void* vpCtx, void* vpData);
apg_uint        uiMemCheckPoint(void* vpCtx);
void            vMemFreeToCheckPoint(void* vpCtx, apg_uint uiChk);
void            vMemClear(void* vpCtx);
 
// VECTOR
// a dynamic buffer for an arbitrary number of fixed-size elements
// Intended for initial set ups, not for dynamic allocation during parsing.
void* vpVecCtor(void* vpMemCtx, apg_uint uiElementSize, apg_uint uiInitialAlloc);
void  vVecDtor(void* vpCtx);
void* vpVecPush(void* vpVec, void* vpElement);
void* vpVecPushn(void* vpCtx, void* vpElement, apg_uint uiCount);
void* vpVecPop(void* vpCtx);
void* vpVecPopn(void* vpCtx, apg_uint uiCount);
void* vpVecPopTo(void* vpCtx, apg_uint uiIndex);
void* vpVecFront(void* vpCtx);
void* vpVecBack(void* vpCtx);
void* vpVecAt(void* vpCtx, apg_uint uiIndex);
apg_uint  uiVecBytes(void* vpCtx);
apg_uint  uiVecSize(void* vpCtx);
apg_uint  uiVecElementSize(void* vpCtx);
apg_uint  uiVecReallocations(void* vpCtx);
apg_uint        uiVecValidate(void* vpCtx);
void  vVecClear(void* vpCtx);
 
// PARSER
// structure passed to all syntax and semantic call back functions
/*
 
// !!!! DEBUG
Therefore, some variables are defined in a hierarchy of useage:
<pre>
Syntax Analysis - uiParserSyntaxAnalysis()
  rule callback functions
  UDT callback functions
Semantic Analysis - uiParserAstTranslate()
  rule callback functions
  UDT callback functions
</pre>
 
 
        Syntax Analysis, both rule and UDT callback functions.
        <pre>
        May be one of:
        PRE_PARSE - indicates the downward traversal state. No phrase has yet been matched.
        MATCH - a non-empty phrase has been matched
        EMPTY - an empty phrase has been matched
        NOMATCH - no phrase has been matched.
    </pre>
    Note on UDT
 
        From uiParserSyntaxAnalysis() may be any of PRE_PARSE, MATCH, EMPTY or NOMATCH.<br>
        From uiParserAstTranslate() may be  PRE_AST or POST_AST.
 
        //   SYNTAX ANALYSIS: output - set uiPhraseLength to the matched phrase length or APG_UNDEFINED if no match found
        // SEMANTIC ANALYSIS: uiPhraseLength for user's use only, ignored by parser on return
 
        // NOT USED BY PARSER - optional user-defined data, may be NULL
*/
typedef struct{
        void*                       vpCtx;                      
        const apg_achar*        acpSrc;                 
        apg_uint                    uiSrcLen;           
        apg_uint                    uiPhraseOffset;     
        apg_uint                    uiState;            
        apg_uint            uiPhraseLength;
        void*                   vpUserData;
} APG_CBDATA;
 
typedef apg_uint (*APG_CALLBACK)(APG_CBDATA* spData);
 
void vExecuteRule(APG_CBDATA* spData, apg_uint uiId, apg_uint uiOffset);
void vExecuteUdt(APG_CBDATA* spData, apg_uint uiId, apg_uint uiOffset);
 
// call back function states
#define PRE_PARSE       ((apg_uint)0) // pre-branch state
 
#define NOMATCH         ((apg_uint)1) // post-branch, string was not matched by grammar syntax
 
#define EMPTY           ((apg_uint)2) // post-branch, syntax was matched by an empty string
 
#define MATCH           ((apg_uint)3) // post-branch, syntax was matched with a string of one or more characters
 
#define PRE_AST         ((apg_uint)4) // post-branch state (semantic analysis only)
 
#define POST_AST        ((apg_uint)5) // post-branch state (semantic analysis only)
 
// parser final state
typedef struct{
        apg_uint uiSuccess; 
        apg_uint uiState; 
        apg_uint uiPhraseLength; 
        apg_uint uiStringLength; 
} APG_PARSER_STATE;
 
// parser statistics
typedef struct{
        apg_uint uiTotal;
        apg_uint uiMatch;
        apg_uint uiEmpty;
        apg_uint uiNoMatch;
} APG_STAT;
 
typedef struct{
        apg_uint uiIndex;
        char* cpName;
        APG_STAT sStat;
} APG_NAME_STAT;
 
typedef struct{
        apg_uint                uiSize; 
        apg_uint                uiNameCount; 
        apg_uint                uiRuleCount; 
        apg_uint                uiUdtCount; 
        APG_NAME_STAT*  spNameStats; 
        APG_NAME_STAT*  spNameStatsAlpha; 
        APG_NAME_STAT*  spNameStatsCount; 
        char*                   cpNames; 
        APG_STAT                sRnm; 
        APG_STAT                sUdt; 
        APG_STAT                sRep; 
        APG_STAT                sAlt; 
        APG_STAT                sCat; 
        APG_STAT                sAnd; 
        APG_STAT                sNot; 
        APG_STAT                sTrg; 
        APG_STAT                sTbs; 
        APG_STAT                sTls; 
        APG_STAT                sTotal; 
} APG_PARSER_STATS;
 
// parser constructor/desctructor
void*           vpParserCtor(void* vpParserInit, PFN_ALERT pfnAlertHandler);
void            vParserDtor(void* vpCtx);
 
// parser syntax analysis
apg_uint        uiParserSyntaxInitCallbacks(void* vpCtx, APG_CALLBACK* spRuleCallbacks, APG_CALLBACK* spUdtCallbacks);
apg_uint        uiParserSyntaxAnalysis(void* vpCtx, apg_uint uiStartRule, const apg_achar* acpSrc, apg_uint uiSrcLen, void* vpData);
apg_uint        uiParserState(void* vpCtx, APG_PARSER_STATE* spState);
 
// parser semantic analysis
void            vParserAstInitNodes(void* vpCtx, apg_uint* uipRules, apg_uint* uipUdts);
void            vParserAstInitCallbacks(void* vpCtx, APG_CALLBACK* spRuleCallbacks, APG_CALLBACK* spUdtCallbacks);
apg_uint        uiParserAstTranslate(void* vpCtx, APG_CALLBACK* pfnRuleCallbacks, APG_CALLBACK* pfnUdtCallbacks, void* vpData);
 
// parser statistics
apg_uint        uiParserStatsEnable(void* vpCtx, apg_uint uiEnable);
apg_uint        uiParserStatsGet(void* vpCtx, APG_PARSER_STATS* spStats, apg_uint* uipBufferSize);
 
// parser trace configuration
apg_uint        uiParserTraceEnable(void* vpCtx, apg_uint uiEnable);
void            vParserTraceOp(void* vpCtx, apg_uint uiOpId, apg_uint uiEnable);
void            vParserTraceRule(void* vpCtx, apg_uint uiIndex, apg_uint uiEnable);
void            vParserTraceUdt(void* vpCtx, apg_uint uiIndex, apg_uint uiEnable);
void            vParserTraceRange(void* vpCtx, apg_uint uiBegin, apg_uint uiCount);
 
// TRACE OPERATOR IDS
#define APG_TRACE_ALL                   1
 
#define APG_TRACE_TRG           2
 
#define APG_TRACE_TBS           3
 
#define APG_TRACE_TLS           4
 
#define APG_TRACE_AND           5
 
#define APG_TRACE_NOT           6
 
#define APG_TRACE_CAT           7
 
#define APG_TRACE_ALT           8
 
#define APG_TRACE_REP           9
 
#define APG_TRACE_RNM           10
 
#define APG_TRACE_UDT           11
 
#define APG_TRACE_COUNT             12
 
// the UDT callback function library
apg_uint uiUdtLib_e_owsp(APG_CBDATA* spData);
apg_uint uiUdtLib_u_wsp(APG_CBDATA* spData);
apg_uint uiUdtLib_u_lineend(APG_CBDATA* spData);
apg_uint uiUdtLib_e_any(APG_CBDATA* spData);
apg_uint uiUdtLib_u_semi_comment(APG_CBDATA* spData);
apg_uint uiUdtLib_u_cpp_comment(APG_CBDATA* spData);
apg_uint uiUdtLib_u_c_comment(APG_CBDATA* spData);
apg_uint uiUdtLib_u_alphanum(APG_CBDATA* spData);
apg_uint uiUdtLib_u_alphanum_hyphen(APG_CBDATA* spData);
apg_uint uiUdtLib_u_alphanum_under(APG_CBDATA* spData);
apg_uint uiUdtLib_u_decnum(APG_CBDATA* spData);
apg_uint uiUdtLib_u_hexnum(APG_CBDATA* spData);
apg_uint uiUdtLib_u_quotedstring(APG_CBDATA* spData);
apg_uint uiUdtLib_u_singlequotedstring(APG_CBDATA* spData);
apg_uint uiUdtLib_u_doublequotedstring(APG_CBDATA* spData);
 
// End C-language linkage specification
#if defined(__cplusplus)
}
#endif
 
#endif // APG_H_6_3