Utilities for solving the Boggle word game.
Project description
Boggler
A solver for the popular word game Boggle.
Install
pip install boggler
Setup
To use the script to solve a Boggle board, you'll need to do a few things first.
-
Create
.csvof the board state like so:Here is an example
board.csv. Note the orientation of the board does not matter.$ cat board.csv y,e,o,s r,e,o,v d,f,e,y n,m,e,qu
-
Find or create a dictionary wordlist file
The dictionary wordlist should have each word on a single line like so
$ cat wordlists/wordlist.txt a aa aaa aah aahed aahing aahs aal ... zwiebacks zwieselite zwinglian zwinglianism zwinglianist zwitter zwitterion zwitterionic
-
Split the dictionary wordlist into separate files based on the first letter of each word.
To split an English wordlist, use the
split_wordlist_alpha.shscript like so:$ split_wordlist_alpha.sh my_wordlist.txt .
This will generate a series of sub-dictionaries for each letter in the alphabet in the current directory.
$ ls my_wordlist.txt words_d.txt words_h.txt words_l.txt words_p.txt words_t.txt words_x.txt words_a.txt words_e.txt words_i.txt words_m.txt words_q.txt words_u.txt words_y.txt words_b.txt words_f.txt words_j.txt words_n.txt words_r.txt words_v.txt words_z.txt words_c.txt words_g.txt words_k.txt words_o.txt words_s.txt words_w.txt
Usage
CLI usage
$ poetry run boggler --help usage: boggler [-h] [-f FORMAT] [-p] [-s] [-d] board wordlists [max_word_length]Boggle board game solver
positional arguments: board Path to board CSV file wordlists Path to directory of wordlist files. The directory must contain text files of the form words_X.txt where "X" is a character of the alphabet max_word_length Maximum length of words searched for on provided board
options: -h, --help show this help message and exit -f FORMAT, --format FORMAT Specify alternative output format including [txt, json] -p, --include-path Include full paths for each word in output -s, --sort Sort output alphabetically. By default the results are sorted by the starting block position on the board from top-to-bottom, left- to-right as given in the board file. -d, --dedup Remove duplicates from word-only output. Note that de-duplication does not preserve the original order of the output, so it is recommended to also use the sort option when de-duplicating.
Example board solve
$ poetry run boggler ./boggler/boards/b1.csv boggler/wordlists/scrabble_2019/
BOARD +---------------+ | S | A | I | P | +---------------+ | L |QU | A | Y | +---------------+ | U | L | L | S | +---------------+ | O | W | H | A | +---------------+ Starting @ (0, 0) ╭──────────┬──────────────────────────────────────────────────────────────────╮ │ Word │ Path │ ├──────────┼──────────────────────────────────────────────────────────────────┤ │ squall │ [(0, 0), (1, 1), (0, 1), (1, 0), (2, 1)] │ │ squall │ [(0, 0), (1, 1), (1, 2), (2, 2), (2, 1)] │ │ squall │ [(0, 0), (1, 1), (1, 2), (2, 1), (1, 0)] │ │ squall │ [(0, 0), (1, 1), (1, 2), (2, 1), (2, 2)] │ │ squally │ [(0, 0), (1, 1), (1, 2), (2, 1), (2, 2), (1, 3)] │ │ squalls │ [(0, 0), (1, 1), (1, 2), (2, 1), (2, 2), (2, 3)] │ │ squash │ [(0, 0), (1, 1), (1, 2), (2, 3), (3, 2)] │ │ sal │ [(0, 0), (0, 1), (1, 0)] │ │ sall │ [(0, 0), (0, 1), (1, 0), (2, 1)] │ │ sallal │ [(0, 0), (0, 1), (1, 0), (2, 1), (1, 2), (2, 2)] │ │ sallals │ [(0, 0), (0, 1), (1, 0), (2, 1), (1, 2), (2, 2), (2, 3)] │ │ sallow │ [(0, 0), (0, 1), (1, 0), (2, 1), (3, 0), (3, 1)] │ │ sallowly │ [(0, 0), (0, 1), (1, 0), (2, 1), (3, 0), (3, 1), (2, 2), (1, 3)] │ │ sai │ [(0, 0), (0, 1), (0, 2)] │ ╰──────────┴──────────────────────────────────────────────────────────────────╯ Starting @ (0, 1) ╭────────┬──────────────────────────────────────────────────╮ │ Word │ Path │ ├────────┼──────────────────────────────────────────────────┤ │ aqua │ [(0, 1), (1, 1), (1, 2)] │ │ aquas │ [(0, 1), (1, 1), (1, 2), (2, 3)] │ │ al │ [(0, 1), (1, 0)] │ │ als │ [(0, 1), (1, 0), (0, 0)] │ │ alu │ [(0, 1), (1, 0), (2, 0)] │ │ alula │ [(0, 1), (1, 0), (2, 0), (2, 1), (1, 2)] │ │ alulas │ [(0, 1), (1, 0), (2, 0), (2, 1), (1, 2), (2, 3)] │ │ all │ [(0, 1), (1, 0), (2, 1)] │ │ allay │ [(0, 1), (1, 0), (2, 1), (1, 2), (1, 3)] │ │ allays │ [(0, 1), (1, 0), (2, 1), (1, 2), (1, 3), (2, 3)] │ │ allow │ [(0, 1), (1, 0), (2, 1), (3, 0), (3, 1)] │ │ aa │ [(0, 1), (1, 2)] │ │ aal │ [(0, 1), (1, 2), (2, 2)] │ │ aals │ [(0, 1), (1, 2), (2, 2), (2, 3)] │ │ aal │ [(0, 1), (1, 2), (2, 1)] │ │ aas │ [(0, 1), (1, 2), (2, 3)] │ │ as │ [(0, 1), (0, 0)] │ │ ai │ [(0, 1), (0, 2)] │ │ aia │ [(0, 1), (0, 2), (1, 2)] │ │ aias │ [(0, 1), (0, 2), (1, 2), (2, 3)] │ ╰────────┴──────────────────────────────────────────────────╯ Starting @ (0,2) ╭──────┬──────╮ │ Word │ Path │ ├──────┼──────┤ ╰──────┴──────╯ Starting @ (0, 3) ╭─────────┬──────────────────────────────────────────────────────────╮ │ Word │ Path │ ├─────────┼──────────────────────────────────────────────────────────┤ │ pya │ [(0, 3), (1, 3), (1, 2)] │ │ pyas │ [(0, 3), (1, 3), (1, 2), (2, 3)] │ │ pa │ [(0, 3), (1, 2)] │ │ paal │ [(0, 3), (1, 2), (0, 1), (1, 0)] │ │ paals │ [(0, 3), (1, 2), (0, 1), (1, 0), (0, 0)] │ │ pal │ [(0, 3), (1, 2), (2, 2)] │ │ paly │ [(0, 3), (1, 2), (2, 2), (1, 3)] │ │ palas │ [(0, 3), (1, 2), (2, 2), (3, 3), (2, 3)] │ │ pall │ [(0, 3), (1, 2), (2, 2), (2, 1)] │ │ pals │ [(0, 3), (1, 2), (2, 2), (2, 3)] │ │ palsy │ [(0, 3), (1, 2), (2, 2), (2, 3), (1, 3)] │ │ palsa │ [(0, 3), (1, 2), (2, 2), (2, 3), (3, 3)] │ │ pal │ [(0, 3), (1, 2), (2, 1)] │ │ pall │ [(0, 3), (1, 2), (2, 1), (1, 0)] │ │ palls │ [(0, 3), (1, 2), (2, 1), (1, 0), (0, 0)] │ │ palla │ [(0, 3), (1, 2), (2, 1), (1, 0), (0, 1)] │ │ pall │ [(0, 3), (1, 2), (2, 1), (2, 2)] │ │ pally │ [(0, 3), (1, 2), (2, 1), (2, 2), (1, 3)] │ │ palla │ [(0, 3), (1, 2), (2, 1), (2, 2), (3, 3)] │ │ pallah │ [(0, 3), (1, 2), (2, 1), (2, 2), (3, 3), (3, 2)] │ │ pallahs │ [(0, 3), (1, 2), (2, 1), (2, 2), (3, 3), (3, 2), (2, 3)] │ │ palls │ [(0, 3), (1, 2), (2, 1), (2, 2), (2, 3)] │ │ pas │ [(0, 3), (1, 2), (2, 3)] │ │ pash │ [(0, 3), (1, 2), (2, 3), (3, 2)] │ │ pasha │ [(0, 3), (1, 2), (2, 3), (3, 2), (3, 3)] │ │ pay │ [(0, 3), (1, 2), (1, 3)] │ │ pays │ [(0, 3), (1, 2), (1, 3), (2, 3)] │ │ pi │ [(0, 3), (0, 2)] │ │ pia │ [(0, 3), (0, 2), (1, 2)] │ │ pial │ [(0, 3), (0, 2), (1, 2), (2, 2)] │ │ pial │ [(0, 3), (0, 2), (1, 2), (2, 1)] │ │ pias │ [(0, 3), (0, 2), (1, 2), (2, 3)] │ │ pia │ [(0, 3), (0, 2), (0, 1)] │ │ pial │ [(0, 3), (0, 2), (0, 1), (1, 0)] │ │ pias │ [(0, 3), (0, 2), (0, 1), (0, 0)] │ ╰─────────┴──────────────────────────────────────────────────────────╯ Starting @ (1, 0) ╭───────┬──────────────────────────────────────────╮ │ Word │ Path │ ├───────┼──────────────────────────────────────────┤ │ la │ [(1, 0), (0, 1)] │ │ las │ [(1, 0), (0, 1), (0, 0)] │ │ lull │ [(1, 0), (2, 0), (2, 1), (2, 2)] │ │ lulls │ [(1, 0), (2, 0), (2, 1), (2, 2), (2, 3)] │ ╰───────┴──────────────────────────────────────────╯ Starting @ (1, 1) ╭───────┬──────────────────────────────────╮ │ Word │ Path │ ├───────┼──────────────────────────────────┤ │ qua │ [(1, 1), (0, 1)] │ │ quai │ [(1, 1), (0, 1), (0, 2)] │ │ quip │ [(1, 1), (0, 2), (0, 3)] │ │ qua │ [(1, 1), (1, 2)] │ │ quai │ [(1, 1), (1, 2), (0, 2)] │ │ quash │ [(1, 1), (1, 2), (2, 3), (3, 2)] │ │ quay │ [(1, 1), (1, 2), (1, 3)] │ │ quays │ [(1, 1), (1, 2), (1, 3), (2, 3)] │ ╰───────┴──────────────────────────────────╯ Starting @ (1, 2) ╭────────┬──────────────────────────────────────────────────╮ │ Word │ Path │ ├────────┼──────────────────────────────────────────────────┤ │ ai │ [(1, 2), (0, 2)] │ │ aia │ [(1, 2), (0, 2), (0, 1)] │ │ aias │ [(1, 2), (0, 2), (0, 1), (0, 0)] │ │ aa │ [(1, 2), (0, 1)] │ │ aal │ [(1, 2), (0, 1), (1, 0)] │ │ aals │ [(1, 2), (0, 1), (1, 0), (0, 0)] │ │ aas │ [(1, 2), (0, 1), (0, 0)] │ │ al │ [(1, 2), (2, 2)] │ │ ala │ [(1, 2), (2, 2), (3, 3)] │ │ alas │ [(1, 2), (2, 2), (3, 3), (2, 3)] │ │ all │ [(1, 2), (2, 2), (2, 1)] │ │ allow │ [(1, 2), (2, 2), (2, 1), (3, 0), (3, 1)] │ │ als │ [(1, 2), (2, 2), (2, 3)] │ │ al │ [(1, 2), (2, 1)] │ │ all │ [(1, 2), (2, 1), (1, 0)] │ │ alls │ [(1, 2), (2, 1), (1, 0), (0, 0)] │ │ alow │ [(1, 2), (2, 1), (3, 0), (3, 1)] │ │ alu │ [(1, 2), (2, 1), (2, 0)] │ │ alula │ [(1, 2), (2, 1), (2, 0), (1, 0), (0, 1)] │ │ alulas │ [(1, 2), (2, 1), (2, 0), (1, 0), (0, 1), (0, 0)] │ │ all │ [(1, 2), (2, 1), (2, 2)] │ │ ally │ [(1, 2), (2, 1), (2, 2), (1, 3)] │ │ alls │ [(1, 2), (2, 1), (2, 2), (2, 3)] │ │ as │ [(1, 2), (2, 3)] │ │ asyla │ [(1, 2), (2, 3), (1, 3), (2, 2), (3, 3)] │ │ ash │ [(1, 2), (2, 3), (3, 2)] │ │ aqua │ [(1, 2), (1, 1), (0, 1)] │ │ aquas │ [(1, 2), (1, 1), (0, 1), (0, 0)] │ │ ay │ [(1, 2), (1, 3)] │ │ ays │ [(1, 2), (1, 3), (2, 3)] │ ╰────────┴──────────────────────────────────────────────────╯ Starting @ (1, 3) ╭──────┬──────────────────────────╮ │ Word │ Path │ ├──────┼──────────────────────────┤ │ yip │ [(1, 3), (0, 2), (0, 3)] │ │ ya │ [(1, 3), (1, 2)] │ │ yap │ [(1, 3), (1, 2), (0, 3)] │ │ yas │ [(1, 3), (1, 2), (2, 3)] │ ╰──────┴──────────────────────────╯ Starting @ (2, 0) ╭──────┬──────╮ │ Word │ Path │ ├──────┼──────┤ ╰──────┴──────╯ Starting @ (2, 1) ╭───────┬──────────────────────────────────────────╮ │ Word │ Path │ ├───────┼──────────────────────────────────────────┤ │ la │ [(2, 1), (1, 2)] │ │ lap │ [(2, 1), (1, 2), (0, 3)] │ │ las │ [(2, 1), (1, 2), (2, 3)] │ │ lash │ [(2, 1), (1, 2), (2, 3), (3, 2)] │ │ lay │ [(2, 1), (1, 2), (1, 3)] │ │ lays │ [(2, 1), (1, 2), (1, 3), (2, 3)] │ │ lo │ [(2, 1), (3, 0)] │ │ lou │ [(2, 1), (3, 0), (2, 0)] │ │ low │ [(2, 1), (3, 0), (3, 1)] │ │ lowly │ [(2, 1), (3, 0), (3, 1), (2, 2), (1, 3)] │ ╰───────┴──────────────────────────────────────────╯ Starting @ (2, 2) ╭───────┬──────────────────────────────────────────╮ │ Word │ Path │ ├───────┼──────────────────────────────────────────┤ │ la │ [(2, 2), (1, 2)] │ │ lap │ [(2, 2), (1, 2), (0, 3)] │ │ lall │ [(2, 2), (1, 2), (2, 1), (1, 0)] │ │ lalls │ [(2, 2), (1, 2), (2, 1), (1, 0), (0, 0)] │ │ las │ [(2, 2), (1, 2), (2, 3)] │ │ lash │ [(2, 2), (1, 2), (2, 3), (3, 2)] │ │ lay │ [(2, 2), (1, 2), (1, 3)] │ │ lays │ [(2, 2), (1, 2), (1, 3), (2, 3)] │ │ la │ [(2, 2), (3, 3)] │ │ las │ [(2, 2), (3, 3), (2, 3)] │ │ lash │ [(2, 2), (3, 3), (2, 3), (3, 2)] │ │ lah │ [(2, 2), (3, 3), (3, 2)] │ │ lahs │ [(2, 2), (3, 3), (3, 2), (2, 3)] │ ╰───────┴──────────────────────────────────────────╯ Starting @ (2, 3) ╭─────────┬──────────────────────────────────────────────────────────╮ │ Word │ Path │ ├─────────┼──────────────────────────────────────────────────────────┤ │ sai │ [(2, 3), (1, 2), (0, 2)] │ │ sap │ [(2, 3), (1, 2), (0, 3)] │ │ sal │ [(2, 3), (1, 2), (2, 2)] │ │ sall │ [(2, 3), (1, 2), (2, 2), (2, 1)] │ │ sallow │ [(2, 3), (1, 2), (2, 2), (2, 1), (3, 0), (3, 1)] │ │ sal │ [(2, 3), (1, 2), (2, 1)] │ │ sall │ [(2, 3), (1, 2), (2, 1), (1, 0)] │ │ sall │ [(2, 3), (1, 2), (2, 1), (2, 2)] │ │ sally │ [(2, 3), (1, 2), (2, 1), (2, 2), (1, 3)] │ │ say │ [(2, 3), (1, 2), (1, 3)] │ │ sal │ [(2, 3), (3, 3), (2, 2)] │ │ salal │ [(2, 3), (3, 3), (2, 2), (1, 2), (2, 1)] │ │ sall │ [(2, 3), (3, 3), (2, 2), (2, 1)] │ │ sallow │ [(2, 3), (3, 3), (2, 2), (2, 1), (3, 0), (3, 1)] │ │ sh │ [(2, 3), (3, 2)] │ │ sha │ [(2, 3), (3, 2), (3, 3)] │ │ shaly │ [(2, 3), (3, 2), (3, 3), (2, 2), (1, 3)] │ │ shall │ [(2, 3), (3, 2), (3, 3), (2, 2), (2, 1)] │ │ shallow │ [(2, 3), (3, 2), (3, 3), (2, 2), (2, 1), (3, 0), (3, 1)] │ │ slap │ [(2, 3), (2, 2), (1, 2), (0, 3)] │ │ slay │ [(2, 3), (2, 2), (1, 2), (1, 3)] │ │ sly │ [(2, 3), (2, 2), (1, 3)] │ ╰─────────┴──────────────────────────────────────────────────────────╯ Starting @ (3, 0) ╭───────┬──────────────────────────────────────────╮ │ Word │ Path │ ├───────┼──────────────────────────────────────────┤ │ ou │ [(3, 0), (2, 0)] │ │ olla │ [(3, 0), (2, 1), (1, 0), (0, 1)] │ │ ollas │ [(3, 0), (2, 1), (1, 0), (0, 1), (0, 0)] │ │ olla │ [(3, 0), (2, 1), (2, 2), (1, 2)] │ │ ollas │ [(3, 0), (2, 1), (2, 2), (1, 2), (2, 3)] │ │ olla │ [(3, 0), (2, 1), (2, 2), (3, 3)] │ │ ollas │ [(3, 0), (2, 1), (2, 2), (3, 3), (2, 3)] │ │ ow │ [(3, 0), (3, 1)] │ │ owl │ [(3, 0), (3, 1), (2, 1)] │ │ owl │ [(3, 0), (3, 1), (2, 2)] │ │ owly │ [(3, 0), (3, 1), (2, 2), (1, 3)] │ │ owls │ [(3, 0), (3, 1), (2, 2), (2, 3)] │ ╰───────┴──────────────────────────────────────────╯ Starting @ (3, 1) ╭───────┬──────────────────────────────────────────╮ │ Word │ Path │ ├───────┼──────────────────────────────────────────┤ │ wull │ [(3, 1), (2, 0), (1, 0), (2, 1)] │ │ wull │ [(3, 1), (2, 0), (2, 1), (1, 0)] │ │ wulls │ [(3, 1), (2, 0), (2, 1), (1, 0), (0, 0)] │ │ wull │ [(3, 1), (2, 0), (2, 1), (2, 2)] │ │ wulls │ [(3, 1), (2, 0), (2, 1), (2, 2), (2, 3)] │ │ wo │ [(3, 1), (3, 0)] │ │ wolly │ [(3, 1), (3, 0), (2, 1), (2, 2), (1, 3)] │ │ wha │ [(3, 1), (3, 2), (3, 3)] │ ╰───────┴──────────────────────────────────────────╯ Starting @ (3, 2) ╭────────┬──────────────────────────────────────────────────╮ │ Word │ Path │ ├────────┼──────────────────────────────────────────────────┤ │ ha │ [(3, 2), (3, 3)] │ │ has │ [(3, 2), (3, 3), (2, 3)] │ │ halal │ [(3, 2), (3, 3), (2, 2), (1, 2), (2, 1)] │ │ hall │ [(3, 2), (3, 3), (2, 2), (2, 1)] │ │ hallo │ [(3, 2), (3, 3), (2, 2), (2, 1), (3, 0)] │ │ hallow │ [(3, 2), (3, 3), (2, 2), (2, 1), (3, 0), (3, 1)] │ ╰────────┴──────────────────────────────────────────────────╯ Starting @ (3, 3) ╭────────┬──────────────────────────────────────────────────╮ │ Word │ Path │ ├────────┼──────────────────────────────────────────────────┤ │ as │ [(3, 3), (2, 3)] │ │ asyla │ [(3, 3), (2, 3), (1, 3), (2, 2), (1, 2)] │ │ ash │ [(3, 3), (2, 3), (3, 2)] │ │ al │ [(3, 3), (2, 2)] │ │ ala │ [(3, 3), (2, 2), (1, 2)] │ │ alap │ [(3, 3), (2, 2), (1, 2), (0, 3)] │ │ alas │ [(3, 3), (2, 2), (1, 2), (2, 3)] │ │ alay │ [(3, 3), (2, 2), (1, 2), (1, 3)] │ │ alays │ [(3, 3), (2, 2), (1, 2), (1, 3), (2, 3)] │ │ all │ [(3, 3), (2, 2), (2, 1)] │ │ allay │ [(3, 3), (2, 2), (2, 1), (1, 2), (1, 3)] │ │ allays │ [(3, 3), (2, 2), (2, 1), (1, 2), (1, 3), (2, 3)] │ │ allow │ [(3, 3), (2, 2), (2, 1), (3, 0), (3, 1)] │ │ als │ [(3, 3), (2, 2), (2, 3)] │ │ ah │ [(3, 3), (3, 2)] │ │ ahs │ [(3, 3), (3, 2), (2, 3)] │ ╰────────┴──────────────────────────────────────────────────╯
Build
Navigate to the project root folder and run the following.
Run poetry build
License
The included wordlists are covered by their respective licenses. All other files MIT © Cameron Blankenbuehler
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
File details
Details for the file boggler-2.0.4.tar.gz.
File metadata
- Download URL: boggler-2.0.4.tar.gz
- Upload date:
- Size: 3.7 MB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via: poetry/1.8.3 CPython/3.12.4 Linux/6.6.34-1-lts
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 | 81abd6b672fb35fef523063c20b08a9d64c5ca70944767b8913b995c0315d378 |
|
| MD5 | 192b1be98dc40f8592401ae2ea225918 |
|
| BLAKE2b-256 | 994b3d5c7e90098588139cf2660e853620d4c95110cd01804afaa175efb20594 |
File details
Details for the file boggler-2.0.4-py3-none-any.whl.
File metadata
- Download URL: boggler-2.0.4-py3-none-any.whl
- Upload date:
- Size: 3.7 MB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via: poetry/1.8.3 CPython/3.12.4 Linux/6.6.34-1-lts
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 | 94ee177920fffcd3cca2071a5e0ad0e00b7c33e6812dc63a9fdca61b28149984 |
|
| MD5 | 203a1c0b0fcd013b11b96b855c70ccae |
|
| BLAKE2b-256 | 87d0400c588595193d09f8ae55a1725f02b3003cc453d6d940e9ec1fa7d1457c |
