[an error occurred while processing this directive]

LineScanner Module Client Specifications

Purpose

A LineScanner provides functions for decomposing a line of text into tokens, evaluating the tokens, and handling errors.

Client Data Model

A LineScanner receives a line of text when it is created. It decomposes the line into tokens as descibed below. While in use, it maintain information about its current position, which is either at a token or at the end of the line. When created, the current position is at the first token of the line.

Tokens
A LineScanner views text as a sequence of tokens, which are strings of consecutive non-white characters, separated by one or more unquoted white characters. Tokens may have three types of values: string, float, or int. A token has an int value if it is a legal C or Java string representation of an integer. A token has a float value if it is a legal C or Java string representation of real number. Legal C or Java string representations of integers are also legal string representations of real numbers, so tokens with int values will also have float values.

A token may have subsequences of characters enclosed in double quotes. All tokens have a string value except when their text contains an unmatched double quote. White characters within quotes are not treated as token separators so that a token can have a string value which contains white characters. Within double quotes, C or Java escape sequences are recognized. The string value of a token with quoted substrings contains the standard C or Java translation for escape sequences. A token that has a quoted substring can not have a float or int value.

Empty lines and lines that begin with white characters are treated in a special way by a LineScanner. Such lines are regarded as having an initial empty string token.

Errors
When a client gets values of tokens, errors can occur due to requests for incorrect value types. A LineScanner has two ways of handling these errors. Some of the functions have preconditions. When a function precondition is violated, the program is terminated with an error message that indicates the nature of the error.

Other functions generate error messages that are saved by the LineScanner. The number of saved messages can be determined by calling errorCount(), and the messages can be printed with calls to printFirstError() or printAllErrors(). The client can also add error messages by calling addError() and remove error messages by calling removeLastError().

Creating and Configuring LineScanners
A LineScanner is created as the returned value of newLineScanner(). This function has parameters to specify the text to be scanned and the echo policy. The echo policy determines whether or not the text is echoed when errors occur. This module defines constants for two possible policies, LS_ECHO and LS_NO_ECHO.

A LineScanner can be attached permanently to a text source. For this kind of use, the source can reuse the LineScanner for new lines by calling setText() with the text of the new line as a parameter. If necessary, the source can change the echo policy by calling setEchoPolicy(). The functions getText() and getEchoPolicy() are provided for retieving the current text and echo policy.

Using a LineScanner
A LineScanner has two groups of functions for evaluating tokens sequentially. The first group consists of read functions readString, readFloat, readInt, and readEnd. The first three return the string, float, or int value of the current token and then advance the current position. The last just generates a saved error message if the current position is not the end of the line.

When using the first group of functions, error message are saved automatically when the text for the current token is incorrectly formatted.

The second group of functions has three subgroups of functions. Methods atString, atFloat, atInt, and atEnd check the type of the token at the current position. Methods currentString, currentFloat, and currentInt retrieve the string, float, or int value of the current token without advancing the current position. These functions have preconditions which, when violated, result in immediate program termination with an error message. Finally, the advance function advances the current position.

When using the second group of functions, the client is responsible for checking the token type with atString(), atFloat(), atInt(), or atEnd(), and adding error messages with addError.

Importing Information

Use of the LineScanner module requires the following include. 
#include "LineScanner.h"

Public Constants

Public Data Types

Public Functions

LineScanner creation and configuration
Token reading with automatic error reporting
Current token type checking
Current token access and advancing
Error control
Error reporting
[an error occurred while processing this directive]