path: root/README

                               ━━━━━━━━━
                                 OCTANS

                                Andinus
                               ━━━━━━━━━


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

1. Demo
2. Installation
.. 1. Release
.. 2. From Source
3. Documentation
.. 1. Implementation
.. 2. Options
4. News
.. 1. v0.1.1 - 2020-01-20
.. 2. v0.1.0 - 2020-01-19


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

• Website: <https://andinus.nand.sh/octans>
• Source: <https://git.tilde.institute/andinus/octans>
• GitHub: <https://github.com/andinus/octans>


1 Demo
══════

  This was recorded with `asciinema(1)'.

  [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 2020-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>


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


2.1 Release
───────────

  1. Run `zef install octans'.

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


2.2 From Source
───────────────

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


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


2.2.2 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>


3 Documentation
═══════════════

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


3.2 Options
───────────

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


3.2.2 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>


3.2.3 verbose
╌╌╌╌╌╌╌╌╌╌╌╌╌

  This will increase verbosity.


4 News
══════

4.1 v0.1.1 - 2020-01-20
───────────────────────

  ⁃ Read puzzle from a file.


4.2 v0.1.0 - 2020-01-19
───────────────────────

  This version improved performance by re-implementing the algorithm to
  find words in grid.