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
1 maintainer
Release files for boggler 2.0.4
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| boggler-2.0.4.tar.gz | 3.7 MB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| boggler-2.0.4-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 7.4 MB
Release files / boggler-2.0.4.tar.gz
| Download URL | boggler-2.0.4.tar.gz |
|---|---|
| Size | 3.7 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
81abd6b672fb35fef523063c20b08a9d64c5ca70944767b8913b995c0315d378
|
|
BLAKE2b-256 checksum How to use checksums |
994b3d5c7e90098588139cf2660e853620d4c95110cd01804afaa175efb20594
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
poetry/1.8.3 CPython/3.12.4 Linux/6.6.34-1-lts
|
Release files / boggler-2.0.4-py3-none-any.whl
| Download URL | boggler-2.0.4-py3-none-any.whl |
|---|---|
| Size | 3.7 MB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
94ee177920fffcd3cca2071a5e0ad0e00b7c33e6812dc63a9fdca61b28149984
|
|
BLAKE2b-256 checksum How to use checksums |
87d0400c588595193d09f8ae55a1725f02b3003cc453d6d940e9ec1fa7d1457c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
poetry/1.8.3 CPython/3.12.4 Linux/6.6.34-1-lts
|
