/* Copyright 2005 Garrett Rooney.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

#ifndef APR_TEMPLATE_H
#define APR_TEMPLATE_H

#include <apr.h>
#include <apr_hash.h>
#include <apr_tables.h>
#include <apr_buckets.h>

#define APR_TEMPLATE_MAJOR_VERSION 0
#define APR_TEMPLATE_MINOR_VERSION 0
#define APR_TEMPLATE_PATCH_VERSION 1

#ifdef __cplusplus
extern "C" {
#endif /* __cplusplus */

/* the types of variables that can appear in a template. */
typedef enum {
  APR_TEMPLATE_SCALAR, /* -> char * */
  APR_TEMPLATE_ARRAY,  /* -> apr_array_header_t of apr_template_variable_t's */
  APR_TEMPLATE_HASH    /* -> apr_hash_t of char * to variable */
} apr_template_variable_type_t;

/* a variable that can be accessed inside a template. */
typedef struct {
  apr_template_variable_type_t type;

  union {
    char *s;
    apr_array_header_t *a;
    apr_hash_t *h;
  } contents;
} apr_template_variable_t;

/* note:  the following helper functions are TOTALLY OPTIONAL, in fact there
 *        are situations (usually with the int and string versions) where you
 *        DON'T want to use them because they result in excess copying, but
 *        i find myself writing them over and over again, so here they are. */

/* helper function to turn an int into a template variable.  the
 * variable is allocated in POOL. */
apr_template_variable_t *
apr_template_make_int (int i, apr_pool_t *pool);

/* helper function to turn a string STR into a template variable. 
 * the variable is allocated in POOL. */
apr_template_variable_t *
apr_template_make_str (const char *str, apr_pool_t *pool);

/* helper function to create a template variable wrapped around an
 * empty array.  the array is initially sized to hold NITEMS and is
 * allocated in POOL. */
apr_template_variable_t *
apr_template_make_array (int nitems, apr_pool_t *pool);

/* helper function to create a template variable wrapped around an
 * empty hash.  the array is allocated in POOL. */
apr_template_variable_t *
apr_template_make_hash (apr_pool_t *pool);

/* a parsed template. */
typedef struct apr_template_t apr_template_t;

/* parse something that looks like this from IN:
 *
 * [% for x in array %]
 *   [% print x %]
 * [% end %]
 *
 * [% if boolean %]
 *   literal text turns into a print
 * [% else %]
 *   other literal text in the other case
 * [% end %]
 *
 * return a template in *TMPL, allocated in POOL.
 */
apr_status_t
apr_template_parse (apr_template_t **tmpl,
                    apr_bucket_brigade *in,
                    apr_pool_t *pool);

/* parse a template out of the file FNAME, returning it in *TMPL and
 * allocating it in POOL.
 */
apr_status_t
apr_template_parse_file (apr_template_t **tmpl,
                         const char *fname,
                         apr_pool_t *pool);

/* execute TMPL in the context of ENVIRONMENT sending output to OUT and
 * using POOL for temporary allocation.
 *
 * ENVIRONMENT is a hash mapping char *'s to apr_template_variable_t *'s.
 */
apr_status_t
apr_template_execute (apr_template_t *tmpl,
                      apr_hash_t *environment,
                      apr_bucket_brigade *out,
                      apr_pool_t *pool);

#ifdef __cplusplus
}
#endif /* __cplusplus */

#endif /* APR_TEMPLATE_H */