1 /* mnemon - A memory training library
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."
20 #ifndef MNEMON_H_INCLUDED
21 #define MNEMON_H_INCLUDED
23 typedef struct _bin bin_t;
24 typedef struct _category category_t;
26 typedef struct _mnemon {
31 category_t *categories;
43 /* Initialize a new mnemon object. This function must be called before
44 * any other mnemon functions are used. */
46 mnemon_init (mnemon_t *mnemon);
48 /* Inidicate the caller is finished with a mnemon object. Free all
49 * resources associated with this object. After this call, the given
50 * mnemon object should not be passed to any other menmon function,
51 * (except mnemon_init to start over). */
53 mnemon_fini (mnemon_t *mnemon);
55 /* Load a specific category of mnemon challenges. The name should
56 * indicate the name of a file within the user's .mnemon directory. */
58 mnemon_load_category (mnemon_t *mnemon,
61 /* Load all categories of mnemon challenges.
63 * This is equivalent to calling mnemon_load_category for all files
64 * found within the user's .mnemon directory. */
66 mnemon_load (mnemon_t *mnemon);
68 /* Run a series of memory challenges acoording to the to_introduce and
69 * to_master counters as set on the given mnemon object.
71 * The challenge system is designed to rapidly reinforce items needing
72 * to be learned and provide exponentially less reinforcement for
73 * items as mastery is displayed. This is achieved by storing the
74 * items in a series of numberred bins.
76 * Items start in bin 0 indicating that they have never been presented
77 * to a user. When an item is presented to the user and answered
78 * correctly, it is moved into the bin of the next higher number.
80 * However, when an item is answered incorrectly, it is moved directly
81 * to bin -2 (if coming from a bin of a positive number), or the bin
82 * of the next lower integer (more negative) if coming from a bin of a
85 * When selecting a new item to challenge, first a bin is chosen
86 * (considering only the non-empty bins). The bin with the lowest
87 * number is the most likely to be chosen, while each succesively-
88 * higher-numbered bin has a probability one-half of that of the
91 * A session of challenges consists of three phases, some of which may
92 * be entirely empty, as follows:
94 * 1. The introduction phase
96 * This phase is controlled by the to_introduce counter which is
97 * by default set to 10. It is decremented every time an item is
98 * introduced from the bin with score 0, or (if there is no bin
99 * with score 0), every time an item is introduced from the bin
100 * with the lowest non-negative score of any bin.
102 * 2. The mastering phase
104 * This phase is controlled by the to_master counter which is
105 * initially set to 10. It begins at the beginning of the session
106 * so can run concurrently with the introduction phase. The
107 * to_master counter is decremented every time an item with a
108 * positive (non-zero) score is answered correctly. It is also
109 * incremented every time an item with a positive (non-zero) score
110 * is answered incorrectly during the introduction phase. If
111 * perfect mastery is demonstrated, the mastering phase is likely
112 * to be complete simultaneous with the introduction stage. If the
113 * user is really struggling with mastery, the mastering phase
114 * will extend long after the introduction phase is over. But
115 * since we never incremeent to_master after the introduction
116 * phase is over, the user cannot build an infinite snowball of
117 * to_master items and have to give up in despair.
119 * 3. The solidifying phase
121 * This final phase continues after the mastering phase for as
122 * long as any items with a negative score remain. The idea here
123 * is that we want to quickly give the reinforcement from a missed
124 * item in the current session. Also, there's a bit of a challenge
125 * to the user to demonstrate good mastery of any non-negative
126 * items presented so that the phase actually terminates. It's
127 * possible for this phase to extend for an arbitrary amount of
128 * time, but not very likely, (since the negative items are chosen
129 * preferentially and the user will continue to see the correct
130 * answers to them over and over).
132 * This function returns after all three phases are complete.
134 * The user's progress (the movement of items to various new bins) is
135 * kept only in memory. In order to save this progress to disk, the
136 * caller must call mnemon_save.
139 mnemon_do_challenges (mnemon_t *mnemon);
141 /* Save the user's progress by updating the category files in the
142 * users .mnemon directory. */
144 mnemon_save (mnemon_t *mnemon);
146 /* Print a histogram showing the number of items in each bin.
148 * If category_name is not NULL, then only the items from the given
149 * category (matching a particular filename within the user's .mnemon
150 * directory) will be shown.
152 * If length is non zero, then only items with a challenge string of
153 * 'length' characters will be shown. (This is only useful for
154 * particular types of challenges, such as for showing anagram
155 * challenges of a given length).
157 * To see a histogram of all currently-loaded items, pass NULL for
158 * category and 0 for length.
160 * Note: Some bins may be removed entirely by (a misfeature side
161 * effect of) the mnemon_do_challenges function, (such as bin 0 being
162 * removed after the introduction phase is complete). An accurate
163 * histogram can be guaranteed by calling menmon_print_histogram
164 * immediately after calling mnemon_load.
167 mnemon_print_histogram (mnemon_t *mnemon,
168 const char *category_name,