Back to index

webcit  8.12-dfsg
Classes | Typedefs | Functions
Template processing functions

Classes

struct  _contexts
 ContextFilter resembles our RTTI information. More...
struct  WCTemplateToken
 Representation of a token; everything thats inbetween <? and > More...

Typedefs

typedef struct _contexts ContextFilter
 ContextFilter resembles our RTTI information.
typedef int(* WCConditionalFunc )(StrBuf *Target, WCTemplputParams *TP)
 this is the signature of a conditional function Note: Target is just passed in for error messages; don't write onto it in regular cases.

Functions

void LogTemplateError (StrBuf *Target, const char *Type, int ErrorPos, WCTemplputParams *TP, const char *Format,...) __attribute__((__format__(__printf__
 log an error while evaluating a token; print it to the actual template
void void LogError (StrBuf *Target, const char *Type, const char *Format,...)
 log an error while in global context; print it to Wildfire / Target
void GetTemplateTokenString (StrBuf *Target, WCTemplputParams *TP, int N, const char **Value, long *len)
 get the actual value of a token parameter in your tmplputs or conditionals use this function to access parameters that can also be retrieved from dynamic facilities: _ -> Gettext; retrieve this token from the i18n facilities : -> lookup a setting of that name B -> bstr; an URL-Parameter = -> subtemplate; parse a template by this name, and treat its content as this tokens value
int HaveTemplateTokenString (StrBuf *Target, WCTemplputParams *TP, int N, const char **Value, long *len)
long GetTemplateTokenNumber (StrBuf *Target, WCTemplputParams *TP, int N, long dflt)
 get the actual integer value of a token parameter in your tmplputs or conditionals use this function to access parameters that can also be retrieved from dynamic facilities: _ -> Gettext; retrieve this token from the i18n facilities : -> lookup a setting of that name B -> bstr; an URL-Parameter = -> subtemplate; parse a template by this name, and treat its content as this tokens value
void RegisterNS (const char *NSName, long len, int nMinArgs, int nMaxArgs, WCHandlerFunc HandlerFunc, WCPreevalFunc PreEvalFunc, int ContextRequired)
 register a template token handler call this function in your InitModule_MODULENAME which will be called at the server start
void RegisterConditional (const char *Name, long len, int nParams, WCConditionalFunc CondF, int ContextRequired)
 register a conditional token <pair> handler call this function in your InitModule_MODULENAME which will be called at the server start conditionals can be ? or ! with a pair or % similar to an implicit if
void RegisterTokenParamDefine (const char *Name, long len, long Value)
 register a string that will represent a long value this will allow to resolve <?...(#"Name")> to Value; that way plain strings can be used an lexed in templates without having the lookup overhead at runtime.
long GetTokenDefine (const char *Name, long len, long DefValue)
 retrieve the long value of a registered string define

Class Documentation

struct _contexts

ContextFilter resembles our RTTI information.

With this structure we can make shure a tmplput function can live with the environment we call it in. if not, we will log/print an error and refuse to call it.

Definition at line 79 of file subst.h.

Class Members
int ContextType
int ControlContextType
int nMaxArgs
int nMinArgs
struct WCTemplateToken

Representation of a token; everything thats inbetween <? and >

Definition at line 129 of file subst.h.

Collaboration diagram for WCTemplateToken:
Class Members
const StrBuf * FileName
int Flags
StrBuf * FlatToken
int HaveParameters
long Line
size_t NameEnd
int nParameters
TemplateParam * Params
const char * pName
void * PreEval
void * Preeval2
const char * pTokenEnd
const char * pTokenStart
size_t TokenEnd
size_t TokenStart

Typedef Documentation

typedef struct _contexts ContextFilter

ContextFilter resembles our RTTI information.

With this structure we can make shure a tmplput function can live with the environment we call it in. if not, we will log/print an error and refuse to call it.

typedef int(* WCConditionalFunc)(StrBuf *Target, WCTemplputParams *TP)

this is the signature of a conditional function Note: Target is just passed in for error messages; don't write onto it in regular cases.

Definition at line 105 of file subst.h.


Function Documentation

long GetTemplateTokenNumber ( StrBuf *  Target,
WCTemplputParams TP,
int  N,
long  dflt 
)

get the actual integer value of a token parameter in your tmplputs or conditionals use this function to access parameters that can also be retrieved from dynamic facilities: _ -> Gettext; retrieve this token from the i18n facilities : -> lookup a setting of that name B -> bstr; an URL-Parameter = -> subtemplate; parse a template by this name, and treat its content as this tokens value

Parameters:
Nwhich token do you want to lookup?
dfltdefault value to be retrieved if not found in preferences
Returns:
the long value

Definition at line 517 of file subst.c.

{
       long Ret;
       if (N >= TP->Tokens->nParameters) {
              LogTemplateError(Target, 
                             "TokenParameter", N, TP, 
                             "invalid token %d. this shouldn't have come till here.\n", N);
              wc_backtrace(); 
              return 0;
       }

       switch (TP->Tokens->Params[N]->Type) {

       case TYPE_STR:
              return atol(TP->Tokens->Params[N]->Start);
              break;
       case TYPE_BSTR:
              if (TP->Tokens->Params[N]->len == 0) {
                     LogTemplateError(Target, 
                                    "TokenParameter", N, TP, 
                                    "Requesting parameter %d; of type BSTR, empty lookup string not admitted.", N);
                     return 0;
              }
              return  LBstr(TKEY(N));
              break;
       case TYPE_PREFSTR:
              LogTemplateError(Target, 
                             "TokenParameter", N, TP, 
                             "requesting a prefstring in param %d want a number", N);
              if (TP->Tokens->Params[N]->len == 0) {
                     LogTemplateError(Target, 
                                    "TokenParameter", N, TP, 
                                    "Requesting parameter %d; of type PREFSTR, empty lookup string not admitted.", N);
                     return 0;
              }
              if (get_PREF_LONG(TKEY(N), &Ret, dflt))
                     return Ret;
              return 0;
       case TYPE_INTDEFINE:
       case TYPE_LONG:
              return TP->Tokens->Params[N]->lvalue;
       case TYPE_PREFINT:
              if (TP->Tokens->Params[N]->len == 0) {
                     LogTemplateError(Target, 
                                    "TokenParameter", N, TP, 
                                    "Requesting parameter %d; of type PREFINT, empty lookup string not admitted.", N);
                     return 0;
              }
              if (get_PREF_LONG(TKEY(N), &Ret, dflt))
                     return Ret;
              return 0;            
       case TYPE_GETTEXT:
              LogTemplateError(Target, 
                             "TokenParameter", N, TP, 
                             "requesting a I18N string in param %d; want a number", N);
              return 0;
       case TYPE_SUBTEMPLATE:
              LogTemplateError(Target, 
                             "TokenParameter", N, TP, 
                             "requesting a subtemplate in param %d; not supported for numbers", N);
              return 0;
       default:
              LogTemplateError(Target, 
                             "TokenParameter", N, TP, 
                             "unknown param type %d; [%d]", N, TP->Tokens->Params[N]->Type);
              return 0;
       }
}

Here is the call graph for this function:

Here is the caller graph for this function:

void GetTemplateTokenString ( StrBuf *  Target,
WCTemplputParams TP,
int  N,
const char **  Value,
long *  len 
)

get the actual value of a token parameter in your tmplputs or conditionals use this function to access parameters that can also be retrieved from dynamic facilities: _ -> Gettext; retrieve this token from the i18n facilities : -> lookup a setting of that name B -> bstr; an URL-Parameter = -> subtemplate; parse a template by this name, and treat its content as this tokens value

Parameters:
Nwhich token do you want to lookup?
Valuereference to the string of the token; don't free me.
lenthe length of Value

Definition at line 423 of file subst.c.

{
       StrBuf *Buf;
       WCTemplputParams SubTP;

       if (N >= TP->Tokens->nParameters) {
              LogTemplateError(Target, 
                             "TokenParameter", N, TP, 
                             "invalid token %d. this shouldn't have come till here.\n", N);
              *Value = "";
              *len = 0;
              return;
       }

       switch (TP->Tokens->Params[N]->Type) {

       case TYPE_INTDEFINE:
       case TYPE_STR:
              *Value = TP->Tokens->Params[N]->Start;
              *len = TP->Tokens->Params[N]->len;
              break;
       case TYPE_BSTR:
              if (TP->Tokens->Params[N]->len == 0) {
                     LogTemplateError(Target, 
                                    "TokenParameter", N, TP, 
                                    "Requesting parameter %d; of type BSTR, empty lookup string not admitted.", N);
                     *len = 0;
                     *Value = EmptyStr;
                     break;
              }
              Buf = (StrBuf*) SBstr(TKEY(N));
              *Value = ChrPtr(Buf);
              *len = StrLength(Buf);
              break;
       case TYPE_PREFSTR:
              if (TP->Tokens->Params[N]->len == 0) {
                     LogTemplateError(Target, 
                                    "TokenParameter", N, TP, 
                                    "Requesting parameter %d; of type PREFSTR, empty lookup string not admitted.", N);
                     *len = 0;
                     *Value = EmptyStr;
                     break;
              }
              get_PREFERENCE(TKEY(N), &Buf);
              *Value = ChrPtr(Buf);
              *len = StrLength(Buf);
              break;
       case TYPE_LONG:
              LogTemplateError(Target, 
                             "TokenParameter", N, TP, 
                             "Requesting parameter %d; of type LONG, want string.", N);
              break;
       case TYPE_PREFINT:
              LogTemplateError(Target, 
                             "TokenParameter", N, TP, 
                             "Requesting parameter %d; of type PREFINT, want string.", N);
              break;
       case TYPE_GETTEXT:
              *Value = _(TP->Tokens->Params[N]->Start);
              *len = strlen(*Value);
              break;
       case TYPE_SUBTEMPLATE:
              if (TP->Tokens->Params[N]->len == 0) {
                     LogTemplateError(Target, 
                                    "TokenParameter", N, TP, 
                                    "Requesting parameter %d; of type SUBTEMPLATE, empty lookup string not admitted.", N);
                     *len = 0;
                     *Value = EmptyStr;
                     break;
              }

              memset(&SubTP, 0, sizeof(WCTemplputParams *));
              SubTP.Context = TP->Context;
              SubTP.Filter.ContextType = TP->Filter.ContextType;
              Buf = NewStrBuf();
              DoTemplate(TKEY(N), Buf, &SubTP);
              *Value = ChrPtr(Buf);
              *len = StrLength(Buf);
              /* we can't free it here, so we put it into the subst so its discarded later on. */
              PutRequestLocalMem(Buf, HFreeStrBuf);
              break;

       default:
              LogTemplateError(Target, 
                             "TokenParameter", N, TP, 
                             "unknown param type %d; [%d]", N, TP->Tokens->Params[N]->Type);
              break;
       }
}

Here is the call graph for this function:

Here is the caller graph for this function:

long GetTokenDefine ( const char *  Name,
long  len,
long  DefValue 
)

retrieve the long value of a registered string define

Parameters:
NameThe name of the define
lenlength of Name
Valuethe value to return if not found

Definition at line 2113 of file subst.c.

{
       void *vPVal;

       if (GetHash(Defines, Name, len, &vPVal) &&
            (vPVal != NULL))
        {
               return *(long*) vPVal;
        }
        else
        {
               return DefValue;
        }
}

Here is the caller graph for this function:

int HaveTemplateTokenString ( StrBuf *  Target,
WCTemplputParams TP,
int  N,
const char **  Value,
long *  len 
)
Returns:
whether GetTemplateTokenString would be able to give you a string

Definition at line 398 of file subst.c.

{
       if (N >= TP->Tokens->nParameters) {
              return 0;
       }

       switch (TP->Tokens->Params[N]->Type) {
       case TYPE_INTDEFINE:
       case TYPE_STR:
       case TYPE_BSTR:
       case TYPE_PREFSTR:
       case TYPE_GETTEXT:
       case TYPE_SUBTEMPLATE:
              return 1;
       case TYPE_LONG:
       case TYPE_PREFINT:
       default:
              return 0;
       }
}

Here is the caller graph for this function:

void void LogError ( StrBuf *  Target,
const char *  Type,
const char *  Format,
  ... 
)

log an error while in global context; print it to Wildfire / Target

Parameters:
Targetyour Target Buffer to print the error message next to the log
TypeWhat sort of thing are we talking about? Tokens? Conditionals?
Formatfor the custom error message

Definition at line 250 of file subst.c.

{
       wcsession *WCC;
       StrBuf *Error;
       StrBuf *Info;
        va_list arg_ptr;

       Info = NewStrBuf();
       Error = NewStrBuf();

        va_start(arg_ptr, Format);
       StrBufVAppendPrintf(Error, Format, arg_ptr);
       va_end(arg_ptr);

       syslog(1, "%s", ChrPtr(Error));

       WCC = WC;
       if (WCC->WFBuf == NULL) WCC->WFBuf = NewStrBuf();

       SerializeJson(WCC->WFBuf, WildFireException(Type, strlen(Type),
                                              0,
                                              Info,
                                              1), 1);

       FreeStrBuf(&Info);
       FreeStrBuf(&Error);
/*
       if (dbg_backtrace_template_errors)
              wc_backtrace(); 
*/
}
void LogTemplateError ( StrBuf *  Target,
const char *  Type,
int  ErrorPos,
WCTemplputParams TP,
const char *  Format,
  ... 
)

log an error while evaluating a token; print it to the actual template

Parameters:
Targetyour Target Buffer to print the error message next to the log
TypeWhat sort of thing are we talking about? Tokens? Conditionals?
TPgrab our set of default information here
Formatfor the custom error message
void RegisterConditional ( const char *  Name,
long  len,
int  nParams,
WCConditionalFunc  CondF,
int  ContextRequired 
)

register a conditional token <pair> handler call this function in your InitModule_MODULENAME which will be called at the server start conditionals can be ? or ! with a pair or % similar to an implicit if

Parameters:
Namewhats the name of your conditional? should start with COND:
lenthe token length so we don't have to measure it.
nParamshow many parameters does your conditional need on top of the default conditional parameters
CondFyour Callback to be called when the template is evaluated at runtime; return 0 or 1 to us please.
ContextRequiredif your token requires a specific context, else say CTX_NONE here.

Definition at line 2067 of file subst.c.

{
       ConditionalStruct *Cond;

       Cond = (ConditionalStruct*)malloc(sizeof(ConditionalStruct));
       memset(Cond, 0, sizeof(ConditionalStruct));
       Cond->PlainName = Name;
       Cond->Filter.nMaxArgs = nParams;
       Cond->Filter.nMinArgs = nParams;
       Cond->CondF = CondF;
       Cond->Filter.ContextType = ContextRequired;
       Cond->Filter.ControlContextType = CTX_NONE;
       Put(Conditionals, Name, len, Cond, NULL);
}

Here is the caller graph for this function:

void RegisterNS ( const char *  NSName,
long  len,
int  nMinArgs,
int  nMaxArgs,
WCHandlerFunc  HandlerFunc,
WCPreevalFunc  PreEvalFunc,
int  ContextRequired 
)

register a template token handler call this function in your InitModule_MODULENAME which will be called at the server start

Parameters:
nMinArgshow much parameters does your token require at least?
nMaxArgshow many parameters does your token accept?
HandlerFuncyour callback when the template is rendered and your token is there
PreEvalFuncis called when the template is parsed; you can do additional syntax checks here or pre-evaluate stuff for better performance
ContextRequiredif your token requires a specific context, else say CTX_NONE here.

Definition at line 25 of file setup.c.

                                  {}

Here is the caller graph for this function:

void RegisterTokenParamDefine ( const char *  Name,
long  len,
long  Value 
)

register a string that will represent a long value this will allow to resolve <?...(#"Name")> to Value; that way plain strings can be used an lexed in templates without having the lookup overhead at runtime.

Parameters:
NameThe name of the define
lenlength of Name
Valuethe value to associate with Name

Definition at line 2103 of file subst.c.

{
       long *PVal;

       PVal = (long*)malloc(sizeof(long));
       *PVal = Value;
       Put(Defines, Name, len, PVal, NULL);
}

Here is the caller graph for this function: