CSCI 136

CSCI 136 - Fall 2019

Data Structures & Advanced Programming

Lab 1: Unix, Workflow, and Coinstrip

In this lab, we will explore tools, techniques, and workflows used by many programmers. We will adopt some of these best practices and use them for managing our written and lab assignments, collaborating, and exchanging feedback.

The skills developed in this lab will help us on multiple fronts. The tools that we explore (Terminal.app, the Atom text editor) and the workflow we use (checkpointing our progress using the Git version control system) will help us to work efficiently, safely, and flexibly throughout the semester.

We will also write a program to play the Silver Dollar Game found at the end of Bailey Chapter 3 (page 67). In addition to gaining experience writing, compiling, and running programs from scratch, this lab will help us to think about how we can efficiently represent data and break our logic into reusable methods. Careful planning will help tremendously, so take the time to write a well-though-out design document before arriving to lab.

PRE-LAB Step 0: Version Control Systems and GitHub

Please complete PRE-LAB Step 0 by Monday at 4pm. This part is worth 2 basis points of your Lab 1 grade.

Review these two short descriptions of what a version control system is and why you might want to use one. We will talk about these more in lecture and lab.
Sign up for a GitHub account by following the git guide on the course webpage. Please thoughtfully choose a username. Make sure to choose the free plan (it's the default) and don't set up an organization. You can skip the little quiz they give you by clicking the skip this step link at the bottom of the page. However, please complete the "Hello World" guide. (If you accidentally exit the guide, you can navigate back to the Hello World guide here.) We will be using those features throughout the semester.
After you've registered, please fill out this Google Form, and include your GitHub username. We will add you to the GitHub Williams CS organization prior to our scheduled lab.

PRE-LAB Step 1: Testing Your CS Mac Lab Account

Log in to the Macs. You must use your CS-department username and password. Please see Lida Doret in TCL 205 if you do not have a CS-department Mac account or if you have forgotten your username/password.

PRE-LAB Step 2: Design Documents

Read through this lab handout and sketch out a design for your Silver Dollar Game program. You should use the sample Dice Design Doc as a guide. Each week your design doc will account for a small portion of your lab grade, so please bring it to lab, be prepared to discuss it with a partner, and be prepared to submit it. For the first week, it is OK if the design is rough: we are not going to deduct points for incorrectness, we just want to make sure you think about the lab in advance.

Step 1: The Mac Lab Environment

Go through the Unix tutorial on the course webpage (called Unix Cheat Sheet in the links section). That guide will teach you how to log in and out of the machines, access the command line shell, use basic Unix commands, and compile and run Java programs. Depending on your prior background, you may already be familiar with this environment. If that is the case, please refresh your memory and review the following commands:

  ls         cd         cp         mv         rm         mkdir      pwd
  man        history    cat        more       grep       head       tail

To be successful, you should type them all out at the command line and use them to explore, create, modify, and rename files. Even though there is nothing to turn in for this step, learning core Unix commands is going to help you with everything you do this semester.

Step 2: Cloning

By the start of Lab, you will have a private repository in your GitHub account, named cs136lab1-USERNAME, where USERNAME is replaced with your GitHub ID. Clone the repository to your local disk using the following steps:

In your brower, click the green "clone or download" button on the right side of the repository page, above the list of repository contents. You can clone via HTTPS or SSH. We'll use HTTPS, so first click on the "Clone with HTTPS" link and then click on the little clipboard with an arrow icon to copy the URL to the local clipboard.
Open up the Terminal.app application and navigate to your home directory by typing
```
$ cd ~
```
Make a new directory called cs136 using
```
$ mkdir cs136
```

Move into the cs136 directory using
```
$ cd cs136
```
Now clone your private repository cs136lab1-USERNAME by typing "git clone" and then pasting the copied repo on the command line (⌘-v). It should look like this:
```
$ git clone https://github.com/williams-cs/cs136lab1-USERNAME.git
```
(It will prompt you for your username, and then for your password)

Change directories into the new repository directory using
```
$ cd cs136lab1-USERNAME
```

Step 3: Text Editors

There are many good text editors. Traditionally, we have used the Emacs text editor in CSCI 136. Emacs is a very powerful editor, and being proficient in Emacs is worth the time investment and the steep learning curve. However, this semester we will start by using the Atom text editor, and revisit Emacs after Spring break.

Open your cs136lab1-USERNAME project folder in Atom:
- Using the launcher, search for and open the Atom application.
- Once you have opened Atom, go to the File menu, click on Add Project Folder, and select the cs136lab1-USERNAME folder that you just cloned.
- In the left pane, you will see a list of all of the files in your project. Click on the README.md file.
Open the README.md in your repository. You may be surprised by the way README.md looks in Atom compared to how it looked on GitHub.com. This is because GitHub understands and formats "Markdown", just like a Web Browser understands and formats HTML. You may want to use the github markdown syntax to format your file so that it displays nicely on github.com.
The README.md of a repository is shown when you view that repository on github.com. Make a small change (perhaps write the word "test" at the bottom of the page). You should see that the README.md file's tab at the top of the application now has a little blue dot. That dot means the tab has unsaved changes. Save the file. The dot should disappear.
You should now see the README.md file change colors in the left-hand menu. If a file is yellow, that means that you have made changes to that file since you last committed it to your git repository. (If a file is green, then git does not yet know that the file exists.)
Go to the Atom menu labeled "Packages", then scroll to the "GitHub" entry, then click the "Toggle Git Tab" entry. You should now see a new column on the right side of Atom.
In the "Unstaged Changes" section on the right, your yellow README.md file should appear. If you click on the "Stage All" button, it should move that file (and all other files with pending changes) to the "Staged Changes" section. Once this is done, you can write a message in window labeled "Commit Message" and press the commit button. (Your message should usually be something informative to describe the changes that were made. In this case, you can just write "Test").
You should now see a small change to the bottom right corner of the Git tab. There should be two arrows, one pointing down and the other pointing up. Next to the arrow that is pointing up, you should see the number one in parenthesis (1). This means that you have a commit on your machine that is not yet sync-ed with your repository on github.com. Go ahead and click that button and then press "Push". It will ask you for your password. If you are successful, you should see your changes reflected in your repository on github.com. Congratulations on making your first git push.

Step 4: First Program

In this step, we will write, compile, and run a Java program under Unix that prints the first ten odd numbers. Call it Odd.java. You will turn in your source code for Odd.java by committing it to your local git repository, and pushing that commit to your private repository on github.com. You should complete this step by the end of lab on Wednesday. The instructors and TAs are around to give as much assistance as we can on this step, so do not hesitate to ask questions! We want you to successfully complete this step so that you can move on to the main lab assignment. This is the simplest program we will write all semester, but it is often the hardest to complete. Ask questions early and often!

Inside your project folder, create a new file named Odd.java. That file should contain class called Odd, and that class should include a main method.
Once you have written your program, compile it using
```
$ javac Odd.java
```
After successfully compiling your program, you should see a new file called Odd.class when you type
```
 $ ls
```

To test your code, type

$ java Odd

The output should look something like:

When you have finished Odd.java and are happy with the output, please commit Odd.java (with a meaningful commit message), and push it to your private repository. Confirm that your changes are visible online.

Step 5: Main Lab Program (Coinstrip.java)

This week, we will write the Silver Dollar Game at the end of Bailey Chapter 3 (page 67). As you think about the design of your game, you should first decide on an internal representation of the coin strip. Make sure your representation supports all of the operations necessary such as:

generating different game boards
testing for a legal move
printing the board
testing for a win
moving pieces easily
...

You should think about alternative designs and be able to justify your decisions. (Do you want a data structure that stores the spaces on the game board? Do you want a data structure that stores the coins? Think about the tradeoffs: which operations become easier to implement if you choose one representation over another?) You may read ahead a little to Vectors if you like, but the lab can be implemented just as efficiently with arrays.

Once you have decided on a representation, write down the set of operations supported by your data structure. In other words, what are the public methods of CoinStrip, what parameters do they take, what do they return, and what do they do? We will briefly discuss this initial design with a partner. Bring a physical copy of your design to lab for discussion. We will check design documents at the beginning of lab.

The main method of your class should create a CoinStrip object and then prompt each of two players to make their moves. A move will be of the form:
```
cn ns
```
where cn specifies the coin to be moved and ns specifies the number of spaces that coin should be moved.
The program should prompt the user for another input if the move is illegal.
To read input from a terminal window, you should use the Scanner class, as we have seen in lecture. Consult the scanner handout, Oracle Scanner documentation or sample code from class for details.

The lab’s description of how to generate a game is somewhat vague. At a high level, you should generate games that are "interesting". This roughly means:

Coin locations should be random.
The number of coins should be either:
1. Specified as an input from the user
2. A randomly generated number within a reasonable range (e.g., 3-5 coins)
The length of the Coinstrip should be long enough that the coins comfortably fit (the game is not “won” before gameplay begins).

Make sure your game enforces all rules described in the textbook. You may want to test your CoinStrip game (or show off your hard work) by playing against a friend.

Lab Deliverables

When you are finished with your CoinStrip program, answer the thought questions at the end of the lab, and put your answers in a separate file called PROBLEMS.md. Commit and push PROBLEMS.md along with your other lab files as part of your repository. Your repository should have the files:

	cs136lab1-USERNAME/
               Odd.java
               CoinStrip.java
               README.md
               PROBLEMS.md

Submitting Your Lab (Due: Sunday, Sept. 15, by 10:00 pm)

As you complete various milestones, 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 include "Lab 1 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 GitHub
Verify your changes on Github. Navigate in your web browser to your private repository on GitHub. It should be available at https://github.com/williams-cs/cs136lab1-USERNAME You should see all changes reflected in the various files that you submit. If not, go back and make sure you 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. Our goal is to grade the programs anonymously to avoid any bias. However, 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 "I am the sole author of the work in this repository." In the comments at the top your Java files.