Assignment 2: Perl-2: CGI Sudoku

Goal

You will use Perl's CGI capabilities with HTML forms to implement a version of the Sukoku puzzle game.

The Game

Our version of sudoku is played on a 4x4 grid, which is divided into four 2x2 regions (top left, top right, bottom left, bottom right). The goal of the game is to place the numbers 1-4 into the grid such that every number appears exactly once in each row, column, and region. The game begins with several numbers that cannot be moved already in place; the player must reason logically to determine how to fill the remaining squares. There is a great deal more information to be found at Wikipedia's article on Sudoku, and there are many online versions available, though usually on larger 9x9 grids. Web Sudoku is one such version.

Specifications

You will write a single Perl script, sudoku.cgi, that allows a user to play a game of Sudoku from beginning to end, checking his/her moves along the way and allowing him/her to undo them.

(i) Initial State

Example initboard.txt (equivalent to the starting game board shown above)

2 0 0 0
1 0 4 0
3 0 0 4
0 0 2 3

(ii) Gameplay

Your program must generate an HTML page that displays the Sudoku board as a table, similar to the ones shown above. The numbers that were initialized from initboard.txt must be uneditable text, and each empty cell must contain a text field so that the user can enter his/her input. The HTML page must also contain a button to submit the form (i.e., play one move).

The user will play the game by repeatedly filling in a single text box and submitting the form. Upon receiving the user's input, your script must perform the following three tests:

(A) Did the user submit a single move?

If the user has filled in more than one input boxes (regardless if the moves are correct or not) you should indicate it with an error message, "Illegal move" and not allow the user to continue unless they only provide a single number. You should also highlight the "offending" cells in red background (as explained below, for invalid moves).

(B) Is the user's move valid?

• If the user's move is valid, you must return the new Sudoku board that results from the user's move, with text fields in the remaining blanks spaces. The number that the user placed must be part of the text of the page, like the numbers in the original layout were, so that it is uneditable from this point forward.
• If the user's move is not valid, you must return the old Sudoku board with a few minor changes to show that the user's move was incorrect:
  • First, the text field where the user made his/her move should still be a text field, but it should be initialized to the value that the user entered so that the user can more easily see why his/her move was invalid.
  • Second, you must indicate to the user why his/her move was invalid by highlighting the row, column, or region with the error. If there are multiple reasons that a move is invalid, then highlight every row/column/region that causes a problem. (To highlight a cell, set its background color to red.)
  • Finally, you must include the message "Illegal Move" somewhere in your page.

  An illegal move

  2
  1		4
  3			4
  		2	3

(C) Is the puzzle complete?

If the user's move is valid, you must check to see if the puzzle has been completed. If it has, you must change the background color in the table to green and include the message "Congratulations" somewhere in your page. You must also provide a "Play Again" link that reinitializes the puzzle from initboard.txt so that the user may start over.

(iii) Undo

Because the user is not allowed to edit legally placed values after he has submitted them, you are required to implement an "Undo" button. The Undo button should appear in the page whenever there is a move to be undone, but it should not appear when there is not (i.e., before the user has placed any numbers or after he has undone all his/her moves). Each press of the undo button should return a new page with the user's previous move removed from the board. The user must be able to undo all his/her moves by repeatedly pressing the button.

Implementation Hint

You may want to store the list of past moves as a space-delimited string value to a hidden <input> component. You will need to update it whenever the user makes a legal move or presses Undo.

Running Your Script (CGIWrap)

Allowing multiple users to run Perl CGI scripts on the same machine raises some security problems, so the tech staff has installed CGIWrap. CGIWrap allows the web server to run your script under your user account, which means, in brief, that you can read and write files that you own but not those owned by others.

To run a Perl script using CGIWrap, you must place it in your public_html/cgi-bin directory on cs1520.cs.pitt.edu. Be aware that your account on this computer is not your usual Pitt account, and your home directory is not your AFS directory. Your username is the same as the userID that you used to submit the first assignment. The initial password is your PeopleSoft ID number which was emailed to you. You are advised to change your password when you log in by running the passwd command and following its instructions.

To copy your script to cs1520.cs.pitt.edu, you may find it useful to use scp to transfer it from unixs.cis.pitt.edu or another Unix machine. If your script is titled yourscript.cgi and your username is userXX, then the following command would copy the script to the appropriate directory:

scp yourscript.cgi userXX@cs1520.cs.pitt.edu:public_html/cgi-bin

Your script must begin with a line that tells CGIWrap to call the Perl interpreter.

#!/usr/bin/perl -w

It must also have its executable bit set.

chmod 755 yourscript.cgi

If your username is userXX and your script is titled yourscript.cgi, then there are two URL's that you can visit to see its output:

http://cs1520.cs.pitt.edu/~userXX/cgi-bin/yourscript.cgi

This shows you the web page returned by your script.

http://cs1520.cs.pitt.edu/~userXX/cgi-debug/yourscript.cgi

This shows you debugging information for your script, including environment variables and the raw text returned by your script (both STDOUT and STDERR)

Note that you do not create a cgi-debug directory to view debugging output; the web server still runs the program in your cgi-bin directory; only the URL is different.

Submitting your assignment

• This project is to be done independently.
• You should submit your project as a single Perl file.
• To submit your assignment:
  • name your project submission using your userID (e.g., user01.cgi)
  • copy the answer file into the directory: /afs/cs.pitt.edu/public/incoming/CS1520/2/
    (e.g.,

    cp sudoku.cgi /afs/cs.pitt.edu/public/incoming/CS1520/2/user01.cgi) 

• You must submit your assignment before the due date ( 11:59pm, Monday, November 7th) to avoid getting any late penalty. The timestamp of the electronic submission will determine if you have met the deadline. There will be no late submissions allowed after 11:59pm, November 9th

Notes on the submission process

• You can copy your file only once in the incoming directory and you cannot edit or remove your submission. So, copy only your final submission.
• You should list the contents of the incoming directory (e.g., using the ls -l command in Unix) to make sure that your submission is there and it has a non-zero file size.
• If you find that there is a problem with your submission and must resubmit it, please use an alternate filename extension to do so, (e.g, user01.second.cgi) and email the instructor.
• It is recommended to first upload your project to your Pitt account (e.g., using ftp) and then copy the file from your account to the specified incoming directory.
• It is your responsibility to submit a file that is working properly!.

Back to the class web page