/*********************************************************************
 * This file is part of the cpplibs suite.
 *
 * Copyright (C) 2001 Topi Mäenpää
 * All rights reserved.
 *
 * This program is free software. You can redistribute and/or modify
 * it under the terms of the free software licence found in the
 * accompanying file "COPYING". The licence terms must always be
 * redistributed with this source file. The above copyright notice
 * must be reproduced in all modified and unmodified copies of this
 * source file.
 *
 * $Revision: 1.6 $
 *********************************************************************/

#ifndef _PROPERTIES_H
#define _PROPERTIES_H

#include "Hashtable.h"
#include "io/IO.h"
#include <iostream>

namespace util
{
	/**
	 * Properties is a utility class for reading name-value pairs from a
	 * stream. It works by reading the stream line by line and storing
	 * the encountered values into itself (Hashtable). It works in two
	 * different modes: "relaxed" and "C". In both modes, the first
	 * token in every line must be a comment or a keyword. In relaxed
	 * mode, everything after the keyword on the same line of input is
	 * treated as the key value as such. The keyword may be separated by
	 * whitespace(s) or one of the characters '=', '-' and ':'. One-line
	 * shell-style comments are recognized. In relaxed mode, the
	 * following file would be perfectly valid:<p><pre>
	 *
	 * #This is a comment
	 * firstvalue = 1
	 * secondvalue : two #this commend WILL BE INCLUDED in the value
	 * thirdvalue three
	 * </pre><p>
	 *
	 * In C-mode, the keyword must be followed by an equality sign (=),
	 * and the sign must be followed by exactly one property value. If
	 * the property value contains spaces, it must be quoted with double
	 * quotes. Within quoted strings, all C escape sequences are
	 * recognized and replaced. In C-mode, comments are recognized also
	 * at end of lines. The property values must be separated by a
	 * semicolon (;). Endlines between properties are not necessary. In
	 * C-mode, previously declared property names can be later
	 * substituted to other values by using the standard shell syntax.
	 * An example:<p><pre>
	 *
	 * //This is a C-style property file
	 * firstvalue = 1; secondvalue = two; //ignored comment
	 * a_substitution = "${firstvalue}+1=2\n";
	 * variablename = "firstvalue";
	 * another_substitution= "${$variablename}+2=3";
	 * </pre>
	 **/
	class Properties : public Hashtable<std::string,std::string>
	{
	public:
		Properties(std::istream& in, bool relaxed=true) throw (io::IOException&);
	};
}

#endif