path: root/README

           ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
                                 OCTANS
             Octans is a program to solve Algot's Wordplay
                          (Wordsearch) puzzles

                                Andinus
           ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━


Table of Contents
─────────────────

Demo
Installation
Documentation
News


━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 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.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>


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


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 [PGP Key].

  ┌────
  │ # Clone the project.
  │ git clone https://git.tilde.institute/andinus/octans
  │ cd octans
  │
  │ # Install octans.
  │ zef install .
  └────


[PGP Key]
<https://andinus.nand.sh/static/D9AE4AEEE1F1B3598E81D9DFB67D55D482A799FD.asc>


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.