/*
 * --------------------------------------------------------------------
 * CS2S03/SE2S03, November 2011
 * Assignment 5, Question 3
 * File: scanner.h
 * --------------------------------------------------------------------
 * This file is the interface for a class that facilitates dividing
 * a string into logical units called "tokens", which are either
 *
 * 1. Strings of consecutive letters and digits representing words
 * 2. One-character strings representing punctuation or separators
 *
 * To use this class, you must first create an instance of a
 * Scanner object by declaring
 *
 * Scanner scanner;
 *
 * You initialize the scanner's input stream by calling
 *
 * scanner.setInput(str);
 *
 * where str is the string from which tokens should be read.
 * Once you have done so, you can then retrieve the next token
 * by making the following call:
 *
 * token = scanner.nextToken();
 *
 * To determine whether any tokens remain to be read, you can call
 * the predicate method scanner.hasMoreTokens(). The nextToken
 * method returns the empty string after the last token is read.
 *
 * The following code fragment serves as an idiom for processing
 * each token in the string inputString:
 *
 * Scanner scanner;
 * scanner.setInput(inputString);
 * while (scanner.hasMoreTokens()) {
 * string token = scanner.nextToken();
 * . . . process the token . . .
 * }
 *
 * The Scanner class also supports the following advanced features,
 * which are documented later in the interface:
 *
 *   setSpaceOption
 * ---------------------- change -----------------
 *   setStringOption
 * -------------------- end of change ------------
 */

#ifndef _scanner_h
#define _scanner_h
#include "genlib.h"

/*
 * Class: Scanner
 * --------------------------------------------------------------------
 * This class is used to represent a single instance of a scanner.
 */

class Scanner {

public:

/*
 * Constructor: Scanner
 * Usage: Scanner scanner;
 * --------------------------------------------------------------------
 * The constructor initializes a new scanner object. The scanner
 * starts empty, with no input to scan.
 */

    Scanner();

/*
 * Destructor: ~Scanner
 * Usage: usually implicit
 * --------------------------------------------------------------------
 * The destructor deallocates any memory associated with this scanner.
 */

    ~Scanner();

/*
 * Method: setInput
 * Usage: scanner.setInput(str);
 * --------------------------------------------------------------------
 * This method configures this scanner to start extracting
 * tokens from the input string str. Any previous input string is
 * discarded.
 */

    void setInput(string str);

/*
 * Method: nextToken
 * Usage: token = scanner.nextToken();
 * --------------------------------------------------------------------
 * This method returns the next token from this scanner. If
 * nextToken is called when no tokens are available, it returns the
 * empty string.
 */

    string nextToken();

/*
 * Method: hasMoreTokens
 * Usage: if (scanner.hasMoreTokens()) . . .
 * --------------------------------------------------------------------
 * This method returns true as long as there are additional
 * tokens for this scanner to read.
 */

    bool hasMoreTokens();

/*
 * Methods: setSpaceOption, getSpaceOption
 * Usage: scanner.setSpaceOption(option);
 * option = scanner.getSpaceOption();
 * --------------------------------------------------------------------
 * This method controls whether this scanner
 * ignores whitespace characters or treats them as valid tokens.
 * By default, the nextToken function treats whitespace characters,
 * such as spaces and tabs, just like any other punctuation mark.
 * If, however, you call
 *
 * scanner.setSpaceOption(Scanner::IgnoreSpaces);
 *
 * the scanner will skip over any white space before reading a
 * token. You can restore the original behavior by calling
 *
 * scanner.setSpaceOption(Scanner::PreserveSpaces);
 *
 * The getSpaceOption function returns the current setting
 * of this option.
 */

    enum spaceOptionT { PreserveSpaces, IgnoreSpaces };
    void setSpaceOption(spaceOptionT option);
    spaceOptionT getSpaceOption();

/* ---------------------- change ----------------------- */
/*
 * Methods: setStringOption, getStringOption
 * Usage: scanner.setStringOption(option);
 *        option = scanner.getStringOption();
 * ------------------------------------------
 * This method controls how this scanner treats double
 * quotation marks in the input.  The default behavior for a scanner
 * is to treat quotes just like any other punctuation character.
 * If, however, you call
 *
 *    scanner.setStringOption(Scanner::ScanQuotesAsStrings);
 *
 * a token beginning with a quotation mark will be scanned up to
 * the closing quotation mark.  The quotation marks are returned
 * as part of the scanned token so that clients can differentiate
 * strings from other token types.  The original behavior can be
 * restored by calling
 *
 *    scanner.setStringOption(Scanner::ScanQuotesAsPunctuation);
 *
 * The getStringOption function returns the current setting
 * of this option.
 */

    enum stringOptionT { ScanQuotesAsPunctuation, ScanQuotesAsStrings };
    void setStringOption(stringOptionT option);
    stringOptionT getStringOption();
/* -------------------- end of change ------------------ */

private:

#include "scanpriv.h"

};

#endif