/*

cls_2: Curl Like Syntax
Yauheni A. Akhotnikau (C) 2001-2003
eao197@yahoo.com
-------------------------------------------------

Permission is granted to anyone to use this software for any purpose on any
computer system, and to redistribute it freely, subject to the following
restrictions:

1. This software is distributed in the hope that it will be useful,
   but WITHOUT ANY WARRANTY; without even the implied warranty of
   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

2. The origin of this software must not be misrepresented, either by
   explicit claim or by omission.

3. Altered versions must be plainly marked as such, and must not be
   misrepresented as being the original software.

-------------------------------------------------

*/

/*!
	\file
	\brief Готовые функции разбора с использованием средств
	стандартного C++.
*/

#if !defined( _CLS_2__STD_CPP__UTILS_HPP_ )
#define _CLS_2__STD_CPP__UTILS_HPP_

#include <iostream>
#include <string>

#include <cls_2/h/cls.hpp>

namespace cls_2
{

namespace std_cpp
{

//! \name Опции функций parse_istream() и parse_file().
//! \{

//! В потоке ошибок должны отображаться имя файла и номер строки.
const unsigned int	es_uses_file_line = 0x1;

//! В потоке ошибок должен отображаться стек разбираемых тегов.
const unsigned int	es_uses_tag_stack = 0x2;

//! \}

//
// parse_istream
//

//! Разбор указанного входного потока.
/*!
	Осуществляет разбор указанного std::istream, используя
	указанные теги. При необходимости в указанный std::ostream
	будет помещаться описание ошибок.

	\return cls_2::c_ok, если разбор прошел успешно.
*/
int
parse_istream(
	//! Что будет разбираться.
	std::istream & in,
	//! Имя данного потока. Будет использоваться в качестве
	//! имени файла, если задана опция es_uses_file_line.
	const std::string & stream_name,
	//! Список тегов, которые должны участвовать в разборе.
	cls_2::tag_t ** tags,
	//! Количество элементов в tags.
	size_t tag_count,
	//! Необязательный поток ошибок.
	std::ostream * error_stream = 0,
	//! Опции разбора.
	unsigned int options =
		es_uses_file_line | es_uses_tag_stack );

//
// parse_file
//

//! Разбор указанного файла.
/*!
	Осуществляет разбор указанного файла, используя
	указанные теги. При необходимости в указанный std::ostream
	будет помещаться описание ошибок. Для чтения файла
	используется класс std::ifstream.

	\return cls_2::c_ok, если разбор прошел успешно.
*/
int
parse_file(
	//! Имя файла для разбора.
	const std::string & stream_name,
	//! Список тегов, которые должны участвовать в разборе.
	cls_2::tag_t ** tags,
	//! Количество элементов в tags.
	size_t tag_count,
	//! Необязательный поток ошибок.
	std::ostream * error_stream = 0,
	//! Опции разбора.
	unsigned int options =
		es_uses_file_line | es_uses_tag_stack );

//
// parse_file
//

//! Разбор указанного файла.
/*!
	\since v.2.6.2

	Осуществляет разбор указанного файла, используя
	указанный тег. Описание ошибки помещается в
	error_desc. Для чтения файла
	используется класс std::ifstream.

	Функция добавлена из-за того, что на практике очень часто
	требуется разбор конфигурационных файлов с оним тегом
	верхнего уровня и с обязательным сохранением описания
	ошибки.

	\return cls_2::c_ok, если разбор прошел успешно.
*/
int
parse_file(
	//! Имя файла для разбора.
	const std::string & stream_name,
	//! Единственный тег для разбора.
	cls_2::tag_t & tag,
	//! Приемник описания ошибки.
	std::string & error_stream,
	//! Опции разбора.
	unsigned int options =
		es_uses_file_line | es_uses_tag_stack );

} /* namespace std_cpp */

} /* namespace cls_2 */

#endif
