git.cworth.org Git - mnemon/blob - mnemon.h

   1 /* mnemon - A memory training library
   2  *
   3  * Copyright © 2006,2011 Carl Worth
   4  *
   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)
   8  * any later version.
   9  *
  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.
  14  *
  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."
  18  */
  19
  20 #ifndef MNEMON_H_INCLUDED
  21 #define MNEMON_H_INCLUDED
  22
  23 typedef struct _bin bin_t;
  24 typedef struct _category category_t;
  25
  26 typedef struct _mnemon {
  27     char *dir_name;
  28
  29     int categories_size;
  30     int num_categories;
  31     category_t *categories;
  32
  33     int bins_size;
  34     int num_bins;
  35     bin_t *bins;
  36
  37     int to_introduce;
  38     int to_master;
  39     int unlearned;
  40     int mastered;
  41 } mnemon_t;
  42
  43 /* Initialize a new mnemon object. This function must be called before
  44  * any other mnemon functions are used. */
  45 void
  46 mnemon_init (mnemon_t *mnemon);
  47
  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). */
  52 void
  53 mnemon_fini (mnemon_t *mnemon);
  54
  55 /* Load a specific category of mnemon challenges. The name should
  56  * indicate the name of a file within the user's .mnemon directory. */
  57 void
  58 mnemon_load_category (mnemon_t          *mnemon,
  59                       const char        *name);
  60
  61 /* Load all categories of mnemon challenges.
  62  *
  63  * This is equivalent to calling mnemon_load_category for all files
  64  * found within the user's .mnemon directory. */
  65 void
  66 mnemon_load (mnemon_t *mnemon);
  67
  68 /* Run a series of memory challenges acoording to the to_introduce and
  69  * to_master counters as set on the given mnemon object.
  70  *
  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.
  75  *
  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.
  79  *
  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
  83  * negative number.
  84  *
  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
  89  * previous bin.
  90  *
  91  * A session of challenges consists of three phases, some of which may
  92  * be entirely empty, as follows:
  93  *
  94  * 1. The introduction phase
  95  *
  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.
 101  *
 102  * 2. The mastering phase
 103  *
 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.
 118  *
 119  * 3. The solidifying phase
 120  *
 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).
 131  *
 132  * This function returns after all three phases are complete.
 133  *
 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.
 137  */
 138 void
 139 mnemon_do_challenges (mnemon_t *mnemon);
 140
 141 /* Save the user's progress by updating the category files in the
 142  * users .mnemon directory. */
 143 void
 144 mnemon_save (mnemon_t *mnemon);
 145
 146 /* Print a histogram showing the number of items in each bin.
 147  *
 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.
 151  *
 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).
 156  *
 157  * To see a histogram of all currently-loaded items, pass NULL for
 158  * category and 0 for length.
 159  *
 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.
 165  */
 166 void
 167 mnemon_print_histogram (mnemon_t    *mnemon,
 168                         const char  *category_name,
 169                         int          length);
 170
 171 #endif