latest version v1.9 - last update 24 Nov 2005

lti::lispStreamHandler

lti::lispStreamHandler Class Reference
[Storable Interface]

The lispStreamHandler class offer an interface for the functor parameters and other classes to read() and write() them in a LISP-like format. More...

#include <ltiLispStreamHandler.h>

Inheritance diagram for lti::lispStreamHandler:

[legend]Collaboration diagram for lti::lispStreamHandler:

[legend]List of all members.


Public Member Functions
	lispStreamHandler ()
	lispStreamHandler (std::ostream &aStream)
	lispStreamHandler (std::istream &aStream)
	lispStreamHandler (const char *aStream)
	lispStreamHandler (const lispStreamHandler &other)
virtual	~lispStreamHandler ()
void	use (std::ostream &aStream)
void	use (std::istream &aStream)
void	clear ()
virtual const char *	getTypeName () const
lispStreamHandler &	copy (const lispStreamHandler &other)
lispStreamHandler &	operator= (const lispStreamHandler &other)
virtual ioHandler *	clone () const
virtual bool	writeBegin ()
virtual bool	writeEnd ()
virtual bool	readBegin ()
virtual bool	readEnd ()
virtual bool	writeSymbol (const std::string &data)
virtual bool	readSymbol (std::string &data)
virtual bool	trySymbol (const std::string &data)
virtual bool	writeComment (const std::string &data)
virtual bool	writeComment (const char *data)
virtual bool	tryBegin ()
virtual bool	tryEnd ()
virtual bool	writeSpaces (const int &s=1)
virtual bool	writeEOL ()
virtual bool	writeKeyValueSeparator ()
virtual bool	writeDataSeparator ()
virtual bool	readKeyValueSeparator ()
virtual bool	readDataSeparator ()
virtual bool	eof ()
virtual bool	restoreLevel ()
virtual void	appendContextStatus () const
write members
virtual bool	write (const std::string &data)
virtual bool	write (const char *data)
virtual bool	write (const double &data)
virtual bool	write (const float &data)
virtual bool	write (const int &data)
virtual bool	write (const unsigned int &data)
virtual bool	write (const char &data)
virtual bool	write (const byte &data)
virtual bool	write (const ubyte &data)
virtual bool	write (const bool &data)
virtual bool	write (const long &data)
virtual bool	write (const unsigned long &data)
virtual bool	write (const short &data)
virtual bool	write (const unsigned short &data)
read members
virtual bool	read (std::string &data)
virtual bool	read (double &data)
virtual bool	read (float &data)
virtual bool	read (int &data)
virtual bool	read (unsigned int &data)
virtual bool	read (char &data)
virtual bool	read (byte &data)
virtual bool	read (ubyte &data)
virtual bool	read (bool &data)
virtual bool	read (long &data)
virtual bool	read (unsigned long &data)
virtual bool	read (short &data)
virtual bool	read (unsigned short &data)
Protected Types
typedef std::map< std::string, std::string >	cacheType
enum	eTokenId { BeginToken, EndToken, SymbolToken, StringToken, ErrorToken }
Protected Member Functions
eTokenId	getNextToken (std::string &token, const bool justTry=false)
eTokenId	getNextTokenFromString (std::string &src, std::string::size_type &srcPos, std::string &token, const bool justTry=false)
void	getNextLine (std::string &newline)
bool	commentFilter ()
bool	isTokenDelimiter (const char &c)
bool	completeLevel (std::string &restOfLevel)
Protected Attributes
std::istream *	inStream
std::string	inString
std::string::size_type	inStringPos
std::ostream *	outStream
bool	supressSpaces
bool	tryEOL
std::list< stackElement >	stack
Static Protected Attributes
static const char	openChar
static const char	closeChar
static const char	separator
static const char	commentChar
static const char	stringChar
static const char	quoteChar
Classes
struct	stackElement
	type for each element of the stack More...

Detailed Description

The lispStreamHandler class offer an interface for the functor parameters and other classes to read() and write() them in a LISP-like format.

This is the LTI-lib standard ioHandler.

If the standard functions atof() and operator<< for numbers consider the locale settings (this occurs in MS-VC++ or newer glibc and gcc with Linux), then the read() and write() methods will also be localed. A typical problem with this "feature" is that if you have a file saved with "LANG=C", the decimal point is a point (e.g. 1.532), and when you try to read it in another locale (for example LANG=de_DE.ISO-8859-1), then all numbers with a decimal point won't be readed correctly, because the method will be expecting a decimal comma (e.g. 1,532).

See also the read and write methods for the basic types for more information

Warning:: The given streams must be "ASCII" streams. If they are created with the binary flag, some weird effects can be expected.

Example:

 // the lisp stream formatting object
 lti::lispStreamHandler lsh;

 // Write example:

 // open a stream in text mode
 std::ofstream out("testfile.bin");
 
 // tell the lisp stream handler to use the given stream
 lsh.use(out);

 lti::write(lsh,"anInteger",5);
 lti::write(lsh,"aString","hello world");

 out.close();
 
 // Read example

 // Open a stream in lisp mode
 std::ifstream in("testfile.bin");

 lsh.use(in);
 int i;
 lti::read(lsh,"anInteger",i);

 std::string str;
 lti::read(lsh,"aString",str);

 in.close();

Member Typedef Documentation

typedef std::map<std::string,std::string> lti::lispStreamHandler::cacheType [protected]

type for the cache of each level, where the value for each symbol is stored

Member Enumeration Documentation

enum lti::lispStreamHandler::eTokenId [protected]

Types of tokens.

Enumerator:

BeginToken Denotes begin of a level.

EndToken Denotes end of a level.

SymbolToken Some atomic token.

StringToken A string token.

ErrorToken Unrecognized token.

Constructor & Destructor Documentation

lti::lispStreamHandler::lispStreamHandler ( )

default constructor

lti::lispStreamHandler::lispStreamHandler ( std::ostream & aStream )

default constructor

Warning:
The given stream must be an "ASCII" stream. If it is created with the binary flag, some weird effects can be expected.

lti::lispStreamHandler::lispStreamHandler ( std::istream & aStream )

default constructor

Warning:
The given stream must be an "ASCII" stream. If it is created with the binary flag, some weird effects can be expected.

lti::lispStreamHandler::lispStreamHandler ( const char * aStream )

default constructor.
This constructor uses the given string as input, as if read from a stread.

Warning:
Note that the given string is NOT a filename, but a string containing the data "stream". This is useful especially for the JNI (java native interface). You can of course also use the std::ostringstream and std::istringstream with the other constructors or with the method use().

lti::lispStreamHandler::lispStreamHandler ( const lispStreamHandler & other )

copy constructor

virtual lti::lispStreamHandler::~lispStreamHandler ( ) [virtual]

destructor

Member Function Documentation

virtual void lti::lispStreamHandler::appendContextStatus ( ) const [virtual]

Overload of context status information.
This function should help the users to find errors in their files. It just inserts some contextual information into the status string to help localizing wrong data.
It is useful for streams that can be edited by hand, because the users will make errors!
Reimplemented from lti::ioHandler.

void lti::lispStreamHandler::clear ( )

This method resets all internal state variables (for input and output streams as well) in a way that the next operations behave as if this handler were used for the first time.
This allows the use of the same handler instance after reopening a stream. Alternativelly, you can just call the use(std::istream&) or use(std::ostream&) members to clear the input or output state variables only. If you use this method "within" a read/write process, the behaviour will be unpredictable.

virtual ioHandler* lti::lispStreamHandler::clone ( ) const [virtual]

returns a pointer to a clone of this functor.

Implements lti::ioHandler.

bool lti::lispStreamHandler::commentFilter ( ) [protected]

this filter eliminates all comments at the beginning of inString

bool lti::lispStreamHandler::completeLevel ( std::string & restOfLevel ) [protected]

complete actual level reads the data from the input string and input stream until the actual level has been readed.

lispStreamHandler& lti::lispStreamHandler::copy ( const lispStreamHandler & other )

copy data of "other" functor.

Parameters:

other the functor to be copied

Returns:
a reference to this functor object

virtual bool lti::lispStreamHandler::eof ( ) [virtual]

if the input stream is at the end of file return true, otherwise false if the stream hasn't been set yet, this function also returns true.

void lti::lispStreamHandler::getNextLine ( std::string & newline ) [protected]

get the next "garbageThreshold" characters from the given stream, and ensures that the last readed character is a delimiter

eTokenId lti::lispStreamHandler::getNextToken ( std::string & token,

const bool justTry = false

) [protected]

read next token from the input string or from the input stream

See also:
getNextTokenFromString.

eTokenId lti::lispStreamHandler::getNextTokenFromString ( std::string & src,

std::string::size_type & srcPos,

std::string & token,

const bool justTry = false

) [protected]

read next token from the given string this member get the next token into the given string
Following tokens are recognized:
beginToken := '('
endToken := ')'
symbolToken := {alpha | digit} | float
stringToken := quote {alpha | digit | other | escape quote} quote
ErrorToken
where
alpha = "A" | "B" | ... "Z" | "a" | "b" | ... "z"
digit = "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9" |
other = "!" | "," | "$" | "%" | "&" | "/" | "[" | "]" | "{" | "}" | "?" | "'" | "#" | "+" | "*" | "-" | "." | "," | ":" | ";"
quote = '"'
escape = '\'
float = ['+' | '-'] {digit} '.' {digit} [exponent]
exponent = eid ['+' | '-'] digit {digit}
eid = 'E' | 'e'
comments will be ignored! They begin with a ';' The ErrorToken is not a real token. This is the way to signalized that no other token could be readed! If justTry = true the source string will remain untouched

virtual const char* lti::lispStreamHandler::getTypeName ( ) const [virtual]

returns the name of this type ("lispStreamHandler")

Reimplemented from lti::ioHandler.

bool lti::lispStreamHandler::isTokenDelimiter ( const char & c ) [inline, protected]

returns true if the given char can indicate the end of a token

lispStreamHandler& lti::lispStreamHandler::operator= ( const lispStreamHandler & other )

copy data of "other" functor.

Parameters:

other the functor to be copied

Returns:
a reference to this functor object

virtual bool lti::lispStreamHandler::read ( unsigned short & data ) [virtual]

read an unsigned short

Warning:
Be aware of the locale you are using. The number must be read with the same locale used when it was written

Implements lti::ioHandler.

virtual bool lti::lispStreamHandler::read ( short & data ) [virtual]

read a short

Warning:
Be aware of the locale you are using. The number must be read with the same locale used when it was written

Implements lti::ioHandler.

virtual bool lti::lispStreamHandler::read ( unsigned long & data ) [virtual]

read an unsigned long

Warning:
Be aware of the locale you are using. The number must be read with the same locale used when it was written

Implements lti::ioHandler.

virtual bool lti::lispStreamHandler::read ( long & data ) [virtual]

read a long

Warning:
Be aware of the locale you are using. The number must be read with the same locale used when it was written

Implements lti::ioHandler.

virtual bool lti::lispStreamHandler::read ( bool & data ) [virtual]

read a boolan

Implements lti::ioHandler.

virtual bool lti::lispStreamHandler::read ( ubyte & data ) [virtual]

read an unsigned byte value

Warning:
Be aware of the locale you are using. The number must be read with the same locale used when it was written

Implements lti::ioHandler.

virtual bool lti::lispStreamHandler::read ( byte & data ) [virtual]

read a signed byte value

Warning:
Be aware of the locale you are using. The number must be read with the same locale used when it was written

Implements lti::ioHandler.

virtual bool lti::lispStreamHandler::read ( char & data ) [virtual]

Read a char value.
The char can be given in two ways:

a numerical representation in decimal code (e.g. 65 represents 'A').
a character representation enclosed in sigle quotes (e.g. 'A')

Warning:
Be aware of the locale you are using. The number must be read with the same locale used when it was written

Implements lti::ioHandler.

virtual bool lti::lispStreamHandler::read ( unsigned int & data ) [virtual]

read an unsigned int value

Warning:
Be aware of the locale you are using. The number must be read with the same locale used when it was written

Implements lti::ioHandler.

virtual bool lti::lispStreamHandler::read ( int & data ) [virtual]

read an integer value

Warning:
Be aware of the locale you are using. The number must be read with the same locale used when it was written

Implements lti::ioHandler.

virtual bool lti::lispStreamHandler::read ( float & data ) [virtual]

read a float value

Warning:
Be aware of the locale you are using. The number must be read with the same locale used when it was written

Implements lti::ioHandler.

virtual bool lti::lispStreamHandler::read ( double & data ) [virtual]

read a double value

Warning:
Be aware of the locale you are using. The number must be read with the same locale used when it was written

Implements lti::ioHandler.

virtual bool lti::lispStreamHandler::read ( std::string & data ) [virtual]

read a std::string
The string should be quoted (i.e. between '"' and '"'), expect if its a single word. The two-char sequences '\"' and '\' will be replaced by '"' and '\' respectivelly.
Implements lti::ioHandler.

virtual bool lti::lispStreamHandler::readBegin ( ) [virtual]

the begin token or tokens: here a "("

Reimplemented from lti::ioHandler.

virtual bool lti::lispStreamHandler::readDataSeparator ( ) [virtual]

write key/value separator A space is expected

Implements lti::ioHandler.

virtual bool lti::lispStreamHandler::readEnd ( ) [virtual]

the end token or tokens: here a ")"

Reimplemented from lti::ioHandler.

virtual bool lti::lispStreamHandler::readKeyValueSeparator ( ) [virtual]

write key/value separator A space is expected

Implements lti::ioHandler.

virtual bool lti::lispStreamHandler::readSymbol ( std::string & data ) [virtual]

read a symbol in the given std::string

Implements lti::ioHandler.

virtual bool lti::lispStreamHandler::restoreLevel ( ) [virtual]

restore all the information in the handler taken in the actual level.
If "complete" is true, the begin-token is also restored
Implements lti::ioHandler.

virtual bool lti::lispStreamHandler::tryBegin ( ) [virtual]

try to read the begin token from the handler.
If present, returns true and the token is removed from the handler, if not present returns false and leaves the handle as it was before calling this member... This is useful in trees or other complicated data structures.
Implements lti::ioHandler.

virtual bool lti::lispStreamHandler::tryEnd ( ) [virtual]

try to read the end token from the handler.
If present, returns true and the token is removed from the handler, if not present returns false and leaves the handle as it was before calling this member... This is usually used when reading lists of data, where the number of elements is unknown.
Implements lti::ioHandler.

virtual bool lti::lispStreamHandler::trySymbol ( const std::string & data ) [virtual]

try to read the given symbol from the handler.
If present, returns true and the token is removed from the handler, if not present returns false and leaves the stream as is...
Parameters:

data the symbol to be readed

Implements lti::ioHandler.

void lti::lispStreamHandler::use ( std::istream & aStream ) [virtual]

indicate the input stream to be used
Calling this method you will reinitialize the state of the parser (see also clear()).
Implements lti::ioHandler.

void lti::lispStreamHandler::use ( std::ostream & aStream ) [virtual]

indicate the output stream to be used
Calling this method you will reinitialize the state of the parser (see also clear()).
Implements lti::ioHandler.

virtual bool lti::lispStreamHandler::write ( const unsigned short & data ) [virtual]

write an unsigned short

Warning:
Be aware of the locale you are using. The number must be read with the same locale used when it was written

Implements lti::ioHandler.

virtual bool lti::lispStreamHandler::write ( const short & data ) [virtual]

write a short

Warning:
Be aware of the locale you are using. The number must be read with the same locale used when it was written

Implements lti::ioHandler.

virtual bool lti::lispStreamHandler::write ( const unsigned long & data ) [virtual]

write an unsigned long

Warning:
Be aware of the locale you are using. The number must be read with the same locale used when it was written

Implements lti::ioHandler.

virtual bool lti::lispStreamHandler::write ( const long & data ) [virtual]

write a long

Warning:
Be aware of the locale you are using. The number must be read with the same locale used when it was written

Implements lti::ioHandler.

virtual bool lti::lispStreamHandler::write ( const bool & data ) [virtual]

write a boolean

Implements lti::ioHandler.

virtual bool lti::lispStreamHandler::write ( const ubyte & data ) [virtual]

write a unsigned 8-bit value

Implements lti::ioHandler.

virtual bool lti::lispStreamHandler::write ( const byte & data ) [virtual]

write an 8-bit signed value

Implements lti::ioHandler.

virtual bool lti::lispStreamHandler::write ( const char & data ) [virtual]

write a char
The char is writen as numerical code if there is no standard ASCII representation. If there is an ASCII representation (i.e. its value is greater or equal 32 (' ') and smaller or equal 127 ('~'), then the ASCII character will be writen enclosed in single quotes.
Implements lti::ioHandler.

virtual bool lti::lispStreamHandler::write ( const unsigned int & data ) [virtual]

write an unsigned integer value

Warning:
Be aware of the locale you are using. The number must be read with the same locale used when it was written

Implements lti::ioHandler.

virtual bool lti::lispStreamHandler::write ( const int & data ) [virtual]

write an integer value

Warning:
Be aware of the locale you are using. The number must be read with the same locale used when it was written

Implements lti::ioHandler.

virtual bool lti::lispStreamHandler::write ( const float & data ) [virtual]

write a float value

Warning:
Be aware of the locale you are using. The number must be read with the same locale used when it was written

Implements lti::ioHandler.

virtual bool lti::lispStreamHandler::write ( const double & data ) [virtual]

write a double value.

Warning:
Be aware of the locale you are using. The number must be read with the same locale used when it was written

Implements lti::ioHandler.

virtual bool lti::lispStreamHandler::write ( const char * data ) [virtual]

write a character string.
This method will write just the string if it does not contain spaces. Otherwise the string will be enclosed by quotes.
Implements lti::ioHandler.

virtual bool lti::lispStreamHandler::write ( const std::string & data ) [virtual]

write a std::string.
This method will write just the string if it does not contain spaces. Otherwise the string will be enclosed by quotes.
Implements lti::ioHandler.

virtual bool lti::lispStreamHandler::writeBegin ( ) [virtual]

the begin token or tokens: here a "(".

Reimplemented from lti::ioHandler.

virtual bool lti::lispStreamHandler::writeComment ( const char * data ) [virtual]

write comment writes the input data without any preprocessing, just ensuring that the comment format is given

Implements lti::ioHandler.

virtual bool lti::lispStreamHandler::writeComment ( const std::string & data ) [virtual]

write comment writes the input data without any preprocessing, just ensuring that the comment format is given

Implements lti::ioHandler.

virtual bool lti::lispStreamHandler::writeDataSeparator ( ) [virtual]

write key/value separator.
In this case the data separator is a space
Implements lti::ioHandler.

virtual bool lti::lispStreamHandler::writeEnd ( ) [virtual]

the end token or tokens: here a ")".

Reimplemented from lti::ioHandler.

virtual bool lti::lispStreamHandler::writeEOL ( ) [virtual]

write end of line

Implements lti::ioHandler.

virtual bool lti::lispStreamHandler::writeKeyValueSeparator ( ) [virtual]

write key/value separator.
In this case the key/value separator is a space
Implements lti::ioHandler.

virtual bool lti::lispStreamHandler::writeSpaces ( const int & s = 1 ) [virtual]

write spaces (default value 1).
A space-token is a char with value 32.
Implements lti::ioHandler.

virtual bool lti::lispStreamHandler::writeSymbol ( const std::string & data ) [virtual]

write a std::string

Implements lti::ioHandler.

Member Data Documentation

const char lti::lispStreamHandler::closeChar [static, protected]

closing char.
Usually ")"

const char lti::lispStreamHandler::commentChar [static, protected]

comment char.
Usually ';'

std::istream* lti::lispStreamHandler::inStream [protected]

pointer to the input stream

std::string lti::lispStreamHandler::inString [protected]

the input stream will be cached into this string

std::string::size_type lti::lispStreamHandler::inStringPos [protected]

actual reading position in the input string

const char lti::lispStreamHandler::openChar [static, protected]

opening char.
Usually "("

std::ostream* lti::lispStreamHandler::outStream [protected]

pointer to the output stream

const char lti::lispStreamHandler::quoteChar [static, protected]

quote char.
Usually "'"

const char lti::lispStreamHandler::separator [static, protected]

separator char.
Usually a space

std::list<stackElement> lti::lispStreamHandler::stack [protected]

the data stack.
All readed symbols and their values are stored here temporarly to allow different sorting of the symbols in the stream

const char lti::lispStreamHandler::stringChar [static, protected]

string char.
Usually '"'

bool lti::lispStreamHandler::supressSpaces [protected]

flag to control spaces supression (for example, there is no need for spaces between parenthesis)

bool lti::lispStreamHandler::tryEOL [protected]

flag to indicate if an EOL is needed

The documentation for this class was generated from the following file:

ltiLispStreamHandler.h

Generated on Thu Nov 24 16:54:31 2005 for LTI-Lib by Doxygen 1.4.4

lti::lispStreamHandler Class Reference [Storable Interface]

Public Member Functions

Protected Types

Protected Member Functions

Protected Attributes

Static Protected Attributes