# [hpat.h] Template / Pattern Evaluation

## contents

#include "standard.h"
#include "scn_base.h"
#include "symbols.h"
#include "otab.h"
#include "gls.h"
#include "hpat_int.h"

The module [hpat] provides some functionality for the evaluation of template files based on the context-free grammar [hpat.sty].

It is used by the STYX reference generator.

## Types & Macros

Pattern types

    #define HPAT_REF_LIST   0 // pattern list
    #define HPAT_REF_PAT    1 // pattern
    #define HPAT_REF_PAR    2 // pattern parameter

HPat_T | Abstract template type

Callback function types

    // pattern reference evaluation function
    typedef c_bool (*PFN_Pat)(HPat_T pHPat);

    // print function
    typedef void (*PFN_PatPrint)(HPat_T pHPat, c_string szTxt);

    // replacement specification pattern load function
    typedef StdCPtr (*PFN_PatLoad)(GLS_Lst(hpatContent) pLst);
    // replacement specification apply function
    typedef c_string (*PFN_PatOpr)(c_string szTxt, StdCPtr pData);
    // replacement specification free function
    typedef void (*PFN_PatFree)(StdCPtr pData);

## Special Functions

    c_string HP_pat_to_txt(GLS_Lst(hpatContent) pLst)
| template term list 'pLst' to string; allocs memory

## Init & Quit

    void HP_init(void)
| initializes template evaluation module
    void HP_quit(void)
| terminates template evaluation module

## Create & Dispose

    HPat_T HP_create(void)
| creates a template evaluation object
    void HP_drop(HPat_T pHP)
| frees template evaluation object 'pHP'

## Get & Set

    void HP_setContext(HPat_T pHP, Abs_T pDocCtx)
| sets evaluation context 'pDocCtx' in template object 'pHP'
    Abs_T HP_getContext(HPat_T pHP)
| evaluation context of template object 'pHP'
    void HP_setPrintFun(HPat_T pHP, PFN_PatPrint pPrint)
| sets print function 'pPrint' in template object 'pHP'
    PFN_PatPrint HP_getPrintFun(HPat_T pHP)
| print function of template object 'pHP'
    void HP_setRefAlias(HPat_T pHP, symbol pRefAlias)
| sets reference alias 'pRefAlias' in template object 'pHP'
    symbol HP_getRefAlias(HPat_T pHP)
| reference alias of template object 'pHP'
    void HP_addPatSpec
         (
           HPat_T pHP, symbol pPat, PFN_Pat pPatFun, long lPatTyp
         )
| adds/overwrites evaluation function 'pPatFun' for pattern 'pPat' of type 'lPatTyp' to template object 'pHP'
    PFN_Pat HP_getPatFun(HPat_T pHP, symbol pPat)
| evaluation function for pattern 'pPat' in template object 'pHP'
    ROW(symbol) HP_getListPatRow(HPat_T pHP, symbol pListPat)
| member patterns of pattern list 'pListPat' in template object 'pHP'
    void HP_setScanner(HPat_T pHP, Scn_T pScn)
| sets external scanner 'pScn' in template object 'pHP' ( will be removed by HP_drop )
    Scn_T HP_getScanner(HPat_T pHP)
| pattern scanner of template object 'pHP'
    symbol HP_getPatRef(GLS_Tok pPatRef)
| symbol of pattern refernce token 'pPatRef'
    c_bool HP_addSpecialFun
           (
             symbol      pPatSym,
             PFN_PatLoad pPatLoad,
             PFN_PatOpr  pPatOpr,
             PFN_PatFree pPatFree
           )
| adds special evaluation functions for replacement specification pattern 'pPatSym' 'pPatLoad': loads replacement specification 'pPatOpr' : applies replacement specification 'pPatFree': frees replacement specification ( RC = ok/error )

## Load & Check

    c_bool HP_load
           (
             HPat_T pHP, Scn_Stream pStream, symbol pSrcId,
             symbol pRootPat, c_bool bRecursive
           )
| loads template pattern from scan stream 'pStream' into template object 'pHP' 'pSrcId' : optional source identifier 'pRootPat' : root pattern for evaluation 'bRecursive': recursive evaluation ( RC = ok/error )
    c_bool HP_check(HPat_T pHP)
| checks loaded template pattern in template object 'pHP' ( RC = ok/error )

## Output Generation

    void HP_gendoc_ref(HPat_T pHP, GLS_Tok pPatRef)
| evaluates and prints reference token 'pPatRef' according template object 'pHP'
    c_bool HP_fun_defined(HPat_T pHP, symbol pRefSym)
| whether template object 'pHP' contains a replacement specification for pattern 'pRefSym'
    c_string HP_fun_apply(HPat_T pHP, symbol pRefSym, c_string szTxt)
| applies the replacement specification for pattern 'pRefSym' in template object 'pHP' to text 'szText' RC = szTxt, if no functions defined, else result text
    void HP_gendoc_pat(HPat_T pHP, symbol pPatSym)
| evaluates and prints pattern 'pPatSym' according template object 'pHP'
    void HP_gendoc_src(HPat_T pHP, symbol pSrcId)
| evaluates and prints template 'pSrcId' according template object 'pHP'