/// @file parser.hpp
/// The base parser class which defines a generic API for statistical parsers.
///
/// @author mouser
/// @date   2003.07.29
//---------------------------------------------------------------------------

/// @defgroup Parsers Parsers
///
/// The Base Parser class is responsible for dividing the input stream into
/// a series of numerical symbols, and for converting symbol numbers to
/// their symbol texts during decompression.  Parsers are commonly just
/// character-based, returning the ascii character for each symbol parsed,
/// and therefore require no training.  But some parsers can be more
/// sophisticated, scanning input streams and building a list of all words
/// or common words, etc.

//---------------------------------------------------------------------------
// forward declarations
class OctaneParser;
//---------------------------------------------------------------------------

//---------------------------------------------------------------------------
// recursive header protection
#ifndef Octane_ParserH
#define Octane_ParserH
//---------------------------------------------------------------------------

//---------------------------------------------------------------------------
// application includes
#include "../core/octaneclass.hpp"
// system includes
using namespace std;
//---------------------------------------------------------------------------



//---------------------------------------------------------------------------
/// The Base Parser class is responsible for dividing the input stream into
/// a series of numerical symbols, and for converting symbol numbers to
/// their symbol texts during decompression.  Parsers are commonly just
/// character-based, returning the ascii character for each symbol parsed,
/// and therefore require no training.  But some parsers can be more sophisticated,
/// scanning input streams and building a list of all words or common words, etc.
///
/// @ingroup Parsers
///
class OctaneParser : public OctaneClass
{
public:
	/// constructor
	OctaneParser() {;};
	/// destructor
	virtual ~OctaneParser() {;};
public:
	//---------------------------------------------------------------------------
	// OCTANE PUBLIC API - RTTI FUNCTIONS - these are supported by all derived classes
	virtual std::string GetName() {return "OctaneParser";}
	virtual std::string GetDescription() {return "Base Parser Class";}
	virtual std::string GetHelpInformation() { return ""; }
	//---------------------------------------------------------------------------
public:
	//---------------------------------------------------------------------------
	// PARSER PUBLIC API - PREPARATIONS FOR PARSING
	virtual bool ResetState() {return true;};
	/// Process (train on) an input stream to update/create a symbol set from it.
	/// @return true on success
	virtual bool CreateSymbolSetUsingStream(bitreader &from) {return true;};
	/// Prepare for parsing mode; must be called after a CreateSymbol call, and before parsing begins.
	/// @return true on success
	virtual bool PrepareForParsing() {return true;};
	/// are we ready to parse? i.e. has symbol set been built.
	virtual bool IsReadyToParse() {return true;};
	/// Let go of any buffered stream - this is an odd function that can be called be compressor if it wants to hand
	///  off the input stream to a new parser or otherwise access the input bitstream from after last symbol parsed.
	///  it is necessary because some parsers can read-ahead in input buffer, and so must rewind the bitstream.
	virtual bool RewindAnyBufferedInput(bitreader &from) {return true;};
	//---------------------------------------------------------------------------
public:
	//---------------------------------------------------------------------------
	// PARSER PUBLIC API - MAIN PARSING FUNCTIONS
	/// Synchronize state for a new stream - this will always be called before beginning a new parsing stream, and
	/// should be used to reset the parse into any initial predictable state.
	virtual void SynchronizeStateForNewStream() {;};
	/// Get a count of the number of symbols stored in the parser.
	virtual int GetSymbolCount()=0;
	/// Parse the next symbol from the input and return its #.
	/// @note The end of stream situation must to be handled specially:
	/// @note When a parser encounters the end of a stream, it *MUST* return a symbol signifying an end-of-stream symbol.
	/// @note This end of stream symbol must be a unique symbol from the symbol set.
	/// @return false *after* the end of stream symbol is returned on prior call.
	virtual bool ParseNextSymbolFromInput(bitreader &from,int &symbolnum)=0;
	/// Parse the next symbol from the input, and set symbolnum to the symbol id#,
	/// @return false *after* end of stream (i.e. first response at end of stream should be the end-of-stream symbol).
	virtual bool WriteSymbolText(bitwriter &to, int symbolnum,bool &isendofstreamsymbol)=0;
	/// Helper function to return the text string of a symbol number.
	/// @return a string with the text of the symbol
	/// @note this should be the empty string to signify end of stream symbol.
	virtual string LookupSymbolText(int symbolnum)=0;
	//---------------------------------------------------------------------------
protected:
	//---------------------------------------------------------------------------
	// PARSER INTERNAL - STATIC HELPER FUNCTIONS - some general purpose helper functions for derived classes
	/// Static helper function to decide whether c is a character found in words, or should be treated as a non-word character.
	/// used by some parsers to differentiate between word characters and separators.
	static bool IsNonWordCharacter(unsigned char c);
	//---------------------------------------------------------------------------
};
//---------------------------------------------------------------------------



//---------------------------------------------------------------------------
#endif
//---------------------------------------------------------------------------

