Annotation of embedaddon/libpdel/tmpl/tmpl.h, revision 1.1
1.1 ! misho 1:
! 2: /*
! 3: * Copyright (c) 2001-2002 Packet Design, LLC.
! 4: * All rights reserved.
! 5: *
! 6: * Subject to the following obligations and disclaimer of warranty,
! 7: * use and redistribution of this software, in source or object code
! 8: * forms, with or without modifications are expressly permitted by
! 9: * Packet Design; provided, however, that:
! 10: *
! 11: * (i) Any and all reproductions of the source or object code
! 12: * must include the copyright notice above and the following
! 13: * disclaimer of warranties; and
! 14: * (ii) No rights are granted, in any manner or form, to use
! 15: * Packet Design trademarks, including the mark "PACKET DESIGN"
! 16: * on advertising, endorsements, or otherwise except as such
! 17: * appears in the above copyright notice or in the software.
! 18: *
! 19: * THIS SOFTWARE IS BEING PROVIDED BY PACKET DESIGN "AS IS", AND
! 20: * TO THE MAXIMUM EXTENT PERMITTED BY LAW, PACKET DESIGN MAKES NO
! 21: * REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, REGARDING
! 22: * THIS SOFTWARE, INCLUDING WITHOUT LIMITATION, ANY AND ALL IMPLIED
! 23: * WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE,
! 24: * OR NON-INFRINGEMENT. PACKET DESIGN DOES NOT WARRANT, GUARANTEE,
! 25: * OR MAKE ANY REPRESENTATIONS REGARDING THE USE OF, OR THE RESULTS
! 26: * OF THE USE OF THIS SOFTWARE IN TERMS OF ITS CORRECTNESS, ACCURACY,
! 27: * RELIABILITY OR OTHERWISE. IN NO EVENT SHALL PACKET DESIGN BE
! 28: * LIABLE FOR ANY DAMAGES RESULTING FROM OR ARISING OUT OF ANY USE
! 29: * OF THIS SOFTWARE, INCLUDING WITHOUT LIMITATION, ANY DIRECT,
! 30: * INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, PUNITIVE, OR CONSEQUENTIAL
! 31: * DAMAGES, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES, LOSS OF
! 32: * USE, DATA OR PROFITS, HOWEVER CAUSED AND UNDER ANY THEORY OF
! 33: * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
! 34: * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF
! 35: * THE USE OF THIS SOFTWARE, EVEN IF PACKET DESIGN IS ADVISED OF
! 36: * THE POSSIBILITY OF SUCH DAMAGE.
! 37: *
! 38: * Author: Archie Cobbs <archie@freebsd.org>
! 39: */
! 40:
! 41: #ifndef _PDEL_TMPL_TMPL_H_
! 42: #define _PDEL_TMPL_TMPL_H_
! 43:
! 44: /*
! 45: * This code supports a simple text template language. An input file
! 46: * is scanned for special function tags. A function tag is an at sign
! 47: * ('@') followed by a contiguous sequence of letters, digits, and
! 48: * underscores, followed by parentheses containing zero or more
! 49: * function arguments.
! 50: *
! 51: * Function arguments may be either other function tags (the argument
! 52: * to the outer function is the result of the inner function invocation),
! 53: * or constant literal strings in double quotes (the argument is the
! 54: * value of the string). Note this means that all function arguments
! 55: * begin with either an at sign or a double quote character. Function
! 56: * arguments are enclosed in parentheses, separated by commas, and
! 57: * may have whitespace around them.
! 58: *
! 59: * When processed, function tags result in a function invocation
! 60: * which returns some text which is then substituted into the output
! 61: * stream. Special control flow function tags control input processing
! 62: * and return the empty string.
! 63: *
! 64: * Non-function tag text input is passed through unaltered.
! 65: *
! 66: * Constant literal strings (enclosed in double quotes) respect the
! 67: * normal C backslash escapes.
! 68: *
! 69: * Built-in functions that take no arguments do not require parentheses,
! 70: * but parentheses may be included for separation purposes.
! 71: *
! 72: * User-supplied functions may return NULL and set errno to indicate
! 73: * an error, in which case the corresponding error string is substituted,
! 74: * after being formatted by the caller-supplied error formatter.
! 75: *
! 76: * The predefined functions are:
! 77: *
! 78: * @while(x) ... @endwhile
! 79: * The text in between is repeated as long as x is true
! 80: * (x is true if it is an integer whose value is non-zero).
! 81: *
! 82: * @loop(numloops) ... @endloop
! 83: * The text in between is repeated 'numloops' times, which
! 84: * must be an integer value.
! 85: *
! 86: * @loopindex(i)
! 87: * Returns the loop index (counting from zero) of the loop
! 88: * that is 'i' loops out from the innermost loop, else -1.
! 89: * If argument is omitted it is assumed to be zero.
! 90: *
! 91: * @if(x) ... [ @elif ... [ @elif ... ] ] [ @else ... ] @endif
! 92: * Conditional execution depending on the truth value of x.
! 93: *
! 94: * @define(name) ... @enddef
! 95: * Defines a run-time function. The text in between is executed
! 96: * whenever @name(...) is subsequently invoked. During this execution,
! 97: * the variables "argc" and "arg0", "arg1", ... are set to the
! 98: * function argument count and arguments, respectively (the function
! 99: * name itself is always the value of "arg0".
! 100: *
! 101: * @break
! 102: * Break out of the nearest enclosing @loop or @while loop.
! 103: *
! 104: * @continue
! 105: * Continue with the next iteration of the nearest enclosing
! 106: * @loop or @while loop.
! 107: *
! 108: * @return
! 109: * Return from within a run-time function.
! 110: *
! 111: * @equal(x,y)
! 112: * Returns "1" if x and y are identical, else "0".
! 113: *
! 114: * @not(x)
! 115: * Returns "1" unless x is an integer whose value is non-zero.
! 116: *
! 117: * @and(arg1, arg2, ...)
! 118: * Returns logical "and" of the truth values of the arguments.
! 119: *
! 120: * @or(arg1, arg2, ...)
! 121: * Returns logical "or" of the truth values of the arguments.
! 122: *
! 123: * @add(arg1, ...)
! 124: * Returns sum of the numerical values of the arguments.
! 125: *
! 126: * @mul(arg1, ...)
! 127: * Returns product of the numerical values of the arguments.
! 128: *
! 129: * @div(arg1, arg2)
! 130: * Returns the first argument divided by the second.
! 131: *
! 132: * @mod(arg1, arg2)
! 133: * Returns the first argument modulo by the second.
! 134: *
! 135: * @lt(arg1, arg2)
! 136: * @gt(arg1, arg2)
! 137: * @le(arg1, arg2)
! 138: * @ge(arg1, arg2)
! 139: * Returns "0" or "1" as arg1 is <, >, <=, or >= arg2.
! 140: *
! 141: * @sub(arg1, ...)
! 142: * Returns subtraction of the numerical values of the second
! 143: * and subsequent arguments from the first.
! 144: *
! 145: * @error(arg)
! 146: * Output the argument using the caller's error formatting.
! 147: *
! 148: * @eval(arg)
! 149: * The argument itself is processed. Embedded function tags
! 150: * are processed normally, while the rest is passed unaltered.
! 151: *
! 152: * @funcname(arg1, arg2, ...)
! 153: * Invoke the generic user-supplied function handler.
! 154: *
! 155: * @@
! 156: * Expands to ``@''
! 157: *
! 158: * @cat(arg1, arg2, ...)
! 159: * Returns concatentated arguments.
! 160: *
! 161: * @set(var, value)
! 162: * Sets run-time variable 'var' to have value 'value'. Variables
! 163: * are global and live until tmpl_process() returns. Returns the
! 164: * empty string.
! 165: *
! 166: * @get(var)
! 167: * Retrieves the value of run-time variable 'var'.
! 168: * Returns the empty string if 'var' is not set.
! 169: *
! 170: * @urlencode(arg)
! 171: * Expands and URL-encodes the argument.
! 172: *
! 173: * @htmlencode(arg)
! 174: * Expands and HTML-encodes the first argument.
! 175: *
! 176: * @output(arg)
! 177: * Outputs the argument directly to the output stream. That is,
! 178: * if this function is invoked from within a user-defined function,
! 179: * the argument goes directly to the template output rather than
! 180: * being concatenated to the return value of the function.
! 181: *
! 182: * @flush()
! 183: * Flushes the template output.
! 184: *
! 185: * @foobar(...)
! 186: * If "foobar" is not defined as a run-time function, then this
! 187: * invokes the supplied handler for user-defined functions.
! 188: * Here "foobar" is any name other than the above function names,
! 189: * consisting of only letters, digits, and underscores.
! 190: *
! 191: */
! 192:
! 193: struct tmpl;
! 194: struct tmpl_ctx;
! 195:
! 196: #define TMPL_FUNCTION_CHARACTER '@'
! 197:
! 198: /***********************************************************************
! 199: CALLBACK FUNCTION TYPES
! 200: ***********************************************************************/
! 201:
! 202: /*
! 203: * Generic function handler type. Should return a malloc'd string (allocated
! 204: * with the same memory type as passed to tmpl_ctx_create()), or else return
! 205: * NULL and either set errno or set *errmsgp to point to a malloc'd string
! 206: * (same memory type) containing an error message. *errmsgp will be NULL
! 207: * initially.
! 208: *
! 209: * The first argument is the function name. Subsequent arguments are the
! 210: * (evaluated) arguments passed to the function. Note that this means "argc"
! 211: * is always >= 1. argv[argc] is NOT guaranteed to be NULL.
! 212: */
! 213: typedef char *tmpl_handler_t(struct tmpl_ctx *ctx, char **errmsgp,
! 214: int argc, char **argv);
! 215:
! 216: /*
! 217: * Error formatter type. This should format the error message string
! 218: * using whatever formatting is desired and return the result in a
! 219: * malloc'd buffer (note: just returning 'errmsg' is wrong; use
! 220: * strdup(3) instead). Return NULL and set errno if there is an error.
! 221: * The "arg" parameter is the same "arg" passed to tmpl_ctx_create().
! 222: */
! 223: typedef char *tmpl_errfmtr_t(struct tmpl_ctx *ctx, const char *errmsg);
! 224:
! 225: /***********************************************************************
! 226: PUBLIC FUNCTIONS
! 227: ***********************************************************************/
! 228:
! 229: __BEGIN_DECLS
! 230:
! 231: /*
! 232: * Create template object by parsing "input". The input stream must
! 233: * be seekable, and is not used again after this function returns.
! 234: *
! 235: * If num_errors != NULL, it will be set to the number of parse
! 236: * errors encountered while parsing the input.
! 237: *
! 238: * Returns NULL and sets errno on failure.
! 239: */
! 240: extern struct tmpl *tmpl_create(FILE *input,
! 241: int *num_errors, const char *mtype);
! 242:
! 243: /*
! 244: * Similar to tmpl_create(), but memory map the file so that its
! 245: * contents don't have to be stored in heap memory. However, the
! 246: * file contents must not change or else subsequent executions will
! 247: * give garbled output.
! 248: */
! 249: extern struct tmpl *tmpl_create_mmap(const char *path,
! 250: int *num_errors, const char *mtype);
! 251:
! 252: /*
! 253: * Destroy and free a template file created by tmpl_create().
! 254: *
! 255: * Upon return, *tmplp is set to NULL. If *tmplp is already NULL,
! 256: * this does nothing.
! 257: */
! 258: extern void tmpl_destroy(struct tmpl **tmplp);
! 259:
! 260: /*
! 261: * Create a template execution context.
! 262: *
! 263: * For all functions that are not predefined, the function is looked up
! 264: * in the 'userfuncs' array (which is not copied and so must remain
! 265: * valid for the life of the exectution context). This array must be
! 266: * sorted by name and terminated with an entry having a NULL name.
! 267: * All userfuncs will have 'arg' passed as their first argument.
! 268: *
! 269: * All strings returned by "handler" MUST be dynamically allocated
! 270: * using memory type 'mtype'.
! 271: *
! 272: * The 'errfmtr' is called to specially format any generated error
! 273: * messages; if it is NULL, error messages are output as plain text.
! 274: */
! 275: extern struct tmpl_ctx *tmpl_ctx_create(void *arg, const char *mtype,
! 276: tmpl_handler_t *handler, tmpl_errfmtr_t *errfmtr);
! 277:
! 278: /*
! 279: * Get context argument.
! 280: */
! 281: extern void *tmpl_ctx_get_arg(struct tmpl_ctx *ctx);
! 282:
! 283: /*
! 284: * Get context memory type.
! 285: */
! 286: extern const char *tmpl_ctx_get_mtype(struct tmpl_ctx *ctx);
! 287:
! 288: /*
! 289: * Execute a template and output the result to 'output'.
! 290: *
! 291: * If a system error is encountered, execution halts and -1
! 292: * is returned with 'errno' set. Otherwise, zero is returned.
! 293: *
! 294: * Flags:
! 295: *
! 296: * TMPL_SKIP_NL_WHITE Skip inter-function text consisting only of
! 297: * one or more newlines followed by whitespace.
! 298: */
! 299: extern int tmpl_execute(struct tmpl *tmpl, struct tmpl_ctx *ctx,
! 300: FILE *output, int flags);
! 301:
! 302: #define TMPL_SKIP_NL_WHITE 0x0001
! 303:
! 304: /*
! 305: * Destroy and free a template context created by tmpl_ctx_create().
! 306: *
! 307: * Upon return, *ctxp is set to NULL. If *ctxp is already NULL,
! 308: * this does nothing.
! 309: */
! 310: extern void tmpl_ctx_destroy(struct tmpl_ctx **ctxp);
! 311:
! 312: /*
! 313: * Functions to get and set variables associated with a context.
! 314: */
! 315: extern const char *tmpl_ctx_get_var(struct tmpl_ctx *ctx, const char *name);
! 316: extern int tmpl_ctx_set_var(struct tmpl_ctx *ctx,
! 317: const char *name, const char *value);
! 318:
! 319: /*
! 320: * Invoke a template function and write the output to "output".
! 321: *
! 322: * Returns zero if successful, otherwise returns -1 and either
! 323: * sets *errmsgp to NULL and errno to the error code, or else
! 324: * sets *errmsgp to some appropriate error message.
! 325: */
! 326: extern int tmpl_execute_func(struct tmpl_ctx *ctx, FILE *output,
! 327: char **errmsgp, int argc, char **argv,
! 328: int flags);
! 329:
! 330: /*
! 331: * Reset a template context.
! 332: *
! 333: * This undoes the result of any variable assignments and run-time
! 334: * function definitions from a previous execution using the context.
! 335: * That is, the context is returned to original state as returned by
! 336: * tmpl_ctx_create().
! 337: */
! 338: extern void tmpl_ctx_reset(struct tmpl_ctx *ctx);
! 339:
! 340: /*
! 341: * Built-in handler for handling a fixed list of user functions.
! 342: *
! 343: * The 'userfuncs' array must be sorted lexicographically by name.
! 344: */
! 345:
! 346: /* Structure describing a user-supplied function */
! 347: struct tmpl_func {
! 348: const char *name; /* function name, null to end list */
! 349: u_int min_args; /* min # args (not counting name) */
! 350: u_int max_args; /* max # args (not counting name) */
! 351: tmpl_handler_t *handler; /* handler for function */
! 352: };
! 353:
! 354: extern char *tmpl_list_handler(struct tmpl_ctx *ctx,
! 355: const struct tmpl_func *userfuncs, u_int uflen,
! 356: char **errmsgp, int argc, char **argv);
! 357:
! 358: __END_DECLS
! 359:
! 360: #endif /* _PDEL_TMPL_TMPL_H_ */
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/icons/cvsweb/back.gif){kind=icon}
Return to tmpl.h CVS log ![[TXT]](/icons/cvsweb/text.gif){kind=icon}
![[DIR]](/icons/cvsweb/dir.gif){kind=icon}
Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / libpdel / tmpl