/* Copyright 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_resolver.h
 * @brief Functions for manipulating resolvers for use in including files
 */

#ifndef ETL_RESOLVER_H
#define ETL_RESOLVER_H

#include "etl_error.h"
#include "etl_stream.h"
#include "etl_array.h"

/** A resolver object. */
typedef struct etl_resolver_t etl_resolver_t;

/**
 * Use @a resolver to find a "file" named @a fname and return its
 * contents in @a *stream.
 */
etl_error_t *
etl_resolver_resolve(etl_stream_t **stream,
                     etl_resolver_t *resolver,
                     const char *fname);

/** Destroy @a resolver. */
void etl_resolver_destroy(etl_resolver_t *resolver);

/**
 * Create a resolver that searches through @a search_paths (which is an
 * array of <tt>char *</tt> paths) to find files.
 */
etl_resolver_t *etl_resolver_file_create(etl_array_t *search_paths);

/**
 * If you want to build your own resolver, you just take a function
 * with this prototype, and pass it to @c etl_resolver_create, along
 * with a baton pointer that'll get passed to your callback when 
 * @c etl_resolver_resolve is called on your resolver.
 */
typedef etl_error_t * (*etl_resolver_resolve_func_t)(etl_stream_t **stream,
                                                     void *baton,
                                                     const char *fname);

/** A callback that destroys the @a baton from a resolver. */
typedef void (*etl_resolver_destroy_func_t)(void *baton);

/**
 * Return a resolver that uses @a resolve_func, @a destroy_func, and
 * @a resolve_baton.
 */
etl_resolver_t *
etl_resolver_create(etl_resolver_resolve_func_t resolve_func,
                    etl_resolver_destroy_func_t destroy_func,
                    void *resolve_baton);

#endif /* ETL_RESOLVER_H */