// An Engine tallies occurrences of strings and can randomly generate output
// text, one character at a time, based on the strings it has tallied.
// The "context size" (hereafter called k) determines the size of strings it
// tallies and the amount of prior context it needs in order to generate
// characters.
// The engine only recognizes (and generates) characters from its alphabet.

interface Engine {

    // The engine must have a constructor as follows:
    //
    // Initialize k, size of my context, to `contextSize' and my alphabet
    // to `alphabet'.  Also seed my random number generator with `seed'.
    // Preconditions: contextSize cannot be negative
    //                the length of alphabet must not be zero
    // public Engine(int contextSize, String alphabet, long seed);
    //
    // (This constructor is described in a comment because Java does not
    // allow interfaces to have constructors.)



    // Let s be the first k characters of nextChunk and c be the 
    // last character of nextChunk.  tally() records the fact that we have
    // observed an occurrence of the string s immediately followed by the 
    // character c.
    //     IllegalCharException occurs if nextChunk contains characters that
    // are not in the engine's alphabet.  StringLengthException occurs if the 
    // length of nextChunk is not k+1.

    public void tally(String nextChunk)
        throws IllegalCharException, StringLengthException;



    // Randomly generate and return the next character of output, based on
    // 1) the previous k characters we have ouput (stored in context) and
    // 2) the frequency, in the input text, with which this context was 
    // followed by the various characters of my alphabet.
    //     IllegalCharException occurs if context contains characters that are
    // not in my alphabet.  StringLengthException occurs if the length of 
    // context is not k.  ContextNotFoundException occurs if I have never
    // tallied a chunk that begins with context.

    public char generateChar(String context)
        throws IllegalCharException, StringLengthException,
	       ContextNotFoundException;

}