1 /* mnemon - A memory training program
3 * Copyright © 2006,2011 Carl Worth
5 * This program is free software; you can redistribute it and/or modify
6 * it under the terms of the GNU General Public License as published by
7 * the Free Software Foundation; either version 3, or (at your option)
10 * This program is distributed in the hope that it will be useful,
11 * but WITHOUT ANY WARRANTY; without even the implied warranty of
12 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13 * GNU General Public License for more details.
15 * You should have received a copy of the GNU General Public License
16 * along with this program; if not, write to the Free Software Foundation,
17 * Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA."
28 #include <sys/types.h>
37 #include <readline/readline.h>
38 #include <readline/history.h>
42 #define ASSERT_NOT_REACHED \
44 static const int NOT_REACHED = 0; \
45 assert (NOT_REACHED); \
48 typedef struct progress {
56 xstrndup (const char *s, size_t n)
62 fprintf (stderr, "Error: out of memory\n");
70 xasprintf (char **strp, const char *fmt, ...)
76 ret = vasprintf (strp, fmt, ap);
80 fprintf (stderr, "Error: out of memory\n");
86 _show_challenge (mnemon_t *mnemon,
87 const char *challenge_type,
88 const char *challenge)
93 if (strcmp (challenge_type, "text") == 0) {
94 printf ("%s\n", challenge);
98 /* XXX: Yes, shelling out to system is total cheese. The planned
99 * fix here is to bring graphical display in process, (or at least
100 * have a custom external program that accepts image filenames on
103 if (strcmp (challenge_type, "image") == 0) {
104 program = "xli -gamma 2.2";
105 } else if (strcmp (challenge_type, "audio") == 0) {
107 } else if (strcmp (challenge_type, "midi") == 0) {
108 program = "timidity -Os";
109 } else if (strcmp (challenge_type, "text-to-speech") == 0) {
110 program = "mnemon-tts";
112 fprintf (stderr, "Error: unsupported challenge type: %s\n",
117 xasprintf (&command, "%s %s/%s >/dev/null 2>&1 &",
126 _hide_challenge (unused (mnemon_t *mnemon),
127 const char *challenge_type)
131 if (strcmp (challenge_type, "image"))
134 /* XXX: And this is just embarrassing (obviously wrong in several
135 * ways). Hopefully I'll amend away any commit that includes this.
137 xasprintf (&command, "killall xli");
142 typedef int (item_match_predicate_t) (void *closure, item_t *item);
144 /* Return the number of items in the bin from the given category (or
145 * from all categories if category == NULL) */
147 bin_num_items_matching (bin_t *bin,
148 item_match_predicate_t *predicate,
151 int i, num_items = 0;
153 if (predicate == NULL)
154 return bin->num_items;
156 for (i = 0; i < bin->num_items; i++)
157 if ((predicate) (closure, bin->items[i]))
163 typedef struct _item_in_category_closure
166 category_t *category;
167 } item_in_category_closure_t;
170 mnemon_item_in_category (void *closure, item_t *item)
172 item_in_category_closure_t *iicc = closure;
173 mnemon_t *mnemon = iicc->mnemon;
174 category_t *category = iicc->category;
176 return (mnemon_item_category (mnemon, item) == category);
179 typedef struct _item_in_category_of_length_closure
182 category_t *category;
184 } item_in_category_of_length_closure_t;
187 mnemon_item_in_category_of_length (void *closure, item_t *item)
189 item_in_category_of_length_closure_t *iicolc = closure;
190 mnemon_t *mnemon = iicolc->mnemon;
191 category_t *category = iicolc->category;
192 unsigned int length = iicolc->length;
194 if (mnemon_item_category (mnemon, item) != category)
197 return strlen (item->challenge) == length;
200 #define HISTOGRAM_ROW_FORMAT "%3d: %3d"
201 #define HISTOGRAM_BAR_WIDTH 63
204 print_histogram_bar (double size,
207 int units_per_cell = (int) ceil (max / HISTOGRAM_BAR_WIDTH);
208 static char const *boxes[8] = {
213 while (size > units_per_cell) {
215 size -= units_per_cell;
218 size /= units_per_cell;
222 else if (size > 6.5/8.0)
224 else if (size > 5.5/8.0)
226 else if (size > 4.5/8.0)
228 else if (size > 3.5/8.0)
230 else if (size > 2.5/8.0)
232 else if (size > 1.5/8.0)
234 else if (size > 0.5/8.0)
240 /* Print a histogram showing the number of items in each bin.
242 * If category_name is not NULL, then only the items from the given
243 * category (matching a particular filename within the user's .mnemon
244 * directory) will be shown.
246 * If length is non zero, then only items with a challenge string of
247 * 'length' characters will be shown. (This is only useful for
248 * particular types of challenges, such as for showing anagram
249 * challenges of a given length).
251 * To see a histogram of all currently-loaded items, pass NULL for
252 * category and 0 for length.
254 * Note: Some bins may be removed entirely by (a misfeature side
255 * effect of) the mnemon_do_challenges function, (such as bin 0 being
256 * removed after the introduction phase is complete). An accurate
257 * histogram can be guaranteed by calling menmon_print_histogram
258 * immediately after calling mnemon_load.
261 print_histogram (mnemon_t *mnemon,
262 const char *category_name,
265 int i, last_score, max;
266 category_t *category = NULL;
269 item_match_predicate_t *predicate = NULL;
270 void *closure = NULL;
271 item_in_category_closure_t item_in_category;
272 item_in_category_of_length_closure_t item_in_category_of_length;
274 if (mnemon->num_bins == 0)
278 category = mnemon_get_category_if_exists (mnemon, category_name);
281 predicate = mnemon_item_in_category_of_length;
282 item_in_category_of_length.mnemon = mnemon;
283 item_in_category_of_length.category = category;
284 item_in_category_of_length.length = length;
285 closure = &item_in_category_of_length;
287 predicate = mnemon_item_in_category;
288 item_in_category.mnemon = mnemon;
289 item_in_category.category = category;
290 closure = &item_in_category;
295 for (i = 0; i < mnemon->num_bins; i++) {
296 num_items = bin_num_items_matching (&mnemon->bins[i],
298 if (i == 0 || num_items > max)
302 for (i = 0; i < mnemon->num_bins; i++) {
303 bin = &mnemon->bins[i];
305 while (bin->score - last_score > 1)
306 printf (HISTOGRAM_ROW_FORMAT "\n", ++last_score, 0);
307 num_items = bin_num_items_matching (bin,
309 printf (HISTOGRAM_ROW_FORMAT " ", bin->score, num_items);
310 print_histogram_bar (num_items, max);
311 last_score = bin->score;
316 _handle_command (mnemon_t *mnemon,
321 switch (command[0]) {
322 /* 'h' for histogram */
325 char *category = NULL;
329 arg += strspn (arg, " \t");
330 len = strcspn (arg, " \t");
332 category = xstrndup (arg, len);
334 arg += strspn (arg, " \t");
338 print_histogram (mnemon, category, length);
344 /* Nothing necessary for repeating. */
348 printf ("Unknown command: %s\n", command);
354 _handle_response (mnemon_t *mnemon,
358 const char *response,
359 double response_time,
361 progress_t *progress)
364 int old_score = item->score;
366 correct = (strcmp (response, item->response) == 0);
370 printf (" %s is the correct answer.",
375 (time_limit != 0.0 && response_time > time_limit))
377 printf ("Correct, but not quite quick enough (%0.2f seconds---needed %0.2f seconds)\n",
378 response_time, time_limit);
382 mnemon_score_item (mnemon, bin, item_index, correct);
386 if (item->score < 0) {
387 printf ("Yes---just give me %d more.",
389 } else if (item->score == 1) {
391 progress->unlearned--;
392 printf ("You got it!");
394 printf ("On your first try, no less!");
397 printf ("Masterful (%dx).", item->score);
398 if (progress->to_master)
399 progress->to_master--;
403 printf (" Oops, you knew that, right? (%dx)\n ",
405 progress->unlearned++;
406 /* We increase to_master here as an extra penalty. If the
407 * user is forgetting stuff learned previously, then more
408 * time should be spent on mastering than learning new
409 * items. Note that we only do this during the initial
410 * phase while new items are still being introduced. */
411 if (progress->to_introduce)
412 progress->to_master++;
417 if (progress->to_introduce)
418 printf ("%d to come. ", progress->to_introduce);
419 if (progress->unlearned)
420 printf ("%d still unlearned. ", progress->unlearned);
421 if (progress->to_introduce == 0 && progress->to_master > 0)
422 printf ("%d items to master", progress->to_master);
426 /* A session of challenges consists of three phases, some of which may
427 * be entirely empty, as follows:
429 * 1. The introduction phase
431 * This phase is controlled by the to_introduce counter which is
432 * by default set to 10. It is decremented every time an item is
433 * introduced from the bin with score 0, or (if there is no bin
434 * with score 0), every time an item is introduced from the bin
435 * with the lowest non-negative score of any bin.
437 * 2. The mastering phase
439 * This phase is controlled by the to_master counter which is
440 * initially set to 10. It begins at the beginning of the session
441 * so can run concurrently with the introduction phase. The
442 * to_master counter is decremented every time an item with a
443 * positive (non-zero) score is answered correctly. It is also
444 * incremented every time an item with a positive (non-zero) score
445 * is answered incorrectly during the introduction phase. If
446 * perfect mastery is demonstrated, the mastering phase is likely
447 * to be complete simultaneous with the introduction stage. If the
448 * user is really struggling with mastery, the mastering phase
449 * will extend long after the introduction phase is over. But
450 * since we never incremeent to_master after the introduction
451 * phase is over, the user cannot build an infinite snowball of
452 * to_master items and have to give up in despair.
454 * 3. The solidifying phase
456 * This final phase continues after the mastering phase for as
457 * long as any items with a negative score remain. The idea here
458 * is that we want to quickly give the reinforcement from a missed
459 * item in the current session. Also, there's a bit of a challenge
460 * to the user to demonstrate good mastery of any non-negative
461 * items presented so that the phase actually terminates. It's
462 * possible for this phase to extend for an arbitrary amount of
463 * time, but not very likely, (since the negative items are chosen
464 * preferentially and the user will continue to see the correct
465 * answers to them over and over).
467 * This function returns after all three phases are complete.
469 * The user's progress (the movement of items to various new bins) is
470 * kept only in memory. In order to save this progress to disk, the
471 * caller must call mnemon_save.
474 _do_challenges (mnemon_t *mnemon, progress_t *progress)
479 category_t *category;
483 /* Count the number of items with negative scores. */
484 progress->unlearned = 0;
485 for (i = 0; i < mnemon->num_bins; i++) {
486 bin = &mnemon->bins[i];
489 progress->unlearned += bin->num_items;
492 progress->to_introduce -= progress->unlearned;
493 if (progress->to_introduce < 0)
494 progress->to_introduce = 0;
496 /* Get rid of bin with score of 0 if we aren't going to be
497 * introducing anything from it. */
498 if (progress->to_introduce == 0) {
499 mnemon_remove_bin (mnemon, 0);
502 if (progress->unlearned) {
503 printf ("You've got %d items to learn already. ", progress->unlearned);
504 if (progress->to_introduce)
505 printf ("I'll introduce %d more as we go.", progress->to_introduce);
508 printf ("Introducing %d new items.\n", progress->to_introduce);
513 struct timeval start, end;
516 mnemon_select_item (mnemon, &bin, &item_index, &category, &introduced);
517 item = bin->items[item_index];
519 if (progress->to_introduce > 0 && introduced)
520 progress->to_introduce--;
523 if (category->time_limit > 0.0) {
524 response = readline ("The next one is timed. Press enter when ready:");
528 _show_challenge (mnemon, category->challenge_type,
531 gettimeofday (&start, NULL);
532 response = readline ("> ");
533 gettimeofday (&end, NULL);
535 _hide_challenge (mnemon, category->challenge_type);
537 /* Terminate on EOF */
538 if (response == NULL) {
543 if (response[0] == '/') {
544 _handle_command (mnemon, response + 1);
551 _handle_response (mnemon, bin, item_index,
553 (end.tv_sec + end.tv_usec / 1e6) -
554 (start.tv_sec + start.tv_usec / 1e6),
555 category->time_limit, progress);
558 /* Replay audio challenges for reinforcement. */
559 if (category->repeat)
561 _show_challenge (mnemon, category->challenge_type,
563 printf ("%s\n", item->challenge);
566 } while (progress->to_introduce ||
567 progress->unlearned ||
568 progress->to_master > 0);
572 main (int argc, char *argv[])
578 void _load_categories()
582 for (i = 1; i < argc; i++)
583 mnemon_load_category (&mnemon, argv[i]);
585 mnemon_load (&mnemon);
591 mnemon_init (&mnemon);
595 /* Set some reasonable defaults for a session */
596 progress.to_introduce = 10;
597 progress.to_master = 10;
598 progress.unlearned = 0;
599 progress.mastered = -1;
601 _do_challenges (&mnemon, &progress);
603 mnemon_save (&mnemon);
605 mnemon_fini (&mnemon);
607 mnemon_init (&mnemon);
611 printf ("Great job.\nHere are your current results:\n");
612 print_histogram (&mnemon, NULL, 0);
613 response = readline ("Press enter to quit.\n");
616 mnemon_fini (&mnemon);