#ifndef __SITECING_UTIL_H
#define __SITECING_UTIL_H

#include <ostream>
#include <string>
#include "sitecing/acomponent.h"

/**
 * @file
 * @brief more or less non-internal utility classes and functions.
 */

namespace sitecing {
    using namespace std;

    /**
     * the html_escape options enumeration.
     */
    enum html_escape_options {
	/**
	 * Turn spaces into &nbsp;
	 */
	html_escape_nbsp       = 0x0001,
	/**
	 * Turn newlines into <br/> or <br>.
	 */
	html_escape_br         = 0x0002,
	/**
	 * Turn quotes to &quot;
	 */
	html_escape_quot       = 0x0004,
	/**
	 * Do not put '/' into <br/> consruct.
	 */
	html_escape_br_noslash = 0x0008
    };
    /**
     * Escape string suitable for html output.
     * @param str the string.
     * @param flags options.
     * @return the string escaped.
     * @see html_escape_options
     */
    string html_escape(const string& str,int flags=html_escape_br);

    /**
     * The output string checkpoint object, letting one to rollback output.
     */
    class checkpoint {
	public:
	    /**
	     * The object's death will enumeration.
	     */
	    enum will_t {
		/**
		 * The stream is to be rolled back at object destruction.
		 */
		will_rollback,
		/**
		 * The stream is not to be rolled back at object destruction.
		 */
		will_commit,
		/**
		 * The object will die intestate. What's the point then?
		 */
		will_intestate
	    };
	    /**
	     * The output stream in question.
	     */
	    ostream* stream;
	    /**
	     * The point at which objhect was created.
	     */
	    ostream::pos_type point;
	    /**
	     * The last will.
	     */
	    will_t last_will;

	    /**
	     * @param s reference to the stream.
	     * @param lw the last will.
	     */
	    checkpoint(ostream& s, will_t lw=will_rollback)
		: stream(&s), last_will(lw) { set(); }
	    /**
	     * @param s pointer to the stream.
	     * @param lw the last will.
	     */
	    checkpoint(ostream* s, will_t lw=will_rollback)
		: stream(s), last_will(lw) { set(); }
	    /**
	     * @param s reference to the sitecing interface where to get output
	     * stream from.
	     * @param lw the last will.
	     */
	    checkpoint(sitecing_interface& s, will_t lw=will_rollback)
		: stream(s.out), last_will(lw) { set(); }
	    /**
	     * @param s pointer to the sitecing interface where to get output
	     * stream from.
	     * @param lw the last will.
	     */
	    checkpoint(sitecing_interface* s, will_t lw=will_rollback)
		: stream(s->out), last_will(lw) { set(); }
	    /**
	     * @param c reference to the component from which the output stream
	     * is obtained.
	     * @param lw the last will.
	     */
	    checkpoint(acomponent& c, will_t lw=will_rollback)
		: stream(c.__SCIF->out), last_will(lw) { set(); }
	    /**
	     * @param c pointer to the component from which the output stream is
	     * obtained.
	     * @param lw the last will.
	     */
	    checkpoint(acomponent* c, will_t lw=will_rollback)
		: stream(c->__SCIF->out), last_will(lw) { set(); }
	    ~checkpoint() {
		if(last_will==will_rollback)
		    rollback();
	    }

	    /**
	     * Set the possible rolback point to the current position in stream.
	     */
	    void set();
	    /**
	     * Make or change will.
	     */
	    void make_will(will_t lw);
	    /**
	     * Rollback the output made so far. In case of rollback will
	     * change to intestate.
	     */
	    void rollback();
	    /**
	     * Commit output so far. In case of rollback will, change to
	     * intestate.
	     */
	    void commit();
    };

}

#endif /* __SITECING_UTIL_H */