path: root/README.org

#+title: Octans
#+subtitle: Octans is a program to solve Algot's Wordplay (Wordsearch) puzzles
#+export_file_name: index
#+setupfile: ~/.emacs.d/org-templates/projects.org

| Website         | https://andinus.nand.sh/octans             |
| Source          | https://git.tilde.institute/andinus/octans |
| GitHub (mirror) | https://github.com/andinus/octans          |

* Demo

This was recorded with ~asciinema~.

[[https://asciinema.org/a/385500][https://asciinema.org/a/385500.png]]

+ Octans v0.1.0 - finds 10 solutions to a puzzle:
  https://asciinema.org/a/385598
+ Octans v0.1.0: https://asciinema.org/a/385500

+ Octans 2021-01-14: https://asciinema.org/a/384464
+ alt-link (download): https://andinus.nand.sh/static/octans

* Installation

Octans is released to CPAN, you can get it from there or install it from
source. In any case, ~zef~ is required to install the distribution.

You can run Octans without ~zef~. Just run ~raku -Ilib bin/octans~ from
within the source directory.

** Release

1. Run ~zef install octans~.

Octans should be installed, try running ~octans --version~ to confirm.

** From Source

You can either download the release archive generated by cgit/GitHub or
clone the project if you have ~git~ installed.

*** Without ~git~

1. Download the release:
   - https://git.tilde.institute/andinus/octans
   - https://github.com/andinus/octans/releases
2. Extract the file.
3. Run ~zef install .~ in source directory.

*** With ~git~

All commits will be signed by my [[https://andinus.nand.sh/static/D9AE4AEEE1F1B3598E81D9DFB67D55D482A799FD.asc][PGP Key]].

#+begin_src sh
# Clone the project.
git clone https://git.tilde.institute/andinus/octans
cd octans

# Install octans.
zef install .
#+end_src

* Documentation

** Implementation

Initially it went over the list of words & checked if they exist in the
grid. This was very slow.

Currently it walks the grid & checks if the current string exist in the
dictionary. This is faster for these reasons:

- The dictionary is sorted, we perform binary range search on the
  dictionary to return the list of all words that start with specific
  string.
- Starting positions are limited.

If the dictionary wasn't sorted then this probably would've been slower
than previous implementation.

The ~neighbors~ subroutine (=lib/Octans/Neighbors.rakumod=) was taken from
my AoC (Advent of Code) 2020's day-11 solution.

** Options

*** dict

Octans's default dictionary file is =/usr/share/dict/words=, use ~--dict~
flag to change the dictionary. The words in dictionary must be seperated
by a newline (=\n=) & sorted alphabetically.

*** length

Minimum word length to look for. Default is 7.

*** path

The path to be passed must be a *readable file* or an *url* in either
format:

- Link when you view it from your local instance:
  https://tilde.zone/web/statuses/105531207939242077

- Link from Algot's profile:
  https://mastodon.art/@Algot/105333136907848390

*** verbose

This will increase verbosity.

* News

** v0.1.4 - 2021-02-19

+ Fix the puzzle parsing regex

  The older regex fails to parse this puzzle:
  https://mastodon.art/@Algot/105690195742318751.

** v0.1.3 - 2021-01-24

+ Added an option to specify minimum word length.

** v0.1.2 - 2021-01-20

+ Input puzzle can now be of any size & not restricted to 4x4 grid.

** v0.1.1 - 2021-01-20

+ Read puzzle from a file.

** v0.1.0 - 2021-01-19

+ Improved performance by using a better algorithm to find words in the
  grid.