Class AbnfParser.

Inherits Garbage. Inherited by EmailParser, ImapParser, LinkParser, SieveParser and SmtpParser.

Provides simple functions to parse ABNF productions.

This class maintains a cursor for an input String and provides functions to examine or extract tokens, advancing the cursor as required. These generic functions may be used by subclasses (e.g. ImapParser) to parse more complex productions.

The functions usually return a token extracted from the input string at the cursor, and advance the cursor to point to the next token. If the input cannot be parsed, a function might return an invalid token (e.g. nextChar() returns 0 once the cursor has passed the end of the input) or signal an error (e.g. end() complains if any input is left over once we've finished parsing what we expected to). In the latter case, ok() is false and error() returns a suitable message (and the input cannot be parsed any further).

In typical usage, one would create a new AbnfParser object for a string, step through its contents with functions like nextChar(), step(), and require(), then call end() when the string has been completely parsed.

AbnfParser::AbnfParser( const String & s )

Constructs an AbnfParser for the String s.

bool AbnfParser::atEnd() const

Returns true if we have parsed the entire input string, and false otherwise.

String AbnfParser::digits( uint min, uint max )

Returns a string of between min and max digits at the cursor and advances the cursor past them. If fewer than min digits are available, it is an error().

void AbnfParser::end()

Asserts that the input has been completely parsed. It is considered an error() if any input text remains when this function is called.

String AbnfParser::error() const

Returns a message describing the first parse error encountered, or an empty string if no errors have occurred (in which case ok() is also true).

const String AbnfParser::following() const

Returns a string of no more than 15 characters containing the first unparsed bits of input. Meant for use in error messages.

String AbnfParser::input() const

Returns the input string.

String AbnfParser::letters( uint min, uint max )

Returns a string of between min and max letters ([A-Za-z]) at the cursor and advances the cursor past them. If fewer than min letters are available, it is an error().

uint AbnfParser::mark()

Saves the current cursor position and error state of the parser and returns an identifier of the current mark. The companion function restore() restores the last or a specified mark. The returned mark is never 0.

char AbnfParser::nextChar() const

Returns the next character at the cursor without changing the cursor position. Returns 0 if there isn't a character available (e.g. when the cursor is past the end of the input string).

uint AbnfParser::number()

Returns the unsigned integer (0*|[1-9][0-9]*) at the cursor and advances the cursor past it. It is an error() if there isn't an integer at the cursor, or if a non-zero number is specified with a leading 0 digit.

bool AbnfParser::ok() const

Returns false once this object has encountered an error during parsing (in which case error() will return a suitable message), or true if it's still usable.

uint AbnfParser::pos() const

Returns the current (0-indexed) position of the cursor in the input() string without changing anything.

bool AbnfParser::present( const String & s )

Checks whether the next characters in the input match s. If so, present() steps past the matching characters and returns true. If not, it returns false without advancing the cursor. The match is case insensitive.

void AbnfParser::require( const String & s )

Requires that the next characters in the input match s (case insensitively), and steps past the matching characters. If s is not present(), it is considered an error().

void AbnfParser::restore( uint m )

Restores the cursor position and error state at the time when mark() returned m. Does nothing if m is not a valid mark.

void AbnfParser::restore()

Restores the last mark()ed cursor position and error state of this parser object.

void AbnfParser::setError( const String & s )

Sets the object's error() to s, provided this is the first time setError() is called with a nonempty argument. (error() returns the argument to the first setError() call.)

ok() will return false after this function has been called with a non-empty argument. This function is intended for use by the individual parser functions.

void AbnfParser::step( uint n )

Advances the cursor past n characters (1 by default) of the input.

AbnfParser::~AbnfParser()

Virtual destructor for the benefit of subclasses.