/******************************************************************************
 * $LastChangedDate: 2011-04-23 21:07:07 -0400 (Sat, 23 Apr 2011) $
 * @file
 * @author  Jim E. Brooks  http://www.palomino3d.org
 * @brief   Template Method to read human-editable text conf file via C++ stream.
 *//*
 * LEGAL:   COPYRIGHT (C) 2007 JIM E. BROOKS
 *          THIS SOURCE CODE IS RELEASED UNDER THE TERMS
 *          OF THE GNU GENERAL PUBLIC LICENSE VERSION 2 (GPL 2).
 ******************************************************************************/

#ifndef BASE_CONF_TXT_HH
#define BASE_CONF_TXT_HH 1

#include <fstream>

namespace base {

string
GetConfTxtFilename( const string& programName );

////////////////////////////////////////////////////////////////////////////////
/// @brief Template Method to read human-editable text conf file via C++ stream.
///
/// --- MIGHT THROW AN EXCEPTION ---
///
/// A configuration file is similar to a UNIX /etc file.
/// ConfTxt::Read() is a Template Method that is responsble for:
/// - Opening and closing a file via a C++ stream.
/// - Getting the next field (word) and passing it as a C++ string
///   to ProcessField() of the client/derivative.
/// - Filtering away comments.
///   Comments are prefixed by '#' (UNIX /etc convention).
///
/// Read() allows the derivative of ProcessField(string& field, ifstream& conf)
/// to modify both passed args.
///
class ConfTxt
{
PREVENT_COPYING(ConfTxt)
public:
                    ConfTxt( void );
    virtual         ~ConfTxt();
    void            Read( const string& pathname );
    virtual void    ProcessField( string& field, std::ifstream& config ) = 0;

// (no data members)
};

} // namespace base

#endif // BASE_CONF_TXT_HH
