/*-
 * Copyright (c) 1999, 2000, 2001, 2002, 2003 Lev Walkin <vlm@lionet.info>.
 * All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions
 * are met:
 * 1. Redistributions of source code must retain the above copyright
 *    notice, this list of conditions and the following disclaimer.
 * 2. Redistributions in binary form must reproduce the above copyright
 *    notice, this list of conditions and the following disclaimer in the
 *    documentation and/or other materials provided with the distribution.
 *
 * THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
 * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
 * ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
 * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
 * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
 * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
 * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
 * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 * SUCH DAMAGE.
 *
 * $Id: sf_fmt.h,v 1.2 2005/05/25 21:55:10 vlm Exp $
 */

#ifndef __SF_FMT_H__
#define __SF_FMT_H__

#include <sys/types.h>

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

/*********************************/
/*** Text formatting functions ***/
/*********************************/

typedef struct fmt_base_internal	fmt_base;

fmt_base *format_init(void);	/* Init base format structure */
void      format_free(fmt_base *base);	/* Destroy it */

/*
 * Add a rule how to handle ${X}, where '{' and '}' must be defined herein,
 * and X will be passed as 'found' directly into char **function(char *found);
 */
int	  format_metarule(fmt_base *base,
	char startwith, char endwith,	/* Characters, like '{' and '}' */
	char **(*function)(char *found, void *optKeyPassed));

/*
 * Do the necessary formatting an return the result stored in internal buffer
 * that is not to be freed.
 */
char *formatf(fmt_base *base, char *text_template, void *optKeyToPass);

char *format_lastresult(fmt_base *, size_t *optSize);
size_t format_lastsize(fmt_base *);
char *format_detach(fmt_base *, size_t *optSize);

/*
 * Overview of format usage (`man formatf` for more).
 * Say, we have invoked
 *
 * 	format_metarule( base=format_init(), '{', '}', ffunc);
 *
 * Then, we will be able to build format strings like in the following examples:
 *
 * EXAMPLE 1. The simple cases.
 *
 * 	formatf(base, "something", ...) will return "something".
 *
 * 	formatf(base, "some ${attr}", ...) will return "some value",
 *		where 'value' is the value returned by ffunc("attr").
 *
 * 	formatf(base, "some ${attr} and ${a2}", ...) will return
 *		"some value and value2", where 'value' and 'value2' are the
 *		values returned by ffunc("attr") and ffunc("a2") respectively.
 *
 * EXAMPLE 2. Joining values.
 *
 * Let's get ffunc("here", ...) returning an array { "v1", "v2", NULL }, then
 * 
 * 	formatf(base, "List is ${here}", ...) will return "List is v1, v2".
 *
 * Please point out that 'v2' and 'v2' are separated by ', ', this is the
 * default separator. To change separator please use a plus ('+') sign like
 * below:
 * 
 * 	formatf(base, "List is ${here+|}", ...) will return "List is v1|v2".
 * 	formatf(base, "${here+,&nbsp;}", ...) will return "v1,&nbsp;v2".
 *
 * EXAMPLE 3. Selecting values.
 *
 * Again, imagine that ffunc("here") returns an array { "v1", "2v", NULL }, then
 *
 *  formatf(base, "Value 0 is ${here[0]}", ...) will return "Value 0 is v1" and
 *  formatf(base, "Value 0 is ${here[1]}", ...) will return "Value 0 is 2v".
 *
 * EXAMPLE 4. The switching case.
 *
 *  formatf(base, "${a?b:c}", ...) will return "b" if ffunc("a", ...) returns
 *  with non-empty list, or "c" if ffunc("a", ...) returns NULL or empty list.
 *
 *   formatf(base, "${a?${b}:${c}}", ...) will return "v1", which is an output
 *   of ffunc("b"), if ffunc("a", ...) returns with non-empty list, or "v2",
 *   which is an output of ffunc("c", ...), if ffunc("a", ...) returns NULL.
 *
 * As you see, those cases are fully recursive.
 *
 * EXAMPLE 5. The switching case with [in]equality test.
 *
 *  formatf(base, "${a==5?b:c}", ...) will return "b" if ffunc("a", ...)
 *  returns with a non-empty list containing "5" in one of its values.
 *  Otherwise, it will return "c".
 *
 * EXAMPLE 6. The real usage.
 *
 * Please guess the behaviour of the following function:
 *
 *	formatf(base, "${param?Value is ${param}.:Parameter empty. Access 
 *	${left==0?restricted:granted with ${left} parrots left}.}", NULL)
 *
 */


#ifdef __cplusplus
}
#endif	/* __cplusplus */

#endif	/* __SF_FMT_H__ */