).
4.1.10 - GrabChar() - Top of Page
Prototype:
char GrabChar(void);
Description:
Grabs the next character (byte) in the file, regardless of the token
separators.
Inputs:
N/A
Output:
Next character (byte) from the file.
Notes:
This function can be used to read in binary big Endean files. Generally, you
would call GrabChar(), and then just shift the bits.
4.1.11 - GrabFloat() - Top of Page
Prototype:
float GrabFloat(void);
Description:
Grabs the next token in the file, and then attempts to convert it to a float
via the atof() function declared in stdlib.h. All token separators are
taken into account. Function callbacks & such will still be called.
Inputs:
N/A
Output:
Next token converted to a float.
Notes:
N/A
4.1.12 - GrabInt() - Top of Page
Prototype:
int GrabInt(void);
Description:
Grabs the next token in the file, and then attempts to convert it to an int
via the atoi() function declared in stdlib.h. All token separators are
taken into account. Function callbacks & such will still be called.
Inputs:
N/A
Output:
Next token converted to an int.
Notes:
N/A
4.1.13 - GrabToken() - Top of Page
Prototype:
char *GrabToken(void);
Description:
The main function of the Cero Parser. This function will scan the file for
any of the token separators you specified with AddTokenSeparator(), as well
as to apply the specified logic of the token separator.
Inputs:
N/A
Output:
0 - End of the file was reached, or an error occurred
1+ - Character pointer to the next token in the file.
Notes:
You are responsible for the cleanup. IE, calling free().
4.1.14 - LoadFile() - Top of Page
Prototype:
int LoadFile(char *file);
Description:
Loads in a new file into the parser for processing.
Inputs:
*file - C style string that contains the name/path of the file to parse.
Output:
1 - File was loaded and the parser was set up
0 - Error occurred. Most likely do to an incorrect file name.
Notes:
All positional data from the previous file will be lost when LoadFile is
called. You can call GetFilePosition() before hand to save the
state of the parser.
The token sets will not be affected by this function.
All files are read in as binary.
4.1.15 - LoadMemory() - Top of Page
Prototype:
int LoadMemory(char *memory);
Description:
Loads in the specified chunk of memory into the parser for parsing.
Currently, only C style strings are supported by this function.
Inputs:
*memory - Pointer to the chuck of memory to load into the parser.
Output:
0 - The specified memory is not valid or the parser was not initialized.
1 - The memory was loaded into the parser.
Notes:
The specified chuck of memory will be duplicated before being loaded into
parser. In other words, you are still responsible for the clean up of the
memory that *memory points to.
You can change the behavior of the above, but setting LOADMEM_DUP at the
top of Parser.c to 0. If LOADMEM_DUP is set to 0, the Parser will own the
memory that you pass in. Setting LOADMEM_DUP to 1 will cause the memory to
be duplicated.
4.1.16 - LoadMemoryLen() - Top of Page
Prototype:
int LoadMemoryLen(char *memory, int len);
Description:
Loads in the specified chunk of memory into the parser for parsing.
This is the same as LoadMemory(), however, you can load in binary memory
Inputs:
*memory - Pointer to the chuck of memory to load into the parser.
len - Size of the memory to load into the Parser
Output:
0 - The specified memory is not valid or the parser was not initialized.
1 - The memory was loaded into the parser.
Notes:
The specified chuck of memory will be duplicated before being loaded into
parser. In other words, you are still responsible for the clean up of the
memory that *memory points to.
You can change the behavior of the above, but setting LOADMEM_DUP at the
top of Parser.c to 0. If LOADMEM_DUP is set to 0, the Parser will own the
memory that you pass in. Setting LOADMEM_DUP to 1 will cause the memory to
be duplicated.
4.1.17 - ParserDeInit() - Top of Page
Prototype:
void ParserDeInit(void);
Description:
Frees all the memory that the parser was using.
Inputs:
N/A
Output:
N/A
Notes:
N/A
4.1.18 - ParserInit() - Top of Page
Prototype:
void ParserInit(char *file, int bufsize)'
Description:
Allocates and initializes all the memory that the parser needs to function.
Once everything has been allocated and initialized, the Parser will load
in the requested number of bytes from the file.
Inputs:
*file - Name/Path of the file to load into the parser. A NULL pointer can
be passed in if you do not wish to load in an initial file.
bufsize - How many bytes to read in from the file at one time. If a 0 is
passed in, bufsize will default to 1024 - 1 KB. This value
can not be changed once it is specified.
Output:
N/A
Notes:
If this function is called more then once, the parser will automatically
call ParserDeInit(), in order to prevent leaking memory.
4.1.19 - PeekToken() - Top of Page
Prototype:
char *PeekToken(void);
Description:
Same behavior as GrabToken(); although, the parser's position in the file
is not updated. Callback functions will still be called.
Inputs:
N/A
Output:
Pointer to the next token the in file.
Notes:
You are responsible for cleaning up the memory when you are done.
4.1.20 - PrintErrorCode() - Top of Page
Prototype:
void PrintErrorCode(void);
Description:
Prints out the current status of the parser to the command prompt.
Format:
<File Name>: <Error Message>
The file name will be the name of the parser file (Parser.c, by default).
The error message will be determined by the Error Code.
Inputs:
N/A
Output:
N/A
Notes:
N/A
4.1.21 - Seek() - Top of Page
Prototype:
int Seek(char *search);
Description:
Scans the file for the specified token. If the token is found, the position
of the parser will be updated to the character directly after the token.
If the token is not found, nothing in the parser will change.
Inputs:
*search - C style string to search for in the file.
Output:
0 - The token was not found. The parser was not updated.
1 - The token was found. The parser was updated.
Notes:
Token sets are not factored in.
4.1.22 - SetFilePosition() - Top of Page
Prototype:
int SetFilePosition(long fpos);
Description:
Changes the position in the file that the parser scans for the tokens.
Inputs:
fpos - Where the parser should start parsing the file.
Output:
0 - Error occurred. Call ErrorCode() or PrintErrorCode() for more info.
1 - Parser's position was updated.
Notes:
N/A
4.1.23 - SetTokenSet() - Top of Page
Prototype:
int SetTokenSet(int tokenset);
Description:
Changes the current token set.
Inputs:
tokenset - Index of the token set to change to.
Output:
-1 - The parser was not initialized or the requested token set was not valid.
0+ - Index of the token set switched to.
Notes:
N/A
4.1.24 - GetParserState() - Top of Page
Prototype:
char * GetParserState(void);
Description:
Returns a pointer to the current Parser state. This is useful to preserve
the Parser's current state.
Inputs:
N/A
Output:
Pointer to the current Parser state.
Notes:
N/A
4.1.25 - SetParserState() - Top of Page
Prototype:
void SetParserState(char *state);
Description:
Sets the Parser state to the specified Parser state.
Inputs:
*state - State the parser should use.
Output:
N/A
Notes:
Settings state to 0, followed by calling ParserInit() will create a new
Parser state.
4.1.26 - GenericDiscard() - Top of Page
Prototype:
int GenericDiscard()(void *unused);
Description:
Generic Parser callback designed to discard the next token.
Inputs:
N/A
Output:
0 - Don't return the token we are discarding.
Notes:
N/A
The following functions are only meant to be called from the functions
in the parser. Making these functions public, and calling them
externally will have undefined results.
4.2.01 - GrabLeftover() - Top of Page
Prototype:
char *GrabLeftover(void)
Description:
Returns any data that was left in the parser. This function is called once
the end of the file is reached, and no more tokens have been found.
Inputs:
N/A
Output:
0 - No data is left, or there was an error.
1+ - Pointer token to return.
Notes:
N/A
4.2.02 - GrabNextChunk() - Top of Page
Prototype:
void GrabNextChunk(void);
Description:
This function handles all file input. It will allocate the space for the
buffer, if required, and then read in the next chunk of the file.
Inputs:
N/A
Output:
N/A
Notes:
N/A
4.2.03 - ProcessToken() - Top of Page
Prototype:
char *ProcessToken(Separator_str *sep, int *spos);
Description:
When ever a token is found, the function is called to handle all logic
attached to the token.
Inputs:
*sep - Pointer to the token separator that was found
*spos - Temporary position where the parser is located in SP. This is a
pointer, in case the token needs to be ignored.
Output:
0 - Continue to search for another token sep.
1+ - Token to return.
Notes:
N/A
The following functions are not implemented in string.h
or operate on different principals.
4.3.01 - RemoveWhiteSpaces() - Top of Page
Prototype:
int RemoveWhiteSpaces(char *sp);
Description:
Removes all spaces, new lines, carriage returns, and tabs from the specified
string.
Inputs:
*sp - string pointer - string to remove the white spaces from.
Output:
-1 - sp was not valid
0+ - New length of the string. The pointer will not be reallocated, so the
original string pointer should be valid.
Notes:
N/A
4.3.02 - ToUpper() - Top of Page
Prototype:
void ToUpper(char *sp);
Description:
Converts a c style string to upper case.
Inputs:
*sp - pointer to the string to convert to upper case.
Output:
N/A
Notes:
N/A
4.3.03 - ToLower() - Top of Page
Prototype:
void ToLower(char *sp)
Description:
Converts a c style string to lower case.
Inputs:
*sp - pointer to the sting to convert to lower case.
Output:
N/A
Notes:
N/A
4.3.04 - Dup() - Top of Page
Prototype:
char *Dup(const char *sp);
Description:
Creates a copy of the specified string.
Inputs:
*sp - String to make a copy of.
Output:
Pointer to the new chunk of memory.
Notes:
N/A
4.3.05 - DupLen() - Top of Page
Prototype:
char *DupLen(const char *sp, int len);
Description:
Creates a copy of the specified string. The NULL terminator is automatically
attached. IE, you can just call strlen() for the param len.
Inputs:
*sp - String to make a copy of.
len - Length of the string/position of the null terminator.
Output:
Pointer to the new chunk of memory.
Notes:
N/A
4.3.06 - DupRange() - Top of Page
Prototype:
char *DupRange(const char *sp, int start, int end);
Description:
Creates a copy of a specific part of a string
Inputs:
*sp - String to make a partial copy of
start - Index in the string to start copying data from
end - Where to stop/last character to copy
Output:
Pointer to the duplicated chunk of the string.
Notes:
N/A
4.3.07 - DupRangeFile() - Top of Page
Prototype:
char *DupRangeFile(const char *file, int start, int end);
Description:
Opens up the specified file, and then reads in the data range to a buffer.
Inputs:
*file - Name/path of the file to read
start - Where in the file to start reading in the data
end - Where to stop reading in data
Output:
0 - The file name was not valid, or the memory couldn't be allocated.
1+ - Pointer to the new buffer containing the requested data.
Notes:
N/A
4.3.08 - Cmp() - Top of Page
Prototype:
char Cmp(const char *osp, const char *osp2);
Description:
Compares two strings together. Cmp() differ from strcmp() (string.h) in two
ways. First, Cmp() returns a 1 if the strings match, and a 0 if not. 2nd,
Cmp() has a non case sensitive and non white space sensitive mode. To
disable case/white space sensitivity, set CaseSensitive (towards the top
of Parser.c) to 1.
Inputs:
*osp - First string to compare
*osp2 - Second string to compare
Output:
0 - Strings don't match
1 - Strings match
Notes:
N/A
5.0 - Change Log - Top of Page
Parser v 8.0
Function callback is now passed a void *
- AddTokenSeparator() now takes a additonal paramater
Restricted GrabToken() from callback from Token with ignore == 1
This would cause a infinate recursion loop.
Fixed a possiable buffer overread
Token order is now preserved correctly
Various Optimizations
Bulk of String Manipulation Funtions now use const when possiable
Preformance Delta:
GNU: ~6% Faster
MS : No performance difference
Note: A few new warnings have been introduced, and need to be fixed
Parser v 7.1
Bug fix relateing to recursion caused by Parser callback function calling
GrabToken().
Added Get/SetParserState()
Added GenericDiscard() Parser callback, since it is
a fairly common function.
Parser v 7.0
Moved most of the documentation to this html file
A few bug/broke logic fixes
Parser v 6.0
Dropped C++ build
Added DeSmet C support - strict ANSI C
Several bug/broken logic fixes
Reduced requested frees and allocs by ~66%
Massive Code Cleanup
Removed a lot of redundant code
Improved internal error handler
Added function callbacks
Cleaned up documentation
Parser v 5.0
Began testing on Linux
Several bug/broken logic fixes
Massive performance boost to internal file handler (~60% faster!)
Parser v 4.0
Implemented binary support
Expanded interal File Handler
Load Files Dynamically
Load Memory Dynamically
Improved Internal Error Handler
Parser v 3.0
Implemented internal File Handler
Parser v 2.0
Added a C++ build
Added the bulk of the String Manipulation Functions
Parser v 1.0 - Original build with
Multiple Token Set Support
Token Separators with logic:
Return
switchto
ignore