# [ptm_gen.h] Parse Term Construction

## contents

#include "symbols.h"
#include "scn_base.h"
#include "scn_abs.h"
#include "prs_dfn.h"
#include "prs_abs.h"
#include "ptm.h"

       The module [ptm_gen] provides a high-level parse interface. It implements
       the construction of the parse tree / term during the parse process.
       The scan, parse and term construction functions are reentrant which offers
       the possibility of multiple concurrent parse operations.

## Types

PT_Diag | Abstract parse term diagnose type

PT_Cfg | Abstract parse term configuration type

## Parsing & Term Construction

    PT_Cfg PT_init(PLR_Tab PTab, Scn_Stream cStream)

initializes parse term construction
for parse table 'PTab' and scan stream 'cStream';
creates a configuration

    PT_Cfg PT_init_extscn(PLR_Tab PTab, AbsScn_T sconfig)

initializes parse term construction
for parse table 'PTab' and external scanner 'sconfig';
creates a configuration

    PT_Cfg PT_init_ext(AbsPlr_T pconfig, AbsScn_T sconfig)

initializes parse term construction
for external parser 'pconfig' and external scanner 'sconfig';
creates a configuration

    void PT_setMsgFun(void (*prMsg)(c_string msg))

defines 'prMsg' as ( static ) default message function
( 'msg': single byte character set or UTF-8 )

    void PT_setDiagFun(PT_Cfg PCfg, PT_Diag PDiag)

adds diagnose environment 'PDiag' to
parse term configuration 'PCfg'

    void PT_setTokConvFun(PT_Cfg PCfg, symbol convTok(symbol tok, symbol val))

adds token value converter 'convTok' to
parse term configuration 'PCfg'
( user-defined shift-handler )

    void PT_setNtmConvFun(PT_Cfg PCfg, PT_Term convNtm(PT_Term Tree))

adds nonterminal value converter 'convNtm' to
parse term configuration 'PCfg'
( user-defined reduce-handler; must release each replaced source tree )

    void PT_setTokConvFunEx
         (
           PT_Cfg PCfg,
           symbol convTok(symbol tok, symbol val, Any_T ctx),
           Any_T ctx
         )

like PT_setTokConvFun
Additionally, a non-NULL context 'ctx' will be passed
to the shift-handler.
Both handler must use the same context.
( currently not supported by 'pim_test' )

    void PT_setNtmConvFunEx
         (
           PT_Cfg PCfg, PT_Term convNtm(PT_Term Tree, Any_T ctx),
           Any_T ctx
         )

like PT_setNtmConvFun
Additionally, a non-NULL context 'ctx' will be passed
to the reduce-handler.
Both handler must use the same context.
( currently not supported by 'pim_test' )

    void PT_setEParser
         (
           PT_Cfg PCfg,
           Abs_T newEParser(Any_T ePlrCtx, c_string language),
           void  freeEParser(Abs_T eParser),
           Any_T ePlrCtx
         )

adds embedded parser constructor 'newEParser',
destructor 'freeEParser' and some context 'ePlrCtx' to
parse term configuration 'PCfg';
must be set for embedded languages

    void PT_quit(PT_Cfg PCfg)

terminates parse term construction;
removes configuration 'PCfg'

    PT_Term PT_parse(PT_Cfg PCfg, c_string StartSymbol, c_bool interprete)
    #define PT_PARSE(pcfg,start)      PT_parse((pcfg),(start),C_False)
    #define PT_INTERPRETE(pcfg,start) PT_parse((pcfg),(start),C_True)

parses and constructs parse term of type C ( see [ptm] )
according configuration 'PCfg';
uses 'StartSymbol' as start nonterminal or default if empty
( interprete --> early reduction )

    PT_Term XPT_parse(PT_Cfg PCfg, c_string StartSymbol, c_bool interprete)
    #define XPT_PARSE(pcfg,start)      XPT_parse((pcfg),(start),C_False)
    #define XPT_INTERPRETE(pcfg,start) XPT_parse((pcfg),(start),C_True)

parses and constructs parse term of type Xaron ( see [ptm] )
according configuration 'PCfg';
uses 'StartSymbol' as start nonterminal or default if empty
( interprete --> early reduction )

    int PT_synErrorCnt(PT_Cfg PCfg)

number of syntax errors in parse term configuration 'PCfg'

    symbol PT_ErrorSymbol(PT_Cfg PCfg)

symbol of error token in parse term configuration 'PCfg'

## Semantic Analysis

## ... using the default environment ( static )

    void PT_diagnose(PT_Term PTree, c_string format, ...)

prints a test message for parse term node 'PTree'
according variable format specification 'format' and '...'

    void PT_error(PT_Term PTree, c_string format, ...)

increments the number of semantic errors and
prints an error message for parse term node 'PTree'
according variable format specification 'format' and '...'

    void PT_warn(PT_Term PTree, c_string format, ...)

increments the number of warnings and
prints a warning message for parse term node 'PTree'
according variable format specification 'format' and '...'

    void PT_setErrorCnt(int cnt)

resets the number of semantic errors with 'cnt'

    int PT_errorCnt(void)

number of semantic errors

    void PT_setWarningCnt(int cnt)

resets the number of warnings with 'cnt'

    int PT_warnCnt(void)

number of warnings

## ... using the diagnose environment ( reentrant )

    PT_Diag PT_diag_init(void (*prMsg)(c_string msg))

creates a diagnose environment
using 'prMsg' as message function
( 'msg': single byte character set or UTF-8 )

    void PT_diag_quit(PT_Diag PDiag)

removes diagnose environment 'PDiag'

    void PT_diag_msg(PT_Term PTree, PT_Diag PDiag, c_string format, ...)

prints a message for parse term node 'PTree'
according diagnose environment 'PDiag',
variable format specification 'format' and '...'

    void PT_diag_test(PT_Term PTree, PT_Diag PDiag, c_string format, ...)

like PT_diag_msg; prints a test message

    void PT_diag_err(PT_Term PTree, PT_Diag PDiag, c_string format, ...)

increments the number of semantic errors
in diagnose environment 'PDiag' and
prints an error message for parse term node 'PTree'
according variable format specification 'format' and '...'

    void PT_diag_warn(PT_Term PTree, PT_Diag PDiag, c_string format, ...)

increments the number of warnings
in diagnose environment 'PDiag' and
prints a warning message for parse term node 'PTree'
according variable format specification 'format' and '...'

    void PT_diag_setErrorCnt(PT_Diag PDiag, int cnt)

resets the number of semantic errors
in diagnose environment 'PDiag' with 'cnt'

    int PT_diag_errorCnt(PT_Diag PDiag)

number of semantic errors in diagnose environment 'PDiag'

    void PT_diag_setWarningCnt(PT_Diag PDiag, int cnt)

resets number of warnings
in diagnose environment 'PDiag' with 'cnt'

    int PT_diag_warnCnt(PT_Diag PDiag)

number of warnings in diagnose environment 'PDiag'

    void (*PT_diag_msgFun(PT_Diag PDiag))(c_string msg)

message function in diagnose environment 'PDiag'

## Accessing configuration ( Xaron support )

    Scn_Stream PT_stream(PT_Cfg PCfg)

current scan stream in parse term configuration 'PCfg'

    PLR_Tab PT_ptab(PT_Cfg PCfg)

current parse table in parse term configuration 'PCfg'