/**
 * HTML escaping and unescaping functions.
 *
 * @file	platon/html/escape.h
 * @author	Ondrej Jombik <nepto@platon.sk>
 * @author	Robert Csok <rcsok@gmx.de>
 * @version	\$Platon: libplaton/platon/html/escape.h,v 1.1 2003/04/21 23:47:39 nepto Exp $
 * @date	2001-2003
 */

#ifndef _PLATON_HTML_ESCAPE_H
#define _PLATON_HTML_ESCAPE_H

#ifndef PLATON_FUNC
# define PLATON_FUNC(_name) _name
#endif
#ifndef PLATON_FUNC_STR
# define PLATON_FUNC_STR(_name) #_name
#endif

#ifdef __cplusplus
extern "C" {
#endif

	/**
	 * HTML entities table structure. Real tables used for escaping and
	 * unescaping HTML entities must have {'\0', NULL} element at the end.
	 *
	 * @struct	html_escape_table <platon/html/escape.h>
	 * @author	Ondrej Jombik <nepto@platon.sk>
	 * @version	\$Platon: libplaton/platon/net/Connection.h,v 1.13 2002/12/07 15:36:32 rajo Exp $
	 * @date	2001-2003
	 */
	struct html_escape_table
	{
		char  code; /**< character code */
		char *html; /**< escape sequence */
	};

	/**
	 * HTML escape types enumeration
	 */
	enum html_escape_types
	{
		HTML_ESCAPE_SPACE         =  1, /**< space to "&nbsp;" */
		HTML_ESCAPE_SPECIAL_CHARS =  2, /**< special chars '<', '>' and '&' */
		HTML_ESCAPE_QUOTES        =  4, /**< special single and double quotes */
		HTML_ESCAPE_ISO8859_1     =  8, /**< iso-8859-1 codepage entities */
		HTML_ESCAPE_ISO8859_2     = 16, /**< iso-8859-2 codepage entities */
		HTML_ESCAPE_ISO8859_15    = 32, /**< iso-8859-15 codepage entities */
		HTML_ESCAPE_ALL           = 63, /**< escape all possible entities */

		/** predefined type for htmlspecialchars() */
		HTML_ESCAPE_HTMLSPECIALCHARS =
			HTML_ESCAPE_SPECIAL_CHARS | HTML_ESCAPE_QUOTES,
		/** predefined type for htmlentities() */
		HTML_ESCAPE_HTMLENTITIES =
			HTML_ESCAPE_SPECIAL_CHARS | HTML_ESCAPE_QUOTES | HTML_ESCAPE_ISO8859_1
	};

	/**
	 * Escapes string from normal text to HTML entities
	 *
	 * @param	str		string to escape
	 * @param	types	entity table codes used for escaping
	 *					(see html_escape_types enumeration)
	 * @return	allocated escaped string or NULL on memory allocation error
	 */
	char *PLATON_FUNC(html_escape)(const char *str, const int types);

	/**
	 * Unescapes string from HTML entities to normal text
	 *
	 * @param	html	string to unescape
	 * @param	types	entity table codes used for unescaping
	 *					(see html_escape_types enumeration)
	 * @return	allocated unescaped string or NULL on memory allocation error
	 */
	char *PLATON_FUNC(html_unescape)(const char *html, const int types);

	/**
	 * Converts special characters to HTML entities
	 *
	 * @param		__s		string to convert
	 * @return		allocated converted string
	 *				or NULL on memory allocation error
	 */
#define htmlspecialchars(__s) html_escape(__s, HTML_ESCAPE_HTMLSPECIALCHARS)

	/**
	 * Convert all applicable characters to HTML entities
	 *
	 * @param		__s		string to convert
	 * @return		allocated converted string
	 *				or NULL on memory allocation error
	 */
#define htmlentities(__s) html_escape(__s, HTML_ESCAPE_HTMLENTITIES)

#ifdef __cplusplus
}
#endif

#endif /* #ifndef _PLATON_HTML_ESCAPE_H */