001package components.statement;
002
003import components.queue.Queue;
004import components.simplewriter.SimpleWriter;
005
006/**
007 * {@code StatementKernel} enhanced with secondary methods.
008 */
009public interface Statement extends StatementKernel {
010
011    /**
012     * Pretty prints {@code this} to the given stream {@code out} {@code offset}
013     * spaces from the left margin using
014     * {@link components.program.Program#INDENT_SIZE Program.INDENT_SIZE} spaces
015     * for each indentation level.
016     *
017     * @param out
018     *            the output stream
019     * @param offset
020     *            the number of spaces to be placed before every nonempty line
021     *            of output; nonempty lines of output that are indented further
022     *            will, of course, continue with even more spaces
023     * @updates out.content
024     * @requires {@code out.is_open and 0 <= offset}
025     * @ensures <pre>
026     * out.content =
027     *   #out.content * [this pretty printed offset spaces from the left margin
028     *                   using Program.INDENT_SIZE spaces for indentation]
029     * </pre>
030     */
031    void prettyPrint(SimpleWriter out, int offset);
032
033    /**
034     * Parses a single BL statement from {@code tokens} into {@code this}.
035     *
036     * @param tokens
037     *            the input tokens
038     * @replaces this
039     * @updates tokens
040     * @requires {@code [<Tokenizer.END_OF_INPUT> is a suffix of tokens]}
041     * @ensures <pre>
042     * if [a statement string is a proper prefix of #tokens] then
043     *  this =
044     *   [Statement corresponding to statement string at start of #tokens]  and
045     *  #tokens = [statement string at start of #tokens] * tokens
046     * else
047     *  [reports an appropriate error message to the console and terminates client]
048     * </pre>
049     */
050    void parse(Queue<String> tokens);
051
052    /**
053     * Parses a maximally long sequence of BL statements from {@code tokens}
054     * into the BLOCK {@code this}.
055     *
056     * @param tokens
057     *            the input tokens
058     * @replaces this
059     * @updates tokens
060     * @requires {@code [<Tokenizer.END_OF_INPUT> is a suffix of tokens]}
061     * @ensures <pre>
062     * if [there is a block string b that is a prefix of #tokens]  and
063     *    [the first token past b in #tokens cannot begin a statement string] then
064     *  this =
065     *   [BLOCK Statement corresponding to a block string at start of #tokens
066     *    that is immediately followed by a token in #tokens that cannot begin
067     *    a statement string]  and
068     *   #tokens =
069     *    [a block string at start of #tokens that is immediately followed
070     *     by a token in #tokens that cannot begin a statement string] * tokens
071     * else
072     *  [reports an appropriate error message to the console and terminates client]
073     * </pre>
074     */
075    void parseBlock(Queue<String> tokens);
076
077}