# [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'