README.org


1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97

#+SETUPFILE: ~/.emacs.d/org-templates/projects.org
#+EXPORT_FILE_NAME: index
#+OPTIONS: toc:2
#+TITLE: Octans

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

* Demo
This was recorded with =asciinema(1)=.

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

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

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

*** 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.1 - 2020-01-20
+ Read puzzle from a file.

** v0.1.0 - 2020-01-19
This version improved performance by re-implementing the algorithm to
find words in grid.
#include <stdarg.h>
#include <stddef.h>
#include <setjmp.h>
#include <cmocka.h>
#include <stdlib.h>

#include "tools/history.h"

void previous_on_empty_returns_null(void **state)
{
    History history = history_new(10);
    char *item = history_previous(history, "inp");

    assert_null(item);
}

void next_on_empty_returns_null(void **state)
{
    History history = history_new(10);
    char *item = history_next(history, "inp");

    assert_null(item);
}

void previous_once_returns_last(void **state)
{
    History history = history_new(10);
    history_append(history, "Hello");

    char *item = history_previous(history, "inp");

    assert_string_equal("Hello", item);
}

void previous_twice_when_one_returns_first(void **state)
{
    History history = history_new(10);
    history_append(history, "Hello");

    char *item1 = history_previous(history, NULL);
    char *item2 = history_previous(history, item1);

    assert_string_equal("Hello", item2);
}

void previous_always_stops_at_first(void **state)
{
    History history = history_new(10);
    history_append(history, "Hello");

    char *item1 = history_previous(history, NULL);
    char *item2 = history_previous(history, item1);
    char *item3 = history_previous(history, item2);
    char *item4 = history_previous(history, item3);
    char *item5 = history_previous(history, item4);
    char *item6 = history_previous(history, item5);

    assert_string_equal("Hello", item6);
}

void previous_goes_to_correct_element(void **state)
{
    History history = history_new(10);
    history_append(history, "Hello");
    history_append(history, "world");
    history_append(history, "whats");
    history_append(history, "going");
    history_append(history, "on");
    history_append(history, "here");

    char *item1 = history_previous(history, NULL);
    char *item2 = history_previous(history, item1);
    char *item3 = history_previous(history, item2);

    assert_string_equal("going", item3);
}

void prev_then_next_returns_empty(void **state)
{
    History history = history_new(10);
    history_append(history, "Hello");

    char *item1 = history_previous(history, NULL);
    char *item2 = history_next(history, item1);

    assert_string_equal("", item2);
}

void prev_with_val_then_next_returns_val(void **state)
{
    History history = history_new(10);
    history_append(history, "Hello");

    char *item1 = history_previous(history, "Oioi");
    char *item2 = history_next(history, item1);

    assert_string_equal("Oioi", item2);
}

void prev_with_val_then_next_twice_returns_null(void **state)
{
    History history = history_new(10);
    history_append(history, "Hello");

    char *item1 = history_previous(history, "Oioi");
    char *item2 = history_next(history, item1);
    char *item3 = history_next(history, item2);

    assert_null(item3);
}

void navigate_then_append_new(void **state)
{
    History history = history_new(10);
    history_append(history, "Hello");
    history_append(history, "again");
    history_append(history, "testing");
    history_append(history, "history");
    history_append(history, "append");

    char *item1 = history_previous(history, "new text");
    assert_string_equal("append", item1);

    char *item2 = history_previous(history, item1);
    assert_string_equal("history", item2);

    char *item3 = history_previous(history, item2);
    assert_string_equal("testing", item3);

    char *item4 = history_next(history, item3);
    assert_string_equal("history", item4);

    char *item5 = history_next(history, item4);
    assert_string_equal("append", item5);

    char *item6 = history_next(history, item5);
    assert_string_equal("new text", item6);
}

void edit_item_mid_history(void **state)
{
    History history = history_new(10);
    history_append(history, "Hello");
    history_append(history, "again");
    history_append(history, "testing");
    history_append(history, "history");
    history_append(history, "append");

    char *item1 = history_previous(history, "new item");
    assert_string_equal("append", item1);

    char *item2 = history_previous(history, item1);
    assert_string_equal("history", item2);

    char *item3 = history_previous(history, item2);
    assert_string_equal("testing", item3);

    char *item4 = history_previous(history, "EDITED");
    assert_string_equal("again", item4);

    char *item5 = history_previous(history, item4);
    assert_string_equal("Hello", item5);

    char *item6 = history_next(history, item5);
    assert_string_equal("again", item6);

    char *item7 = history_next(history, item6);
    assert_string_equal("EDITED", item7);

    char *item8 = history_next(history, item7);
    assert_string_equal("history", item8);

    char *item9 = history_next(history, item8);
    assert_string_equal("append", item9);

    char *item10 = history_next(history, item9);
    assert_string_equal("new item", item10);
}

void edit_previous_and_append(void **state)
{
    History history = history_new(10);
    history_append(history, "Hello");
    history_append(history, "again");
    history_append(history, "testing");
    history_append(history, "history");
    history_append(history, "append");

    char *item1 = history_previous(history, "new item");
    assert_string_equal("append", item1);

    char *item2 = history_previous(history, item1);
    assert_string_equal("history", item2);

    char *item3 = history_previous(history, item2);
    assert_string_equal("testing", item3);

    history_append(history, "EDITED");

    char *item4 = history_previous(history, NULL);
    assert_string_equal("EDITED", item4);
}

void start_session_add_new_submit_previous(void **state)
{
    History history = history_new(10);
    history_append(history, "hello");

    char *item1 = history_previous(history, NULL);
    assert_string_equal("hello", item1);

    char *item2 = history_next(history, item1);
    assert_string_equal("", item2);

    char *item3 = history_previous(history, "new text");
    assert_string_equal("hello", item3);

    history_append(history, item3);
}