/* Copyright 2005-2006 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.
 */

/**
 * @file etl_variables.h
 * @brief Functions and data structures for working with ETL variables
 */

#ifndef ETL_VARIABLES_H
#define ETL_VARIABLES_H

#include <stdint.h>

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

/** The types of variables that can appear in a template. */
typedef enum {
  ETL_VARIABLE_STRING,  /**< A string */
  ETL_VARIABLE_INTEGER, /**< A 64 bit integer */
  ETL_VARIABLE_ARRAY,   /**< An array of variables */
  ETL_VARIABLE_HASH     /**< A mapping of strings to variables */
} etl_variable_type_t;

/** A variable that can be accessed inside a template. */
typedef struct etl_variable_t etl_variable_t;

/** Get the type of @a var. */
etl_variable_type_t etl_variable_type(const etl_variable_t *var);

/**
 * Get the underlying character data for @a var.
 *
 * @note @a var must be of type @c ETL_VARIABLE_STRING.
 */
const char *
etl_variable_content_str(const etl_variable_t *var);

/**
 * Get the underlying integer data for @a var.
 *
 * @note @a var must be of type @c ETL_VARIABLE_INTEGER.
 */
uint64_t
etl_variable_content_int(const etl_variable_t *var);

/**
 * Get the number of elements in array @a var.
 *
 * @note @a var must be of type @c ETL_VARIABLE_ARRAY.
 */
uint32_t
etl_variable_array_nelts(const etl_variable_t *var);

/**
 * Get the element at position @a elt in array @a arr, or @c NULL if
 * @a elt is larger than @a arr's maximum element.
 *
 * @note @a arr must be of type @c ETL_VARIABLE_ARRAY.
 */
const etl_variable_t *
etl_variable_array_idx(const etl_variable_t *arr, uint32_t elt);

/**
 * Get the element at key @a key in @a hash, or @c NULL if there is
 * none.
 *
 * @note @a hash must be of type @c ETL_VARIABLE_HASH.
 */
const etl_variable_t *
etl_variable_hash_get(const etl_variable_t *hash, const char *key);

/** Return an @c etl_variable_t that is True. */
const etl_variable_t *etl_variable_true();

/** Return an @c etl_variable_t that is False. */
const etl_variable_t *etl_variable_false();

/**
 * Helper function to turn an @c int64_t into a template variable.
 */
etl_variable_t *
etl_variable_make_int(int64_t i);

/**
 * Helper function to turn a string @a str into a template variable.
 */
etl_variable_t *
etl_variable_make_str(const char *str);

/**
 * Helper function to create a template variable wrapped around an
 * empty array.  The array is initially sized to hold @a nitems.
 */
etl_variable_t *
etl_variable_make_array(uint32_t nitems);

/**
 * Helper function to create a template variable wrapped around an
 * empty hash.
 */
etl_variable_t *
etl_variable_make_hash();

/** Destroy @a var and anything it contains.  */
void etl_variable_destroy(etl_variable_t *var);

/**
 * Traverse over the contents of @a hash, calling @a callback and passing
 * it @a baton for each key value pair @a hash contains.
 *
 * @a note @a hash must be of type @c ETL_VARIABLE_HASH.
 */
void etl_variable_hash_traverse(const etl_variable_t *hash,
                                void (*callback)(const char *key,
                                                 etl_variable_t *val,
                                                 void *baton),
                                void *baton);

/**
 * Set the value of @a var to @a str.
 *
 * @note @a var must be of type @c ETL_VARIABLE_STRING.
 */
void etl_variable_str__set(etl_variable_t *var, const char *str);

/**
 * Set the value of @a var to @a val.
 *
 * @note @a var must be of type @c ETL_VARIABLE_INTEGER.
 */
void etl_variable_int__set(etl_variable_t *var, int64_t val);

/**
 * Set the entry for @a key in @a hash to @a val.
 *
 * @note @a var must be of type @c ETL_VARIABLE_HASH.
 *
 * @note @a hash will take ownership of @a val, and thus will destroy
 *       it when @a hash is destroyed.
 */
void etl_variable_hash_set(etl_variable_t *hash,
                           const char *key,
                           etl_variable_t *val);

/**
 * Push @a item onto @a array.
 *
 * @note @a var must be of type @c ETL_VARIABLE_ARRAY.
 *
 * @note that @a array will take ownership of @a item, and thus will
 *       destroy it when @a array is destroyed.
 */
void etl_variable_array_push(etl_variable_t *array, etl_variable_t *item);

#ifdef __cplusplus
}
#endif /* __cplusplus */

#endif /* ETL_VARIABLES_H */