vimniscient 0.2.0__py3-none-any.whl

vimniscient/generate.py

@@ -0,0 +1,102 @@
+"""Practice texts made from a seed, for skills where any sentence will do.
+
+A lesson task can name a `generate` kind. Its Learn round keeps the authored
+text; Recall and reviews can get a generated one instead, so a skill gets
+practised on sentences you haven't seen. The same seed always gives the same
+task, so a run can be replayed and every kind can be checked in Neovim
+(tests/check_generate.py).
+
+The sentences stay mnemonic: they're the hooks from mnemonics.yaml (what keys
+stand for) and facts from lessons/sources.md.
+
+Kinds, all word text objects (w1d1):
+  ciw-typo    two letters of a word swapped; ciw and type it right
+  daw-double  a word doubled; daw deletes one copy and its space
+  ciW-dotted  a word written with dots between its letters; ciW rewrites it
+"""
+
+import random
+import re
+from dataclasses import replace
+from functools import cache
+
+from vimniscient.lessons import Task
+from vimniscient.mnemonics import _tables
+
+KINDS = ("ciw-typo", "daw-double", "ciW-dotted")
+
+# Facts from lessons/sources.md, one sentence each.
+FACTS = [
+    "Ebbinghaus tested himself on nonsense syllables and published his results in 1885.",
+    "Forgetting is steepest right after learning, then the curve levels off.",
+    "Miller wrote about the magical number seven, plus or minus two.",
+    "Cowan later argued that short-term memory holds about four chunks.",
+    "Retrieval practice beat restudying on a test a week later.",
+    "Restudying looked better after five minutes, which is why it feels like it works.",
+    "Spacing reviews out is among the best replicated findings about memory.",
+    "Sleep after learning helps new memories stabilise.",
+    "Rereading makes text feel familiar, and people mistake that for knowing it.",
+    "Words read aloud are remembered better than words read silently.",
+    "Mixed practice feels harder than blocked practice but tests better later.",
+    "Practising with variation helps a skill carry over to new conditions.",
+    "Trying to recall an answer before seeing it helps you remember it later.",
+    "Fitts and Posner described three stages of skill: cognitive, associative and autonomous.",
+    "Desirable difficulties make learning feel harder but make it last.",
+]
+
+
+@cache
+def sentences() -> list[str]:
+    hooks = list(dict.fromkeys(hook for table in _tables()[:2] for hook in table.values()))
+    # as written: a capital would change the key ("u is down" is not "U is down")
+    return [h + ("" if h.endswith(".") else ".") for h in hooks] + FACTS
+
+
+_WORD = re.compile(r"(?<![\w'.-])[A-Za-z]{4,}(?![\w'-])")
+
+
+def _words(sentence: str, spaced: bool) -> list[re.Match]:
+    """Plain words of four letters or more; `spaced` wants a space on both sides (a WORD)."""
+    found = list(_WORD.finditer(sentence))
+    if spaced:
+        found = [m for m in found if m.start() > 0 and sentence[m.start() - 1] == " "
+                 and m.end() < len(sentence) and sentence[m.end()] == " "]
+    else:  # daw and ciw want the word to have a space after it, or anything but a letter
+        found = [m for m in found if m.end() < len(sentence)]
+    return found
+
+
+def generate(kind: str, seed: str, parent: Task) -> Task:
+    """A `kind` task from `seed`, with the parent task's hint and place in its lesson."""
+    rng = random.Random(f"{kind}:{seed}")
+    while True:
+        sentence = rng.choice(sentences())
+        words = _words(sentence, spaced=kind == "ciW-dotted")
+        if kind == "daw-double":
+            words = [m for m in words if sentence[m.end()] == " "]
+        if kind == "ciw-typo":
+            words = [m for m in words if len(set(m.group()[1:-1])) > 1]
+        if words:
+            break
+    m = rng.choice(words)
+    word, before, after = m.group(), sentence[: m.start()], sentence[m.end():]
+    if kind == "ciw-typo":
+        while True:
+            i = rng.randrange(1, len(word) - 2)
+            if word[i] != word[i + 1]:
+                break
+        shown = word[:i] + word[i + 1] + word[i] + word[i + 2:]
+        start, cursor = before + shown + after, len(before) + rng.randrange(len(shown))
+        goal, solution = f'Fix "{shown}" to "{word}".', f"ciw{word}<Esc>"
+    elif kind == "daw-double":
+        start = before + word + " " + word + after
+        cursor = len(before) + rng.choice([0, len(word) + 1]) + rng.randrange(len(word))
+        goal, solution = f'Delete the doubled "{word}".', "daw"
+    elif kind == "ciW-dotted":
+        shown = ".".join(word)
+        start, cursor = before + shown + after, len(before) + rng.randrange(len(shown))
+        goal, solution = f'Write the dotted "{shown}" as "{word}".', f"ciW{word}<Esc>"
+    else:
+        raise ValueError(f"no generator called {kind}")
+    return replace(parent, goal=goal, start=[start], cursor=(1, cursor), target=[sentence],
+                   solution=solution, ft="", variants=[], generated=seed)

vimniscient/habits.py

@@ -0,0 +1,116 @@
+"""Bad habits, read from hardtime.nvim's log (~/.local/state/nvim/hardtime.nvim.log).
+
+hardtime writes three kinds of message:
+  Use dj instead of 2dd                          -> a card: what's shorter than 2dd?
+  You pressed the j key too soon! Use [count]j…  -> drill the motion lessons
+  The <Up> key is disabled!                      -> same, for arrow keys
+"""
+
+import os
+import re
+from collections import Counter
+from dataclasses import dataclass
+from datetime import date, datetime, timedelta
+from pathlib import Path
+
+from vimniscient.cards import Card, Deck
+from vimniscient.keys import split_keys
+
+LOG = Path(os.environ.get("XDG_STATE_HOME", Path.home() / ".local/state")) / "nvim" / "hardtime.nvim.log"
+
+_LINE = re.compile(r"^\[\w+\s+\w{3} (\d{2} \w{3} \d{4}) [^\]]*\] (.+)$")
+_USE = re.compile(r"^Use (.+) instead of (.+)$")
+_TOO_SOON = re.compile(r"^You pressed the (\S+) key too soon!")
+_DISABLED = re.compile(r"^The (\S+) key is disabled!")
+
+# Keys pressed over and over -> lessons that teach the better motions.
+DRILL_LESSONS = {
+    "j": ["w1d6-counts", "w2d2-search", "w1d3-sentences"],
+    "k": ["w1d6-counts", "w2d2-search", "w1d3-sentences"],
+    "h": ["w1d4-find", "w1d1-words"],
+    "l": ["w1d4-find", "w1d1-words"],
+}
+_ARROWS = {"<Down>": "j", "<Up>": "k", "<Left>": "h", "<Right>": "l"}
+
+
+@dataclass
+class Habit:
+    message: str
+    total: int
+    recent: int  # in the last two weeks
+    last: date
+
+
+def read_log() -> list[tuple[date, str]]:
+    if not LOG.exists():
+        return []
+    entries = []
+    for line in LOG.read_text(errors="replace").splitlines():
+        m = _LINE.match(line.strip())
+        if not m:
+            continue
+        try:
+            day = datetime.strptime(m.group(1), "%d %b %Y").date()
+        except ValueError:
+            continue
+        entries.append((day, m.group(2).strip()))
+    return entries
+
+
+def habits(days: int = 14) -> list[Habit]:
+    """Every distinct message, most frequent recently first."""
+    since = date.today() - timedelta(days=days)
+    total: Counter[str] = Counter()
+    recent: Counter[str] = Counter()
+    last: dict[str, date] = {}
+    for day, message in read_log():
+        total[message] += 1
+        if day >= since:
+            recent[message] += 1
+        last[message] = max(day, last.get(message, day))
+    return sorted(
+        (Habit(m, total[m], recent[m], last[m]) for m in total),
+        key=lambda h: (-h.recent, -h.total, h.message),
+    )
+
+
+def habit_deck() -> Deck:
+    """One card per "Use X instead of Y" hint, most frequent first."""
+    deck = Deck("habits", "Your habits")
+    for i, habit in enumerate(habits()):
+        m = _USE.match(habit.message)
+        if not m:
+            continue
+        better, worse = m.group(1), m.group(2)
+        n = len(split_keys(better))
+        deck.cards.append(
+            Card(
+                deck="habits",
+                id=f"habits:{habit.message}",
+                prompt=f"You typed {worse}. hardtime knows the same edit in {n} key{'' if n == 1 else 's'}: which?",
+                answers=[better],
+                style="keys",
+                case_sensitive=True,
+                note=f"hardtime caught this {habit.total}×.",
+                order=i,
+            )
+        )
+    return deck
+
+
+def drill_lessons(days: int = 7) -> list[str]:
+    """Lessons worth repeating because of keys pressed over and over lately."""
+    since = date.today() - timedelta(days=days)
+    keys: Counter[str] = Counter()
+    for day, message in read_log():
+        if day < since:
+            continue
+        m = _TOO_SOON.match(message) or _DISABLED.match(message)
+        if m:
+            key = _ARROWS.get(m.group(1), m.group(1))
+            if key in DRILL_LESSONS:
+                keys[key] += 1
+    lessons: list[str] = []
+    for key, _ in keys.most_common():
+        lessons += [lesson for lesson in DRILL_LESSONS[key] if lesson not in lessons]
+    return lessons

vimniscient/keys.py

@@ -0,0 +1,14 @@
+"""Counting keystrokes written in Vim key notation (`ciwfoo<Esc>`)."""
+
+import re
+
+_TOKEN = re.compile(r"<[^<>\s]+>|.", re.S)
+
+
+def split_keys(keys: str) -> list[str]:
+    """Split `ci"x<Esc>` into ['c', 'i', '"', 'x', '<Esc>']."""
+    return _TOKEN.findall(keys)
+
+
+def count_keys(keys: str) -> int:
+    return len(split_keys(keys))

vimniscient/lessons/sources.md

@@ -0,0 +1,59 @@
+# Sources for the facts in the lesson texts
+
+The lesson texts are mnemonic: they describe the key being practised (see
+`../mnemonics.yaml`), and the rest is about the science of learning and memory.
+Every factual claim in them should trace back to one of these.
+
+- **Atkinson & Raugh (1975).** An application of the mnemonic keyword method to
+  the acquisition of a Russian vocabulary. *JEP: Human Learning and Memory*
+  1(2). The keyword method: link a foreign word to a sound-alike word and an
+  image.
+- **Bjork (1994).** Memory and metamemory considerations in the training of
+  human beings. In *Metacognition*. "Desirable difficulties": conditions that
+  make learning feel harder (spacing, testing, interleaving) often make it last.
+- **Cowan (2001).** The magical number 4 in short-term memory. *Behavioral and
+  Brain Sciences* 24(1). About four chunks.
+- **Dunlosky, Rawson, Marsh, Nathan & Willingham (2013).** Improving students'
+  learning with effective learning techniques. *Psychological Science in the
+  Public Interest* 14(1). High utility: practice testing, distributed practice.
+  Moderate: interleaved practice, elaborative interrogation, self-explanation.
+  Low: highlighting, rereading, summarization, keyword mnemonic, imagery for
+  text.
+- **Ebbinghaus (1885).** *Über das Gedächtnis.* Nonsense syllables, tested on
+  himself; the forgetting curve, steepest right after learning.
+- **Fitts & Posner (1967).** *Human Performance.* Three stages of skill
+  learning: cognitive, associative, autonomous.
+- **Miller (1956).** The magical number seven, plus or minus two. *Psychological
+  Review* 63(2).
+- **Roediger & Karpicke (2006).** Test-enhanced learning. *Psychological
+  Science* 17(3). Retrieval practice beat restudying on a test a week later,
+  though restudying looked better after five minutes.
+- **Spacing effect.** Among the best-replicated findings in memory research;
+  see Cepeda, Pashler, Vul, Wixted & Rohrer (2006), Distributed practice in
+  verbal recall tasks, *Psychological Bulletin* 132(3).
+- **Sleep and consolidation.** Sleep after learning helps memories stabilise;
+  see Diekelmann & Born (2010), The memory function of sleep, *Nature Reviews
+  Neuroscience* 11(2).
+- **Fluency illusion.** Rereading makes text feel familiar, which people
+  mistake for knowing it; see Bjork, Dunlosky & Kornell (2013), Self-regulated
+  learning, *Annual Review of Psychology* 64.
+- **Production effect.** Words read aloud are remembered better than words
+  read silently; MacLeod, Gopie, Hourihan, Neary & Ozubko (2010), The
+  production effect, *JEP: Learning, Memory, and Cognition* 36(3).
+- **Interleaving.** Mixed practice feels harder than blocked practice but
+  tests better later; Rohrer & Taylor (2007), The shuffling of mathematics
+  problems improves learning, *Instructional Science* 35.
+- **Variability of practice.** Practising with variation helps a skill carry
+  over to new conditions; Kerr & Booth (1978), Specific and varied practice
+  of motor skill, *Perceptual and Motor Skills* 46(2).
+- **Lag effect.** Longer gaps between reviews tend to beat shorter ones;
+  covered in Cepeda et al. (2006) above.
+- **Life dates and years used:** Ebbinghaus born 1850, *Über das Gedächtnis*
+  1885; Miller 1956; Roediger & Karpicke 2006.
+- **Recall before the answer.** Trying to retrieve an answer, even
+  unsuccessfully, before seeing it improves later memory of it; Kornell,
+  Hays & Bjork (2009), Unsuccessful retrieval attempts enhance subsequent
+  learning, *JEP: Learning, Memory, and Cognition* 35(4). This is why the
+  app shows what keys stand for only after you answer.
+- **ed's `t`.** The ed manual: "(.,.)t(.) Copies (i.e., transfers) the
+  addressed lines". **grep** takes its name from ed's `g/re/p`.

vimniscient/lessons/w1d1-words.yaml

@@ -0,0 +1,223 @@
+week: 1
+day: 1
+title: Word text objects
+intro: |
+  Read a Vim command as a small sentence: a verb, then a noun. The verbs are
+  `c` *change*, `d` *delete* and `y` *yank* (Vim's old word for copy). The noun
+  is a text object: `i` *inner* or `a` (*a word*, or *around* it), then what
+  kind of thing, `w` for *word*. So `ciw` reads *change inner word*, and it
+  works from anywhere inside the word. `iw` is the word alone, `aw` takes its
+  space too. Capital `W` is a big WORD: everything between two spaces, dots
+  included.
+keys: [ciw, diw, daw, ciW, yiw, viwp]
+tasks:
+  - goal: 'Fix "while" to "whole" (the cursor is in the middle of the word).'
+    start: |-
+      ciw is change inner word: it swaps the wh▮ile word, wherever the cursor sits.
+    target: |-
+      ciw is change inner word: it swaps the whole word, wherever the cursor sits.
+    solution: 'ciwwhole<Esc>'
+    hint: 'c changes, i keeps it inner, w names the word: ciw, from anywhere inside it.'
+    generate: ciw-typo  # Recall and reviews can get a new text (generate.py)
+    variants:
+      - goal: 'Fix "spaec" to "space" (the cursor is in the middle of the word).'
+        start: |-
+          The i in ciw means inner: just the word, never the spa▮ec around it.
+        target: |-
+          The i in ciw means inner: just the word, never the space around it.
+        solution: 'ciwspace<Esc>'
+      - goal: 'Fix "anywhrere" to "anywhere" (the cursor is in the middle of the word).'
+        start: |-
+          Change inner word: c is the verb, iw the noun, and the cursor sits anywh▮rere in it.
+        target: |-
+          Change inner word: c is the verb, iw the noun, and the cursor sits anywhere in it.
+        solution: 'ciwanywhere<Esc>'
+      - goal: 'Fix "memroy" to "memory" (the cursor is in the middle of the word).'
+        start: |-
+          Testing yourself beats rereading: type ciw from mem▮roy, not from the page.
+        target: |-
+          Testing yourself beats rereading: type ciw from memory, not from the page.
+        solution: 'ciwmemory<Esc>'
+      - goal: 'Fix "undersocres" to "underscores" (the cursor is in the middle of the word).'
+        start: |-
+          In ciw, the w is a word: letters, digits and under▮socres, nothing else.
+        target: |-
+          In ciw, the w is a word: letters, digits and underscores, nothing else.
+        solution: 'ciwunderscores<Esc>'
+  - goal: 'Delete one "own", including its space.'
+    start: |-
+      The a in daw is around: the word and its own ▮own space.
+    target: |-
+      The a in daw is around: the word and its own space.
+    solution: 'daw'
+    hint: 'd deletes, a takes the word with its space, w is the word: daw leaves no double space.'
+    generate: daw-double  # Recall and reviews can get a new text (generate.py)
+    variants:
+      - goal: 'Delete the second "behind".'
+        start: |-
+          daw leaves no double space behind be▮hind.
+        target: |-
+          daw leaves no double space behind.
+        solution: 'daw'
+      - goal: 'Delete one "its", including its space.'
+        start: |-
+          daw takes a word and what is around it, its ▮its trailing space.
+        target: |-
+          daw takes a word and what is around it, its trailing space.
+      - goal: 'Delete one "himself".'
+        start: |-
+          Ebbinghaus tested ▮himself himself on nonsense syllables; daw cuts the echo.
+        target: |-
+          Ebbinghaus tested himself on nonsense syllables; daw cuts the echo.
+      - goal: 'Delete one "so".'
+        start: |-
+          With daw, a means around: the word goes, and ▮so so does one space.
+        target: |-
+          With daw, a means around: the word goes, and so does one space.
+  - goal: 'Write the dotted "e.v.e.r.y.t.h.i.n.g" as "everything".'
+    start: |-
+      Big W, big WORD: ciW takes e.v.e.r.y▮.t.h.i.n.g between two spaces.
+    target: |-
+      Big W, big WORD: ciW takes everything between two spaces.
+    solution: 'ciWeverything<Esc>'
+    hint: 'A WORD (capital W) runs from space to space, dots included. Try ciW.'
+    generate: ciW-dotted  # Recall and reviews can get a new text (generate.py)
+    variants:
+      - goal: 'Replace the whole URL with "a URL".'
+        start: |-
+          ciW sees www.wa▮ls.info as one WORD: dots do not split it.
+        target: |-
+          ciW sees a URL as one WORD: dots do not split it.
+        solution: 'ciWa URL<Esc>'
+      - goal: 'Replace "e.g." with "for example".'
+        start: |-
+          A WORD runs from space to space, e.▮g. a dotted abbreviation.
+        target: |-
+          A WORD runs from space to space, for example a dotted abbreviation.
+        solution: 'ciWfor example<Esc>'
+      - goal: 'Replace the path with "a path".'
+        start: |-
+          ciW sees ~/notes/vi▮m.md as one WORD, slashes and all.
+        target: |-
+          ciW sees a path as one WORD, slashes and all.
+        solution: 'ciWa path<Esc>'
+      - goal: 'Replace "Fitts&Posner(1967)" with "Fitts-and-Posner".'
+        start: |-
+          ciW: from space to space, Fitts&Pos▮ner(1967) counts as one WORD.
+        target: |-
+          ciW: from space to space, Fitts-and-Posner counts as one WORD.
+        solution: 'ciWFitts-and-Posner<Esc>'
+  - goal: 'Spell the function name out as change_inner_word.'
+    ft: python
+    start: |-
+      def ▮chg_in_wd(word, new):
+          """c = change, i = inner, w = word."""
+          return new
+    target: |-
+      def change_inner_word(word, new):
+          """c = change, i = inner, w = word."""
+          return new
+    solution: 'ciwchange_inner_word<Esc>'
+    hint: 'Underscores belong to a word, so ciw takes the whole name.'
+    variants:
+      - goal: 'Spell the function name out as delete_a_word.'
+        start: |-
+          def ▮del_a_wd(text):
+              """d = delete, a = a word and its space, w = word."""
+              return text
+        target: |-
+          def delete_a_word(text):
+              """d = delete, a = a word and its space, w = word."""
+              return text
+        solution: 'ciwdelete_a_word<Esc>'
+      - goal: 'Spell the function name out as change_inner_WORD.'
+        start: |-
+          def ▮chg_in_WD(text, new):
+              """c = change, i = inner, W = WORD, space to space."""
+              return new
+        target: |-
+          def change_inner_WORD(text, new):
+              """c = change, i = inner, W = WORD, space to space."""
+              return new
+        solution: 'ciwchange_inner_WORD<Esc>'
+      - goal: 'Spell the function name out as yank_inner_word.'
+        start: |-
+          def ▮ynk_in_wd(text):
+              """y = yank, Vim's older word for copy; i = inner; w = word."""
+              return text
+        target: |-
+          def yank_inner_word(text):
+              """y = yank, Vim's older word for copy; i = inner; w = word."""
+              return text
+        solution: 'ciwyank_inner_word<Esc>'
+      - goal: 'Spell the function name out as snake_case_name.'
+        start: |-
+          def ▮snk_cs_nm(name):
+              """ciw takes it all: underscores belong to the word."""
+              return name
+        target: |-
+          def snake_case_name(name):
+              """ciw takes it all: underscores belong to the word."""
+              return name
+        solution: 'ciwsnake_case_name<Esc>'
+  - goal: 'Copy "word" over "noun".'
+    start: |-
+      viwp puts the ▮word you yanked over the other noun
+    target: |-
+      viwp puts the word you yanked over the other word
+    solution: 'yiw$viwp'
+    hint: 'yiw yanks the inner word; $ jumps to the last one; viwp selects it and puts the yank over it.'
+    variants:
+      - goal: 'Copy "verb" over "noun".'
+        start: |-
+          Put is a ▮verb, and yank is a noun.
+        target: |-
+          Put is a verb, and yank is a verb.
+        solution: 'yiw$bviwp'
+      - goal: 'Copy "yank" over "paste".'
+        start: |-
+          viwp swaps a selection for the ▮yank, so select, then put the paste
+        target: |-
+          viwp swaps a selection for the yank, so select, then put the yank
+        solution: 'yiw$viwp'
+      - goal: 'Copy "spaced" over "massed".'
+        start: |-
+          ▮spaced reviews beat massed ones, so keep them massed
+        target: |-
+          spaced reviews beat massed ones, so keep them spaced
+        solution: 'yiw$viwp'
+      - goal: 'Copy "mixed" over the last "blocked".'
+        start: |-
+          Rohrer and Taylor: blocked practice feels better than ▮mixed, yet scores below blocked
+        target: |-
+          Rohrer and Taylor: blocked practice feels better than mixed, yet scores below mixed
+        solution: 'yiw$viwp'
+  - goal: 'Delete the doubled "the".'
+    start: |-
+      daw: delete a word, and ▮the the space after it.
+    target: |-
+      daw: delete a word, and the space after it.
+    solution: 'daw'
+    hint: 'daw takes the word and its trailing space.'
+    generate: daw-double  # Recall and reviews can get a new text (generate.py)
+    variants:
+      - goal: 'Delete the doubled "like".'
+        start: |-
+          Doubled words ▮like like this one are what daw is for.
+        target: |-
+          Doubled words like this one are what daw is for.
+      - goal: 'Delete the doubled "four".'
+        start: |-
+          Cowan put short-term memory at about ▮four four chunks.
+        target: |-
+          Cowan put short-term memory at about four chunks.
+      - goal: 'Delete the doubled "familiar".'
+        start: |-
+          Rereading builds a fluency illusion: the text feels ▮familiar familiar, not known.
+        target: |-
+          Rereading builds a fluency illusion: the text feels familiar, not known.
+      - goal: 'Delete the doubled "and".'
+        start: |-
+          daw: d for delete, a for a word ▮and and its space.
+        target: |-
+          daw: d for delete, a for a word and its space.