Refactoring a Crossword Game Program¶

In my CS 212 class on Udacity, the most complex lesson involved a crossword game program (for games such as Scrabble® and Words with Friends®). The program was developed incrementally. First I asked "what words can be made with a rack of seven letters?", then I asked "how can you place words onto a single row?", and finally, I, with the help of the students, developed a program to find the highest scoring play anywhere on the board. This approach made for a good sequence of exercises, each building on the previous one. But the code ended up being overly complicated—it accumlated technical debt—because it kept around ideas from each iteration.

In this notebook I will refactor the program to pay off the debt.

Vocabulary¶

Our program uses these concepts:

• Dictionary: A set of all legal words.
• Word: a string of letters. Words in the dictionary are all uppercase.
• Tile: a letter (or a blank) that can be played on the board to form words.
• Blank: a tile with no letter on it; the player who places it on the board gets to choose which letter it will represent.
• Rack: a collection of up to seven tiles that a player may use to make words.
• Board: a grid of squares onto which players play tiles to make words.
• Square: a location on the board; a square can hold one tile. (The variable s will stand for a square number, and sq for the contents of a square.)
• Bonus: some squares give you bonus scores: double or triple letter or word scores.
• Play: a play consists of placing some tiles on the board to form a continuous string of letters in one direction (across or down), such that only valid words are formed, and such that one of the letters is placed on an anchor square.
• Anchor square: Every play must place a letter on an anchor square: either the center start square or a square that is adjacent to a tile previously played on the board.
• Direction: Every play must be in either the ACROSS or DOWN direction. (The variable dir stands for a direction.)
• Cross word: a word formed in the other direction from a play. For example, a play forms a word in the across direction, and in doing so, places a letter that extends a word in the down direction. This new extended cross word must be in the dictionary.
• Score: the points awarded for a play, consisting of the sum of the word scores for each word made (the main word and possibly any cross words), plus a bingo bonus if all seven letters are used.
• Word score: Each word scores the sum of the letter scores for each tile (either placed by the player or already on the board but part of the word) times the word bonus score. The word bonus score starts at 1, and is multiplied by 2 for each double word square and 3 for each triple word square covered by a tile on this play.
• Letter score: The letter score is the value on the letter tile (for example, 1 for A and 10 for Q) times the letter bonus score. The letter bonus is 2 when a tile is first placed on a double letter square (or the center star) and 3 when first placed on a triple letter square; it is 1 for a tile already on the board, or for a new tile played on a non-letter-bonus square. The letter score for a blank tile is always zero.
• Bingo: a bonus gained by using all seven tiles in one play. In Words with Friends® the bingo bonus is 35; in Scrabble® it is 50.
• Game: players take turns making plays until one player has no more tiles. After making a play, the player's

rack is replenished with tiles until the player has 7 tiles or until the bag of tiles is empty.

• Prefix: a string of zero or more letters that starts some word in the dictionary. Not a concept that has to do

with the rules of the game; it will be important in our algorithm that finds valid plays.

This notebook uses these imports:

Dictionary and Words¶

We will represent the dictionary as a set of words. A word is an uppercase string of letters, like 'WORD'. There are several standard dictionaries used by different communities of players; we will use the ENABLE dictionary—we can cache a local copy with this shell command:

Now we can define a word and load the dictionary:

Tiles, Blanks, and Racks¶

We'll represent a tile as a one-character string, like 'W'. We'll represent a rack as a string of tiles, usually of length 7, such as 'EELRTTS'. (I also considered a collections.Counter to represent a rack, but felt that str was simpler, and with the rack size limited to 7, efficiency was not a major issue.)

The blank tile causes some complications. We'll represent a blank in a player's rack as the underscore character, '_'. But once the blank is played on the board, it must be used as if it was a specific letter. However, it doesn't score the points of the letter. I chose to use the lowercase version of the letter to represent this. That way, we know what letter the blank is standing for, and we can distingush between scoring and non-scoring tiles. For example, 'EELRTT_' is a rack that contains a blank; and 'LETTERs' is a word played on the board that uses the blank to stand for the letter S.

We'll define letters to give all the distinct letters that can be made by a rack, and remove to remove letters from a rack (after they have been played).

The Board, Squares, Directions, and Bonus Squares¶

In the previous version of this program, the board was a two-dimensional matrix, and a square on the board was denoted by a (row, col) pair of indexes. There's nothing wrong with that representation, but for this version we will choose a different representation that is simpler in most ways:

• The board is represented as a one-dimensional list of squares.
• The default board is 15×15 squares, but

we will include a border around the outside, making the board of size 17×17.

• Squares are denoted by integer indexes, from 0 to 288.
• To move in the ACROSS direction from one square to the next, increment the square index by 1.
• To move in the DOWN direction from one square to the next, increment the square index by 17.
• The border squares are filled with a symbol, OFF, indicating that they are off the board.

The advantage of the border is that the code never has to check if it is at the edge of the board; it can always look at the neighboring square without fear of indexing off the end of the board.

• Each square on the board is initially filled by a symbol indicating the bonus value of the square. When a tile is placed on a square,

the tile replaces the bonus value.

How will we implement this? We'll define Board as a subclass of list and give it two additional attributes:

• down: the increment to move in the down direction; 17 for a standard board.
• directions: the four increments to move to any neighboring square; (1, 17, -1, -17) in a standard board.

Jupyter/Ipython notebooks have a special convention for displaying objects in HTML. We will adopt it as a method of Board:

• _repr_html_: return a string of HTML that displays the board as a table.

We'll define WWF as the standard board for Words with Friends®.

Displaying the Board in HTML¶

I want to diaplay the board in HTML, as a table with different background colors for the bonus squares; and gold-colored letter tiles. I also want to display the point values for each letter on the tiles; I'll use a defaultdict of {letter: int} named POINTS for that.

Plays¶

A Play describes the placement of tiles on the board. We will implement Play as a named tuple of four components:

• start: the index number of the square that holds the first letter in the word.
• dir: the direction, with 1 indicating ACROSS and board.down (normally, 17) indicating DOWN.
• letters: the letters of the word, in order, as a str. Blanks are lowercase. Some letters are from the rack; some may have been on the board.
• rack: the letters that would remain in the player's rack after making this play. Not strictly necessary as part of the play, but useful information.

The function make_play returns a new board with the play made on it. It does not do any checking to see if the play follows the rules.

Example Board¶

Let's test out what we've done so far. I'll put some words on a board, which I will call board:

Strategy for Finding Legal Plays¶

This is our strategy for finding all possible legal plays on a board:

• Find all anchor squares on the board. An anchor square is a square that is adjacent to a letter on the board—every legal move must place a letter on an anchor square. (On the game's first play, there are no letters on the board, and the STAR square in the center counts as the only anchor square.)
• Using just the letters in the rack, find all prefixes of words in the dictionary. For example, with the rack ABC, we find that B, BA, and BAC are all prefixes of the word BACK (and the rack contains other prefixes of other words as well).
• For each anchor square and for both directions (across and down):
  • Try each prefix before the anchor (that is, to the left or above the anchor). Don't allow a prefix to extend to another anchor or off the board. That means we won't have to worry about cross words for the prefix. If there are already letters on the board before the anchor point, use them as the prefix rather than prefixes from the rack.
  • Starting at the anchor, march forward one square at a time, trying to fill empty squares with each possible letter from the rack that forms a valid word prefix. If the march forward hits letters that are already on the board, make sure they form a valid prefix too. Also check that any cross words are valid words. When we make a complete word (with an empty or OFF square ahead), yield the play that made the word.

So, each legal play will have a prefix of zero or more letters, followed by one letter from the rack covering an anchor square, followed by zero or more additional letters, which can be from the rack or already on the board.

Prefixes¶

Here we define the set of all prefixes of all words in the dictionary:

That's too many prefixes to look at; let's try a smaller example below. Note that the empty string is a prefix, and we include HELP because it is a prefix of HELPER, but we don't include HELPER, because there is nothing we can add to it to make a word in this dictionary:

The function rack_prefixes gives the set of prefixes that can be made just from the letters in the rack. Most of the work is done by extend_prefixes, which accumulates a set of prefixes into results:

The number of prefixes in a rack is usually on the order of a hundred, unless there is a blank in the rack:

Anchor Squares¶

An anchor square is either the star in the middle of the board, or an empty square that is adjacent to a letter:

Plays on Example Board¶

Let's work through the process of finding plays on the example board. First, we'll find all the anchors:

To visualize these anchors, we'll make each one be a star, on a copy of board:

Now we'll define a rack, and find all the prefixes for the rack:

We wont go through all the anchor/prefix combinations; we'll just pick one: the anchor above the M in MUSES:

There's only room for prefixes of length 0 or 1, because anything longer than that would hit the anchor to the right of the G in GAVE; to avoid duplication of effort, we only allow words to run into other anchors on the right, not the left. Let's try the 1-letter prefix B first:

Now we can start to march forward. On the anchor square we can place any letter from the rack that makes a valid prefix, and that also turns .MUSES into a valid word. There's only one such letter, A:

We can continue marching forward, trying letters from the rack that form valid prefixes. Let's try the combination CK:

We've spelled the word BACK, but we can't count it as a legal play, because we've hit two adjacent letters, BE, that are already on the board. We check that BACKBE froms a valid prefix, and continue to the next empty square, where we can choose an N:

We continue to the next square (a double word square), and place an H, which completes a word, BACKBENCH, and simultaneously makes a cross word, THE:

We would record this play, and backtrack to consider other letters for this and other prefix/anchor combinations. Now let's code this up!

Code for Finding All Plays¶

The function all_plays generates all legal plays by first trying all prefix plays, and then trying to extend each one, one letter at a time. (Note that it also generates the empty play, because a player always has the option of passing.)

Note the syntax yield from, new in Python 3.3: "yield from c" is the same as "for x in c: yield x".

Now for the function prefix_plays, which returns a list of all partial plays consisting of a prefix placed before the anchor. Note that these are not legal plays; they are partial plays, some of which will end up being extended into legal plays.

There are two cases: if there are letters on the board immediately before the anchor, then those letters form the only allowable prefix. If not, we can use any prefix from the rack up to maxlen, which is the number of empty squares that do not run into another anchor, nor off the board.

Now extend_play takes a partial play, determines the square, s, that is one square past the end of the play, and tries all possible letters there. If adding a letter forms a valid prefix (and also does not form an invalid cross word), then we continue on (by calling extend_play recursively). If adding the letter forms a valid word, we yield the play.

Crosswords¶

If adding a letter in, say, the ACROSS direction also adds on to a word in the DOWN direction, then we need to make sure that this cross word is also valid. The function crossword finds the cross word at square s and returns it with a '.' indicating the empty square where the new letter will be placed, so we would get '.MUSES' and 'T.E' for the two crosswords in the 'BACKBENCH' play.

The function valid_crossword checks if replacing the empty square with a specific letter will form a valid word:

We can now see all the prefix plays for the anchor at 141 (just above MUSES):

And we can see all the ways to extend the play of 'B' there:

Scoring¶

Now we'll show how to count up the points made by a play. The score is the sum of the word score for the play, plus a bingo score if all seven letters are used, plus the sum of the word scores for any cross words. The word score is the sum of the letter scores (where each letter score may be doubled or tripled by a bonus square when the letter is first played on the square), all multiplied by any word bonus(es) encountered by the newly-placed letters.

Here are the various helper functions:

What should the BACKBENCH play score? The word covers two double-word bonuses, but no letter bonuses. The sum of the letter point values is 3+1+3+5+3+1+1+3+4 = 24, and 24×2×2 = 96. The cross word AMUSES scores 8, and THE is on a double word bonus, so it scores 6×2 = 12. There is one letter remaining in the rack, so no bingo, just a total score of 96 + 8 + 12 = 116.

We can find the highest scoring play by enumerating all plays and taking the one with the maximum score:

Playing a Game¶

Now let's play a complete game. We start with a bag of tiles:

Then the function play_game will take a list of player strategies as input, and play those strategies against each other over the course of a game. A strategy is a function that takes a board and a rack as input and returns a play. For example, highest_scoring_play is a strategy. If the optional argument verbose is true, then the board is displayed after each play.