Lab 6: PostScript

In this week’s lab (described in Section 10.5 of Bailey), we will implement a small portion of PostScript, the stack-based programming language. PostScript was designed to describe graphical images. When you print to a PostScript printer, your computer converts your document into a program written in this language. Your printer then interprets that program in order to render the image on paper.

PRE-LAB: Step 0

Before lab, please do the following:

Read the Javadoc for the Token, Reader, and SymbolTable starter files. These classes will be helpful in your implementation.
For more implementation details, skim the Token.java, Reader.java, and SymbolTable.java source files (also in your private repository) before coming to lab.
Prepare a design document for the program before lab so that you can start working right away.

Lab Assignment

Complete Laboratory Assignment 10.5, which begins on page 247 of Bailey.

Helpful Notes

The starter files can be found online and in your private GitLab repository. We have also posted Javadoc documentation on the lab webpage. In addition to starter Java files, we have included several sample PostScript programs that will be useful for testing your code. PostScript files end with the .ps file extension.
Make use of the functionality of the classes that you are given. Be careful not to spend time developing code that is already there! Pay careful attention to the different class constructors, and ask questions if you have any.
Name your interpreter class Interpreter. You should only need to modify the Interpreter class and nothing else.
Your program should read commands from standard input. You can also redirect input from a file. For example, you can read the basics.ps in the samples directory into your Interpreter program by using a command like:
```
  $ java Interpreter < samples/basics.ps
```
Make your main method very short. All it should do is create an Interpreter object and tell that object to process the PostScript program provided as standard input. Create a method interpret that takes a single parameter of type Reader and processes the PostScript tokens returned by that Reader.
Develop your interpret method incrementally. Get your simple push, pop, and pstack operations working, then move on to the arithmetic operators, and finally the definition and usage of symbols. Decompose the program into small, manageable helper methods as you go!
Your program should report errors when it encounters invalid input, and these should contain meaningful error messages. You can use Assert.condition() and Assert.fail() for this, or use the Java assert statement. Think about the different operations that may share preconditions. Can you create helper methods that meaningfully handle multiple operations?
You should begin by implementing the basic operations (pstack, add, sub, mul, div, dup, exch, eq, ne, lt, def, pop, quit, and ptable). The lt (less than) instruction is similar to the eq instruction, but tests if one number is less than the other.
Implementing the basic operations above will allow you to earn a B for the functionality portion of your grade. You can reach an A by implementing the extensions outlined in thought questions 3 and 4 from the book. In particular, you should implement procedure definitions and calls, and you should implement the if instruction. These extensions may require a little thought, but ought to be straightforward to implement if you have designed your interpreter well.
You can use the gs interpreter on the computers in the lab if you want to try out the commands yourself. Type the command
```
  $  gs -dNODISPLAY
```
This will give you a text-only PostScript interpreter. You can type commands at the prompt as they appear in the lab assignment. Type quit to exit the interpreter.

Style

Changes to checkstyle for this lab

There are no new rules for the checkstyle tool; however, there is one important lab-specific exception.

For this lab, you are likely to have a method with a large switch statement to that calls one of your methods based on the operation input by the user. It is acceptable if the method containing this statement generates a checkstyle error due to length longer than 30. (Generally, breaking methods into smaller pieces is desirable—but in this case, keeping these method calls in one place is also desirable.) You should still use good design principles for this method otherwise, but you will not lose points just because of the checkstyle error in this case.

Running checkstyle

To run checkstyle, type the following command at the terminal:

$ ./checkstyle

The ./ is peculiar to Unix: it tells the terminal to look for the checkstyle program in the current directory. This command runs checkstyle on every Java program in your directory. To run checkstyle on a specific Java file, type:

$ ./checkstyle SomeFile.java

Lab Deliverables

By the start of lab, you should see a new private repository called cs136lab06-postscript in your GitLab account (where USERNAMES is replaced by your usernames).

For this lab, please submit the following:

cs136lab06-postscript/
    README.md
    Interpreter.java
    Reader.java
    SymbolTable.java
    Token.java
    samples/...

The Reader.java, SymbolTable.java, and Token.java files contain starter code. Interpreter.java should contain your well-documented source code.

Recall in previous labs that you had a Java file that contained a convenient main method pre-populated with a variety of helpful tests. It is always a good practice to create a small set of tests to facilitate development, and you are encouraged to do so here.

As in all labs, you will be graded on design, documentation, style, and correctness. Be sure to document your program with appropriate comments, a general description at the top of the file, and a description of each method with pre- and post-conditions where appropriate. Also, use comments and descriptive variable names to clarify sections of the code which may not be clear to someone trying to understand it.

Whenever you see yourself duplicating functionality, consider moving that code to a helper method. There are several opportunities in this lab to simplify your code by using helper methods.

Submitting Your Lab

As you complete portions of this lab, you should commit your changes and push them. Commit early and often. When the deadline arrives, we will retrieve the latest version of your code. If you are confident that you are done, please use the phrase "Lab Submission" as the commit message for your final commit. If you later decide that you have more edits to make, it is OK. We will look at the latest commit before the deadline.

Be sure to push your changes to GitLab.
Verify your changes on GitLab. Navigate in your web browser to your private repository on GitLab. It should be available at https://evolene.cs.williams.edu/cs136-labs/[your username]/lab06-postscript.git. You should see all changes reflected in the files that you push. If not, go back and make sure you have both committed and pushed.

We will know that the files are yours because they are in your git repository. Do not include identifying information in the code that you submit. We grade your lab programs anonymously to avoid bias. In your README.md file, please cite any sources of inspiration or collaboration (e.g., conversations with classmates). We take the honor code very seriously, and so should you. Please include the statement "We are the sole authors of the work in this repository." in the comments at the top of your Java files.