ArFileParser Class Reference

Class for parsing files more easily. More...

#include <ArFileParser.h>

Public Member Functions
bool	addHandler (const char *keyword, ArRetFunctor1< bool, ArArgumentBuilder *> *functor)
	Adds a functor to handle a keyword that wants an easily parsable string.
bool	addHandlerWithError (const char *keyword, ArRetFunctor3< bool, ArArgumentBuilder *, char *, size_t > *functor)
	Adds a functor to handle a keyword that wants an easily parsable string and returns error messages. More...
	ArFileParser (const char *baseDirectory="./", bool isPreCompressQuotes=false)
	Constructor. More...
void	cancelParsing ()
	If parseFile is currently in progress, then terminates it as soon as possible.
void	clearCommentDelimiters ()
	Clears the strings used to mark comments in the file to be parsed. More...
const char *	getBaseDirectory (void) const
	Gets the base directory.
bool	parseFile (const char *fileName, bool continueOnErrors=true, bool noFileNotFoundMessage=false, char *errorBuffer=NULL, size_t errorBufferLen=0)
	Opens, parses, and then closes the specified file. More...
bool	parseFile (FILE *file, char *buffer, int bufferLength, bool continueOnErrors=true, char *errorBuffer=NULL, size_t errorBufferLen=0)
	Parses an open file; the file is not closed by this method. More...
bool	parseLine (char *line, char *errorBuffer=NULL, size_t errorBufferLen=0)
	Function to parse a single line.
bool	remHandler (const char *keyword, bool logIfCannotFind=true)
	Removes a handler for a keyword.
bool	remHandler (ArRetFunctor1< bool, ArArgumentBuilder *> *functor)
	Removes any handlers with this functor.
bool	remHandler (ArRetFunctor3< bool, ArArgumentBuilder *, char *, size_t > *functor)
	Removes any handlers with this functor.
void	resetCounters (void)
	Function to reset counters.
void	setBaseDirectory (const char *baseDirectory)
	Sets the base directory.
void	setCommentDelimiters (const std::list< std::string > &delimiters)
	Sets the strings used to mark comments in the file to be parsed. More...
void	setMaxNumArguments (size_t maxNumArguments=512)
	Sets the maximum number of arguments in a line we can expect.
void	setPreParseFunctor (ArFunctor1< const char *> *functor)
void	setQuiet (bool isQuiet)
	Turn on this flag to reduce the number of verbose log messages.
	~ArFileParser (void)
	Destructor.

Protected Member Functions
bool	isInterrupted ()
	Returns true if cancelParsing() has been called during parseFile()

Protected Attributes
std::string	myBaseDir
std::list< std::string >	myCommentDelimiterList
ArMutex	myInterruptMutex
bool	myIsInterrupted
bool	myIsPreCompressQuotes
bool	myIsQuiet
int	myLineNumber
std::map< std::string, HandlerCBType *, ArStrCaseCmpOp >	myMap
size_t	myMaxNumArguments
ArFunctor1< const char * > *	myPreParseFunctor
HandlerCBType *	myRemainderHandler

Detailed Description

Class for parsing files more easily.

This class helps parse text files based on keywords followed by various values. To use it, add functors of different types of arguments with addHandler(), then call parseFile() to parse the file and invoke the various functors as items are read from the file. parseFile() returns true if there were no errors parsing and false if there were errors.

One side feature is that you can have ONE handler for the keyword NULL, and if there is a line read that isn't entirely comments or whitespace that handler will be given the line. There isn't an explicit set for them since then there'd be another set of 5 adds.

There should be some whitespace after keywords in the file, and any semicolon (;) or hash mark (#) will act as a comment with the rest of the line ignored. (Alternative comment delimeters may be set using setCommentDelimeters()). If no handler exists for the first word the line is passed to the handler above for NULL. You can't have any lines longer than 10000 characters or keywords longer than 512 characters (though I don't know why you'd have either). If you have more than 2048 words on a line you'll have problems as well.

Note

ArFileParser does not escape any special characters when writing or loading to/from a file. Therefore in general keywords, values, and comments must not contain characters which have special meaning in a config file, such as '#', ';', tab or newline.

Constructor & Destructor Documentation

ArFileParser()

ArFileParser::ArFileParser	(	const char *	baseDirectory = "./",
		bool	isPreCompressQuotes = false
	)

Constructor.

Parameters

baseDirectory

the char * name of the base directory; the file name is specified relative to this directory

isPreCompressQuotes

a bool set to true if the file parser should treat strings enclosed in double-quotes as a single argument (such strings must be surrounded by spaces). This is roughly equivalent to calling ArArgumentBuilder::compressQuoted(false) on the resulting builder, but is more efficient and handles embedded spaces better. The default value is false and preserves the original behavior where each argument is a space-separated alphanumeric string.

Member Function Documentation

addHandlerWithError()

bool ArFileParser::addHandlerWithError	(	const char *	keyword,
		ArRetFunctor3< bool, ArArgumentBuilder *, char *, size_t > *	functor
	)

Adds a functor to handle a keyword that wants an easily parsable string and returns error messages.

This function has a different name than addProcessFileCB just so that if you mean to get this function but have the wrong functor you'll get an error.

The rem's are the same though since that shouldn't matter.

clearCommentDelimiters()

void ArFileParser::clearCommentDelimiters

(

)

Clears the strings used to mark comments in the file to be parsed.

Call this method to indicate that the file type to be parsed does not contain comments.

parseFile() [1/2]

bool ArFileParser::parseFile	(	const char *	fileName,
		bool	continueOnErrors = true,
		bool	noFileNotFoundMessage = false,
		char *	errorBuffer = NULL,
		size_t	errorBufferLen = 0
	)

Opens, parses, and then closes the specified file.

Parameters

fileName	the file to open
continueOnErrors	whether to continue or immediately bail upon an error
noFileNotFoundMessage	whether or not to log if we find a file (we normally want to but for robot param files that'd be too annoying since we test for a lot of files)
errorBuffer	buffer to put errors into if not NULL. Only the first error is saved, and as soon as this function is called it immediately empties the errorBuffer
errorBufferLen	the length of errorBuffer

if( setvbuf( file, buf, _IOFBF, sizeof( buf ) ) != 0 ) printf( "Incorrect type or size of buffer for file\n" ); else printf( "'file' now has a buffer of 1024 bytes\n" );

parseFile() [2/2]

bool ArFileParser::parseFile	(	FILE *	file,
		char *	buffer,
		int	bufferLength,
		bool	continueOnErrors = true,
		char *	errorBuffer = NULL,
		size_t	errorBufferLen = 0
	)

Parses an open file; the file is not closed by this method.

Parameters

file	the open FILE* to be parsed; must not be NULL
buffer	a non-NULL char array in which to read the file
bufferLength	the number of chars in the buffer; must be greater than 0
continueOnErrors	a bool set to true if parsing should continue even after an error is detected
file	File pointer for a file to be parsed. The file must be open for reading (e.g. with ArUtil::fopen()) and this pointer must not be NULL.
buffer	a non-NULL char array in which to read the file
bufferLength	the number of chars in the buffer; must be greater than 0
continueOnErrors	a bool set to true if parsing should continue even after an error is detected
errorBuffer	buffer to put errors into if not NULL. Only the first error is saved, and as soon as this function is called it immediately empties the errorBuffer
errorBufferLen	the length of errorBuffer

setCommentDelimiters()

void ArFileParser::setCommentDelimiters

(

const std::list< std::string > &

delimiters

)

Sets the strings used to mark comments in the file to be parsed.

By default, the ";" and "#" strings are used to indicate comments.

Call this method to override the defaults.

Parameters

delimiters

each string represents a comment delimiter. The comment delimiter and any following characters in the current line will be stripped during parsing of the file

---

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

• ArFileParser.h
• ArFileParser.cpp