Scanner Module Client Specifications

Purpose

The Scanner module allows a client to open source code file, read lines, and extract tokens ( directives, operation codes, operands and labels ) from a MIPS assembly language source file.

Client Data Model

GetLine(){public} is used to read a single line of text from a source file. It is passed a pointer to a source file. Maximum line length is defined as a constant. Getline() returns a pointer to the beginning of the line read from the source file. It uses the standard C function, fgets(), to accomplish its task.

GetToken(){public} may be called to extract tokens from a line of text. It accepts the address of a character pointer to a text string. It returns a pointer to a token. Tokens are delimited by ascii tab, space and newline and other special characters. GetToken() uses the standard C functions to accomplish its mission.

GetTokenline(){public} receives a pointer to a file and calls getLine() and getToken(). GetTokenLine() also takes the token fetched by getToken() and places it into the appropriate member in the structure "tokenList." A boolean variable is returned and is set to 'false' when the end of a file has been reached.

Error Handling Policy
The Scanner module does not halt execution of a program or prevent the creation of an executable file; however, the following errors / events are detected :

- source file pointer points to NULL.
- general file errors associated with the source file as detected by the C function, fgets().

In either of the above cases, lineptr is assigned to NULL and returned to the calling function.

Importing Information

Use of the Scanner module requires the following include header files:

    #include "header.h"
    #include <stdio.h>
    #include <string.h>
    #include <ctype.h>
#include <stdlib.h>

Public Data Types

lineptr
A pointer to character type used to point the beginning of an array. It is also used to keep track of where the token process left off after getToken() returns a token.

tokenptr
A pointer to a character type that points to the token returned by getToken().

fileptr
A pointer of type FILE that points to the assembly language source file.

        maxline
        An integer constant that sets the maximum number of characters allowed in a line of text.

tokenlist
        A pointer to a structure containing the tokens of the line.

Public Functions

int getLine(FILE * fileptr, char *lineptr)

GetLine() reads a line of text from the source file using the C function fgets(). GetLine() assigns lineptr to the next line of text or to NULL in the event of a file error or end of file.

Example: GetLine(fileptr, lineptr);

char *getToken( char **lineptr)

GetToken() extracts tokens from a text string as delimited by ascii space, tab and newline and other special characters. GetToken() returns a character pointer to a token or a NULL pointer (if no token was detected in the line). GetToken() requires that the client provide a character pointer to mark the beginning of the text string. GetToken() is passed the address of lineptr (double indirection). This pointer is also used to keep track of where the token process left off after it returns a token. This character pointer must have scope over the module that getToken() is called from. Typically, this is the same pointer used to store a line of text taken from the source file.

Example: tokenptr = getToken(&lineptr);

int getTokenLine(tokenStruct *tokenList, FILE *file_ptr)

GetTokenline() receives a pointer to a file and calls getLine() and getToken(). GetTokenLine() also takes the token fetched by getToken() and places it into the appropriate member in the structure "tokenList." A boolean variable is returned and is set to 'false' when the end of a file has been reached.

Example: getTokenLine (tokenlist, file_ptr);